Class: SwarmSDK::AgentRegistry

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/agent_registry.rb

Overview

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.

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

Class Method Summary collapse

Class Method Details

.clear ⇒ void

This method returns an undefined value.

Clear all registrations

Primarily useful for testing to ensure clean state between tests.

Examples:

In test setup/teardown

def teardown
  SwarmSDK::AgentRegistry.clear
end



141
142
143
 
# File 'lib/swarm_sdk/agent_registry.rb', line 141

def clear
  @agents.clear
end

.get(name) ⇒ Proc?

Retrieve a registered agent block

Examples:

block = SwarmSDK::AgentRegistry.get(:backend)
builder.instance_eval(&block) if block

Parameters:

  • name (Symbol, String) —

    Agent name

Returns:

  • (Proc, nil) —

    The registration block or nil if not found



103
104
105
 
# File 'lib/swarm_sdk/agent_registry.rb', line 103

def get(name)
  @agents[name.to_sym]
end

.names ⇒ Array<Symbol>

List all registered agent names

Examples:

SwarmSDK::AgentRegistry.names
# => [:backend, :frontend, :database]

Returns:

  • (Array<Symbol>) —

    Names of all registered agents



127
128
129
 
# File 'lib/swarm_sdk/agent_registry.rb', line 127

def names
  @agents.keys
end

.register(name) { ... } ⇒ void

This method returns an undefined value.

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.

Examples:

Register a backend agent

SwarmSDK::AgentRegistry.register(:backend) do
  model "claude-sonnet-4"
  description "Backend developer"
  tools :Read, :Edit, :Bash
end

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

Parameters:

  • name (Symbol, String) —

    Agent name (will be symbolized)

Yields:

  • Agent configuration block using Agent::Builder DSL

Raises:

  • (ArgumentError) —

    If no block is provided

  • (ArgumentError) —

    If agent with same name is already registered



82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/swarm_sdk/agent_registry.rb', line 82

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

.registered?(name) ⇒ Boolean

Check if an agent is registered

Examples:

if SwarmSDK::AgentRegistry.registered?(:backend)
  puts "Backend agent is available"
end

Parameters:

  • name (Symbol, String) —

    Agent name

Returns:

  • (Boolean) —

    true if agent is registered



116
117
118
 
# File 'lib/swarm_sdk/agent_registry.rb', line 116

def registered?(name)
  @agents.key?(name.to_sym)
end