Agent capability (external brain)

Preview. The contract and the SDKs (Go, TypeScript, Python) are complete. The BMA platform side is deployed with text input only; file inputs are refused explicitly.

By default BMA’s server harness runs every session. With the agent capability, an executor that contains a complete agent (its own model loop and tools, for example a desktop app) serves the sessions instead: BMA delivers each user turn to it, and it streams Managed Agents events back. Clients see the same sessions, the same event log and the same /v1 stream either way.

How it fits

Bind an agent to an executor

Connect your executor with a machine token and advertise capabilities.agent in executor.register (models, permission modes, interaction kinds, max_sessions). The SDK does this for you with ServeAgent / serveAgent / serve_agent.
Bind the BMA agent to that machine:

curl -sS -X PUT "$BMA_BASE_URL/api/v1/orgs/$ORG/projects/$PROJ/agents/$AGENT/executor-binding" \
  -H "Authorization: Bearer $BMA_API_KEY" -H "content-type: application/json" \
  -d '{"machine_id": "mch_..."}'

GET …/executor-binding returns the bound machine and the agent capability its executor last registered. From then on:

Session operation	Becomes on the executor
input (`user.message`)	`turn.start`, or `turn.input` while a turn runs
cancel (`user.interrupt`)	`turn.cancel`
archive	`session.close`

Input queues while the executor is offline and is delivered when it reconnects.

Protocol

Method	Direction	Purpose
`turn.start`	platform → executor	Open or resume the session and start a turn; idempotent by `turn_id`
`turn.input`	platform → executor	Add input to the running turn; idempotent by `input_id`
`turn.cancel`	platform → executor	Stop the turn; the session stays
`session.close`	platform → executor	Release the local conversation
`interaction.response`	platform → executor	Approval or answer
`session.event`	executor → platform	Durable agent event; the response is the ACK
`session.event_delta`	executor → platform	Streaming preview, may be lost
`interaction.request` / `interaction.cancel`	executor → platform	Ask for, or withdraw, an approval or answer

The executor stores its local conversation handle in executor_session_ref; BMA sends it back on the next turn.start, so the executor can resume after a restart.

What the server harness does that an external brain does not

Context compaction, context_too_large handling, automatic session titles and BMA’s built-in tools belong to the server harness. An external brain manages its own context and tools, and can still use BMA machines through the hand side of the protocol.

Get started

Concepts

Executor & brains

Agent capability (external brain)

How it fits

Bind an agent to an executor

Protocol

What the server harness does that an external brain does not

​How it fits

​Bind an agent to an executor

​Protocol

​What the server harness does that an external brain does not

How it fits

Bind an agent to an executor

Protocol

What the server harness does that an external brain does not