Multi-Agent

OpenMotoko supports spawning sub-agents for parallel task execution. The primary agent can delegate work to specialized sub-agents, each with their own context and budget.

Architecture

AgentManager

The AgentManager controls the lifecycle of all agents:

• Maximum 4 concurrent sub-agents
• Each agent is persisted to the agents database table
• Supports waiting for one agent or all agents to complete
• Agents have configurable timeouts

Agent roles

Role	Description
primary	The main agent handling user conversations
sub	A spawned agent executing a delegated task

Agent statuses

Status	Description
idle	Created but not yet running
running	Actively processing
waiting	Blocked on sub-agent results
completed	Finished successfully
failed	Terminated with an error

Tool definitions

The LLM can use two tools to work with sub-agents:

spawn_agent

Spawns a new sub-agent with a specific task.

{
  "task": "Research the latest Node.js 24 features and summarize them",
  "name": "node-researcher",
  "model": "fast",
  "budget": 0.50
}

Parameter	Type	Default	Description
task	string	(required)	Task description for the sub-agent
name	string	(auto)	Human-readable name
model	string	(parent model)	Model alias to use
budget	number	1.00	Max cost in USD

wait_agents

Waits for one or more sub-agents to complete.

{
  "agentIds": ["agent_abc123", "agent_def456"]
}

The primary agent blocks until all specified agents finish, then receives their outputs.

Sub-agent constraints

• Each sub-agent runs for a maximum of 10 turns
• Sub-agents have their own system prompt tailored to their task
• Sub-agents inherit the parent’s skill access
• Budget is enforced per-agent; exceeding it terminates the agent

WebSocket events

Event	Fields	Description
agent:spawned	agentId, parentId, name, model	Sub-agent created
agent:completed	agentId, parentId, name, output, durationMs	Sub-agent finished
agent:failed	agentId, parentId, name, output, durationMs	Sub-agent errored

REST API

Method	Path	Description
GET	/api/agents	List all agents
GET	/api/agents/:id	Get agent details
DELETE	/api/agents/:id	Kill a running agent

Use cases

Parallel research: spawn multiple agents to research different topics simultaneously, then synthesize their findings.

Code review: one agent analyzes code quality while another checks for security issues.

Data processing: split a large dataset across agents for parallel analysis.

Multi-step workflows: chain agents where each handles one stage of a pipeline.