Use the official Anthropic SDK

This is an operations page for apps that already use the official Anthropic SDK. BMA’s /v1 routes use the object model of the Anthropic Managed Agents API (beta managed-agents-2026-04-01): agents, environments, sessions and events. Point the official 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. The routes serve a subset of that API: the unsupported list and the behavior differences below apply. The quickstart uses exactly this connection. 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 not part of the /v1 API shape. 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: Skill version endpoints, 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, creating self_hosted environments, and the 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.
• On create: vault_ids, budget; tool, skill and MCP overrides in agent_with_overrides (400 unsupported_session_override).
• 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/deployments) 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:

• 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: built-in tools that have an official name (bash, web_fetch, web_search) are reported as agent.tool_use under that name; a BMA tool without an official counterpart (for example create_machine) keeps its BMA name and its machine_id argument. MCP calls are agent.mcp_tool_use and custom tool calls are agent.custom_tool_use, as in the official API.
• Errors in a session: session.error uses the official error types; a failure with no official type is unknown_error, and error.code carries the BMA detail (for example context_too_large). A turn that ends in an error ends with session.status_idle stop_reason: {"type": "retries_exhausted"}.
• Session list: one project-wide sequence of pages, newest first by default (order=asc reverses it); each agent’s internal default session never appears and archived sessions appear only with include_archived=true. The statuses, created_at and agent_version filters act on the fetched page, so a page can be short while next_page is still set.
• 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 keeps the agent: a later retrieve returns it with archived_at, lists exclude it unless include_archived=true, and it rejects updates and new sessions. Changing only description or metadata does not create a new version. Permission policy auto becomes always_ask.
• Environments: 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 is where the store is mounted on machines that can mount (/mnt/memory/<store>).
• SSE: after the opening : ok comment the stream sends a ping event whenever it has been silent for 15 seconds.
• HTTP: responses carry a request-id header and errors a request_id; error bodies add error.code; 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. Call them with the generic request methods of the official SDKs; the schemas are in the API reference.