Class: SwarmSDK::V3::AgentDefinition

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

Overview

Immutable agent configuration

Defines everything about an agent’s identity, capabilities, and memory settings. Once created, a definition cannot be modified — create a new one instead.

Examples:

Minimal definition

definition = AgentDefinition.new(
  name: :assistant,
  description: "A helpful assistant",
)

Full definition with memory

definition = AgentDefinition.new(
  name: :researcher,
  description: "Research specialist",
  model: "claude-sonnet-4",
  system_prompt: "You are an expert researcher.",
  tools: [:Read, :Write, :Edit, :Bash, :Grep, :Glob],
  directory: "/path/to/project",
  parameters: { temperature: 0.7, thinking: { type: "enabled", budget_tokens: 10_000 } },
  headers: { "anthropic-beta" => "some-feature" },
  memory_directory: ".swarm/memory",
  memory_stm_turns: 8,
  memory_retrieval_top_k: 15,
)

Custom memory adapter

definition = AgentDefinition.new(
  name: :assistant,
  description: "Assistant with Postgres memory",
  memory_adapter: PgvectorAdapter.new("postgres://localhost/myapp"),
)

Constant Summary collapse

VALID_API_VERSIONS =

Valid API versions for OpenAI provider

["v1/responses", "v1/chat/completions"].freeze
VALID_QUEUE_MODES =

Valid queue delivery modes

[:all, :one_at_a_time].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name:, description:, model: nil, provider: nil, system_prompt: nil, tools: [], directory: ".", base_url: nil, max_concurrent_tools: nil, parameters: {}, headers: {}, memory_directory: nil, memory_adapter: nil, memory_stm_turns: nil, memory_retrieval_top_k: nil, memory_semantic_weight: nil, memory_keyword_weight: nil, memory_associative: nil, skills: [], mcp_servers: [], output_schema: nil, api_version: nil, hooks: [], steering_mode: :all, subtask_model: nil, subtask_provider: nil, subtask_base_url: nil, subtask_headers: {}, subtask_parameters: {}) ⇒ AgentDefinition

Create a new agent definition

Parameters:

  • name (Symbol, String) —

    Agent identifier (required)

  • description (String) —

    Agent role description (required)

  • model (String, nil) (defaults to: nil) —

    LLM model ID

  • provider (String, nil) (defaults to: nil) —

    LLM provider

  • system_prompt (String, nil) (defaults to: nil) —

    System prompt instructions

  • tools (Array<Symbol>) (defaults to: []) —

    Tool names

  • directory (String) (defaults to: ".") —

    Working directory

  • base_url (String, nil) (defaults to: nil) —

    Custom API endpoint

  • max_concurrent_tools (Integer, nil) (defaults to: nil) —

    Max concurrent tool executions

  • parameters (Hash) (defaults to: {}) —

    Raw API body parameters

  • headers (Hash) (defaults to: {}) —

    Raw HTTP headers

  • memory_directory (String, nil) (defaults to: nil) —

    Filesystem adapter path

  • memory_adapter (Memory::Adapters::Base, nil) (defaults to: nil) —

    Custom adapter instance

  • memory_stm_turns (Integer) (defaults to: nil) —

    Recent turns in STM

  • memory_retrieval_top_k (Integer) (defaults to: nil) —

    Cards to retrieve per turn

  • memory_semantic_weight (Float) (defaults to: nil) —

    Semantic search weight

  • memory_keyword_weight (Float) (defaults to: nil) —

    Keyword search weight

  • memory_associative (Boolean, nil) (defaults to: nil) —

    Enable associative memory

  • skills (Array<String>) (defaults to: []) —

    Skill directory paths

  • mcp_servers (Array<Hash, V3::MCP::ServerDefinition>) (defaults to: []) —

    MCP server configurations

  • output_schema (Hash, Object, nil) (defaults to: nil) —

    JSON Schema for structured output (pass-through to RubyLLM)

  • api_version (String, nil) (defaults to: nil) —

    API version for OpenAI provider. Valid values: “v1/responses”, “v1/chat/completions”. Defaults to “v1/responses” when provider is “openai”. Ignored for other providers.

  • hooks (Array<Hash>) (defaults to: []) —

    Hook configurations. Each hash has :event (Symbol), :block (Proc), and optional :match keys. See Hooks::Runner for details.

  • steering_mode (Symbol) (defaults to: :all) —

    Steering queue delivery mode (:all or :one_at_a_time). Default: :all (all steering messages injected together).

  • subtask_model (String, nil) (defaults to: nil) —

    Model for this agent’s subtasks

  • subtask_provider (String, nil) (defaults to: nil) —

    Provider for subtask model

  • subtask_base_url (String, nil) (defaults to: nil) —

    Custom API base URL for subtask model

  • subtask_headers (Hash) (defaults to: {}) —

    Custom HTTP headers for subtask model

  • subtask_parameters (Hash) (defaults to: {}) —

    Raw API body parameters for subtask model

Raises:



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 173

def initialize(
  name:,
  description:,
  model: nil,
  provider: nil,
  system_prompt: nil,
  tools: [],
  directory: ".",
  base_url: nil,
  max_concurrent_tools: nil,
  parameters: {},
  headers: {},
  memory_directory: nil,
  memory_adapter: nil,
  memory_stm_turns: nil,
  memory_retrieval_top_k: nil,
  memory_semantic_weight: nil,
  memory_keyword_weight: nil,
  memory_associative: nil,
  skills: [],
  mcp_servers: [],
  output_schema: nil,
  api_version: nil,
  hooks: [],
  steering_mode: :all,
  subtask_model: nil,
  subtask_provider: nil,
  subtask_base_url: nil,
  subtask_headers: {},
  subtask_parameters: {}
)
  config = Configuration.instance

  @name = name.to_sym
  @description = description
  @model = model || config.default_model
  @provider = provider
  @system_prompt = system_prompt
  @tools = Array(tools).map(&:to_sym)
  @directory = File.expand_path(directory)
  @base_url = base_url
  @max_concurrent_tools = max_concurrent_tools || config.default_max_concurrent_tools
  @parameters = parameters.freeze
  @headers = headers.freeze
  @memory_directory = memory_directory
  @memory_adapter = memory_adapter
  @memory_stm_turns = memory_stm_turns || config.default_stm_turns
  @memory_retrieval_top_k = memory_retrieval_top_k || config.default_retrieval_top_k
  @memory_semantic_weight = memory_semantic_weight || config.default_semantic_weight
  @memory_keyword_weight = memory_keyword_weight || config.default_keyword_weight
  @memory_associative = memory_associative.nil? ? config.default_associative_memory : memory_associative
  @skills = Array(skills).map { |s| File.expand_path(s) }.freeze
  @mcp_servers = Array(mcp_servers).map do |config|
    config.is_a?(V3::MCP::ServerDefinition) ? config : V3::MCP::ServerDefinition.new(**config)
  end.freeze
  @output_schema = output_schema
  @api_version = resolve_api_version(api_version)
  @hooks = Array(hooks).freeze
  @steering_mode = steering_mode.to_sym
  @subtask_model = subtask_model
  @subtask_provider = subtask_provider
  @subtask_base_url = subtask_base_url
  @subtask_headers = subtask_headers.freeze
  @subtask_parameters = subtask_parameters.freeze

  validate!
  freeze
end

Instance Attribute Details

#api_version ⇒ String? (readonly)

Returns API version for OpenAI provider (“v1/responses” or “v1/chat/completions”). Defaults to “v1/responses” when provider is “openai”. nil for non-OpenAI providers.

Returns:

  • (String, nil) —

    API version for OpenAI provider (“v1/responses” or “v1/chat/completions”). Defaults to “v1/responses” when provider is “openai”. nil for non-OpenAI providers.



110
111
112
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 110

def api_version
  @api_version
end

#base_url ⇒ String? (readonly)

Returns Custom API endpoint.

Returns:

  • (String, nil) —

    Custom API endpoint



66
67
68
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 66

def base_url
  @base_url
end

#description ⇒ String (readonly)

Returns Agent role description.

Returns:

  • (String) —

    Agent role description



48
49
50
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 48

def description
  @description
end

#directory ⇒ String (readonly)

Returns Working directory.

Returns:

  • (String) —

    Working directory



63
64
65
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 63

def directory
  @directory
end

#headers ⇒ Hash (readonly)

Returns Raw HTTP headers.

Returns:

  • (Hash) —

    Raw HTTP headers



75
76
77
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 75

def headers
  @headers
end

#hooks ⇒ Array<Hash> (readonly)

Returns Hook configurations (frozen). Each hash has :event, :block, and optional :match keys. Opaque to the definition — Hooks::Runner interprets them.

Returns:

  • (Array<Hash>) —

    Hook configurations (frozen). Each hash has :event, :block, and optional :match keys. Opaque to the definition — Hooks::Runner interprets them.



114
115
116
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 114

def hooks
  @hooks
end

#max_concurrent_tools ⇒ Integer? (readonly)

Returns Maximum concurrent tool executions.

Returns:

  • (Integer, nil) —

    Maximum concurrent tool executions



69
70
71
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 69

def max_concurrent_tools
  @max_concurrent_tools
end

#mcp_servers ⇒ Array<V3::MCP::ServerDefinition> (readonly)

Returns MCP server configurations (frozen).

Returns:



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

def mcp_servers
  @mcp_servers
end

#memory_adapter ⇒ Memory::Adapters::Base? (readonly)

Returns Custom adapter instance.

Returns:



81
82
83
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 81

def memory_adapter
  @memory_adapter
end

#memory_associative ⇒ Boolean (readonly)

Returns Whether to surface exploration cards as tangential memories the agent is encouraged to naturally bring up in conversation.

Returns:

  • (Boolean) —

    Whether to surface exploration cards as tangential memories the agent is encouraged to naturally bring up in conversation



97
98
99
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 97

def memory_associative
  @memory_associative
end

#memory_directory ⇒ String? (readonly)

Returns Filesystem adapter path (nil = no memory).

Returns:

  • (String, nil) —

    Filesystem adapter path (nil = no memory)



78
79
80
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 78

def memory_directory
  @memory_directory
end

#memory_keyword_weight ⇒ Float (readonly)

Returns Hybrid search keyword weight (0.0-1.0).

Returns:

  • (Float) —

    Hybrid search keyword weight (0.0-1.0)



93
94
95
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 93

def memory_keyword_weight
  @memory_keyword_weight
end

#memory_retrieval_top_k ⇒ Integer (readonly)

Returns Cards to retrieve per turn.

Returns:

  • (Integer) —

    Cards to retrieve per turn



87
88
89
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 87

def memory_retrieval_top_k
  @memory_retrieval_top_k
end

#memory_semantic_weight ⇒ Float (readonly)

Returns Hybrid search semantic weight (0.0-1.0).

Returns:

  • (Float) —

    Hybrid search semantic weight (0.0-1.0)



90
91
92
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 90

def memory_semantic_weight
  @memory_semantic_weight
end

#memory_stm_turns ⇒ Integer (readonly)

Returns Recent turns to keep in short-term memory.

Returns:

  • (Integer) —

    Recent turns to keep in short-term memory



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

def memory_stm_turns
  @memory_stm_turns
end

#model ⇒ String (readonly)

Returns LLM model ID.

Returns:

  • (String) —

    LLM model ID



51
52
53
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 51

def model
  @model
end

#name ⇒ Symbol (readonly)

Returns Agent identifier.

Returns:

  • (Symbol) —

    Agent identifier



45
46
47
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 45

def name
  @name
end

#output_schema ⇒ Hash, ... (readonly)

Returns JSON Schema for structured output (pass-through to RubyLLM).

Returns:

  • (Hash, Object, nil) —

    JSON Schema for structured output (pass-through to RubyLLM)



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

def output_schema
  @output_schema
end

#parameters ⇒ Hash (readonly)

Returns Raw API body parameters (temperature, thinking, etc.).

Returns:

  • (Hash) —

    Raw API body parameters (temperature, thinking, etc.)



72
73
74
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 72

def parameters
  @parameters
end

#provider ⇒ String? (readonly)

Returns LLM provider.

Returns:

  • (String, nil) —

    LLM provider



54
55
56
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 54

def provider
  @provider
end

#skills ⇒ Array<String> (readonly)

Returns Skill directory paths (expanded, frozen).

Returns:

  • (Array<String>) —

    Skill directory paths (expanded, frozen)



100
101
102
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 100

def skills
  @skills
end

#steering_mode ⇒ Symbol (readonly)

Returns Steering queue delivery mode (:all or :one_at_a_time).

Returns:

  • (Symbol) —

    Steering queue delivery mode (:all or :one_at_a_time)



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

def steering_mode
  @steering_mode
end

#subtask_base_url ⇒ String? (readonly)

Returns Custom API base URL for subtask model.

Returns:

  • (String, nil) —

    Custom API base URL for subtask model



128
129
130
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 128

def subtask_base_url
  @subtask_base_url
end

#subtask_headers ⇒ Hash (readonly)

Returns Custom HTTP headers for subtask model.

Returns:

  • (Hash) —

    Custom HTTP headers for subtask model



131
132
133
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 131

def subtask_headers
  @subtask_headers
end

#subtask_model ⇒ String? (readonly)

Returns Model for this agent’s subtasks (nil = use global config or inherit).

Returns:

  • (String, nil) —

    Model for this agent’s subtasks (nil = use global config or inherit)



122
123
124
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 122

def subtask_model
  @subtask_model
end

#subtask_parameters ⇒ Hash (readonly)

Returns Raw API body parameters for subtask model.

Returns:

  • (Hash) —

    Raw API body parameters for subtask model



134
135
136
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 134

def subtask_parameters
  @subtask_parameters
end

#subtask_provider ⇒ String? (readonly)

Returns Provider for subtask model.

Returns:

  • (String, nil) —

    Provider for subtask model



125
126
127
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 125

def subtask_provider
  @subtask_provider
end

#system_prompt ⇒ String? (readonly)

Returns System prompt instructions.

Returns:

  • (String, nil) —

    System prompt instructions



57
58
59
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 57

def system_prompt
  @system_prompt
end

#tools ⇒ Array<Symbol> (readonly)

Returns Tool names.

Returns:

  • (Array<Symbol>) —

    Tool names



60
61
62
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 60

def tools
  @tools
end

Instance Method Details

#memory_enabled? ⇒ Boolean

Whether this agent has memory enabled

Returns:

  • (Boolean) —

    true if memory_directory or memory_adapter is set



245
246
247
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 245

def memory_enabled?
  !@memory_directory.nil? || !@memory_adapter.nil?
end

#subtask_config? ⇒ Boolean

Whether this agent has subtask model configuration

Returns:

  • (Boolean) —

    true if any subtask_* option is set



252
253
254
255
256
257
258
 
# File 'lib/swarm_sdk/v3/agent_definition.rb', line 252

def subtask_config?
  !@subtask_model.nil? ||
    !@subtask_provider.nil? ||
    !@subtask_base_url.nil? ||
    !@subtask_headers.empty? ||
    !@subtask_parameters.empty?
end