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/.

Nickname assignment is handled by the AnalyticalBrain::Runner which runs synchronously at spawn time, generating a unique nickname based on the task — same as generic sub-agents.

Results are delivered through natural text messages routed by Events::Subscribers::SubagentMessageRouter.

See Also:

Constant Summary

Constants included from SubagentPrompts

Tools::SubagentPrompts::COMMUNICATION_INSTRUCTION, Tools::SubagentPrompts::EXPECTED_DELIVERABLE_PREFIX

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



70
71
72
73
 
# File 'lib/tools/spawn_specialist.rb', line 70

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.



23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/tools/spawn_specialist.rb', line 23

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. " \
    "Its text messages are forwarded to you automatically. " \
    "Address it via @name to send follow-up instructions."

  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.



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/tools/spawn_specialist.rb', line 37

def self.input_schema
  {
    type: "object",
    properties: {
      name: name_property,
      task: {
        type: "string",
        description: "What the specialist should do (persisted 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 



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

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, persists the task as a user message, and queues background processing. Returns immediately (non-blocking).

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



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/tools/spawn_specialist.rb', line 82

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)
  nickname = child.name
  "Specialist @#{nickname} spawned (session #{child.id}). " \
    "Its messages will appear in your conversation. " \
    "Reply with @#{nickname} to send it instructions."
end