Class: SwarmSDK::V3::AgentBuilder

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

Overview

DSL builder for creating a single V3 Agent

Provides a clean, block-based interface for defining an agent without needing to construct AgentDefinition kwargs directly. Unlike the V2 builder which manages multi-agent swarms, this creates a single agent.

Examples:

Minimal agent

agent = SwarmSDK::V3.agent do
  name :assistant
  description "A helpful assistant"
end

Full agent with memory

agent = SwarmSDK::V3.agent do
  name :researcher
  description "Research specialist"
  model "claude-sonnet-4"
  provider "anthropic"
  system_prompt "You are an expert researcher."
  tools :Read, :Write, :Edit, :Bash, :Grep, :Glob
  directory "/path/to/project"

  memory do
    directory ".swarm/memory"
    stm_turns 8
    retrieval_top_k 15
  end
end

agent.ask("Hello!")

DSL Methods collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ AgentBuilder

Returns a new instance of AgentBuilder.



55
56
57
58
59
60
61
62
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 55

def initialize
  @config = {}
  @tools = []
  @skills = []
  @mcp_servers = []
  @hooks = []
  @memory_config = nil
end

Class Method Details

.build { ... } ⇒ Agent

Build an Agent from a DSL block

Examples:

agent = AgentBuilder.build do
  name :coder
  description "Code writer"
  tools :Read, :Edit
end

Yields:

  • DSL block evaluated via instance_eval

Returns:

  • (Agent) —

    Initialized agent ready for use



48
49
50
51
52
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 48

def build(&block)
  builder = new
  builder.instance_eval(&block)
  builder.to_agent
end

Instance Method Details

#after_ask {|ctx| ... } ⇒ void

This method returns an undefined value.

Register an after_ask hook

Fires after SwarmSDK::V3::Agent#execute_turn completes. Observation only —halt and replace have no effect.

Examples:

Log responses

after_ask { |ctx| log_response(ctx.response) }

Yields:



286
287
288
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 286

def after_ask(&block)
  @hooks << { event: :after_ask, block: block }
end

#after_tool(match: nil) {|ctx| ... } ⇒ void

This method returns an undefined value.

Register an after_tool hook

Fires after tool execution. Can replace the tool result. Supports match filtering.

Examples:

Sanitize Bash output

after_tool(match: /Bash/) { |ctx| ctx.replace(sanitize(ctx.tool_result)) }

Parameters:

  • match (Symbol, String, Regexp, Array, nil) (defaults to: nil) —

    Tool name matcher

Yields:



319
320
321
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 319

def after_tool(match: nil, &block)
  @hooks << { event: :after_tool, match: compile_matcher(match), block: block }
end

#api_version(value) ⇒ void

This method returns an undefined value.

Set API version for OpenAI provider

Controls which OpenAI API endpoint to use. Only applicable when provider is “openai”. Defaults to “v1/responses” for OpenAI agents.

Examples:

Use Chat Completions API

api_version "v1/chat/completions"

Use Responses API (default for OpenAI)

api_version "v1/responses"

Parameters:

  • value (String) —

    API version (“v1/responses” or “v1/chat/completions”)



240
241
242
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 240

def api_version(value)
  @config[:api_version] = value
end

#base_url(value) ⇒ void

This method returns an undefined value.

Set custom API endpoint

Examples:

base_url "https://api.example.com"

Parameters:

  • value (String) —

    Base URL



176
177
178
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 176

def base_url(value)
  @config[:base_url] = value
end

#before_ask {|ctx| ... } ⇒ void

This method returns an undefined value.

Register a before_ask hook

Fires before SwarmSDK::V3::Agent#execute_turn. Can halt (returns nil from ask) or replace the prompt.

Examples:

Log every prompt

before_ask { |ctx| puts "Processing: #{ctx.prompt}" }

Block certain prompts

before_ask { |ctx| ctx.halt("Blocked") if ctx.prompt.include?("secret") }

Yields:



272
273
274
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 272

def before_ask(&block)
  @hooks << { event: :before_ask, block: block }
end

#before_tool(match: nil) {|ctx| ... } ⇒ void

This method returns an undefined value.

Register a before_tool hook

Fires before tool execution. Can halt (returns error string to LLM without executing the tool). Supports match filtering.

Examples:

Block Bash tool

before_tool(match: :Bash) { |ctx| ctx.halt("Bash disabled") }

Validate Write/Edit arguments

before_tool(match: [:Write, :Edit]) { |ctx| validate(ctx.tool_arguments) }

Parameters:

  • match (Symbol, String, Regexp, Array, nil) (defaults to: nil) —

    Tool name matcher

Yields:



304
305
306
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 304

def before_tool(match: nil, &block)
  @hooks << { event: :before_tool, match: compile_matcher(match), block: block }
end

#description(value) ⇒ void

This method returns an undefined value.

Set agent description

Examples:

description "Research specialist"

Parameters:

  • value (String) —

    Agent role description



84
85
86
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 84

def description(value)
  @config[:description] = value
end

#directory(value) ⇒ void

This method returns an undefined value.

Set working directory

Examples:

directory "/path/to/project"

Parameters:

  • value (String) —

    Directory path



165
166
167
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 165

def directory(value)
  @config[:directory] = value
end

#headers(value) ⇒ void

This method returns an undefined value.

Set raw HTTP headers

Examples:

headers("anthropic-beta" => "some-feature")

Parameters:

  • value (Hash) —

    Headers hash



209
210
211
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 209

def headers(value)
  @config[:headers] = value
end

#max_concurrent_tools(value) ⇒ void

This method returns an undefined value.

Set maximum concurrent tool executions

Examples:

max_concurrent_tools 5

Parameters:

  • value (Integer) —

    Max concurrent tools



187
188
189
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 187

def max_concurrent_tools(value)
  @config[:max_concurrent_tools] = value
end

#mcp_server(name, **options) ⇒ void

This method returns an undefined value.

Add an MCP server connection

Can be called multiple times; servers accumulate across calls. Each server provides tools that the agent can invoke via MCP protocol.

Examples:

HTTP server

mcp_server :api,
  type: :http,
  url: "https://example.com/mcp",
  headers: { "Authorization" => "Bearer token" }

Stdio server with tool filtering

mcp_server :filesystem,
  type: :stdio,
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
  tools: [:read_file, :list_directory]

Parameters:

  • name (Symbol, String) —

    Server identifier

  • options (Hash) —

    Server configuration options

Options Hash (**options):

  • :type (Symbol) —

    Transport type (:stdio or :http)

  • :command (String) —

    Subprocess command (stdio)

  • :args (Array<String>) —

    Subprocess arguments (stdio)

  • :env (Hash) —

    Subprocess environment (stdio)

  • :url (String) —

    HTTP endpoint URL (http)

  • :headers (Hash) —

    HTTP headers (http)

  • :tools (Array<Symbol>) —

    Tool names to expose (nil = all)



366
367
368
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 366

def mcp_server(name, **options)
  @mcp_servers << options.merge(name: name)
end

#memory { ... } ⇒ void

This method returns an undefined value.

Configure memory via a sub-block

Examples:

memory do
  directory ".swarm/memory"
  stm_turns 8
  retrieval_top_k 15
end

Yields:

  • DSL block evaluated on a MemoryBuilder



255
256
257
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 255

def memory(&block)
  @memory_config = MemoryBuilder.build(&block)
end

#model(value) ⇒ void

This method returns an undefined value.

Set LLM model

Examples:

model "claude-sonnet-4"

Parameters:

  • value (String) —

    Model identifier



95
96
97
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 95

def model(value)
  @config[:model] = value
end

#name(value) ⇒ void

This method returns an undefined value.

Set agent name

Examples:

name :researcher

Parameters:

  • value (Symbol, String) —

    Agent identifier



73
74
75
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 73

def name(value)
  @config[:name] = value
end

#on_stop {|ctx| ... } ⇒ void

This method returns an undefined value.

Register an on_stop hook

Fires after ask() completes successfully. Observation only —the response has already been produced. Useful for logging, metrics, or cleanup.

Examples:

Track completions

on_stop { |ctx| metrics.increment("agent.#{ctx.agent_name}.completed") }

Yields:



334
335
336
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 334

def on_stop(&block)
  @hooks << { event: :on_stop, block: block }
end

#output_schema(value) ⇒ void

This method returns an undefined value.

Set output schema for structured output

The schema is passed through to RubyLLM’s Chat#with_schema. Can be a Hash (raw JSON Schema) or any object responding to #to_json_schema.

Examples:

Raw JSON Schema

output_schema({ type: "object", properties: { name: { type: "string" } } })

Parameters:

  • value (Hash, Object) —

    Schema definition



223
224
225
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 223

def output_schema(value)
  @config[:output_schema] = value
end

#parameters(value) ⇒ void

This method returns an undefined value.

Set raw API body parameters

Examples:

parameters(temperature: 0.7, thinking: { type: "enabled", budget_tokens: 10_000 })

Parameters:

  • value (Hash) —

    Parameters hash



198
199
200
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 198

def parameters(value)
  @config[:parameters] = value
end

#provider(value) ⇒ void

This method returns an undefined value.

Set LLM provider

Examples:

provider "anthropic"

Parameters:

  • value (String) —

    Provider name



106
107
108
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 106

def provider(value)
  @config[:provider] = value
end

#skills(*paths) ⇒ void

This method returns an undefined value.

Add skill directories to the agent

Can be called multiple times; paths accumulate across calls. Each path should be a directory containing a SKILL.md file, or a parent directory whose children contain SKILL.md files.

Examples:

Single call

skills "/path/to/skills"

Multiple calls accumulate

skills "/skills/pdf"
skills "/skills/csv"

Parameters:

  • paths (Array<String>) —

    Skill directory paths



154
155
156
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 154

def skills(*paths)
  @skills.concat(paths.flatten)
end

#system_prompt(value) ⇒ void

This method returns an undefined value.

Set system prompt instructions

Examples:

system_prompt "You are an expert researcher."

Parameters:

  • value (String) —

    System prompt text



117
118
119
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 117

def system_prompt(value)
  @config[:system_prompt] = value
end

#to_agent ⇒ Agent

Build the Agent from collected configuration

Returns:

  • (Agent) —

    Initialized agent

Raises:



376
377
378
379
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 376

def to_agent
  definition = AgentDefinition.new(**definition_kwargs)
  Agent.new(definition)
end

#tools(*names) ⇒ void

This method returns an undefined value.

Add tools to the agent

Can be called multiple times; tools accumulate across calls.

Examples:

Single call

tools :Read, :Write, :Edit

Multiple calls accumulate

tools :Read, :Write
tools :Bash, :Grep
# => [:Read, :Write, :Bash, :Grep]

Parameters:

  • names (Array<Symbol, String>) —

    Tool names



135
136
137
 
# File 'lib/swarm_sdk/v3/agent_builder.rb', line 135

def tools(*names)
  @tools.concat(names.flatten)
end