Agent Mesh

Agent Mesh lets BMO resolve a remote A2A target by capability instead of a fixed URL. Instead of wiring “call this specific endpoint,” you can ask for the capability you need and let the registry pick a target.

Maturity: Advanced integration surface. Mesh is for capability-based remote delegation after A2A is already part of your operating model; it is not required for local sub-agents or normal TUI work.

flowchart LR request["invoke_a2a(capability=...)"] --> registry["Mesh registry resolve"] registry --> candidate["Candidate endpoint"] candidate --> invoke["A2A invocation"] invoke --> result["Outcome returned to current run"]

When to use it

You have several A2A-compatible agents and want to call them by role or capability.
You want to delegate to “whatever agent can do X” without hard-coding URLs.
You run multiple BMO instances (or mixed agents) and use a shared registry for cross-machine resolve.

If you only ever call one known remote agent, use A2A with agent_card_url and leave mesh disabled.

Handoff: Mesh selects a capable peer; A2A runs the remote Task. Results are proposals or evidence until your workspace accepts them—not automatic local apply. Maintainer topics: Agent mesh and A2A (handoff-plane map lives in the agent-cli workspace docs/meta-design/ when using a monorepo checkout).

What you should see

Capability resolution produces an explicit target before the A2A invocation. The selected peer performs work inside its own authority boundary and returns an outcome to the current run for synthesis.

For workstream or factory-shaped runs, treat that outcome as a remote proposal or imported evidence until local policy, review, and workspace authority accept or apply it. Mesh chooses a capable peer; it does not grant local apply authority or replace workspace claims.

Enable the mesh

In your config (e.g. bmo.toml or ~/.config/bmo/bmo.toml):

[options.mesh]
enabled = true

For a single BMO process, that uses an in-process registry. For cross-machine use, point at a registry server:

[options.mesh]
enabled = true
registry_url = "https://mesh.example.com"

Optional: restrict which capabilities the agent may use:

[options.mesh]
enabled = true
allowed_capabilities = ["run_tests", "lint", "code_review"]

A2A must be enabled for invoke_a2a to work; mesh only changes how the target is chosen when you use a capability.

Using capability-based invoke

When mesh is enabled, the agent can call invoke_a2a with a capability instead of agent_card_url:

invoke_a2a(capability="run_tests", message="Run the full test suite")

BMO resolves the capability in the registry and then invokes the chosen target. If you also pass agent_card_url, the URL wins and the registry is skipped.

`mesh_resolve` vs `invoke_a2a`

Step	Tool	What it does
Discover	`mesh_resolve`	Returns ranked candidates (`node_id`, endpoint) for a capability—yellow-pages query only.
Execute	`invoke_a2a`	Sends the message and owns the remote A2A task (`task_id`, state, follow-ups).

Use mesh_resolve when you need to inspect or form a team before invoking. Use invoke_a2a(capability=…) when you want resolve + invoke in one call (what most prompts use). create_team can bundle mesh discovery with local teammates.

Inspecting why a resolve ranked the way it did

Use the explanation family when you need the live resolver stack instead of just the candidate list:

Surface	Use
`bmo config show-mesh-explain --capability run_tests`	Read one live resolve from the shell.
`/mesh-explain run_tests`	Inspect the same resolve from the TUI.
`GET /v1/mesh/explain?capability=run_tests`	Read the JSON snapshot over HTTP.
`get_mesh_resolve_explanation`	Agent-tool access to the same JSON body.

The explanation reports whether dispatch, outcome routing, and niche routing were active, bypassed, disabled, or degraded for that lookup.

Transport fallback

When mesh returns multiple remote candidates, invoke_a2a tries them in order. If the first peer is unreachable (network error), BMO attempts the next candidate—re-bid on transport failure, not on input-required or task failure from a reachable peer.

Registry types

Mode	Config	Use case
In-process	`enabled = true`, no `registry_url`	Single BMO; registry is local to this process.
Server-backed	`enabled = true`, `registry_url = "https://..."`	Multiple BMO instances or agents; they all register and resolve via the same server.

How it fits with other BMO coordination features

Use sub-agents when the work should stay inside one BMO session.
Use mesh when the work should be delegated to a remote A2A peer selected by capability.
Use agent kinds when you want to inspect which local roles exist in your effective config.
Use a workstream record when remote output needs to be reviewed alongside delegated lanes, verification, and residual work.

Options

Option	Default	Description
`enabled`	`false`	Enable the mesh (registry and capability-based resolve).
`registry_url`	(empty)	Base URL of the registry server; empty = in-process registry.
`allowed_capabilities`	(empty)	Allowlist of capabilities for resolve/invoke; empty = allow all.

A2A Protocol — Using invoke_a2a with a URL, continuing tasks, and running BMO as an A2A server.
Multi-Agent Workflows — Spawning sub-agents, teams, and CSV fan-out inside a BMO session.
Agent kinds — Configured local roles, prompts, and tool policy.
Implementation notes: agent-mesh.md

Visual: capability-resolution topology

Capability-resolution topology

Current runRequests a capability such as test, review, or deploy check.

Mesh registryMaps capability to eligible peers and endpoint metadata.

Selected peerA2A-compatible target receives the bounded request.

Remote executionThe peer performs work within its own authority boundary.

OutcomeResult returns to the current run for synthesis and next action.

FallbackIf no capability resolves, use an explicit URL or local sub-agent path.

Mesh is capability routing; it does not make remote agents part of the local session state.