API Reference

ping

Minimal liveness check. Returns { status: 'ok', timestamp }.

Parameters

No parameters.

Returns

{ status: 'ok', timestamp: number }

Example

await callTool("ping", {});

get_health

Health report: ledger size, fleet/agent/message counts, uptime, last event. Use for monitoring and alerting.

Parameters

No parameters.

Returns

{ status: 'ok'|'degraded'|'error', uptime_ms, fleets, agents, messages, capabilities, events, ledger_bytes, events_log_bytes, last_event_timestamp? }

Example

const { status, fleets, agents, ... } = await callTool("get_health", {});

save_fleet_template

Save a named fleet template (set of agent specs) for reuse.

Parameters

Returns

{ template: { name, description, agents, created_at } }

Example

await callTool("save_fleet_template", {
  name: "auth-review",
  description: "Review auth module",
  agents: [{ role: "Reviewer", prompt: "Find security issues", agent: "code-reviewer" }],
});

subscribe_inbox

Subscribe to an agent's inbox via Server-Sent Events (SSE). Returns a stream URL that the agent opens to receive real-time push of incoming P2P messages. Falls back to polling get_inbox if SSE is unreachable.

Parameters

Returns

{ agent_id, stream_url, instructions }

Example

const { stream_url } = await callTool("subscribe_inbox", { agent_id: "a2" });
// Open an HTTP GET to stream_url. Each event is SSE-formatted.

list_fleet_templates

List all saved fleet templates, sorted by name.

Parameters

No parameters.

Returns

{ templates: FleetTemplate[] }

Example

const { templates } = await callTool("list_fleet_templates", {});

spawn_from_template

Return a fleet spec from a saved template, ready to pass to spawn_fleet.

Parameters

Returns

{ spec: { agents: TemplateAgent[] } }

Example

const { spec } = await callTool("spawn_from_template", { name: "auth-review" });
await callTool("spawn_fleet", spec);

spawn_fleet

Spawn N parallel agents as independent OS processes.

Parameters

Returns

{ fleet_id: string, agent_ids: string[] }

Example

await callTool("spawn_fleet", {
  agents: [
    { role: "Explorer", prompt: "Map the auth layer", agent: "codebase-onboarding-engineer" },
  ],
});

fleet_status

Check fleet and agent status.

Parameters

Returns

{ fleet: Fleet, agents: Agent[] }

Example

await callTool("fleet_status", { fleet_id: "abc-123" });

list_fleets

List all fleets with summaries (agent count, status, completion).

Parameters

No parameters.

Returns

{ fleets: FleetSummary[] } where each summary is { id, status, created_at, completed_at, agent_count, agents_complete, agents_failed, agents_running }

Example

await callTool("list_fleets", {});

set_fleet_timeout

Set a per-fleet timeout override (in ms). Agents exceeding this are auto-failed.

Parameters

Returns

{ ok: true, timeout_ms: number }

Example

await callTool("set_fleet_timeout", { fleet_id: "abc-123", timeout_ms: 60000 });

collect_results

Get all agent outputs from a fleet.

Parameters

Returns

{ fleet_id: string, results: Array<{ role, status, output, error }> }

Example

const { results } = await callTool("collect_results", { fleet_id: "abc-123" });

send_message

Send a P2P message from one agent to another.

Parameters

Returns

{ message_id: string }

Example

await callTool("send_message", {
  from_agent_id: "a1",
  to_agent_id: "a2",
  fleet_id: "abc-123",
  type: "handoff",
  payload: JSON.stringify({ context: "Found 3 files", next_step: "Review" }),
});

get_inbox

Get messages in an agent's inbox.

Parameters

Returns

{ messages: Message[] }

Example

const { messages } = await callTool("get_inbox", { agent_id: "a1" });

ack_message

Acknowledge a message, removing it from the agent's inbox.

Parameters

Returns

{ ok: boolean } (idempotent on non-existent message)

Example

await callTool("ack_message", { agent_id: "a1", message_id: "msg-456" });

register_capability

Register an agent's capabilities for routing. Auto-called when spawning a premade agent.

Parameters

Returns

{ ok: true }

Example

await callTool("register_capability", {
  agent_id: "a1", fleet_id: "abc-123", role: "Security Auditor",
  skills: ["auth", "vulnerabilities", "owasp"],
});

route_work

Find the best-matching registered agents for a task description.

Parameters

Returns

{ matches: Array<{ agent_id, score, role }> } sorted by score descending

Example

const { matches } = await callTool("route_work", {
  description: "audit authentication security vulnerabilities",
});
// matches[0] → best agent for the task

list_agents

List all available premade agents from .opencode/agents/.

Parameters

No parameters.

Returns

{ count: number, agents: Array<{ filename, name, description, mode }> }

Example

const { agents } = await callTool("list_agents", {});

attach_agent

Dynamically attach a premade agent to a running fleet mid-flight.

Parameters

Returns

{ agent_id, fleet_id, role, agent_file, message }

Example

await callTool("attach_agent", {
  fleet_id: "abc-123", role: "Security Reviewer",
  prompt: "Audit the auth middleware for vulnerabilities",
  agent: "application-security-engineer",
});