Claude Managed Agents compatibility

BMA serves a compatible subset of the Claude Managed Agents API (beta managed-agents-2026-04-01). Point the official Anthropic SDK (Python ≥ 2.3 or TypeScript ≥ 1.3) at BMA by setting base_url and using a BMA API key, and the capabilities listed below work. BMA is not a drop-in replacement: the unsupported list and the behavior differences below apply. The rule BMA follows for requests: a field BMA cannot honor is rejected with 400 and an error.code that names it (usually unsupported or unsupported_session_override) instead of being accepted and ignored. The known exceptions are listed below until they are fixed. Models and sandbox specifications are outside API compatibility. BMA runs the models configured for your organization (model ids are BMA model names, not Claude model ids), and its sandboxes use BMA’s own machine images and sizes, not the Claude cloud sandbox (Ubuntu 24.04, 8 GB memory, 10 GB disk). See Machines.

​

Supported subset

​

Not supported

• Endpoints: Skills, Vaults (and credentials), Deployments and deployment runs, Dreams, Tunnels, User profiles, GET /v1/agents/{id}/versions, session thread endpoints, session resource retrieve/update, memory store archive, memory versions.
• Multi-agent orchestration and threads, outcomes (user.define_outcome), budgets, self_hosted environments and their work queue endpoints.
• github_repository session resources.
• Agent history: retrieving or starting a session on an older agent version.
• Image and document content blocks in user.message; system.message.
• user.custom_tool_result. Return custom tool results with the BMA extension event user.tool_result instead.
• On create: session metadata, vault_ids, budget; tool, skill and MCP overrides in agent_with_overrides (400 unsupported_session_override). Set session metadata with an update after create.
• Agent fields: the read, write, edit, glob and grep built-in tools (accepted only with enabled: false; the agent works on files through bash); web_fetch/web_search options allowed_domains, blocked_domains, max_content_tokens, url_sources, user_location; pinned skill versions and type: "anthropic" skills; execution_identity other than service_account; any multiagent.
• Environment fields: networking.type: "limited" (BMA cannot enforce an egress allowlist on its sandbox provider); cargo, gem and go packages.
• created_at[…] filters on the event list (400).

Unsupported fields are rejected with 400 and error.code = "unsupported". Paths outside the served endpoints (for example /v1/skills or /v1/vaults) return 404 with a plain {"error": "not found"} body instead of the Anthropic error envelope; the SDKs still raise their not-found error.

​

Known exceptions

These requests are currently ignored instead of rejected, until they are fixed:

• GET /v1/files?ids[]=… returns all files, not only the listed ids.
• include_archived on the session list is ignored, and the list includes archived sessions by default.
• GET /v1/agents/{id}?version=N returns the current version.
• expires_in_seconds on file upload is ignored when sent after the file part (rejected when sent before it).

​

Behavior differences

• IDs use BMA prefixes (aprf_ for agents, mpo_ for environments, ses_ for sessions).
• Model ids are BMA model names.
• Tool events: agent.tool_use.name is the BMA tool name (for example run_command instead of bash), and its input carries machine_id. MCP calls are reported as agent.tool_use with the name mcp__<server>__<tool>, not as agent.mcp_tool_use. Custom tool calls are reported as agent.tool_use, not as agent.custom_tool_use.
• Errors in a session: session.error does not yet use the official error types: error.type is "error" or "unknown_error", retry_status is null, and the turn ends with session.status_idle stop_reason: {"type": "error"} instead of retries_exhausted. error.code carries the BMA detail (for example context_too_large).
• Session list: pagination is per agent, so with many sessions per agent a page can miss sessions; a hidden default session of each agent can appear in the list; without order the list is not sorted newest first.
• Event ids: a streaming preview has a different id from the final agent.message, and the user.message id in the send response differs from the id in the stream and history. Use agent_input_id and bma_sequence to correlate.
• Usage is counted per BMA agent, so every session of the same agent reports the agent total.
• Agents: archive deletes the agent, so a later retrieve is 404. Changing only description or metadata does not create a new version. Permission policy auto becomes always_ask.
• Environments: the list returns every environment on one page; the stored config is limited to 512 bytes.
• Sessions: delete archives instead of deleting (retrieve still returns the session with status terminated). Machines start on the first tool call that needs one, not at session create, so chat-only sessions never hold a machine. Status rescheduling means work is queued while the machine is provisioned, resumed or restored.
• Session lifecycle events: session.status_rescheduled, session.status_terminated, session.deleted, session.usage, span events and agent.thread_context_compacted are not emitted.
• Memory stores: the store name is stored as a slug and store metadata is not kept; a memory id changes when its path changes; the returned mount_path does not exist on the machine.
• SSE: after the opening : ok comment the stream sends no keepalive pings.
• HTTP: no request-id response header and no request_id in errors; error bodies add error.code; a malformed id returns 400 instead of 404; no rate-limit or retry-after headers; an oversized body (over 8 MiB) is 400, not 413; an unknown route or wrong method is 404, never 405.
• Sessions without a title get one generated after the first turn (session.updated).

​

How BMA maps the objects

​

Authentication and headers

​

Agents

• description and metadata are stored (16 keys, key ≤ 64, value ≤ 512 characters).
• system is optional; tools: [] clears the toolset.
• Built-in tools: bash maps to BMA’s run_command; web_fetch and web_search map to BMA’s web tools.
• Permission policies: always_allow and always_ask map directly; auto becomes always_ask.
• Skills: {type: "custom", skill_id, version} with version omitted or "latest"; BMA always runs the latest revision.
• MCP: URL servers. BMA adds mcp_servers[].bma_auth (bearer, oauth, sigv4) that references a project secret.

​

Sessions and events

• Stream start: a stream opened without Last-Event-ID delivers events emitted after it opens, like Anthropic. If you send first and subscribe second while a turn is running, the stream starts just before that turn’s input so you still get the whole turn.
• Resume: durable events carry bma_sequence (BMA extension). Resume history from next_page and the stream with Last-Event-ID: <bma_sequence> or the opaque id of the last durable frame. Last-Event-ID: 0 replays the whole session.
• user.interrupt stops only that session’s turn; the next user.message continues the conversation.
• See Machines for when machines start, pause and resume.

​

BMA extensions

All optional. A client that only implements the Anthropic contract can ignore them. Typed helpers for these are in bma-sdk; the schemas are in the API reference.