For the complete documentation index, see llms.txt. This page is also available as Markdown.

Agents API

Register external agents, list the first-party agent catalog, route events to agents, run agents end-to-end, inspect runs, and halt agents.

Operation
Endpoint

Register an external agent

POST /v1/execution/agents/register

List first-party agent catalog

GET /v1/agents

Get an agent (definition; registration not yet wired)

GET /v1/agents/{agent_id}

List an agent's actions

GET /v1/agents/{agent_id}/actions

Route an event/intent

POST /v1/agents/route

Run an agent end-to-end

POST /v1/agents/run

Enqueue an event for async routing

POST /v1/agents/events

Inspect a routing decision

GET /v1/agents/routing-decisions/{id}

List runs

GET /v1/agents/runs

Run detail

GET /v1/agents/runs/{run_id}

Why a run did what it did

GET /v1/agents/runs/{run_id}/why

Evidence used for a run

GET /v1/agents/runs/{run_id}/evidence

§6 gate trace for a run

GET /v1/agents/runs/{run_id}/gate-trace

Canonical Proof for a run

GET /v1/agents/runs/{run_id}/proof

Halt one agent

POST /v1/agents/{agent_id}/halt

Halt every agent in a category

POST /v1/agents/halt-category

MCP JSON-RPC entry

POST /v1/agents/mcp (see MCP Server API Reference)

Register an External Agent

External agents are registered by an execution:admin caller. Brain stores the record in a pending_onchain state; the caller supplies the identity fields and, optionally, the on-chain attestation references (scope_hash, onchain_address, registered_tx) once the BrainMCPAgentRegistry write exists.

agent_id, role, and display_name are required; scope_hash (hex), onchain_address, and registered_tx are optional.

Response (201 Created):

The agent then connects over MCP using a JWT whose scope_hash claim must equal the scope_hash stored on-chain. The MCP server verifies that match on every call.

List the First-Party Agent Catalog

GET /v1/agents returns the internal first-party agent definitions (capability, category, default-enabled state). Not the external-agent registry.

Filters: kind, capability, category (business | consumer | agnostic), state (enabled | disabled).

Get an Agent

Returns { "definition": <catalog def with shadow_mode>, "registration": null }. The on-chain registration join is not wired yet, so registration is always null today; the BrainMCPAgentRegistry reader is a pending follow-up.

Route an Event

The router scores candidate agents by capability + tenant scope grants + evidence and returns the best one. Routing is advisory. The selected agent still proposes through the gated path. The selection is itself an audit event.

Provide event (a domain-event name) or intent (free-form text), plus optional context. Tenant-equality required.

Field
Meaning

selected_agent_id

The chosen agent, or null when nothing matches

fallback_agent_ids

Other eligible agents, best first

confidence

Router confidence in the selection (0..1)

evidence_score

Fraction of the agent's required evidence that is present (0..1)

policy_status

routed, unscoped (matched but tenant scoped none), or no_match

execution_mode

execute, propose, confirm, notify_only, reject, or null

Run an Agent End-to-End

The full route → resolve action → dry-run §6 gate → persist agent_runs row → propose pipeline. Money-movers are shadowed by default. A financial proposal from an un-promoted agent terminates as shadow_completed and moves no money. Going live is a deliberate per-agent promotion with strict caps + allowlisted rails.

A proposal-layer idempotency collision returns 409 with agent_proposal_duplicate.

Enqueue an Event (async)

Routing Decisions & Run History

Endpoint
Purpose

GET /v1/agents/routing-decisions/{id}

Routing decision detail

GET /v1/agents/runs

List runs (filter agent_id, status, category, limit)

GET /v1/agents/runs/{run_id}

Run summary (statuscompleted, failed, shadow_completed, rejected)

GET /v1/agents/runs/{run_id}/why

Structured reason + (redacted) reasoning trace + candidate agents + behavior_hash

GET /v1/agents/runs/{run_id}/evidence

Evidence the run consulted

GET /v1/agents/runs/{run_id}/gate-trace

The §6 gate-check rows for the run's PaymentIntent

GET /v1/agents/runs/{run_id}/proof

Proxy to the canonical Proof artifact for the run's PaymentIntent

GET /v1/agents/{agent_id}/actions

All actions a given agent produced (proposal + payment_intent + status)

Kill-Switch

Endpoint
Purpose

POST /v1/agents/{agent_id}/halt

Pause every in-flight intent for the agent and set its state to quarantined

POST /v1/agents/halt-category

Emergency-stop every agent in a category. Body { "category": "business" }

Both routes are tenant-root and emit audit events. Halting an agent atomically pauses its in-flight PaymentIntents (the rail dispatcher re-reads state immediately before submission and aborts cleanly if the intent was paused).

What's Next

📤 Payment Intents

The Ledger entity agents propose.

📜 BrainMCPAgentRegistry

The on-chain registry.

Last updated