Class: SwarmSDK::Agent::Builder

Inherits:
Object
  • Object
show all
Includes:
SwarmMemory::DSL::BuilderExtension
Defined in:
lib/swarm_sdk/agent/builder.rb

Overview

Builder provides fluent API for configuring agents

This class offers a Ruby DSL for defining agents with a clean, readable syntax. It collects configuration and then adds the agent to the swarm.

Examples:

agent :backend do
  model "gpt-5"
  prompt "You build APIs"
  tools :Read, :Write, :Bash

  hook :pre_tool_use, matcher: "Bash" do |ctx|
    SwarmSDK::Hooks::Result.halt("Blocked!") if dangerous?(ctx)
  end
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from SwarmMemory::DSL::BuilderExtension

#memory

Constructor Details

#initialize(name) ⇒ Builder

Returns a new instance of Builder.



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/swarm_sdk/agent/builder.rb', line 34

def initialize(name)
  @name = name
  @description = nil
  @model = "gpt-5"
  @provider = nil
  @base_url = nil
  @api_version = nil
  @context_window = nil
  @system_prompt = nil
  # Use Set for tools to automatically handle duplicates when tools() is called multiple times.
  # This ensures that if someone does: tools :Read; tools :Write; tools :Read
  # the final set contains only [:Read, :Write] without duplicates.
  # We convert to Array in to_definition for compatibility with Agent::Definition.
  @tools = Set.new
  @delegates_to = []
  @directory = "."
  @parameters = {}
  @headers = {}
  @timeout = nil
  @mcp_servers = []
  @disable_default_tools = nil # nil = include all default tools
  @bypass_permissions = false
  @coding_agent = nil # nil = not set (will default to false in Definition)
  @assume_model_exists = nil
  @hooks = []
  @permissions_config = {}
  @default_permissions = {} # Set by SwarmBuilder from all_agents
  @memory_config = nil
  @shared_across_delegations = nil # nil = not set (will default to false in Definition)
  @context_management_config = nil # Context management DSL hooks
end

Instance Attribute Details

#default_permissions=(value) ⇒ Object (writeonly)

Expose default_permissions for Swarm::Builder to set from all_agents



22
23
24
 
# File 'lib/swarm_sdk/agent/builder.rb', line 22

def default_permissions=(value)
  @default_permissions = value
end

#mcp_servers ⇒ Object (readonly)

Expose mcp_servers for tests



25
26
27
 
# File 'lib/swarm_sdk/agent/builder.rb', line 25

def mcp_servers
  @mcp_servers
end

Instance Method Details

#api_version(version = :__not_provided__) ⇒ Object

Set/get API version (OpenAI-compatible providers only)



88
89
90
91
92
 
# File 'lib/swarm_sdk/agent/builder.rb', line 88

def api_version(version = :__not_provided__)
  return @api_version if version == :__not_provided__

  @api_version = version
end

#api_version_set? ⇒ Boolean

Check if api_version has been explicitly set

Used by Swarm::Builder to determine if all_agents api_version should apply.

Returns:

  • true if api_version was explicitly set



385
386
387
 
# File 'lib/swarm_sdk/agent/builder.rb', line 385

def api_version_set?
  !@api_version.nil?
end

#assume_model_exists(enabled) ⇒ Object

Set assume_model_exists flag



185
186
187
 
# File 'lib/swarm_sdk/agent/builder.rb', line 185

def assume_model_exists(enabled)
  @assume_model_exists = enabled
end

#base_url(url = :__not_provided__) ⇒ Object

Set/get base URL



81
82
83
84
85
 
# File 'lib/swarm_sdk/agent/builder.rb', line 81

def base_url(url = :__not_provided__)
  return @base_url if url == :__not_provided__

  @base_url = url
end

#base_url_set? ⇒ Boolean

Check if base_url has been explicitly set

Used by Swarm::Builder to determine if all_agents base_url should apply.

Returns:

  • true if base_url was explicitly set



376
377
378
 
# File 'lib/swarm_sdk/agent/builder.rb', line 376

def base_url_set?
  !@base_url.nil?
end

#bypass_permissions(enabled) ⇒ Object

Set bypass_permissions flag



166
167
168
 
# File 'lib/swarm_sdk/agent/builder.rb', line 166

def bypass_permissions(enabled)
  @bypass_permissions = enabled
end

#coding_agent(enabled) ⇒ void

This method returns an undefined value.

Set coding_agent flag

When true, includes the base system prompt for coding tasks. When false (default), uses only the custom system prompt.

Examples:

coding_agent true  # Include base prompt for coding tasks

Parameters:

  • Whether to include base coding prompt



180
181
182
 
# File 'lib/swarm_sdk/agent/builder.rb', line 180

def coding_agent(enabled)
  @coding_agent = enabled
end

#coding_agent_set? ⇒ Boolean

Check if coding_agent has been explicitly set

Used by Swarm::Builder to determine if all_agents coding_agent should apply.

Returns:

  • true if coding_agent was explicitly set



403
404
405
 
# File 'lib/swarm_sdk/agent/builder.rb', line 403

def coding_agent_set?
  !@coding_agent.nil?
end

#context_management { ... } ⇒ void

This method returns an undefined value.

Configure context management handlers

Define custom handlers for context warning thresholds (60%, 80%, 90%). Handlers receive a rich context object with message manipulation methods. When a custom handler is registered, automatic compression is disabled for that threshold, giving full control to the handler.

Examples:

Basic compression at 60%

context_management do
  on :warning_60 do |ctx|
    ctx.compress_tool_results(keep_recent: 10)
  end
end

Multiple thresholds with different strategies

context_management do
  on :warning_60 do |ctx|
    ctx.compress_tool_results(keep_recent: 15, truncate_to: 500)
  end

  on :warning_80 do |ctx|
    ctx.prune_old_messages(keep_recent: 30)
    ctx.compress_tool_results(keep_recent: 5, truncate_to: 200)
  end

  on :warning_90 do |ctx|
    ctx.log_action("emergency_pruning", remaining: ctx.tokens_remaining)
    ctx.prune_old_messages(keep_recent: 15)
  end
end

Conditional logic based on metrics

context_management do
  on :warning_80 do |ctx|
    if ctx.usage_percentage > 85
      ctx.prune_old_messages(keep_recent: 10)
    else
      ctx.compress_tool_results(keep_recent: 5)
    end
  end
end

Yields:

  • Context management DSL block



336
337
338
339
340
 
# File 'lib/swarm_sdk/agent/builder.rb', line 336

def context_management(&block)
  builder = ContextManagement::Builder.new
  builder.instance_eval(&block)
  @context_management_config = builder.build
end

#context_window(tokens = :__not_provided__) ⇒ Object

Set/get explicit context window override



95
96
97
98
99
 
# File 'lib/swarm_sdk/agent/builder.rb', line 95

def context_window(tokens = :__not_provided__)
  return @context_window if tokens == :__not_provided__

  @context_window = tokens
end

#delegates_to(*agent_names) ⇒ Object

Set delegation targets



245
246
247
 
# File 'lib/swarm_sdk/agent/builder.rb', line 245

def delegates_to(*agent_names)
  @delegates_to.concat(agent_names)
end

#description(text) ⇒ Object

Set description



195
196
197
 
# File 'lib/swarm_sdk/agent/builder.rb', line 195

def description(text)
  @description = text
end

#directory(dir) ⇒ Object

Set directory



240
241
242
 
# File 'lib/swarm_sdk/agent/builder.rb', line 240

def directory(dir)
  @directory = dir
end

#disable_default_tools(*tools) ⇒ Object

Disable default tools

Examples:

Disable all default tools

disable_default_tools true

Disable specific tools (array)

disable_default_tools [:Think, :TodoWrite]

Disable specific tools (separate arguments)

disable_default_tools :Think, :TodoWrite

Parameters:

    • true: Disable ALL default tools
    • Array of symbols: Disable specific tools (e.g., [:Think, :TodoWrite])


151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/swarm_sdk/agent/builder.rb', line 151

def disable_default_tools(*tools)
  # Handle different argument forms
  @disable_default_tools = case tools.size
  when 0
    nil
  when 1
    # Single argument: could be true/false/array
    tools.first
  else
    # Multiple arguments: treat as array of tool names
    tools.map(&:to_sym)
  end
end

#headers(header_hash = :__not_provided__) ⇒ Object

Set/get custom HTTP headers



109
110
111
112
113
 
# File 'lib/swarm_sdk/agent/builder.rb', line 109

def headers(header_hash = :__not_provided__)
  return @headers if header_hash == :__not_provided__

  @headers = header_hash
end

#headers_set? ⇒ Boolean

Check if headers have been set

Used by Swarm::Builder for merging all_agents headers.

Returns:

  • true if headers were set



421
422
423
 
# File 'lib/swarm_sdk/agent/builder.rb', line 421

def headers_set?
  @headers.any?
end

#hook(event, matcher: nil, command: nil, timeout: nil, &block) ⇒ Object

Add a hook (Ruby block OR shell command)

Examples:

Ruby block

hook :pre_tool_use, matcher: "Bash" do |ctx|
  HookResult.halt("Blocked") if dangerous?(ctx)
end

Shell command

hook :pre_tool_use, matcher: "Bash", command: "validate.sh"


258
259
260
261
262
263
264
265
266
 
# File 'lib/swarm_sdk/agent/builder.rb', line 258

def hook(event, matcher: nil, command: nil, timeout: nil, &block)
  @hooks << {
    event: event,
    matcher: matcher,
    command: command,
    timeout: timeout,
    block: block,
  }
end

#mcp_server(name, **options) ⇒ Object

Add an MCP server configuration

Examples:

stdio transport

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

SSE transport

mcp_server :web, type: :sse, url: "https://example.com/mcp", headers: { authorization: "Bearer token" }

HTTP/streamable transport

mcp_server :api, type: :http, url: "https://api.example.com/mcp", timeout: 60


132
133
134
135
 
# File 'lib/swarm_sdk/agent/builder.rb', line 132

def mcp_server(name, **options)
  server_config = { name: name }.merge(options)
  @mcp_servers << server_config
end

#model(model_name = :__not_provided__) ⇒ Object

Set/get agent model



67
68
69
70
71
 
# File 'lib/swarm_sdk/agent/builder.rb', line 67

def model(model_name = :__not_provided__)
  return @model if model_name == :__not_provided__

  @model = model_name
end

#model_set? ⇒ Boolean

Check if model has been explicitly set (not default)

Used by Swarm::Builder to determine if all_agents model should apply.

Returns:

  • true if model was explicitly set



358
359
360
 
# File 'lib/swarm_sdk/agent/builder.rb', line 358

def model_set?
  @model != "gpt-5"
end

#parameters(params = :__not_provided__) ⇒ Object

Set/get LLM parameters



102
103
104
105
106
 
# File 'lib/swarm_sdk/agent/builder.rb', line 102

def parameters(params = :__not_provided__)
  return @parameters if params == :__not_provided__

  @parameters = params
end

#parameters_set? ⇒ Boolean

Check if parameters have been set

Used by Swarm::Builder for merging all_agents parameters.

Returns:

  • true if parameters were set



412
413
414
 
# File 'lib/swarm_sdk/agent/builder.rb', line 412

def parameters_set?
  @parameters.any?
end

#permissions(&block) ⇒ Object

Configure permissions for this agent

Examples:

permissions do
  Write.allow_paths "backend/**/*"
  Write.deny_paths "backend/secrets/**"
end


275
276
277
 
# File 'lib/swarm_sdk/agent/builder.rb', line 275

def permissions(&block)
  @permissions_config = PermissionsBuilder.build(&block)
end

#permissions_hash=(hash) ⇒ void

This method returns an undefined value.

Set permissions directly from hash (for YAML translation)

This is intentionally separate from permissions() to keep the DSL clean. Called by Configuration when translating YAML permissions.

Parameters:

  • Permissions configuration hash



349
350
351
 
# File 'lib/swarm_sdk/agent/builder.rb', line 349

def permissions_hash=(hash)
  @permissions_config = hash || {}
end

#prepend_tools(*tool_names) ⇒ void

This method returns an undefined value.

Add tools from all_agents configuration

Used by Swarm::Builder to add all_agents tools. Since we use Set, order doesn't matter and duplicates are handled automatically.

Parameters:

  • Tool names to add



235
236
237
 
# File 'lib/swarm_sdk/agent/builder.rb', line 235

def prepend_tools(*tool_names)
  @tools.merge(tool_names.map(&:to_sym))
end

#provider(provider_name = :__not_provided__) ⇒ Object

Set/get provider



74
75
76
77
78
 
# File 'lib/swarm_sdk/agent/builder.rb', line 74

def provider(provider_name = :__not_provided__)
  return @provider if provider_name == :__not_provided__

  @provider = provider_name
end

#provider_set? ⇒ Boolean

Check if provider has been explicitly set

Used by Swarm::Builder to determine if all_agents provider should apply.

Returns:

  • true if provider was explicitly set



367
368
369
 
# File 'lib/swarm_sdk/agent/builder.rb', line 367

def provider_set?
  !@provider.nil?
end

#shared_across_delegations(enabled) ⇒ self

Configure delegation isolation mode

Examples:

shared_across_delegations true  # Allow sharing (old behavior)

Parameters:

  • If true, allows sharing instances across delegations (old behavior) If false (default), creates isolated instances per delegation

Returns:

  • Returns self for method chaining



287
288
289
290
 
# File 'lib/swarm_sdk/agent/builder.rb', line 287

def shared_across_delegations(enabled)
  @shared_across_delegations = enabled
  self
end

#system_prompt(text) ⇒ Object

Set system prompt (matches YAML key)



190
191
192
 
# File 'lib/swarm_sdk/agent/builder.rb', line 190

def system_prompt(text)
  @system_prompt = text
end

#timeout(seconds = :__not_provided__) ⇒ Object

Set/get timeout



116
117
118
119
120
 
# File 'lib/swarm_sdk/agent/builder.rb', line 116

def timeout(seconds = :__not_provided__)
  return @timeout if seconds == :__not_provided__

  @timeout = seconds
end

#timeout_set? ⇒ Boolean

Check if timeout has been explicitly set

Used by Swarm::Builder to determine if all_agents timeout should apply.

Returns:

  • true if timeout was explicitly set



394
395
396
 
# File 'lib/swarm_sdk/agent/builder.rb', line 394

def timeout_set?
  !@timeout.nil?
end

#to_definition ⇒ Agent::Definition

Build and return an Agent::Definition

This method converts the builder's configuration into a validated Agent::Definition object. The caller is responsible for adding it to a swarm.

Converts @tools Set to Array here because Agent::Definition expects an array. The Set was only used during building to handle duplicates efficiently.

Returns:

  • Fully configured and validated agent definition



434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/swarm_sdk/agent/builder.rb', line 434

def to_definition
  agent_config = {
    description: @description || "Agent #{@name}",
    model: @model,
    system_prompt: @system_prompt,
    tools: @tools.to_a, # Convert Set to Array for Agent::Definition compatibility
    delegates_to: @delegates_to,
    directory: @directory,
  }

  # Add optional fields
  agent_config[:provider] = @provider if @provider
  agent_config[:base_url] = @base_url if @base_url
  agent_config[:api_version] = @api_version if @api_version
  agent_config[:context_window] = @context_window if @context_window
  agent_config[:parameters] = @parameters if @parameters.any?
  agent_config[:headers] = @headers if @headers.any?
  agent_config[:timeout] = @timeout if @timeout
  agent_config[:mcp_servers] = @mcp_servers if @mcp_servers.any?
  agent_config[:disable_default_tools] = @disable_default_tools unless @disable_default_tools.nil?
  agent_config[:bypass_permissions] = @bypass_permissions
  agent_config[:coding_agent] = @coding_agent
  agent_config[:assume_model_exists] = @assume_model_exists unless @assume_model_exists.nil?
  agent_config[:permissions] = @permissions_config if @permissions_config.any?
  agent_config[:default_permissions] = @default_permissions if @default_permissions.any?
  agent_config[:memory] = @memory_config if @memory_config
  agent_config[:shared_across_delegations] = @shared_across_delegations unless @shared_across_delegations.nil?

  # Convert DSL hooks to HookDefinition format
  agent_config[:hooks] = convert_hooks_to_definitions if @hooks.any?

  # Merge context management hooks into agent hooks
  if @context_management_config
    agent_config[:hooks] ||= {}
    agent_config[:hooks][:context_warning] ||= []
    agent_config[:hooks][:context_warning].concat(@context_management_config)
  end

  Agent::Definition.new(@name, agent_config)
end

#tools(*tool_names, include_default: true, replace: false) ⇒ Object

Set or add tools

Uses Set internally to automatically deduplicate tool names across multiple calls. This allows calling tools() multiple times without worrying about duplicates.

Examples:

Basic usage with defaults

tools :Grep, :Read  # include_default: true is implicit

Explicit tools only, no defaults

tools :Grep, :Read, include_default: false

Multiple calls (cumulative, automatic deduplication)

tools :Read
tools :Write, :Edit  # @tools now contains Set[:Read, :Write, :Edit]
tools :Read          # Still Set[:Read, :Write, :Edit] - no duplicate

Replace tools (for markdown overrides)

tools :Read, :Write, replace: true  # Replaces all existing tools

Parameters:

  • Tool names to add

  • (defaults to: true)

    Whether to include default tools (Read, Grep, etc.)

  • (defaults to: false)

    If true, replaces existing tools instead of merging (default: false)



221
222
223
224
225
226
 
# File 'lib/swarm_sdk/agent/builder.rb', line 221

def tools(*tool_names, include_default: true, replace: false)
  @tools = Set.new if replace
  @tools.merge(tool_names.map(&:to_sym))
  # When include_default is false, disable all default tools
  @disable_default_tools = true unless include_default
end

#tools_list ⇒ Array<Symbol>

Get tools list as array for validation

Returns:

  • List of tools



30
31
32
 
# File 'lib/swarm_sdk/agent/builder.rb', line 30

def tools_list
  @tools.to_a
end