Class: Tools::SpawnSpecialist

Inherits:
Base
  • Object
show all
Includes:
SubagentPrompts
Defined in:
lib/tools/spawn_specialist.rb

Overview

Spawns a named specialist sub-agent from the agent registry. The specialist has a predefined system prompt and tool set defined in its Markdown definition file under agents/.

Results are delivered back through ReturnResult.

See Also:

Constant Summary

Constants included from SubagentPrompts

Tools::SubagentPrompts::EXPECTED_DELIVERABLE_PREFIX, Tools::SubagentPrompts::RETURN_INSTRUCTION

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

schema

Constructor Details

#initialize(session:, agent_registry: nil) ⇒ SpawnSpecialist

Returns a new instance of SpawnSpecialist.

Parameters:

  • session (Session) —

    the parent session spawning the specialist

  • agent_registry (Agents::Registry, nil) (defaults to: nil) —

    injectable for testing



63
64
65
66
 
# File 'lib/tools/spawn_specialist.rb', line 63

def initialize(session:, agent_registry: nil, **)
  @session = session
  @agent_registry = agent_registry || Agents::Registry.instance
end

Class Method Details

.description ⇒ Object

Builds description dynamically to include available specialists.



18
19
20
21
22
23
24
25
26
27
 
# File 'lib/tools/spawn_specialist.rb', line 18

def self.description
  base = "Spawn a named specialist sub-agent to work on a task autonomously. " \
    "The specialist has a predefined role, system prompt, and tool set."

  registry = Agents::Registry.instance
  return base unless registry.any?

  specialist_list = registry.catalog.map { |name, desc| "- #{name}: #{desc}" }.join("\n")
  "#{base}\n\nAvailable specialists:\n#{specialist_list}"
end

.input_schema ⇒ Object

Builds input schema dynamically to include named agent enum.



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/tools/spawn_specialist.rb', line 30

def self.input_schema
  {
    type: "object",
    properties: {
      name: name_property,
      task: {
        type: "string",
        description: "What the specialist should do (emitted as its first user message)"
      },
      expected_output: {
        type: "string",
        description: "Description of the expected deliverable"
      }
    },
    required: %w[name task expected_output]
  }
end

.tool_name ⇒ Object 



15
 
# File 'lib/tools/spawn_specialist.rb', line 15

def self.tool_name = "spawn_specialist"

Instance Method Details

#execute(input) ⇒ String, Hash{Symbol => String}

Creates a child session with the specialist’s predefined prompt and tools, emits the task as a user message, and queues background processing.

Parameters:

  • input (Hash<String, Object>) —

    with “name”, “task”, and “expected_output”

Returns:

  • (String) —

    confirmation with child session ID

  • (Hash{Symbol => String}) —

    with :error key on validation failure



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/tools/spawn_specialist.rb', line 74

def execute(input)
  task = input["task"].to_s.strip
  expected_output = input["expected_output"].to_s.strip
  name = input["name"].to_s.strip

  return {error: "Name cannot be blank"} if name.empty?
  return {error: "Task cannot be blank"} if task.empty?
  return {error: "Expected output cannot be blank"} if expected_output.empty?

  definition = @agent_registry.get(name)
  return {error: "Unknown agent: #{name}"} unless definition

  child = spawn_child(definition, task, expected_output)
  "Specialist '#{name}' spawned (session #{child.id}). Result will arrive as a tool response."
end