Agent Tools

Agent tools enable the core multi-agent coordination patterns in Routa. They handle agent lifecycle, task delegation, messaging, and event subscriptions.

In essential mode, 7 agent tools are available. In full mode, all 14 agent tools are available.

Core Agent Tools (Essential Mode)

list_agents

List all agents in the workspace with their status and role.

workspaceId

string

Workspace ID (uses default if omitted)

Returns:

[
  {
    "id": "agent-uuid",
    "name": "Coordinator",
    "role": "ROUTA",
    "status": "ACTIVE",
    "parentId": null
  }
]

Usage:

const result = await tools.listAgents(workspaceId);
// Check what other agents are working on to avoid conflicts

read_agent_conversation

Read another agent’s conversation history.

agentId

string

required

ID of the agent whose conversation to read

lastN

number

Number of recent messages to retrieve

startTurn

number

Start turn number (inclusive)

endTurn

number

End turn number (inclusive)

includeToolCalls

boolean

default:"false"

Include tool call messages

Returns:

{
  "agentId": "agent-uuid",
  "agentName": "Implementor-Auth",
  "messageCount": 15,
  "messages": [
    {
      "role": "user",
      "content": "Implement JWT authentication",
      "turn": 0,
      "timestamp": "2024-03-03T10:00:00Z"
    }
  ]
}

Usage:

// Read last 5 messages from an agent
const conv = await tools.readAgentConversation({
  agentId: "agent-123",
  lastN: 5
});

create_agent

Create a new agent with a specific role.

name

string

required

Name for the new agent

role

string

required

Agent role: ROUTA (coordinator), CRAFTER (implementor), GATE (verifier), or DEVELOPER

workspaceId

string

Workspace ID (uses default if omitted)

parentId

string

Parent agent ID for hierarchy

modelTier

string

default:"SMART"

Model tier: SMART, BALANCED, or FAST

Returns:

{
  "agentId": "new-agent-uuid",
  "name": "Auth-Implementor",
  "role": "CRAFTER",
  "status": "PENDING"
}

Usage:

const result = await tools.createAgent({
  name: "Auth-Implementor",
  role: "CRAFTER",
  parentId: coordinatorId,
  modelTier: "FAST"
});

set_agent_name

Set your agent’s name to reflect the current task. Call this in your first response.

name

string

required

Short task-focused name (1-5 words)

Returns:

{
  "ok": true,
  "name": "Auth-Implementor"
}

Every specialist prompt instructs agents to call this tool first. Names should be descriptive and task-focused.

delegate_task

Assign a task to an existing agent and activate it.

agentId

string

required

UUID of the agent to delegate to

taskId

string

required

UUID of the task to delegate (from create_task, NOT a task name)

callerAgentId

string

required

UUID of the calling agent

Returns:

{
  "agentId": "agent-uuid",
  "taskId": "task-uuid",
  "status": "delegated"
}

The taskId must be a UUID from create_task, not a task name or @@@task identifier. If you see an error like “Task not found”, use list_tasks to find the correct UUID or create_task to create a new task first.

delegate_task_to_agent

Delegate a task to a new agent by spawning a real agent process. This is the primary delegation tool for coordinators.

taskId

string

required

UUID of the task to delegate (MUST be a UUID from create_task, NOT a task name)

callerAgentId

string

required

Your agent ID (the coordinator’s agent ID)

callerSessionId

string

Your session ID (if known)

specialist

string

required

Specialist type: CRAFTER for implementation, GATE for verification, DEVELOPER for solo plan+implement

provider

string

ACP provider to use (e.g., claude, copilot, opencode). Uses default if omitted.

cwd

string

Working directory for the agent

additionalInstructions

string

Extra instructions beyond the task content

waitMode

string

When to notify: immediate (per agent) or after_all (when all in parallel group complete)

Returns:

{
  "agentId": "spawned-agent-uuid",
  "processId": 12345,
  "status": "spawned"
}

Usage:

// Delegate implementation task
const result = await tools.delegateTaskToAgent({
  taskId: "dda97509-b414-4c50-9835-73a1ec2f...",
  callerAgentId: myAgentId,
  specialist: "CRAFTER",
  waitMode: "after_all"  // Wait for all parallel tasks
});

IMPORTANT: First call set_note_content on the spec note with @@@task blocks — it auto-creates tasks and returns UUIDs. Then use those UUIDs with this tool.

send_message_to_agent

Send a message from one agent to another.

fromAgentId

string

required

ID of the sending agent

toAgentId

string

required

ID of the receiving agent

message

string

required

Message content

Returns:

{
  "delivered": true,
  "toAgentId": "recipient-uuid",
  "fromAgentId": "sender-uuid"
}

Usage:

// Ask another agent about their progress
await tools.messageAgent({
  fromAgentId: myId,
  toAgentId: implementorId,
  message: "Have you completed the auth migration?"
});

report_to_parent

Submit a completion report to the parent agent. Required to signal task completion.

agentId

string

required

ID of the reporting agent

taskId

string

required

ID of the completed task

summary

string

required

Summary of what was accomplished

filesModified

string[]

List of modified files

verificationResults

string

Verification output

success

boolean

required

Whether the task was completed successfully

Returns:

{
  "reported": true,
  "parentId": "parent-agent-uuid",
  "success": true
}

Usage:

await tools.reportToParent({
  agentId: myId,
  taskId: assignedTaskId,
  summary: "Implemented JWT auth with refresh tokens. All tests passing.",
  filesModified: ["src/auth/jwt.ts", "src/auth/middleware.ts"],
  verificationResults: "npm test -- auth\n✓ 15 tests passing",
  success: true
});

CRITICAL: Every CRAFTER and GATE agent MUST call this tool when finished. Without it, the coordinator won’t know the task is complete.

Extended Agent Tools (Full Mode Only)

wake_or_create_task_agent

Wake an existing agent assigned to a task, or create a new Crafter agent if none exists.

taskId

string

required

ID of the task

contextMessage

string

required

Context message for the agent

callerAgentId

string

required

ID of the calling agent

workspaceId

string

Workspace ID (uses default if omitted)

agentName

string

Name for new agent (if created)

modelTier

string

Model tier for new agent

Returns:

{
  "agentId": "agent-uuid",
  "action": "woken",  // or "created"
  "name": "Auth-Implementor"
}

send_message_to_task_agent

Send a message to the agent currently assigned to a task.

taskId

string

required

ID of the task

message

string

required

Message content

callerAgentId

string

required

ID of the calling agent

get_agent_status

Get the current status, message count, and assigned tasks for an agent.

agentId

string

required

ID of the agent

Returns:

{
  "agentId": "agent-uuid",
  "name": "Auth-Implementor",
  "role": "CRAFTER",
  "status": "ACTIVE",
  "modelTier": "FAST",
  "parentId": "coordinator-uuid",
  "messageCount": 23,
  "tasks": [
    {
      "id": "task-uuid",
      "title": "Implement JWT auth",
      "status": "IN_PROGRESS"
    }
  ]
}

get_agent_summary

Get a summary of an agent including last response, tool call counts, and active tasks.

agentId

string

required

ID of the agent

Returns:

{
  "agentId": "agent-uuid",
  "name": "Auth-Implementor",
  "role": "CRAFTER",
  "status": "ACTIVE",
  "messageCount": 23,
  "toolCallCount": 45,
  "lastResponse": {
    "content": "Implemented JWT middleware...",
    "timestamp": "2024-03-03T10:15:00Z"
  },
  "activeTasks": [
    { "id": "task-uuid", "title": "Implement JWT auth" }
  ]
}

subscribe_to_events

Subscribe an agent to workspace events (AGENT_CREATED, TASK_COMPLETED, TASK_STATUS_CHANGED, etc.).

agentId

string

required

ID of the subscribing agent

agentName

string

required

Name of the subscribing agent

eventTypes

string[]

required

Event types to subscribe to

excludeSelf

boolean

default:"true"

Exclude self-generated events

oneShot

boolean

default:"false"

Auto-remove after first matching event

waitGroupId

string

Wait group ID for after_all semantics

priority

number

default:"0"

Priority (higher = notified first)

Returns:

{
  "subscriptionId": "sub-uuid",
  "eventTypes": ["TASK_COMPLETED"],
  "oneShot": false,
  "priority": 0
}

Usage:

// Subscribe to task completions
const sub = await tools.subscribeToEvents({
  agentId: coordinatorId,
  agentName: "Coordinator",
  eventTypes: ["TASK_COMPLETED"],
  oneShot: false
});

unsubscribe_from_events

Remove an event subscription.

subscriptionId

string

required

ID of the subscription to remove

Returns:

{
  "unsubscribed": true,
  "subscriptionId": "sub-uuid"
}

Common Patterns

Coordinator Wave Delegation

// 1. Write spec with @@@task blocks (auto-creates tasks)
const specResult = await tools.setNoteContent({
  noteId: "spec",
  content: specWithTaskBlocks,
  workspaceId
});

const taskIds = specResult.tasks.map(t => t.taskId);

// 2. Delegate Wave 1 with after_all wait mode
for (const taskId of wave1TaskIds) {
  await tools.delegateTaskToAgent({
    taskId,
    callerAgentId: myId,
    specialist: "CRAFTER",
    waitMode: "after_all"  // Notified when ALL complete
  });
}

// 3. END TURN - wait for notification

Implementor Coordination Check

// Check what other agents are working on
const agents = await tools.listAgents(workspaceId);
for (const agent of agents) {
  if (agent.status === "ACTIVE") {
    const conv = await tools.readAgentConversation({
      agentId: agent.id,
      lastN: 3
    });
    // Check for file conflicts
  }
}

Task Completion Report

// When done with a task
await tools.reportToParent({
  agentId: myId,
  taskId: myTaskId,
  summary: "Completed auth implementation. Tests passing.",
  filesModified: ["src/auth/jwt.ts"],
  verificationResults: "npm test\n✓ 15 passing",
  success: true
});

REST API

MCP Tools

ACP

A2A

Core Agent Tools (Essential Mode)

list_agents

read_agent_conversation

create_agent

set_agent_name

delegate_task

delegate_task_to_agent

send_message_to_agent

report_to_parent

Extended Agent Tools (Full Mode Only)

wake_or_create_task_agent

send_message_to_task_agent

get_agent_status

get_agent_summary

subscribe_to_events

unsubscribe_from_events

Common Patterns

Coordinator Wave Delegation

Implementor Coordination Check

Task Completion Report

See Also

Build docs developers (and LLMs) love

REST API

MCP Tools

ACP

A2A

​Core Agent Tools (Essential Mode)

​list_agents

​read_agent_conversation

​create_agent

​set_agent_name

​delegate_task

​delegate_task_to_agent

​send_message_to_agent

​report_to_parent

​Extended Agent Tools (Full Mode Only)

​wake_or_create_task_agent

​send_message_to_task_agent

​get_agent_status

​get_agent_summary

​subscribe_to_events

​unsubscribe_from_events

​Common Patterns

​Coordinator Wave Delegation

​Implementor Coordination Check

​Task Completion Report

​See Also

Build docs developers (and LLMs) love

Core Agent Tools (Essential Mode)

list_agents

read_agent_conversation

create_agent

set_agent_name

delegate_task

delegate_task_to_agent

send_message_to_agent

report_to_parent

Extended Agent Tools (Full Mode Only)

wake_or_create_task_agent

send_message_to_task_agent

get_agent_status

get_agent_summary

subscribe_to_events

unsubscribe_from_events

Common Patterns

Coordinator Wave Delegation

Implementor Coordination Check

Task Completion Report

See Also