Multi-Agent & Teams

BMO supports multiple patterns for agent-to-agent coordination, from simple sub-agent spawning to persistent team workflows.

For the bigger coordination map across local sub-agents, remote mesh peers, staged workflows, and regulation layers, see Workflow map and How BMO thinks and acts.

Spawning sub-agents

Use spawn_agent when you need a child agent with its own prompt and optional tool/model/worktree overrides:

spawn_agent(
  prompt="Refactor the auth module to use JWT",
  tools=["view", "edit", "bash"]
)

The child agent runs concurrently. Use wait_agent(ids=[...]) to block until it finishes, or get_agent_output(id="...") to poll without blocking.

Shared workspace claims

In the full app, concurrent agents share BMO’s data directory, session/message stores, and working tree. BMO coordinates that live tree with workspace_claim: soft claims publish intent, hard claims block overlapping BMO mutation tools that consult the claim guard, and /workspace-claims shows active owners and negotiation state.

Claims are process-local and advisory. They are useful for same-tree BMO coordination, but they are not durable locks and they do not stop external editors, shell commands, or a separate BMO process from changing files. Use worktree isolation when you need filesystem-level separation.

Sub-agent tool reference

Tool	Description
spawn_agent	Spawn a child agent with a prompt and scoped tool set
wait_agent	Block until a child agent completes; stream or collect output
send_input	Inject a follow-up message into a running child agent
get_agent_output	Read partial or final output without blocking
close_agent	Terminate a child agent and release its resources
list_agents	List all active child agents with their status

Worktree isolation

Pass worktree: true to give the child agent its own git branch and filesystem copy:

spawn_agent(
  prompt="Refactor the auth module",
  worktree=True
)

The response includes worktree_path and worktree_branch so you can inspect or merge the output. See Worktree Isolation for full details.

Concurrency limits

[options]
agent_max_depth = 1    # max spawn depth (-1 = unlimited)
agent_max_threads = 6  # max concurrent sub-agent goroutines (-1 = unlimited)

Teams

Teams are persistent groups of goal-oriented sub-agents. Create a team and assign tasks to its members:

create_team(
  name="api-team",
  goal="Refactor the auth module to use JWT",
  teammates=[
    {"name": "architect", "prompt": "Design the migration plan", "model": "large"},
    {"name": "implementer", "prompt": "Land the code changes", "tools": ["view", "edit", "bash"]},
    {"name": "reviewer", "prompt": "Review the resulting diff"}
  ]
)

Teams support structured task management with team_create_task, team_update_task, team_list_tasks, and message passing via team_send_message / team_read_messages. Shut down with team_shutdown.

Remote team server

For cross-machine team coordination, point BMO at a remote team backend:

[options.teams]
server_url = "https://bmo-team-server.example.com"
token = "${BMO_TEAMS_TOKEN}"

CSV fan-out

spawn_agents_on_csv fans out one agent per row in a CSV file:

spawn_agents_on_csv(
  csv_path="tasks.csv",
  instruction="Process row {row}: update {file}"
)

Each row becomes an isolated job. Workers use report_agent_job_result for structured result reporting. Progress is visible via /team in the TUI.

Team lifecycle hooks

Control team quality gates with hooks that run on agent idle or task completion:

[[options.team_hooks.teammate_idle]]
type = "command"
command = "validate-output"

[[options.team_hooks.task_completed]]
type = "command"
command = "run-acceptance-tests"

Exit code 2 from a team hook blocks completion and re-injects stderr back to the agent.

Related

• Agent Mesh — Discover and invoke remote A2A agents by capability (e.g. “run_tests”) when using invoke_a2a.
• A2A Protocol — Call remote A2A agents by URL and run BMO as an A2A server.
• For orchestration at scale and building apps on BMO (scheduler, server API, programmatic entrypoints), start with Workflow map and How BMO thinks and acts. Those pages give the current product-facing map; the repo roadmap remains the maintainer planning artifact.