Agents

BMO uses the word agent in more than one sense. Agent kinds are configured roles in merged config. Coordination surfaces are the runtime mechanisms that delegate work (local child runs, background nanites, teams, remote mesh/A2A, CSV jobs, arena, automation). Live children are the in-session runs you inspect with /agents or /agent-family.

This guide orients you across those axes so you can pick the smallest surface that fits the job — before you read eight feature pages in isolation.

flowchart TD
  q1{"Need interactive steering\nor approval per step?"}
  q1 -->|yes| sub["spawn_agent / agent tool\n(subagent pool)"]
  q1 -->|no| q2{"Remote peer or\ncapability routing?"}
  q2 -->|yes| mesh["mesh_resolve + invoke_a2a"]
  q2 -->|no| q3{"Shared task queue,\nmailbox, shutdown?"}
  q3 -->|yes| team["create_team / teams backend"]
  q3 -->|no| q4{"Bounded background\nside work?"}
  q4 -->|yes| nanite["bmo nanite run / enqueue"]
  q4 -->|no| q5{"Compare candidates\non same prompt?"}
  q5 -->|yes| arena["Arena"]
  q5 -->|no| q6{"One prompt per CSV row?"}
  q6 -->|yes| csv["spawn_agents_on_csv"]
  q6 -->|no| direct["Primitives or staged workflow"]

Naming disambiguation

Term	Means	Inspect with	Not
Agent kind	Configured role (`coder`, `task`, custom `options.agents.<id>`)	`/agent_kinds`, `list_agent_kinds`	Live spawned children
Live child / subagent	In-process delegated run in the current session	`/agents`, `/agent-family`	Agent kinds registry
Nanite	Budget-bounded background micro-run on the nanite pool	`/spawn-status`, workstream `last_nanite_*`	Renamed subagent
Team	Shared goal, task list, mailbox, shutdown path	`/team`, `bmo team status`	Mesh routing
Mesh peer	Remote agent chosen by capability tag	A2A task status, `/a2a`	Local spawn pool
Agent job (CSV)	One worker per CSV row with structured reporting	Parent output, `/team`	Durable team state

Kinds tell you which prompt, mesh tags, and tool policy apply. Coordination surfaces tell you how work is delegated and which pool owns capacity.

Coordination surfaces

Surface	Best for	Entry	Capacity guard	Interactive	Main inspect
`spawn_agent` / `agent`	One focused local task with steering	Parent tool turn	`options.agent_max_threads`, per-agent `[delegation]`	Yes	`/agents`, `/agent-family`
`bmo nanite run`	Bounded background check, summary, or handoff	CLI or enqueue	`options.nanite_max_threads`	No	`/spawn-status`, workstream status
`create_team`	Shared tasks, mailbox, blockers, lifecycle	Parent tool turn	Team backend + spawn limits	Async mailbox	`/team`
`mesh_resolve` + `invoke_a2a`	Remote work by capability, not fixed URL	Parent tool turn	Remote + local policy	Remote async	`/a2a`, A2A logs
`spawn_agents_on_csv`	Same prompt template per CSV row	Parent tool turn	`max_concurrency` + spawn limits	Per-row worker	`/team`, output CSV
`orchestrate_workflow` / `execute_dag`	Ordered remote calls with checkpoints	Workflow tools	Workflow + remote limits	Pause/resume per node	Workflow result tools
Arena	Compare candidates on the same prompt	Arena surfaces	Arena config	Review-oriented	`/arena`
Automation rules / compaction	Event-driven or idle-gated follow-on	Config + events	Rule dedupe, compaction gates	No	Logs, `/compaction`

For nanite vs subagent detail, see the comparison table in Nanites. For remote protocol roles, see Protocols.

Agent kinds

Agent kinds are the local role catalog: which prompts, mesh capability tags, and explicit tool allowlists BMO knows about in your effective config. They are data-defined in merged config and prompt profiles — not a fixed marketing list.

Question	Open
Which roles exist in my config?	`/agent_kinds`, `list_agent_kinds`, `GET /v1/agent-kinds`
Which children are running now?	`/agents`, `/agent-family`, `list_agents`
Which remote peers match a capability?	`mesh_resolve`, Agent Mesh

When spawning a child, you can pass an agent parameter to select a kind. Kinds do not replace choosing a coordination surface: a task kind still runs through spawn_agent (subagent pool) unless you explicitly use nanite, team, or remote paths.

Start here: Agent kinds.

Runtime authority and boundaries

Boundary	Rule
Subagent pool vs nanite pool	Separate concurrency guards; both can be active
Teams vs mesh	Teams own shared task/mailbox state; mesh only routes remote peers
Workflow tools vs primitives	Workflows own control flow; they do not bypass permission gates
Full app vs minimal MCP	Shared session/claims apply in full app; minimal MCP is scoped filesystem only
Workspace claims vs worktrees	Claims coordinate BMO mutation paths; worktrees give filesystem separation
Arena vs worker pool	Arena compares candidates; it is not long-lived parallel execution

Hidden unattended autonomy is not the product contract. Long-running or delayed work should stay visible through inspectable surfaces (spawn status, teams, workflows, rules, compaction).

Entry surface

If you work in…	Start with…
TUI	`/agent-family` (live children), `/agent_kinds` (role catalog), `/spawn-status` (pool posture), `/team` (teams and CSV jobs)
CLI	`bmo nanite run`, `bmo config show-spawning`, `bmo team status`
HTTP / MCP	`GET /v1/spawn/status`, `get_spawn_status`, `list_agent_kinds`, A2A and mesh tools when exposed
Integrator	This guide + Workflow map + Protocols

Walkthrough: parallel refactor with the right surface

Setup: You want three independent test-writing tasks in one session, with visibility into each child and no remote peers involved.

Step	Choice	Action	Question answered
1	Surface	`spawn_agent` per task (not nanite — you may steer approvals)	Is this interactive delegation?
2	Kind	Default or `agent: "task"` if configured	Which prompt/tools apply?
3	Inspect	`/agent-family` ranked view	Who is running and in what state?
4	Pool	`/spawn-status` if saturated	Are subagent or nanite pools full?
5	Recovery	`esc` on parent; `close_agent` for held slots	Are cancelled children still holding slots?

If the same work were a 30-second diff summary with no steering, use nanite instead and read last_nanite_* on the bound workstream.

Pick your job

Need a configured role catalog?
  → /agent_kinds → Agent kinds feature page

Need live children in this session?
  → /agent-family → /agents → list_agents

Parallel local tasks with steering?
  → spawn_agent → Multi-Agent Workflows guide

Quick bounded background pass?
  → bmo nanite run → Nanites feature page

Shared task list and mailbox?
  → create_team → Teams feature page

Remote peer by capability?
  → mesh_resolve + invoke_a2a → Agent Mesh + A2A

Same prompt per CSV row?
  → spawn_agents_on_csv

Pool saturated or drain mode?
  → /spawn-status → get_spawn_status

Compare candidates on one prompt?
  → Arena feature page

Multi-Agent Workflows — recipes for parallel work, CSV fan-out, teams, worktrees
Workflow map — where agents fit in the four common branches
Agent kinds — role registry and mesh tags
Nanites — background micro-runs and handoff
Agent Mesh — capability-based remote routing
How BMO thinks and acts — shared workspace and agent-native model

Maintainer routing detail: multi-agent orchestration surface.