swarm_sdk 2.4.2 → 2.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e0a32d6cd3def4eb9f0df716e7f10076023f8c1efd5442bdd5f6501af95d542
-  data.tar.gz: e243a4b009844dcf19c7e425ff632a9cf19fe8d7d0e9325107c8ef50efb35f8f
+  metadata.gz: 2357a0a9317288666f8e26f001e2d3b42402870d0e7e03560b6ff14109b36f56
+  data.tar.gz: 0c11addc8f0578cfd796cda4795dfb51f2f4b134280eab2601e600b0b90670c8
 SHA512:
-  metadata.gz: e8493eac228cb132c969476d884c2e2ae3d7008bbceef134c411549545e8c879e6a4aaa75c9c04835555b28193740633163142c2696ba42f6a85d8ea26ed79b3
-  data.tar.gz: 104440a7754b2fa74bc74eade37cf6ea76cbef2b334d0f5eb0f54bb0f1a38091d3c403294baccbf5a74a44c10468dd5fff89f89abe6c7b5cbba06c36b365e6d0
+  metadata.gz: '029817745549dfcd04234c2b4e9f809e139fc222cf717f366d09c5cca6d7b7e2ae50a6f2c52058380a2a1e860e86526618ca06de464589f1d10eb21bebe1bb04'
+  data.tar.gz: 2455fab120ec48edeb80adfa0bfa5ede016f09a49eb4ab2dc2e48490432d4b282255999f5540cb494267d4fe46c8d2f72e94ea7fcc37059db58f533ebd0bd834

data/lib/swarm_sdk/agent_registry.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Global registry for reusable agent definitions
+  #
+  # AgentRegistry allows declaring agents in separate files that can be
+  # referenced by name in swarm definitions. This promotes code reuse and
+  # separation of concerns - agent definitions can live in dedicated files
+  # while swarm configurations compose them together.
+  #
+  # ## Usage
+  #
+  # Register agents globally (typically in separate files):
+  #
+  #   # agents/backend.rb
+  #   SwarmSDK.agent :backend do
+  #     model "claude-sonnet-4"
+  #     description "Backend API developer"
+  #     system_prompt "You build REST APIs"
+  #     tools :Read, :Edit, :Bash
+  #   end
+  #
+  # Reference registered agents in swarm definitions:
+  #
+  #   # swarm.rb
+  #   SwarmSDK.build do
+  #     name "Dev Team"
+  #     lead :backend
+  #
+  #     agent :backend  # Pulls from registry
+  #   end
+  #
+  # ## Override Support
+  #
+  # Registered agents can be extended with additional configuration:
+  #
+  #   SwarmSDK.build do
+  #     name "Dev Team"
+  #     lead :backend
+  #
+  #     agent :backend do
+  #       # Registry config is applied first, then this block
+  #       tools :CustomTool  # Adds to tools from registry
+  #       delegates_to :database
+  #     end
+  #   end
+  #
+  # @note This registry is not thread-safe. In multi-threaded environments,
+  #   register all agents before spawning threads, or synchronize access
+  #   externally. For typical fiber-based async usage (the default in SwarmSDK),
+  #   this is not a concern.
+  #
+  class AgentRegistry
+    @agents = {}
+
+    class << self
+      # Register an agent definition block
+      #
+      # Stores a configuration block that will be executed when the agent
+      # is referenced in a swarm definition. The block receives an
+      # Agent::Builder context and can use all builder DSL methods.
+      #
+      # @param name [Symbol, String] Agent name (will be symbolized)
+      # @yield Agent configuration block using Agent::Builder DSL
+      # @return [void]
+      # @raise [ArgumentError] If no block is provided
+      # @raise [ArgumentError] If agent with same name is already registered
+      #
+      # @example Register a backend agent
+      #   SwarmSDK::AgentRegistry.register(:backend) do
+      #     model "claude-sonnet-4"
+      #     description "Backend developer"
+      #     tools :Read, :Edit, :Bash
+      #   end
+      #
+      # @example Register with MCP servers
+      #   SwarmSDK::AgentRegistry.register(:filesystem_agent) do
+      #     model "gpt-4"
+      #     description "File manager"
+      #     mcp_server :fs, type: :stdio, command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem"]
+      #   end
+      def register(name, &block)
+        raise ArgumentError, "Block required for agent registration" unless block_given?
+
+        sym_name = name.to_sym
+        if @agents.key?(sym_name)
+          raise ArgumentError,
+            "Agent '#{sym_name}' is already registered. " \
+              "Use SwarmSDK.clear_agent_registry! to reset, or choose a different name."
+        end
+
+        @agents[sym_name] = block
+      end
+
+      # Retrieve a registered agent block
+      #
+      # @param name [Symbol, String] Agent name
+      # @return [Proc, nil] The registration block or nil if not found
+      #
+      # @example
+      #   block = SwarmSDK::AgentRegistry.get(:backend)
+      #   builder.instance_eval(&block) if block
+      def get(name)
+        @agents[name.to_sym]
+      end
+
+      # Check if an agent is registered
+      #
+      # @param name [Symbol, String] Agent name
+      # @return [Boolean] true if agent is registered
+      #
+      # @example
+      #   if SwarmSDK::AgentRegistry.registered?(:backend)
+      #     puts "Backend agent is available"
+      #   end
+      def registered?(name)
+        @agents.key?(name.to_sym)
+      end
+
+      # List all registered agent names
+      #
+      # @return [Array<Symbol>] Names of all registered agents
+      #
+      # @example
+      #   SwarmSDK::AgentRegistry.names
+      #   # => [:backend, :frontend, :database]
+      def names
+        @agents.keys
+      end
+
+      # Clear all registrations
+      #
+      # Primarily useful for testing to ensure clean state between tests.
+      #
+      # @return [void]
+      #
+      # @example In test setup/teardown
+      #   def teardown
+      #     SwarmSDK::AgentRegistry.clear
+      #   end
+      def clear
+        @agents.clear
+      end
+    end
+  end
+end

data/lib/swarm_sdk/builders/base_builder.rb

@@ -64,11 +64,14 @@ module SwarmSDK
         @swarm_registry_config = builder.registrations
       end
 
-      # Define an agent with fluent API or load from markdown content
+      # Define an agent with fluent API, load from markdown, or reference registry
       #
-      # Supports two forms:
-      # 1. Inline DSL: agent :name do ... end
-      # 2. Markdown content: agent :name, <<~MD ... MD
+      # Supports multiple forms:
+      # 1. Registry lookup: agent :name (pulls from global registry)
+      # 2. Registry + overrides: agent :name do ... end (when registered)
+      # 3. Inline DSL: agent :name do ... end (when not registered)
+      # 4. Markdown content: agent :name, <<~MD ... MD
+      # 5. Markdown + overrides: agent :name, <<~MD do ... end
       #
       # @example Inline DSL
       #   agent :backend do
@@ -77,6 +80,15 @@ module SwarmSDK
       #     tools :Read, :Write
       #   end
       #
+      # @example Registry lookup (agent must be registered with SwarmSDK.agent)
+      #   agent :backend  # Pulls configuration from registry
+      #
+      # @example Registry + overrides
+      #   agent :backend do
+      #     # Base config from registry, then apply overrides
+      #     tools :CustomTool  # Adds to registry-defined tools
+      #   end
+      #
       # @example Markdown content
       #   agent :backend, <<~MD
       #     ---
@@ -87,19 +99,38 @@ module SwarmSDK
       #     You build APIs.
       #   MD
       def agent(name, content = nil, &block)
+        name = name.to_sym
+
         # Case 1: agent :name, <<~MD do ... end (markdown + overrides)
         if content.is_a?(String) && block_given? && markdown_content?(content)
           load_agent_from_markdown_with_overrides(content, name, &block)
+
         # Case 2: agent :name, <<~MD (markdown only)
         elsif content.is_a?(String) && !block_given? && markdown_content?(content)
           load_agent_from_markdown(content, name)
-        # Case 3: agent :name do ... end (inline DSL)
+
+        # Case 3: agent :name (registry lookup only - no content, no block)
+        elsif content.nil? && !block_given?
+          load_agent_from_registry(name)
+
+        # Case 4: agent :name do ... end (with registered agent - registry + overrides)
+        elsif content.nil? && block_given? && AgentRegistry.registered?(name)
+          load_agent_from_registry_with_overrides(name, &block)
+
+        # Case 5: agent :name do ... end (inline DSL - not registered)
         elsif block_given?
           builder = Agent::Builder.new(name)
           builder.instance_eval(&block)
           @agents[name] = builder
+
         else
-          raise ArgumentError, "Invalid agent definition. Use: agent :name { ... } OR agent :name, <<~MD ... MD OR agent :name, <<~MD do ... end"
+          raise ArgumentError,
+            "Invalid agent definition for '#{name}'. Use:\n  " \
+              "agent :#{name} { ... }           # Inline DSL\n  " \
+              "agent :#{name}                   # Registry lookup\n  " \
+              "agent :#{name} { ... }           # Registry + overrides (if registered)\n  " \
+              "agent :#{name}, <<~MD ... MD     # Markdown\n  " \
+              "agent :#{name}, <<~MD do ... end # Markdown + overrides"
         end
       end
 
@@ -138,6 +169,54 @@ module SwarmSDK
         str.start_with?("---") || str.include?("\n---\n")
       end
 
+      # Load an agent from the global registry
+      #
+      # Retrieves the registered agent block and executes it in the context
+      # of a new Agent::Builder.
+      #
+      # @param name [Symbol] Agent name
+      # @return [void]
+      # @raise [ConfigurationError] If agent is not registered
+      #
+      # @example
+      #   load_agent_from_registry(:backend)
+      def load_agent_from_registry(name)
+        registered_proc = AgentRegistry.get(name)
+        unless registered_proc
+          raise ConfigurationError,
+            "Agent '#{name}' not found in registry. " \
+              "Either define inline with `agent :#{name} do ... end` or " \
+              "register globally with `SwarmSDK.agent :#{name} do ... end`"
+        end
+
+        builder = Agent::Builder.new(name)
+        builder.instance_eval(&registered_proc)
+        @agents[name] = builder
+      end
+
+      # Load an agent from the registry with additional overrides
+      #
+      # Applies the registered configuration first, then executes the
+      # override block to customize the agent.
+      #
+      # @param name [Symbol] Agent name
+      # @yield Override block with additional configuration
+      # @return [void]
+      #
+      # @example
+      #   load_agent_from_registry_with_overrides(:backend) do
+      #     tools :CustomTool  # Adds to registry-defined tools
+      #   end
+      def load_agent_from_registry_with_overrides(name, &override_block)
+        registered_proc = AgentRegistry.get(name)
+        # Guaranteed to exist since we checked in the condition
+
+        builder = Agent::Builder.new(name)
+        builder.instance_eval(&registered_proc)  # Base config from registry
+        builder.instance_eval(&override_block)   # Apply overrides
+        @agents[name] = builder
+      end
+
       # Load an agent from markdown content
       #
       # Returns a hash of the agent config (not a Definition yet) so that

data/lib/swarm_sdk/config.rb

@@ -91,6 +91,7 @@ module SwarmSDK
       webfetch_base_url: ["SWARM_SDK_WEBFETCH_BASE_URL", nil],
       webfetch_max_tokens: ["SWARM_SDK_WEBFETCH_MAX_TOKENS", 4096],
       allow_filesystem_tools: ["SWARM_SDK_ALLOW_FILESYSTEM_TOOLS", true],
+      env_interpolation: ["SWARM_SDK_ENV_INTERPOLATION", true],
     }.freeze
 
     class << self
@@ -279,7 +280,7 @@ module SwarmSDK
     # @return [Integer, Float, Boolean, String] The parsed value
     def parse_env_value(value, key)
       case key
-      when :allow_filesystem_tools
+      when :allow_filesystem_tools, :env_interpolation
         # Convert string to boolean
         case value.to_s.downcase
         when "true", "yes", "1", "on", "enabled"

data/lib/swarm_sdk/configuration/parser.rb

@@ -30,9 +30,18 @@ module SwarmSDK
         :nodes,
         :external_swarms
 
-      def initialize(yaml_content, base_dir:)
+      # Initialize parser with YAML content and options
+      #
+      # @param yaml_content [String] YAML configuration content
+      # @param base_dir [String, Pathname] Base directory for resolving paths
+      # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+      #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+      #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+      #   When false, skips interpolation entirely.
+      def initialize(yaml_content, base_dir:, env_interpolation: nil)
         @yaml_content = yaml_content
         @base_dir = Pathname.new(base_dir).expand_path
+        @env_interpolation = env_interpolation
         @config_type = nil
         @swarm_id = nil
         @swarm_name = nil
@@ -55,7 +64,7 @@ module SwarmSDK
         end
 
         @config = Utils.symbolize_keys(@config)
-        interpolate_env_vars!(@config)
+        interpolate_env_vars!(@config) if env_interpolation_enabled?
 
         validate_version
         detect_and_validate_type
@@ -86,6 +95,17 @@ module SwarmSDK
 
       private
 
+      # Check if environment variable interpolation is enabled
+      #
+      # Uses the local setting if explicitly set, otherwise falls back to global config.
+      #
+      # @return [Boolean] true if interpolation should be performed
+      def env_interpolation_enabled?
+        return @env_interpolation unless @env_interpolation.nil?
+
+        SwarmSDK.config.env_interpolation
+      end
+
       def validate_version
         version = @config[:version]
         raise ConfigurationError, "Missing 'version' field in configuration" unless version

data/lib/swarm_sdk/configuration.rb

@@ -38,9 +38,13 @@ module SwarmSDK
       # Load configuration from YAML file
       #
       # @param path [String, Pathname] Path to YAML configuration file
+      # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+      #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+      #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+      #   When false, skips interpolation entirely.
       # @return [Configuration] Validated configuration instance
       # @raise [ConfigurationError] If file not found or invalid
-      def load_file(path)
+      def load_file(path, env_interpolation: nil)
         path = Pathname.new(path).expand_path
 
         unless path.exist?
@@ -50,7 +54,7 @@ module SwarmSDK
         yaml_content = File.read(path)
         base_dir = path.dirname
 
-        new(yaml_content, base_dir: base_dir).tap(&:load_and_validate)
+        new(yaml_content, base_dir: base_dir, env_interpolation: env_interpolation).tap(&:load_and_validate)
       rescue Errno::ENOENT
         raise ConfigurationError, "Configuration file not found: #{path}"
       end
@@ -60,12 +64,17 @@ module SwarmSDK
     #
     # @param yaml_content [String] YAML configuration content
     # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
-    def initialize(yaml_content, base_dir: Dir.pwd)
+    # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+    #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+    #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+    #   When false, skips interpolation entirely.
+    def initialize(yaml_content, base_dir: Dir.pwd, env_interpolation: nil)
       raise ArgumentError, "yaml_content cannot be nil" if yaml_content.nil?
       raise ArgumentError, "base_dir cannot be nil" if base_dir.nil?
 
       @yaml_content = yaml_content
       @base_dir = Pathname.new(base_dir).expand_path
+      @env_interpolation = env_interpolation
       @parser = nil
       @translator = nil
     end
@@ -77,7 +86,7 @@ module SwarmSDK
     #
     # @return [self]
     def load_and_validate
-      @parser = Parser.new(@yaml_content, base_dir: @base_dir)
+      @parser = Parser.new(@yaml_content, base_dir: @base_dir, env_interpolation: @env_interpolation)
       @parser.parse
 
       # Sync parsed data to instance variables for backward compatibility

data/lib/swarm_sdk/version.rb

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

data/lib/swarm_sdk/workflow/builder.rb

@@ -119,6 +119,9 @@ module SwarmSDK
       #
       # @return [Workflow] Configured workflow instance
       def build_workflow
+        # Resolve any missing agents from global registry before building definitions
+        resolve_missing_agents_from_registry
+
         # Build agent definitions
         agent_definitions = build_agent_definitions
 
@@ -138,6 +141,52 @@ module SwarmSDK
 
         workflow
       end
+
+      # Resolve agents referenced in nodes that aren't defined at workflow level
+      #
+      # For each agent referenced in a node but not defined with `agent :name do ... end`,
+      # checks the global AgentRegistry and loads the agent if found.
+      #
+      # This allows workflows to reference globally registered agents without
+      # explicitly re-declaring them at the workflow level.
+      #
+      # @return [void]
+      # @raise [ConfigurationError] If agent not found in workflow or registry
+      def resolve_missing_agents_from_registry
+        # Collect all agents referenced in nodes
+        referenced_agents = collect_referenced_agents
+
+        # Find agents that aren't defined at workflow level
+        defined_agents = @agents.keys
+        missing_agents = referenced_agents - defined_agents
+
+        # Try to resolve each missing agent from the global registry
+        missing_agents.each do |agent_name|
+          if AgentRegistry.registered?(agent_name)
+            # Load from registry (uses same method as BaseBuilder)
+            load_agent_from_registry(agent_name)
+          else
+            raise ConfigurationError,
+              "Agent '#{agent_name}' referenced in node but not found. " \
+                "Either define at workflow level with `agent :#{agent_name} do ... end` " \
+                "or register globally with `SwarmSDK.agent :#{agent_name} do ... end`"
+          end
+        end
+      end
+
+      # Collect all agent names referenced across all nodes
+      #
+      # Includes both directly referenced agents and delegation targets.
+      #
+      # @return [Array<Symbol>] Unique agent names referenced in nodes
+      def collect_referenced_agents
+        @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])
+          end
+        end.uniq
+      end
     end
   end
 end

data/lib/swarm_sdk.rb

@@ -95,6 +95,73 @@ module SwarmSDK
       Config.reset!
     end
 
+    # Register a global agent definition
+    #
+    # Declares an agent configuration that can be referenced by name in any
+    # swarm definition. This allows defining agents in separate files and
+    # composing them into swarms without duplication.
+    #
+    # The registered block uses the Agent::Builder DSL and is executed when
+    # the agent is referenced in a swarm definition.
+    #
+    # @param name [Symbol, String] Agent name (will be symbolized)
+    # @yield Agent configuration block using Agent::Builder DSL
+    # @return [void]
+    # @raise [ArgumentError] If no block is provided
+    #
+    # @example Register agent in separate file
+    #   # agents/backend.rb
+    #   SwarmSDK.agent :backend do
+    #     model "claude-sonnet-4"
+    #     description "Backend API developer"
+    #     system_prompt "You build REST APIs"
+    #     tools :Read, :Edit, :Bash
+    #     delegates_to :database
+    #   end
+    #
+    # @example Reference in swarm definition
+    #   # swarm.rb
+    #   require_relative "agents/backend"
+    #
+    #   SwarmSDK.build do
+    #     name "Dev Team"
+    #     lead :backend
+    #
+    #     agent :backend  # Pulls from registry
+    #   end
+    #
+    # @example Extend registered agent with overrides
+    #   SwarmSDK.build do
+    #     name "Extended Team"
+    #     lead :backend
+    #
+    #     agent :backend do
+    #       # Registry config applied first, then this block
+    #       tools :CustomTool    # Adds to existing tools
+    #       delegates_to :cache  # Adds delegation target
+    #     end
+    #   end
+    #
+    # @see AgentRegistry
+    def agent(name, &block)
+      AgentRegistry.register(name, &block)
+    end
+
+    # Clear the global agent registry
+    #
+    # Removes all registered agent definitions. Primarily useful for testing
+    # to ensure clean state between tests.
+    #
+    # @return [void]
+    #
+    # @example In test teardown
+    #   def teardown
+    #     SwarmSDK.clear_agent_registry!
+    #   end
+    def clear_agent_registry!
+      AgentRegistry.clear
+    end
+
     # Main entry point for DSL - builds simple multi-agent swarms
     #
     # @return [Swarm] Always returns a Swarm instance
@@ -208,6 +275,11 @@ module SwarmSDK
     #
     # @param yaml_content [String] YAML configuration content
     # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
+    # @param allow_filesystem_tools [Boolean, nil] Whether to allow filesystem tools (nil uses global setting)
+    # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+    #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+    #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+    #   When false, skips interpolation entirely.
     # @return [Swarm, Workflow] Configured swarm or workflow instance
     # @raise [ConfigurationError] If YAML is invalid or configuration is incorrect
     #
@@ -230,8 +302,11 @@ module SwarmSDK
     # @example Load with default base_dir (Dir.pwd)
     #   yaml = File.read("config.yml")
     #   swarm = SwarmSDK.load(yaml)  # base_dir defaults to Dir.pwd
-    def load(yaml_content, base_dir: Dir.pwd, allow_filesystem_tools: nil)
-      config = Configuration.new(yaml_content, base_dir: base_dir)
+    #
+    # @example Load without environment variable interpolation
+    #   swarm = SwarmSDK.load(yaml, env_interpolation: false)
+    def load(yaml_content, base_dir: Dir.pwd, allow_filesystem_tools: nil, env_interpolation: nil)
+      config = Configuration.new(yaml_content, base_dir: base_dir, env_interpolation: env_interpolation)
       config.load_and_validate
       swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
 
@@ -253,6 +328,11 @@ module SwarmSDK
     # loading swarms from configuration files.
     #
     # @param path [String, Pathname] Path to YAML configuration file
+    # @param allow_filesystem_tools [Boolean, nil] Whether to allow filesystem tools (nil uses global setting)
+    # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+    #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+    #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+    #   When false, skips interpolation entirely.
     # @return [Swarm, Workflow] Configured swarm or workflow instance
     # @raise [ConfigurationError] If file not found or configuration invalid
     #
@@ -262,8 +342,11 @@ module SwarmSDK
     #
     # @example With absolute path
     #   swarm = SwarmSDK.load_file("/absolute/path/config.yml")
-    def load_file(path, allow_filesystem_tools: nil)
-      config = Configuration.load_file(path)
+    #
+    # @example Load without environment variable interpolation
+    #   swarm = SwarmSDK.load_file("config.yml", env_interpolation: false)
+    def load_file(path, allow_filesystem_tools: nil, env_interpolation: nil)
+      config = Configuration.load_file(path, env_interpolation: env_interpolation)
       swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
 
       # Apply hooks if any are configured (YAML-only feature)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.4.2
+  version: 2.4.4
 platform: ruby
 authors:
 - Paulo Arruda
@@ -139,6 +139,7 @@ files:
 - lib/swarm_sdk/agent/definition.rb
 - lib/swarm_sdk/agent/llm_instrumentation_middleware.rb
 - lib/swarm_sdk/agent/system_prompt_builder.rb
+- lib/swarm_sdk/agent_registry.rb
 - lib/swarm_sdk/builders/base_builder.rb
 - lib/swarm_sdk/claude_code_agent_adapter.rb
 - lib/swarm_sdk/concerns/cleanupable.rb