swarm_sdk 2.7.9 → 2.7.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6af3c1d2b4f71135747902e3d94b4541904bf1877c02064cb928cccc742cf9b
-  data.tar.gz: a829be669e85d25c1fa85cc05410b44bb3d9785ad0a72bfe238ae92f1859c828
+  metadata.gz: 7863f2b6c3b7c74c13ca47957713e5588167a09a2c95acfebb3c53bab571af7f
+  data.tar.gz: edf4cc3e12b13327909b8c21a5b0b40dafde5707ff82883762d980b267330e8b
 SHA512:
-  metadata.gz: af53d4fa1e8a4ae2ace5297e90743ddd219e3015f3ffa62e89dedb607f73e9641d3cb3d44b506a76e2a70a72074aa3f504229cb4a7d02b056af6b0b555c59bdd
-  data.tar.gz: 333359fe2c10fbb772675ae035fa00de4eb1a1cf9d3f5ee7e7b4440d8d6bd25cfc96d1efbadf8621e5bf3c6ef53f8e790a8d31db3c682c1ac7f47d61507c4843
+  metadata.gz: df8234592d637315378d078c211b98b61bf3411d11ac49b2c2d82954314cf985686deb927d9d8f41855a341675fb216814415a7be0b7e5e0297fd593b83fc95f
+  data.tar.gz: 360d76065cbc15d6968d13616cb5e2c29d5a6b3771aa58a7490fca5cf360fc6b0a2bd3b3c7c90b98d89388205ad927ea998b2804fb1076bed5d91aff0d982596

data/lib/swarm_sdk/swarm/agent_initializer.rb

@@ -189,119 +189,18 @@ module SwarmSDK
         results
       end
 
-      # Collect all delegation instances that need to be created
+      # Pass 2: Wire delegation tools (lazy loading for isolated delegates)
       #
-      # Validates delegation configs and returns a list of instances to create.
-      # This is done sequentially to fail fast on configuration errors.
+      # This pass wires delegation tools for primary agents:
+      # - Shared delegates use the primary agent instance
+      # - Isolated delegates use LazyDelegateChat (created on first use)
       #
-      # @return [Array<Hash>] Array of { instance_name:, base_name:, definition: }
-      def collect_delegation_instances_to_create
-        instances = []
-
-        @swarm.agent_definitions.each do |delegator_name, delegator_def|
-          delegator_def.delegation_configs.each do |delegation_config|
-            delegate_base_name = delegation_config[:agent]
-
-            # Validate delegate exists
-            unless @swarm.agent_definitions.key?(delegate_base_name)
-              raise ConfigurationError,
-                "Agent '#{delegator_name}' delegates to unknown agent '#{delegate_base_name}'"
-            end
-
-            delegate_definition = @swarm.agent_definitions[delegate_base_name]
-
-            # Skip if delegate wants to be shared (use primary instead)
-            next if delegate_definition.shared_across_delegations
-
-            instance_name = "#{delegate_base_name}@#{delegator_name}"
-
-            instances << {
-              instance_name: instance_name,
-              base_name: delegate_base_name,
-              definition: delegate_definition,
-            }
-          end
-        end
-
-        instances
-      end
-
-      # Create multiple delegation instances in parallel using Async fibers
-      #
-      # @param instances_to_create [Array<Hash>] Array of instance configs
-      # @param tool_configurator [ToolConfigurator] Shared tool configurator
-      # @return [Array<Array>] Array of [instance_name, chat] tuples
-      def create_delegation_instances_in_parallel(instances_to_create, tool_configurator)
-        return [] if instances_to_create.empty?
-
-        results = []
-        errors = []
-        mutex = Mutex.new
-
-        Sync do
-          barrier = Async::Barrier.new
-
-          instances_to_create.each do |config|
-            barrier.async do
-              delegation_chat = create_agent_chat_for_delegation(
-                instance_name: config[:instance_name],
-                base_name: config[:base_name],
-                agent_definition: config[:definition],
-                tool_configurator: tool_configurator,
-              )
-              mutex.synchronize { results << [config[:instance_name], delegation_chat] }
-            rescue StandardError => e
-              # Catch errors to avoid Async warning logs (which fail in tests with StringIO)
-              mutex.synchronize { errors << [config[:instance_name], e] }
-            end
-          end
-
-          barrier.wait
-        end
-
-        # Re-raise first error if any occurred
-        unless errors.empty?
-          # Emit events for all errors (not just the first)
-          errors.each do |inst_name, err|
-            LogStream.emit(
-              type: "delegation_instance_initialization_error",
-              instance_name: inst_name,
-              error_class: err.class.name,
-              error_message: err.message,
-              timestamp: Time.now.utc.iso8601,
-            )
-          end
-
-          # Re-raise first error with context
-          instance_name, error = errors.first
-          raise error.class, "Delegation instance '#{instance_name}' initialization failed: #{error.message}", error.backtrace
-        end
-
-        results
-      end
-
-      # Pass 2: Create delegation instances and wire delegation tools
-      #
-      # This pass has three sub-steps that must happen in order:
-      # 2a. Create delegation instances (ONLY for agents with shared_across_delegations: false)
-      # 2b. Wire primary agents to delegation instances OR shared primaries
-      # 2c. Wire delegation instances to their delegates (nested delegation support)
-      #
-      # Sub-pass 2a is parallelized using Async::Barrier for faster initialization.
+      # Sub-pass 2a (eager creation) is REMOVED - delegation instances are now lazy.
+      # Sub-pass 2c (nested delegation) is handled by LazyDelegateChat when initialized.
       def pass_2_register_delegation_tools
         tool_configurator = ToolConfigurator.new(@swarm, @swarm.scratchpad_storage, @swarm.plugin_storages)
 
-        # Sub-pass 2a: Create delegation instances for isolated agents (parallelized)
-        delegation_instances_to_create = collect_delegation_instances_to_create
-
-        results = create_delegation_instances_in_parallel(delegation_instances_to_create, tool_configurator)
-
-        # Store results after all parallel creation completes
-        results.each do |instance_name, delegation_chat|
-          @swarm.delegation_instances[instance_name] = delegation_chat
-        end
-
-        # Sub-pass 2b: Wire primary agents to delegation instances OR shared primaries OR registered swarms
+        # Wire primary agents to delegates (shared primaries or lazy loaders)
         @swarm.agent_definitions.each do |delegator_name, delegator_def|
           delegator_chat = @agents[delegator_name]
 
@@ -314,43 +213,25 @@ module SwarmSDK
               delegator_chat: delegator_chat,
               delegation_config: delegation_config,
               tool_configurator: tool_configurator,
-              create_nested_instances: false,
             )
           end
         end
 
-        # Sub-pass 2c: Wire delegation instances to their delegates (nested delegation)
-        # Convert to array first to avoid "can't add key during iteration" error
-        @swarm.delegation_instances.to_a.each do |instance_name, delegation_chat|
-          base_name = extract_base_name(instance_name)
-          delegate_definition = @swarm.agent_definitions[base_name]
-
-          # Register delegation tools for THIS instance's delegates_to
-          delegate_definition.delegation_configs.each do |delegation_config|
-            wire_delegation(
-              delegator_name: instance_name.to_sym,
-              delegator_chat: delegation_chat,
-              delegation_config: delegation_config,
-              tool_configurator: tool_configurator,
-              create_nested_instances: true,
-            )
-          end
-        end
+        # NOTE: Nested delegation wiring is now handled by LazyDelegateChat#wire_delegation_tools
+        # when the lazy delegate is first accessed.
       end
 
-      # Wire a single delegation from one agent/instance to a delegate
+      # Wire a single delegation from one agent to a delegate
       #
-      # This is the unified logic for delegation wiring used by both:
-      # - Sub-pass 2b: Primary agents → delegates
-      # - Sub-pass 2c: Delegation instances → nested delegates
+      # For isolated delegates, creates a LazyDelegateChat wrapper instead of
+      # eagerly creating the chat instance.
       #
       # @param delegator_name [Symbol, String] Name of the agent doing the delegating
       # @param delegator_chat [Agent::Chat] Chat instance of the delegator
       # @param delegation_config [Hash] Delegation configuration with :agent, :tool_name, and :preserve_context 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:, delegation_config:, tool_configurator:, create_nested_instances:)
+      def wire_delegation(delegator_name:, delegator_chat:, delegation_config:, tool_configurator:)
         delegate_name_sym = delegation_config[:agent]
         delegate_name_str = delegate_name_sym.to_s
         custom_tool_name = delegation_config[:tool_name]
@@ -365,8 +246,6 @@ module SwarmSDK
             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,
             preserve_context: preserve_context,
           )
         else
@@ -404,18 +283,17 @@ module SwarmSDK
 
       # Wire delegation to a local agent
       #
-      # Determines whether to use shared primary or isolated instance based on
-      # the delegate's shared_across_delegations setting.
+      # For shared delegates, uses the primary agent instance.
+      # For isolated delegates, creates a LazyDelegateChat wrapper that
+      # defers creation until first use.
       #
       # @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
       # @param preserve_context [Boolean] Whether to preserve context between delegations
       # @return [void]
-      def wire_agent_delegation(delegator_name:, delegator_chat:, delegate_name_sym:, custom_tool_name:, tool_configurator:, create_nested_instances:, preserve_context:)
+      def wire_agent_delegation(delegator_name:, delegator_chat:, delegate_name_sym:, custom_tool_name:, preserve_context:)
         delegate_definition = @swarm.agent_definitions[delegate_name_sym]
 
         # Determine which chat instance to use
@@ -423,24 +301,18 @@ module SwarmSDK
           # Shared mode: use primary agent (semaphore-protected)
           @agents[delegate_name_sym]
         else
-          # Isolated mode: use delegation instance
+          # Isolated mode: use lazy loader (created on first delegation)
           instance_name = "#{delegate_name_sym}@#{delegator_name}"
 
-          if create_nested_instances
-            # For nested delegation: create if not exists
-            @swarm.delegation_instances[instance_name] ||= create_agent_chat_for_delegation(
-              instance_name: instance_name,
-              base_name: delegate_name_sym,
-              agent_definition: delegate_definition,
-              tool_configurator: tool_configurator,
-            )
-          else
-            # For primary delegation: instance was pre-created in 2a
-            @swarm.delegation_instances[instance_name]
-          end
+          LazyDelegateChat.new(
+            instance_name: instance_name,
+            base_name: delegate_name_sym,
+            agent_definition: delegate_definition,
+            swarm: @swarm,
+          )
         end
 
-        # Create delegation tool pointing to chosen instance
+        # Create delegation tool pointing to chosen instance (or lazy loader)
         tool = create_delegation_tool(
           name: delegate_name_sym.to_s,
           description: delegate_definition.description,
@@ -467,18 +339,15 @@ module SwarmSDK
       #
       # Create Agent::Context for each agent to track delegations and metadata.
       # This is needed regardless of whether logging is enabled.
+      #
+      # NOTE: Delegation instances are now lazy-loaded, so their contexts are
+      # set up in LazyDelegateChat#setup_context when first accessed.
       def pass_3_setup_contexts
-        # Setup contexts for PRIMARY agents
+        # Setup contexts for PRIMARY agents only
+        # (Delegation instances handle their own context setup via LazyDelegateChat)
         @agents.each do |agent_name, chat|
           setup_agent_context(agent_name, @swarm.agent_definitions[agent_name], chat, is_delegation: false)
         end
-
-        # Setup contexts for DELEGATION instances
-        @swarm.delegation_instances.each do |instance_name, chat|
-          base_name = extract_base_name(instance_name)
-          agent_definition = @swarm.agent_definitions[base_name]
-          setup_agent_context(instance_name.to_sym, agent_definition, chat, is_delegation: true)
-        end
       end
 
       # Setup context for an agent (primary or delegation instance)
@@ -541,16 +410,15 @@ module SwarmSDK
       # Pass 4: Configure hook system
       #
       # Setup the callback system for each agent, integrating with RubyLLM callbacks.
+      #
+      # NOTE: Delegation instances are now lazy-loaded, so their hooks are
+      # configured in LazyDelegateChat#configure_hooks when first accessed.
       def pass_4_configure_hooks
-        # Configure hooks for PRIMARY agents
+        # Configure hooks for PRIMARY agents only
+        # (Delegation instances handle their own hook setup via LazyDelegateChat)
         @agents.each do |agent_name, chat|
           configure_hooks_for_agent(agent_name, chat)
         end
-
-        # Configure hooks for DELEGATION instances
-        @swarm.delegation_instances.each do |instance_name, chat|
-          configure_hooks_for_agent(instance_name.to_sym, chat)
-        end
       end
 
       # Configure hooks for an agent (primary or delegation instance)
@@ -569,18 +437,17 @@ module SwarmSDK
       #
       # If the swarm was loaded from YAML with agent-specific hooks,
       # apply them now via HooksAdapter.
+      #
+      # NOTE: Delegation instances are now lazy-loaded, so their YAML hooks are
+      # applied in LazyDelegateChat#apply_yaml_hooks when first accessed.
       def pass_5_apply_yaml_hooks
         return unless @swarm.config_for_hooks
 
-        # Apply YAML hooks to PRIMARY agents
+        # Apply YAML hooks to PRIMARY agents only
+        # (Delegation instances handle their own YAML hooks via LazyDelegateChat)
         @agents.each do |agent_name, chat|
           apply_yaml_hooks_for_agent(agent_name, chat)
         end
-
-        # Apply YAML hooks to DELEGATION instances
-        @swarm.delegation_instances.each do |instance_name, chat|
-          apply_yaml_hooks_for_agent(instance_name.to_sym, chat)
-        end
       end
 
       # Apply YAML hooks for an agent (primary or delegation instance)
@@ -603,13 +470,14 @@ module SwarmSDK
       # - Tools must be activated AFTER all registration is complete
       # - This populates @llm_chat.tools from the registry
       #
+      # NOTE: Delegation instances are now lazy-loaded, so their tools are
+      # activated in LazyDelegateChat#initialize_chat when first accessed.
+      #
       # @return [void]
       def pass_6_activate_tools
-        # Activate tools for PRIMARY agents
+        # Activate tools for PRIMARY agents only
+        # (Delegation instances handle their own tool activation via LazyDelegateChat)
         @agents.each_value(&:activate_tools_for_prompt)
-
-        # Activate tools for DELEGATION instances
-        @swarm.delegation_instances.each_value(&:activate_tools_for_prompt)
       end
 
       # Create Agent::Chat instance with rate limiting
@@ -653,103 +521,8 @@ module SwarmSDK
         chat
       end
 
-      # Create a delegation-specific instance of an agent
-      #
-      # V7.0: Simplified - just calls register_all_tools with instance_name
-      #
-      # @param instance_name [String] Unique instance name ("base@delegator")
-      # @param base_name [Symbol] Base agent name (for definition lookup)
-      # @param agent_definition [Agent::Definition] Base agent definition
-      # @param tool_configurator [ToolConfigurator] Shared tool configurator
-      # @return [Agent::Chat] Delegation-specific chat instance
-      def create_agent_chat_for_delegation(instance_name:, base_name:, agent_definition:, tool_configurator:)
-        # Create chat with instance_name for isolated conversation + tool state
-        chat = Agent::Chat.new(
-          definition: agent_definition.to_h,
-          agent_name: instance_name.to_sym, # Full instance name for isolation
-          global_semaphore: @swarm.global_semaphore,
-        )
-
-        # Set provider agent name for logging
-        chat.provider.agent_name = instance_name if chat.provider.respond_to?(:agent_name=)
-
-        # V7.0 SIMPLIFIED: Just call register_all_tools with instance_name!
-        # Base name extraction happens automatically in create_plugin_tool
-        tool_configurator.register_all_tools(
-          chat: chat,
-          agent_name: instance_name.to_sym,
-          agent_definition: agent_definition,
-        )
-
-        # Register MCP servers (tracked by instance_name automatically)
-        if agent_definition.mcp_servers.any?
-          mcp_configurator = McpConfigurator.new(@swarm)
-          mcp_configurator.register_mcp_servers(
-            chat,
-            agent_definition.mcp_servers,
-            agent_name: instance_name,
-          )
-        end
-
-        # Setup tool activation dependencies (Plan 025)
-        chat.setup_tool_activation(
-          tool_configurator: tool_configurator,
-          agent_definition: agent_definition,
-        )
-
-        # Notify plugins (use instance_name, plugins extract base_name if needed)
-        notify_plugins_agent_initialized(instance_name.to_sym, chat, agent_definition, tool_configurator)
-
-        # NOTE: activate_tools_for_prompt is called in Pass 6 after all plugins
-
-        chat
-      end
-
-      # Register agent delegation tools
-      #
-      # Creates delegation tools that allow one agent to call another.
-      #
-      # @param chat [Agent::Chat] The chat instance
-      # @param delegate_names [Array<Symbol>] Names of agents to delegate to
-      # @param agent_name [Symbol] Name of the agent doing the delegating
-      def register_delegation_tools(chat, delegate_names, agent_name:)
-        return if delegate_names.empty?
-
-        delegate_names.each do |delegate_name|
-          delegate_name_sym = delegate_name.to_sym
-          delegate_name_str = delegate_name.to_s
-
-          # Check if target is a local agent
-          if @agents.key?(delegate_name_sym)
-            # Delegate to local agent
-            delegate_agent = @agents[delegate_name_sym]
-            delegate_definition = @swarm.agent_definitions[delegate_name_sym]
-
-            tool = create_delegation_tool(
-              name: delegate_name_str,
-              description: delegate_definition.description,
-              delegate_chat: delegate_agent,
-              agent_name: agent_name,
-              delegating_chat: chat,
-            )
-
-            chat.add_tool(tool)
-          elsif @swarm.swarm_registry&.registered?(delegate_name_str)
-            # Delegate to registered swarm
-            tool = create_delegation_tool(
-              name: delegate_name_str,
-              description: "External swarm: #{delegate_name_str}",
-              delegate_chat: nil, # Swarm delegation - no direct chat
-              agent_name: agent_name,
-              delegating_chat: chat,
-            )
-
-            chat.add_tool(tool)
-          else
-            raise ConfigurationError, "Agent '#{agent_name}' delegates to unknown target '#{delegate_name_str}' (not a local agent or registered swarm)"
-          end
-        end
-      end
+      # NOTE: create_agent_chat_for_delegation and register_delegation_tools were removed.
+      # Delegation instances are now lazy-loaded via LazyDelegateChat.
 
       # Create plugin storages for all agents
       #

data/lib/swarm_sdk/swarm/lazy_delegate_chat.rb

@@ -0,0 +1,372 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Swarm
+    # Lazy loader for delegation agent chats
+    #
+    # Instead of creating delegation instances eagerly at swarm initialization,
+    # this class defers creation until the first delegation call. This improves
+    # initialization performance for swarms where not all agents are used.
+    #
+    # Thread-safe via Mutex - safe for concurrent access.
+    #
+    # @example
+    #   lazy_chat = LazyDelegateChat.new(
+    #     instance_name: "backend@frontend",
+    #     base_name: :backend,
+    #     agent_definition: backend_def,
+    #     swarm: swarm
+    #   )
+    #
+    #   # Later, when delegation is first called:
+    #   chat = lazy_chat.chat  # Creates agent on first access
+    #   chat.ask("Do something")
+    class LazyDelegateChat
+      attr_reader :instance_name, :base_name, :agent_definition
+
+      # Initialize a lazy delegate chat wrapper
+      #
+      # @param instance_name [String] Unique instance name ("base@delegator")
+      # @param base_name [Symbol] Base agent name (for definition lookup)
+      # @param agent_definition [Agent::Definition] Agent definition
+      # @param swarm [Swarm] Parent swarm reference
+      def initialize(instance_name:, base_name:, agent_definition:, swarm:)
+        @instance_name = instance_name
+        @base_name = base_name
+        @agent_definition = agent_definition
+        @swarm = swarm
+        @chat = nil
+        @mutex = Mutex.new
+        @initialized = false
+      end
+
+      # Get or create the agent chat instance
+      #
+      # On first call, creates the agent chat and runs initialization.
+      # Subsequent calls return the cached instance.
+      #
+      # @return [Agent::Chat] The initialized chat instance
+      def chat
+        return @chat if @initialized
+
+        @mutex.synchronize do
+          return @chat if @initialized
+
+          @chat = initialize_chat
+          @initialized = true
+          @chat
+        end
+      end
+
+      # Check if the agent has been initialized
+      #
+      # @return [Boolean] True if chat has been created
+      def initialized?
+        @mutex.synchronize { @initialized }
+      end
+
+      private
+
+      # Create and initialize the agent chat
+      #
+      # This mirrors the initialization done in AgentInitializer passes 1-6
+      # but for a single lazy delegate.
+      #
+      # @return [Agent::Chat] Fully initialized chat instance
+      def initialize_chat
+        emit_lazy_init_start
+
+        # Create tool configurator
+        tool_configurator = ToolConfigurator.new(
+          @swarm,
+          @swarm.scratchpad_storage,
+          @swarm.plugin_storages,
+        )
+
+        # Create the agent chat (mirrors AgentInitializer#create_agent_chat_for_delegation)
+        chat = create_delegation_chat(tool_configurator)
+
+        # Store in delegation_instances (so other code can find it)
+        @swarm.delegation_instances[@instance_name] = chat
+
+        # Wire delegation tools for this instance (nested delegation support)
+        wire_delegation_tools(chat, tool_configurator)
+
+        # Setup context
+        setup_context(chat)
+
+        # Configure hooks
+        configure_hooks(chat)
+
+        # Apply YAML hooks if present
+        apply_yaml_hooks(chat)
+
+        # Activate tools
+        chat.activate_tools_for_prompt
+
+        # Notify plugins
+        notify_plugins(chat, tool_configurator)
+
+        emit_lazy_init_complete
+
+        chat
+      end
+
+      # Create the delegation chat instance
+      #
+      # @param tool_configurator [ToolConfigurator] Tool configuration helper
+      # @return [Agent::Chat] Newly created chat instance
+      def create_delegation_chat(tool_configurator)
+        chat = Agent::Chat.new(
+          definition: @agent_definition.to_h,
+          agent_name: @instance_name.to_sym,
+          global_semaphore: @swarm.global_semaphore,
+        )
+
+        # Set provider agent name for logging
+        chat.provider.agent_name = @instance_name if chat.provider.respond_to?(:agent_name=)
+
+        # Register all tools (built-in, permissions, etc.)
+        tool_configurator.register_all_tools(
+          chat: chat,
+          agent_name: @instance_name.to_sym,
+          agent_definition: @agent_definition,
+        )
+
+        # Register MCP servers if configured
+        if @agent_definition.mcp_servers.any?
+          mcp_configurator = McpConfigurator.new(@swarm)
+          mcp_configurator.register_mcp_servers(
+            chat,
+            @agent_definition.mcp_servers,
+            agent_name: @instance_name,
+          )
+        end
+
+        # Setup tool activation dependencies
+        chat.setup_tool_activation(
+          tool_configurator: tool_configurator,
+          agent_definition: @agent_definition,
+        )
+
+        chat
+      end
+
+      # Wire delegation tools for this instance (nested delegation support)
+      #
+      # If this agent delegates to other agents, create those tools.
+      # The delegate targets may themselves be lazy.
+      #
+      # @param chat [Agent::Chat] The chat instance
+      # @param tool_configurator [ToolConfigurator] Tool configuration helper
+      # @return [void]
+      def wire_delegation_tools(chat, tool_configurator)
+        @agent_definition.delegation_configs.each do |delegation_config|
+          delegate_name_sym = delegation_config[:agent]
+          delegate_name_str = delegate_name_sym.to_s
+          custom_tool_name = delegation_config[:tool_name]
+          preserve_context = delegation_config.fetch(:preserve_context, true)
+
+          # Check if target is a registered swarm
+          if @swarm.swarm_registry&.registered?(delegate_name_str)
+            wire_swarm_delegation(chat, delegate_name_str, custom_tool_name, preserve_context)
+          elsif @swarm.agent_definitions.key?(delegate_name_sym)
+            wire_agent_delegation(chat, delegate_name_sym, custom_tool_name, tool_configurator, preserve_context)
+          else
+            raise ConfigurationError,
+              "Agent '#{@instance_name}' delegates to unknown target '#{delegate_name_str}'"
+          end
+        end
+      end
+
+      # Wire delegation to an external swarm
+      #
+      # @param chat [Agent::Chat] The delegating chat
+      # @param swarm_name [String] Name of the registered swarm
+      # @param custom_tool_name [String, nil] Optional custom tool name
+      # @param preserve_context [Boolean] Whether to preserve context
+      # @return [void]
+      def wire_swarm_delegation(chat, swarm_name, custom_tool_name, preserve_context)
+        tool = Tools::Delegate.new(
+          delegate_name: swarm_name,
+          delegate_description: "External swarm: #{swarm_name}",
+          delegate_chat: nil,
+          agent_name: @instance_name,
+          swarm: @swarm,
+          delegating_chat: chat,
+          custom_tool_name: custom_tool_name,
+          preserve_context: preserve_context,
+        )
+
+        chat.tool_registry.register(
+          tool,
+          source: :delegation,
+          metadata: { delegate_name: swarm_name, delegation_type: :swarm, preserve_context: preserve_context },
+        )
+      end
+
+      # Wire delegation to a local agent
+      #
+      # For lazy-loaded agents, creates a LazyDelegateChat wrapper.
+      # For shared agents, uses the primary instance.
+      #
+      # @param chat [Agent::Chat] The delegating chat
+      # @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 preserve_context [Boolean] Whether to preserve context
+      # @return [void]
+      def wire_agent_delegation(chat, delegate_name_sym, custom_tool_name, tool_configurator, preserve_context)
+        delegate_definition = @swarm.agent_definitions[delegate_name_sym]
+
+        # Determine which chat instance to use
+        target_chat = if delegate_definition.shared_across_delegations
+          # Shared mode: use primary agent
+          @swarm.agents[delegate_name_sym]
+        else
+          # Isolated mode: create nested lazy loader or get existing instance
+          nested_instance_name = "#{delegate_name_sym}@#{@instance_name}"
+
+          # Check if already exists (might have been created by another path)
+          existing = @swarm.delegation_instances[nested_instance_name]
+          if existing
+            existing
+          else
+            # Create lazy loader for nested delegation
+            LazyDelegateChat.new(
+              instance_name: nested_instance_name,
+              base_name: delegate_name_sym,
+              agent_definition: delegate_definition,
+              swarm: @swarm,
+            )
+          end
+        end
+
+        # Create delegation tool pointing to chosen instance
+        tool = Tools::Delegate.new(
+          delegate_name: delegate_name_sym.to_s,
+          delegate_description: delegate_definition.description,
+          delegate_chat: target_chat,
+          agent_name: @instance_name,
+          swarm: @swarm,
+          delegating_chat: chat,
+          custom_tool_name: custom_tool_name,
+          preserve_context: preserve_context,
+        )
+
+        chat.tool_registry.register(
+          tool,
+          source: :delegation,
+          metadata: {
+            delegate_name: delegate_name_sym,
+            delegation_mode: delegate_definition.shared_across_delegations ? :shared : :isolated,
+            preserve_context: preserve_context,
+          },
+        )
+      end
+
+      # Setup agent context
+      #
+      # @param chat [Agent::Chat] The chat instance
+      # @return [void]
+      def setup_context(chat)
+        delegate_tool_names = @agent_definition.delegation_configs.map do |delegation_config|
+          delegation_config[:tool_name] || Tools::Delegate.tool_name_for(delegation_config[:agent])
+        end
+
+        context = Agent::Context.new(
+          name: @instance_name.to_sym,
+          swarm_id: @swarm.swarm_id,
+          parent_swarm_id: @swarm.parent_swarm_id,
+          delegation_tools: delegate_tool_names,
+          metadata: { is_delegation_instance: true },
+        )
+
+        chat.setup_context(context) if chat.respond_to?(:setup_context)
+
+        # Configure logging if enabled
+        return unless LogStream.emitter
+
+        chat.setup_logging if chat.respond_to?(:setup_logging)
+      end
+
+      # Configure hooks for the agent
+      #
+      # @param chat [Agent::Chat] The chat instance
+      # @return [void]
+      def configure_hooks(chat)
+        return unless chat.respond_to?(:setup_hooks)
+
+        chat.setup_hooks(
+          registry: @swarm.hook_registry,
+          agent_definition: @agent_definition,
+          swarm: @swarm,
+        )
+      end
+
+      # Apply YAML hooks if present
+      #
+      # @param chat [Agent::Chat] The chat instance
+      # @return [void]
+      def apply_yaml_hooks(chat)
+        return unless @swarm.config_for_hooks
+
+        agent_config = @swarm.config_for_hooks.agents[@base_name]
+        return unless agent_config
+
+        hooks = agent_config.is_a?(Hash) ? agent_config[:hooks] : agent_config.hooks
+        return unless hooks&.any?
+
+        Hooks::Adapter.apply_agent_hooks(chat, @instance_name.to_sym, hooks, @swarm.name)
+      end
+
+      # Notify plugins that agent was initialized
+      #
+      # @param chat [Agent::Chat] The chat instance
+      # @param tool_configurator [ToolConfigurator] Tool configuration helper
+      # @return [void]
+      def notify_plugins(chat, tool_configurator)
+        PluginRegistry.all.each do |plugin|
+          plugin_storages = @swarm.plugin_storages[plugin.name] || {}
+          storage = plugin_storages[@base_name]
+
+          context = {
+            storage: storage,
+            agent_definition: @agent_definition,
+            tool_configurator: tool_configurator,
+          }
+
+          plugin.on_agent_initialized(
+            agent_name: @instance_name.to_sym,
+            agent: chat,
+            context: context,
+          )
+        end
+      end
+
+      # Emit lazy initialization start event
+      #
+      # @return [void]
+      def emit_lazy_init_start
+        LogStream.emit(
+          type: "agent_lazy_initialization_start",
+          instance_name: @instance_name,
+          base_name: @base_name,
+          timestamp: Time.now.utc.iso8601,
+        )
+      end
+
+      # Emit lazy initialization complete event
+      #
+      # @return [void]
+      def emit_lazy_init_complete
+        LogStream.emit(
+          type: "agent_lazy_initialization_complete",
+          instance_name: @instance_name,
+          base_name: @base_name,
+          timestamp: Time.now.utc.iso8601,
+        )
+      end
+    end
+  end
+end

data/lib/swarm_sdk/swarm.rb

@@ -581,6 +581,61 @@ module SwarmSDK
     # @return [void]
     attr_writer :swarm_registry
 
+    # Force initialization of all lazy delegation instances
+    #
+    # By default, delegation instances for isolated delegates are lazy-loaded
+    # (created on first delegation call). This method forces immediate initialization
+    # of all lazy delegates, which can be useful for:
+    # - Testing: Verify delegation instance properties without mocking
+    # - Preloading: Initialize all agents upfront for predictable timing
+    #
+    # This method is recursive - it will initialize nested lazy delegates until
+    # all delegation chains are fully initialized.
+    #
+    # @return [void]
+    #
+    # @example Force-initialize all delegates for testing
+    #   swarm.initialize_agents
+    #   swarm.initialize_lazy_delegates!
+    #   assert swarm.delegation_instances.key?("backend@lead")
+    def initialize_lazy_delegates!
+      initialize_agents unless @agents_initialized
+
+      # Keep initializing until no more lazy delegates are found
+      # This handles nested delegation chains (A -> B -> C)
+      loop do
+        initialized_any = false
+
+        # Find all delegation tools with lazy loaders in primary agents
+        @agents.each_value do |chat|
+          chat.tools.each_value do |tool|
+            next unless tool.is_a?(Tools::Delegate)
+            next unless tool.lazy? && !tool.initialized?
+
+            tool.initialize_delegate!
+            initialized_any = true
+          end
+        end
+
+        # Also check delegation instances for their own lazy delegates (nested)
+        @delegation_instances.values.each do |chat|
+          # Skip if this is still a LazyDelegateChat (shouldn't happen after above loop)
+          next if chat.is_a?(Swarm::LazyDelegateChat)
+
+          chat.tools.each_value do |tool|
+            next unless tool.is_a?(Tools::Delegate)
+            next unless tool.lazy? && !tool.initialized?
+
+            tool.initialize_delegate!
+            initialized_any = true
+          end
+        end
+
+        # Exit loop when no more lazy delegates were initialized
+        break unless initialized_any
+      end
+    end
+
     # --- Internal API (for Executor use only) ---
     # Hook triggers for swarm lifecycle events are provided by HookTriggers module
 

data/lib/swarm_sdk/tools/delegate.rb

@@ -37,7 +37,7 @@ module SwarmSDK
         end
       end
 
-      attr_reader :delegate_name, :delegate_target, :tool_name, :preserve_context
+      attr_reader :delegate_name, :delegate_target, :tool_name, :preserve_context, :delegate_chat
 
       # Initialize a delegation tool
       #
@@ -94,6 +94,32 @@ module SwarmSDK
         @tool_name
       end
 
+      # Check if this delegate uses lazy loading
+      #
+      # @return [Boolean] True if delegate is lazy-loaded
+      def lazy?
+        @delegate_chat.is_a?(Swarm::LazyDelegateChat)
+      end
+
+      # Check if this delegate has been initialized
+      #
+      # @return [Boolean] True if delegate chat is ready (either eager or lazy-initialized)
+      def initialized?
+        return true unless lazy?
+
+        @delegate_chat.initialized?
+      end
+
+      # Force initialization of lazy delegate
+      #
+      # If the delegate is lazy-loaded, this will trigger immediate initialization.
+      # For eager delegates, this is a no-op.
+      #
+      # @return [Agent::Chat] The resolved chat instance
+      def initialize_delegate!
+        resolve_delegate_chat
+      end
+
       # Execute delegation with pre/post hooks
       #
       # @param message [String] Message to send to the agent
@@ -226,6 +252,9 @@ module SwarmSDK
 
       # Delegate to an agent
       #
+      # Handles both eager Agent::Chat instances and lazy-loaded delegates.
+      # LazyDelegateChat instances are initialized on first access.
+      #
       # @param message [String] Message to send to the agent
       # @param call_stack [Array] Delegation call stack for circular dependency detection
       # @param reset_context [Boolean] Whether to reset the agent's conversation history before delegation
@@ -234,11 +263,14 @@ module SwarmSDK
         # Push delegate target onto call stack to track delegation chain
         call_stack.push(@delegate_target)
         begin
+          # Resolve the chat instance (handles lazy loading)
+          chat = resolve_delegate_chat
+
           # Clear conversation if reset_context is true OR if preserve_context is false
           # reset_context takes precedence as it's an explicit request
-          @delegate_chat.clear_conversation if reset_context || !@preserve_context
+          chat.clear_conversation if reset_context || !@preserve_context
 
-          response = @delegate_chat.ask(message, source: "delegation")
+          response = chat.ask(message, source: "delegation")
           response.content
         ensure
           # Always pop from stack, even if delegation fails
@@ -246,6 +278,20 @@ module SwarmSDK
         end
       end
 
+      # Resolve the delegate chat instance
+      #
+      # If the delegate is a LazyDelegateChat, initializes it on first access.
+      # Otherwise, returns the chat directly.
+      #
+      # @return [Agent::Chat] The resolved chat instance
+      def resolve_delegate_chat
+        if @delegate_chat.is_a?(Swarm::LazyDelegateChat)
+          @delegate_chat.chat
+        else
+          @delegate_chat
+        end
+      end
+
       # Delegate to a registered swarm
       #
       # @param message [String] Message to send to the swarm

data/lib/swarm_sdk/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.7.9
+  version: 2.7.10
 platform: ruby
 authors:
 - Paulo Arruda
@@ -200,6 +200,7 @@ files:
 - lib/swarm_sdk/swarm/builder.rb
 - lib/swarm_sdk/swarm/executor.rb
 - lib/swarm_sdk/swarm/hook_triggers.rb
+- lib/swarm_sdk/swarm/lazy_delegate_chat.rb
 - lib/swarm_sdk/swarm/logging_callbacks.rb
 - lib/swarm_sdk/swarm/mcp_configurator.rb
 - lib/swarm_sdk/swarm/swarm_registry_builder.rb