swarm_sdk 2.6.0 → 2.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 100b5eeda25839a9c9a02270edf2d84b4623e267a55f215fa79c7479a0333f96
-  data.tar.gz: f63cf4bf9726f769edad0b620b8738223879d2e8ceb4f2111b9be317868ace46
+  metadata.gz: ce2f1c2ddb88cfb9a4fe7505fc0417494c2baf22a41678cbe7eb9085d96f136f
+  data.tar.gz: 5d5c8174d6f96d52f6855636d5fc7c485db6a0470e11d18ee2b5866fcd91431a
 SHA512:
-  metadata.gz: 742e655084a0c9307694ef1d10b868cee0f3b3af77f7c5b3bd0bd6bf25f3a97a677bb31e6dda8a9d9074f072099e575fbc8ba7bb12e6e9b56431fc839436e30b
-  data.tar.gz: 8d943e6f17b77eac4d747ba9b9a73fdc1eb2600a40646b641ae226b6e239acb7daab3271b345a8b712cf0d405170f2251f5a7b29eae77f4d991c56f9af8ce828
+  metadata.gz: 5e503eeda171b1840cabc10fccc5f98d1c4bcd75eba1782f885fd19cc09219b39850662c901793ff9e9d0cbfbdfcc9759071c782476bb793ab87f9ddd94c3ae9
+  data.tar.gz: 054e3a4db5ead9c96e2d332a1a85e9102bdaabe8e50c1e3163776789709289b5fbc73fce5f73b4af856c6e1ca0a3e6f5b3cbf4918f10f6a946c9ef6223384b12

data/lib/swarm_sdk/agent/builder.rb

@@ -250,8 +250,39 @@ module SwarmSDK
       end
 
       # Set delegation targets
-      def delegates_to(*agent_names)
-        @delegates_to.concat(agent_names)
+      #
+      # Supports multiple formats for flexibility:
+      #
+      # @example Simple array (backwards compatible)
+      #   delegates_to :frontend, :backend, :qa
+      #
+      # @example Hash with custom tool names
+      #   delegates_to frontend: "AskFrontend",
+      #                backend: "GetBackendHelp",
+      #                qa: "RequestReview"
+      #
+      # @example Mixed - some auto, some custom
+      #   delegates_to :frontend,
+      #                backend: "GetBackendHelp",
+      #                :qa
+      #
+      # @param agent_names_and_options [Array<Symbol, Hash>] Agent names and/or hash with custom tool names
+      # @return [void]
+      def delegates_to(*agent_names_and_options)
+        agent_names_and_options.each do |item|
+          case item
+          when Symbol, String
+            # Simple format: :frontend
+            @delegates_to << { agent: item.to_sym, tool_name: nil }
+          when Hash
+            # Hash format: { frontend: "AskFrontend", backend: nil }
+            item.each do |agent, tool_name|
+              @delegates_to << { agent: agent.to_sym, tool_name: tool_name }
+            end
+          else
+            raise ConfigurationError, "delegates_to accepts Symbols or Hashes, got #{item.class}"
+          end
+        end
       end
 
       # Add a hook (Ruby block OR shell command)

data/lib/swarm_sdk/agent/definition.rb

@@ -24,7 +24,7 @@ module SwarmSDK
         :context_window,
         :directory,
         :tools,
-        :delegates_to,
+        :delegation_configs, # Full delegation config with tool names
         :system_prompt,
         :provider,
         :base_url,
@@ -125,7 +125,8 @@ module SwarmSDK
         # Inject default write restrictions for security
         @tools = inject_default_write_permissions(@tools)
 
-        @delegates_to = Array(config[:delegates_to] || []).map(&:to_sym).uniq
+        # Parse delegation configuration (supports both simple arrays and custom tool names)
+        @delegation_configs = parse_delegation_config(config[:delegates_to])
         @mcp_servers = Array(config[:mcp_servers] || [])
 
         # Parse hooks configuration
@@ -135,6 +136,20 @@ module SwarmSDK
         validate!
       end
 
+      # Get agent names that this agent delegates to (backwards compatible)
+      #
+      # Returns an array of agent name symbols. This maintains backwards compatibility
+      # with existing code that expects delegates_to to be a simple array.
+      #
+      # @return [Array<Symbol>] Delegate agent names
+      #
+      # @example
+      #   agent_definition.delegates_to
+      #   # => [:frontend, :backend, :qa]
+      def delegates_to
+        @delegation_configs.map { |config| config[:agent] }
+      end
+
       # Get plugin-specific configuration
       #
       # Plugins store their configuration in the generic plugin_configs hash.
@@ -146,7 +161,7 @@ module SwarmSDK
       #
       # @example
       #   agent_definition.plugin_config(:memory)
-      #   # => { directory: "tmp/memory", mode: :researcher }
+      #   # => { directory: "tmp/memory", mode: :full_access }
       def plugin_config(plugin_name)
         @plugin_configs[plugin_name.to_sym] || @plugin_configs[plugin_name.to_s]
       end
@@ -160,7 +175,7 @@ module SwarmSDK
           context_window: @context_window,
           directory: @directory,
           tools: @tools,
-          delegates_to: @delegates_to,
+          delegates_to: @delegation_configs, # Serialize full config
           system_prompt: @system_prompt,
           provider: @provider,
           base_url: @base_url,
@@ -285,6 +300,51 @@ module SwarmSDK
         File.expand_path(directory_config.to_s)
       end
 
+      # Parse delegation configuration
+      #
+      # Supports multiple formats for backwards compatibility and new features:
+      # 1. Simple array (backwards compatible): [:frontend, :backend]
+      # 2. Hash with custom tool names: { frontend: "AskFrontend", backend: nil }
+      # 3. Array of hashes: [{ agent: :frontend, tool_name: "AskFrontend" }]
+      #
+      # Returns normalized format: [{agent: :name, tool_name: "Custom" or nil}]
+      #
+      # @param delegation_config [nil, Array, Hash] Delegation configuration
+      # @return [Array<Hash>] Normalized delegation config
+      def parse_delegation_config(delegation_config)
+        return [] if delegation_config.nil?
+        return [] if delegation_config.respond_to?(:empty?) && delegation_config.empty?
+
+        # Handle array format (could be symbols or hashes)
+        if delegation_config.is_a?(Array)
+          delegation_config.flat_map do |item|
+            case item
+            when Symbol, String
+              # Simple format: :frontend → {agent: :frontend, tool_name: nil}
+              [{ agent: item.to_sym, tool_name: nil }]
+            when Hash
+              # Could be already normalized or hash format
+              if item.key?(:agent)
+                # Already normalized: {agent: :frontend, tool_name: "Custom"}
+                [item]
+              else
+                # Hash format in array: {frontend: "AskFrontend"}
+                item.map { |agent, tool_name| { agent: agent.to_sym, tool_name: tool_name } }
+              end
+            else
+              raise ConfigurationError, "Invalid delegation config format: #{item.inspect}"
+            end
+          end.uniq { |config| config[:agent] } # Remove duplicates by agent name
+        elsif delegation_config.is_a?(Hash)
+          # Hash format: {frontend: "AskFrontend", backend: nil}
+          delegation_config.map do |agent, tool_name|
+            { agent: agent.to_sym, tool_name: tool_name }
+          end
+        else
+          raise ConfigurationError, "delegates_to must be an Array or Hash, got #{delegation_config.class}"
+        end
+      end
+
       # Extract plugin-specific configuration keys from the config hash
       #
       # Standard SDK keys are filtered out, leaving only plugin-specific keys.

data/lib/swarm_sdk/builders/base_builder.rb

@@ -276,8 +276,17 @@ module SwarmSDK
           builder.tools(*tool_names)
         end
 
-        # Add delegates_to
-        builder.delegates_to(*config[:delegates_to]) if config[:delegates_to]&.any?
+        # Add delegates_to (handle both array and hash formats)
+        if config[:delegates_to]&.any?
+          delegation_config = config[:delegates_to]
+          if delegation_config.is_a?(Hash)
+            # Hash format: pass as single argument
+            builder.delegates_to(delegation_config)
+          elsif delegation_config.is_a?(Array)
+            # Array format: splat the array
+            builder.delegates_to(*delegation_config)
+          end
+        end
 
         # Add MCP servers
         config[:mcp_servers]&.each do |server|
@@ -333,7 +342,15 @@ module SwarmSDK
           when :tools
             merged[:tools] = Array(merged[:tools]) + Array(value)
           when :delegates_to
-            merged[:delegates_to] = Array(merged[:delegates_to]) + Array(value)
+            # Handle merging delegation configs (can be array or hash)
+            existing = merged[:delegates_to] || []
+            new_value = value || []
+
+            # Convert both to array of delegation configs for merging
+            existing_array = normalize_delegation_array(existing)
+            new_array = normalize_delegation_array(new_value)
+
+            merged[:delegates_to] = existing_array + new_array
           when :parameters
             merged[:parameters] = (merged[:parameters] || {}).merge(value || {})
           when :headers
@@ -357,6 +374,35 @@ module SwarmSDK
         merged
       end
 
+      # Normalize delegation config to array of hashes format
+      #
+      # Converts various delegation formats to normalized array for merging:
+      # - Array of symbols: [:frontend, :backend] → [{agent: :frontend, tool_name: nil}, ...]
+      # - Hash: {frontend: "Custom"} → [{agent: :frontend, tool_name: "Custom"}, ...]
+      # - Array of hashes: [{agent: :frontend, tool_name: "Custom"}] → unchanged
+      #
+      # @param delegation_config [Array, Hash] Delegation configuration
+      # @return [Array<Hash>] Normalized array of {agent:, tool_name:} hashes
+      def normalize_delegation_array(delegation_config)
+        return [] if delegation_config.nil? || (delegation_config.respond_to?(:empty?) && delegation_config.empty?)
+
+        case delegation_config
+        when Array
+          delegation_config.map do |item|
+            case item
+            when Symbol, String
+              { agent: item.to_sym, tool_name: nil }
+            when Hash
+              item.key?(:agent) ? item : item.map { |agent, tool_name| { agent: agent.to_sym, tool_name: tool_name } }
+            end
+          end.flatten
+        when Hash
+          delegation_config.map { |agent, tool_name| { agent: agent.to_sym, tool_name: tool_name } }
+        else
+          []
+        end
+      end
+
       # Apply all_agents defaults to an agent builder
       #
       # @param agent_builder [Agent::Builder] The agent builder to configure

data/lib/swarm_sdk/configuration/parser.rb

@@ -90,7 +90,28 @@ module SwarmSDK
         return [] unless agent_config
 
         delegates = agent_config[:delegates_to] || []
-        Array(delegates).map(&:to_sym)
+
+        # Handle both array and hash formats for delegates_to
+        case delegates
+        when Array
+          # Array of symbols: [:frontend, :backend]
+          # OR array of hashes: [{agent: :frontend, tool_name: "Custom"}]
+          delegates.map do |item|
+            case item
+            when Symbol, String
+              item.to_sym
+            when Hash
+              # Extract agent name from hash format
+              agent_name = item[:agent] || item["agent"]
+              agent_name&.to_sym
+            end
+          end.compact # Remove nils from malformed hashes
+        when Hash
+          # Hash format: {frontend: "Custom", backend: nil}
+          delegates.keys.map(&:to_sym)
+        else
+          []
+        end
       end
 
       attr_reader :base_dir

data/lib/swarm_sdk/configuration/translator.rb

@@ -168,7 +168,19 @@ module SwarmSDK
             tools(*tool_names)
           end
 
-          delegates_to(*config[:delegates_to]) if config[:delegates_to]&.any?
+          # Handle both array and hash formats for delegates_to
+          if config[:delegates_to]&.any?
+            delegation_config = config[:delegates_to]
+            if delegation_config.is_a?(Hash)
+              # Hash format: { frontend: "Custom", backend: nil }
+              # Pass as single hash argument, not splatted
+              delegates_to(delegation_config)
+            elsif delegation_config.is_a?(Array)
+              # Array format: [:frontend, :backend] OR [{agent: :frontend, tool_name: "Custom"}]
+              # Splat the array
+              delegates_to(*delegation_config)
+            end
+          end
 
           config[:mcp_servers]&.each do |server|
             mcp_server(server[:name], **server.except(:name))
@@ -229,7 +241,16 @@ module SwarmSDK
               tools_override = agent_config[:tools]
 
               agent_cfg = agent(agent_name, reset_context: reset_ctx)
-              agent_cfg = agent_cfg.delegates_to(*delegates) if delegates.any?
+
+              # Handle both array and hash formats for delegates_to
+              if delegates.any?
+                if delegates.is_a?(Hash)
+                  agent_cfg = agent_cfg.delegates_to(delegates)
+                elsif delegates.is_a?(Array)
+                  agent_cfg = agent_cfg.delegates_to(*delegates)
+                end
+              end
+
               agent_cfg.tools(*tools_override) if tools_override
             end
 

data/lib/swarm_sdk/configuration.rb

@@ -104,7 +104,28 @@ module SwarmSDK
       return [] unless agent_config
 
       delegates = agent_config[:delegates_to] || []
-      Array(delegates).map(&:to_sym)
+
+      # Handle both array and hash formats for delegates_to
+      case delegates
+      when Array
+        # Array of symbols: [:frontend, :backend]
+        # OR array of hashes: [{agent: :frontend, tool_name: "Custom"}]
+        delegates.map do |item|
+          case item
+          when Symbol, String
+            item.to_sym
+          when Hash
+            # Extract agent name from hash format
+            agent_name = item[:agent] || item["agent"]
+            agent_name&.to_sym
+          end
+        end.compact # Remove nils from malformed hashes
+      when Hash
+        # Hash format: {frontend: "Custom", backend: nil}
+        delegates.keys.map(&:to_sym)
+      else
+        []
+      end
     end
 
     # Convert configuration to Swarm or Workflow using appropriate builder

data/lib/swarm_sdk/swarm/agent_initializer.rb

@@ -88,8 +88,9 @@ module SwarmSDK
       # @param delegate_chat [Agent::Chat] The delegate's chat instance
       # @param agent_name [Symbol] Name of the delegating agent
       # @param delegating_chat [Agent::Chat, nil] The chat instance of the agent doing the delegating
+      # @param custom_tool_name [String, nil] Optional custom tool name (overrides auto-generated name)
       # @return [Tools::Delegate] Delegation tool
-      def create_delegation_tool(name:, description:, delegate_chat:, agent_name:, delegating_chat: nil)
+      def create_delegation_tool(name:, description:, delegate_chat:, agent_name:, delegating_chat: nil, custom_tool_name: nil)
         Tools::Delegate.new(
           delegate_name: name,
           delegate_description: description,
@@ -97,6 +98,7 @@ module SwarmSDK
           agent_name: agent_name,
           swarm: @swarm,
           delegating_chat: delegating_chat,
+          custom_tool_name: custom_tool_name,
         )
       end
 
@@ -140,8 +142,8 @@ module SwarmSDK
 
         # Sub-pass 2a: Create delegation instances for isolated agents
         @swarm.agent_definitions.each do |delegator_name, delegator_def|
-          delegator_def.delegates_to.each do |delegate_base_name|
-            delegate_base_name = delegate_base_name.to_sym
+          delegator_def.delegation_configs.each do |delegation_config|
+            delegate_base_name = delegation_config[:agent]
 
             unless @swarm.agent_definitions.key?(delegate_base_name)
               raise ConfigurationError,
@@ -177,11 +179,11 @@ module SwarmSDK
           # Skip if delegator doesn't exist as primary (wasn't created in pass_1)
           next unless delegator_chat
 
-          delegator_def.delegates_to.each do |delegate_name|
+          delegator_def.delegation_configs.each do |delegation_config|
             wire_delegation(
               delegator_name: delegator_name,
               delegator_chat: delegator_chat,
-              delegate_name: delegate_name,
+              delegation_config: delegation_config,
               tool_configurator: tool_configurator,
               create_nested_instances: false,
             )
@@ -195,11 +197,11 @@ module SwarmSDK
           delegate_definition = @swarm.agent_definitions[base_name]
 
           # Register delegation tools for THIS instance's delegates_to
-          delegate_definition.delegates_to.each do |nested_delegate_name|
+          delegate_definition.delegation_configs.each do |delegation_config|
             wire_delegation(
               delegator_name: instance_name.to_sym,
               delegator_chat: delegation_chat,
-              delegate_name: nested_delegate_name,
+              delegation_config: delegation_config,
               tool_configurator: tool_configurator,
               create_nested_instances: true,
             )
@@ -215,22 +217,24 @@ module SwarmSDK
       #
       # @param delegator_name [Symbol, String] Name of the agent doing the delegating
       # @param delegator_chat [Agent::Chat] Chat instance of the delegator
-      # @param delegate_name [Symbol, String] Name of the delegate target
+      # @param delegation_config [Hash] Delegation configuration with :agent and :tool_name keys
       # @param tool_configurator [ToolConfigurator] Tool configuration helper
       # @param create_nested_instances [Boolean] Whether to create new instances for nested delegation
       # @return [void]
-      def wire_delegation(delegator_name:, delegator_chat:, delegate_name:, tool_configurator:, create_nested_instances:)
-        delegate_name_str = delegate_name.to_s
-        delegate_name_sym = delegate_name.to_sym
+      def wire_delegation(delegator_name:, delegator_chat:, delegation_config:, tool_configurator:, create_nested_instances:)
+        delegate_name_sym = delegation_config[:agent]
+        delegate_name_str = delegate_name_sym.to_s
+        custom_tool_name = delegation_config[:tool_name]
 
         # Check if target is a registered swarm
         if @swarm.swarm_registry&.registered?(delegate_name_str)
-          wire_swarm_delegation(delegator_name, delegator_chat, delegate_name_str)
+          wire_swarm_delegation(delegator_name, delegator_chat, delegate_name_str, custom_tool_name)
         elsif @swarm.agent_definitions.key?(delegate_name_sym)
           wire_agent_delegation(
             delegator_name: delegator_name,
             delegator_chat: delegator_chat,
             delegate_name_sym: delegate_name_sym,
+            custom_tool_name: custom_tool_name,
             tool_configurator: tool_configurator,
             create_nested_instances: create_nested_instances,
           )
@@ -245,14 +249,16 @@ module SwarmSDK
       # @param delegator_name [Symbol, String] Name of the delegating agent
       # @param delegator_chat [Agent::Chat] Chat instance of the delegator
       # @param swarm_name [String] Name of the registered swarm
+      # @param custom_tool_name [String, nil] Optional custom tool name
       # @return [void]
-      def wire_swarm_delegation(delegator_name, delegator_chat, swarm_name)
+      def wire_swarm_delegation(delegator_name, delegator_chat, swarm_name, custom_tool_name)
         tool = create_delegation_tool(
           name: swarm_name,
           description: "External swarm: #{swarm_name}",
           delegate_chat: nil, # Swarm delegation - no direct chat
           agent_name: delegator_name,
           delegating_chat: delegator_chat,
+          custom_tool_name: custom_tool_name,
         )
 
         delegator_chat.add_tool(tool)
@@ -266,10 +272,11 @@ module SwarmSDK
       # @param delegator_name [Symbol, String] Name of the delegating agent
       # @param delegator_chat [Agent::Chat] Chat instance of the delegator
       # @param delegate_name_sym [Symbol] Name of the delegate agent
+      # @param custom_tool_name [String, nil] Optional custom tool name
       # @param tool_configurator [ToolConfigurator] Tool configuration helper
       # @param create_nested_instances [Boolean] Whether to create new instances if not found
       # @return [void]
-      def wire_agent_delegation(delegator_name:, delegator_chat:, delegate_name_sym:, tool_configurator:, create_nested_instances:)
+      def wire_agent_delegation(delegator_name:, delegator_chat:, delegate_name_sym:, custom_tool_name:, tool_configurator:, create_nested_instances:)
         delegate_definition = @swarm.agent_definitions[delegate_name_sym]
 
         # Determine which chat instance to use
@@ -301,6 +308,7 @@ module SwarmSDK
           delegate_chat: target_chat,
           agent_name: delegator_name,
           delegating_chat: delegator_chat,
+          custom_tool_name: custom_tool_name,
         )
 
         delegator_chat.add_tool(tool)
@@ -326,8 +334,10 @@ module SwarmSDK
 
       # Setup context for an agent (primary or delegation instance)
       def setup_agent_context(agent_name, agent_definition, chat, is_delegation: false)
-        delegate_tool_names = agent_definition.delegates_to.map do |delegate_name|
-          Tools::Delegate.tool_name_for(delegate_name)
+        # Generate actual tool names (custom or auto-generated) for context tracking
+        delegate_tool_names = agent_definition.delegation_configs.map do |delegation_config|
+          # Use custom name if provided, otherwise auto-generate
+          delegation_config[:tool_name] || Tools::Delegate.tool_name_for(delegation_config[:agent])
         end
 
         context = Agent::Context.new(

data/lib/swarm_sdk/tools/delegate.rb

@@ -36,13 +36,15 @@ module SwarmSDK
       # @param agent_name [Symbol, String] Name of the agent using this tool
       # @param swarm [Swarm] The swarm instance (provides hook_registry, delegation_call_stack, swarm_registry)
       # @param delegating_chat [Agent::Chat, nil] The chat instance of the agent doing the delegating (for accessing hooks)
+      # @param custom_tool_name [String, nil] Optional custom tool name (overrides auto-generated name)
       def initialize(
         delegate_name:,
         delegate_description:,
         delegate_chat:,
         agent_name:,
         swarm:,
-        delegating_chat: nil
+        delegating_chat: nil,
+        custom_tool_name: nil
       )
         super()
 
@@ -53,8 +55,8 @@ module SwarmSDK
         @swarm = swarm
         @delegating_chat = delegating_chat
 
-        # Generate tool name using canonical method
-        @tool_name = self.class.tool_name_for(delegate_name)
+        # Use custom tool name if provided, otherwise generate using canonical method
+        @tool_name = custom_tool_name || self.class.tool_name_for(delegate_name)
         @delegate_target = delegate_name.to_s
       end
 

data/lib/swarm_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.6.0"
+  VERSION = "2.6.1"
 end

data/lib/swarm_sdk/workflow/agent_config.rb

@@ -37,10 +37,26 @@ module SwarmSDK
 
       # Set delegation targets for this agent
       #
-      # @param agent_names [Array<Symbol>] Names of agents to delegate to
+      # Supports multiple formats for flexibility:
+      # - Array: delegates_to(:frontend, :backend)
+      # - Hash: delegates_to(frontend: "AskFrontend", backend: "GetBackend")
+      #
+      # @param agent_names_and_options [Array<Symbol, Hash>] Names and/or hash with custom tool names
       # @return [self] For method chaining
-      def delegates_to(*agent_names)
-        @delegates_to = agent_names.map(&:to_sym)
+      def delegates_to(*agent_names_and_options)
+        # Parse delegation configs (same logic as Agent::Builder)
+        @delegates_to = []
+        agent_names_and_options.each do |item|
+          case item
+          when Symbol, String
+            @delegates_to << { agent: item.to_sym, tool_name: nil }
+          when Hash
+            item.each do |agent, tool_name|
+              @delegates_to << { agent: agent.to_sym, tool_name: tool_name }
+            end
+          end
+        end
+
         update_registration
         self
       end

data/lib/swarm_sdk/workflow/builder.rb

@@ -183,10 +183,45 @@ module SwarmSDK
         @nodes.values.flat_map do |node_builder|
           # Collect both direct agents and their delegation targets
           node_builder.agent_configs.flat_map do |config|
-            [config[:agent]] + Array(config[:delegates_to])
+            # Extract delegate agent names (handles array and hash formats)
+            delegate_names = extract_delegate_agent_names(config[:delegates_to] || [])
+            [config[:agent]] + delegate_names
           end
         end.uniq
       end
+
+      # Extract agent names from delegation configuration
+      #
+      # Handles multiple formats:
+      # - Array of symbols: [:frontend, :backend]
+      # - Hash: {frontend: "Custom", backend: nil}
+      # - Array of hashes: [{agent: :frontend, tool_name: "Custom"}]
+      #
+      # @param delegation_config [Array, Hash, nil] Delegation configuration
+      # @return [Array<Symbol>] Array of agent name symbols
+      def extract_delegate_agent_names(delegation_config)
+        return [] if delegation_config.nil?
+        return [] if delegation_config.respond_to?(:empty?) && delegation_config.empty?
+
+        case delegation_config
+        when Array
+          delegation_config.map do |item|
+            case item
+            when Symbol, String
+              item.to_sym
+            when Hash
+              # Extract agent name from normalized format
+              agent_name = item[:agent] || item["agent"]
+              agent_name&.to_sym
+            end
+          end.compact # Remove nils from malformed hashes
+        when Hash
+          # Hash format: keys are agent names
+          delegation_config.keys.map(&:to_sym)
+        else
+          []
+        end
+      end
     end
   end
 end

data/lib/swarm_sdk/workflow/node_builder.rb

@@ -541,7 +541,10 @@ module SwarmSDK
       # @return [void]
       def auto_add_delegate_agents
         # Collect all agents mentioned in delegates_to
-        all_delegates = @agent_configs.flat_map { |ac| ac[:delegates_to] }.uniq
+        # Extract agent names from all delegation configs (handles hash and array formats)
+        all_delegates = @agent_configs.flat_map do |ac|
+          extract_delegate_agent_names(ac[:delegates_to] || [])
+        end.uniq
 
         # Find delegates that aren't explicitly declared
         declared_agents = @agent_configs.map { |ac| ac[:agent] }
@@ -552,6 +555,39 @@ module SwarmSDK
           @agent_configs << { agent: delegate_name, delegates_to: [], reset_context: true }
         end
       end
+
+      # Extract agent names from delegation configuration
+      #
+      # Handles multiple formats:
+      # - Array of symbols: [:frontend, :backend]
+      # - Hash: {frontend: "Custom", backend: nil}
+      # - Array of hashes: [{agent: :frontend, tool_name: "Custom"}]
+      #
+      # @param delegation_config [Array, Hash, nil] Delegation configuration
+      # @return [Array<Symbol>] Array of agent name symbols
+      def extract_delegate_agent_names(delegation_config)
+        return [] if delegation_config.nil?
+        return [] if delegation_config.respond_to?(:empty?) && delegation_config.empty?
+
+        case delegation_config
+        when Array
+          delegation_config.map do |item|
+            case item
+            when Symbol, String
+              item.to_sym
+            when Hash
+              # Extract agent name from normalized format
+              agent_name = item[:agent] || item["agent"]
+              agent_name&.to_sym
+            end
+          end.compact # Remove nils from malformed hashes
+        when Hash
+          # Hash format: keys are agent names
+          delegation_config.keys.map(&:to_sym)
+        else
+          []
+        end
+      end
     end
   end
 end

data/lib/swarm_sdk/workflow.rb

@@ -377,7 +377,9 @@ module SwarmSDK
           end
 
           # Validate delegation targets exist
-          config[:delegates_to].each do |delegate|
+          # Extract agent names from delegation config (supports both array and hash formats)
+          delegate_names = extract_delegate_agent_names(config[:delegates_to])
+          delegate_names.each do |delegate|
             unless @agent_definitions.key?(delegate)
               raise ConfigurationError,
                 "Node '#{node_name}' agent '#{agent_name}' delegates to undefined agent '#{delegate}'"
@@ -550,5 +552,38 @@ module SwarmSDK
           "Invalid scratchpad mode: #{value.inspect}. Use :enabled, :per_node, or :disabled"
       end
     end
+
+    # Extract agent names from delegation configuration
+    #
+    # Handles multiple formats:
+    # - Array of symbols: [:frontend, :backend]
+    # - Hash: {frontend: "Custom", backend: nil}
+    # - Array of hashes: [{agent: :frontend, tool_name: "Custom"}]
+    #
+    # @param delegation_config [Array, Hash, nil] Delegation configuration
+    # @return [Array<Symbol>] Array of agent name symbols
+    def extract_delegate_agent_names(delegation_config)
+      return [] if delegation_config.nil?
+      return [] if delegation_config.respond_to?(:empty?) && delegation_config.empty?
+
+      case delegation_config
+      when Array
+        delegation_config.map do |item|
+          case item
+          when Symbol, String
+            item.to_sym
+          when Hash
+            # Extract agent name from normalized format
+            agent_name = item[:agent] || item["agent"]
+            agent_name&.to_sym
+          end
+        end.compact # Remove nils from malformed hashes
+      when Hash
+        # Hash format: keys are agent names
+        delegation_config.keys.map(&:to_sym)
+      else
+        []
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.6.0
+  version: 2.6.1
 platform: ruby
 authors:
 - Paulo Arruda