Class: SwarmSDK::V3::Tools::SubTask

Inherits:
Base
  • Object
show all
Defined in:
lib/swarm_sdk/v3/tools/sub_task.rb

Overview

SubTask tool for spawning focused subtask agents

Allows an agent to spawn a copy of itself for a focused subtask. The subtask agent shares the parent’s memory (read-only), MCP connections, and skill access. It runs in the same process.

SubTask is opt-in — agents must include :SubTask in their tools list. This prevents accidental cost explosion from unintended spawning.

## Depth control

Subtasks track nesting depth. The maximum depth is controlled by Configuration#max_subtask_depth (default: 1, meaning the parent can spawn subtasks, but subtasks cannot spawn further subtasks).

Examples:

Agent definition with SubTask

AgentDefinition.new(
  name: :researcher,
  description: "Research agent",
  tools: [:Read, :Grep, :Glob, :Think, :SubTask],
)

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

#name

Constructor Details

#initialize(agent_definition:, memory_store: nil, directory: ".", subtask_depth: 0) ⇒ SubTask

Returns a new instance of SubTask.

Parameters:

  • agent_definition (AgentDefinition) —

    Parent agent’s definition

  • memory_store (Memory::Store, nil) (defaults to: nil) —

    Parent’s memory store

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

    Working directory

  • subtask_depth (Integer) (defaults to: 0) —

    Current nesting depth



39
40
41
42
43
44
45
 
# File 'lib/swarm_sdk/v3/tools/sub_task.rb', line 39

def initialize(agent_definition:, memory_store: nil, directory: ".", subtask_depth: 0)
  super()
  @agent_definition = agent_definition
  @memory_store = memory_store
  @directory = directory
  @subtask_depth = subtask_depth
end

Class Method Details

.creation_requirements ⇒ Array<Symbol>

Returns Constructor requirements.

Returns:

  • (Array<Symbol>) —

    Constructor requirements



30
31
32
 
# File 'lib/swarm_sdk/v3/tools/sub_task.rb', line 30

def creation_requirements
  [:agent_definition, :memory_store, :directory, :subtask_depth]
end

Instance Method Details

#execute(title:, instructions:, **_kwargs) ⇒ String

Execute the SubTask tool

Spawns a SubTaskAgent, runs the instructions, and returns the result. The subtask agent is always cleaned up via ensure block.

Parameters:

  • title (String) —

    Short title for logging

  • instructions (String) —

    Detailed instructions for the subtask

Returns:

  • (String) —

    Subtask result or error message



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/swarm_sdk/v3/tools/sub_task.rb', line 110

def execute(title:, instructions:, **_kwargs)
  return validation_error("title is required") if title.to_s.strip.empty?
  return validation_error("instructions are required") if instructions.to_s.strip.empty?

  next_depth = @subtask_depth + 1
  max_depth = Configuration.instance.max_subtask_depth

  if next_depth > max_depth
    return error(
      "Maximum subtask depth (#{max_depth}) exceeded. " \
        "Cannot spawn nested subtask at depth #{next_depth}.",
    )
  end

  agent = SubTaskAgent.new(
    @agent_definition,
    parent_memory_store: @memory_store,
    subtask_depth: next_depth,
  )

  EventStream.emit(
    type: "subtask_spawned",
    agent: @agent_definition.name,
    subtask_agent: agent.id,
    title: title,
    depth: next_depth,
  )

  prompt = <<~PROMPT.strip
    # SubTask: #{title}

    #{instructions}
  PROMPT

  response = agent.ask(prompt)
  format_result(title, response)
rescue StandardError => e
  EventStream.emit(
    type: "subtask_failed",
    agent: @agent_definition.name,
    subtask_agent: agent&.id,
    title: title,
    error: "#{e.class}: #{e.message}",
  )
  error("Subtask '#{title}' failed: #{e.class}: #{e.message}")
ensure
  agent&.clear
end