BMA’s /v1 routes use the Anthropic Managed Agents object model, so the official Anthropic SDKs for Python and TypeScript work against a BMA deployment once you set the base URL and use a BMA API key. The quickstart walks through agents, environments, sessions and events with them. Which fields and endpoints the core serves, and where it differs, is on Use the official Anthropic SDK. bma-sdk 2.1.0 is the official SDK plus the BMA extensions in one client, for Go, TypeScript and Python. The shared resources (agents, environments, sessions, events, files, skills, vaults, memory stores) are the official SDK’s own; the extensions (machines, machine pools, desktop and terminal sessions and their tickets, projects) are typed methods under client.beta. Install it below for typed extension methods and resumable send-and-stream, or keep using the official SDK as shown after it. The 1.x line (native /api/v1) is frozen and not covered by these docs.

Connect

The SDK sends the key as x-api-key, adds anthropic-version and the Managed Agents anthropic-beta header, and appends /v1 to the base URL. Pass the API origin, without a path. x-bma-project-id selects the project; it is optional when the key sees only one.
Python needs anthropic 2.3 or newer and TypeScript @anthropic-ai/sdk 1.3 or newer. Python behind a proxy that cannot reach the BMA host: set no_proxy for it.

Managed Agents extensions

Extension resources follow the Anthropic style: top-level plural paths (/v1/machines, /v1/terminal_sessions, /v1/desktop_sessions, /v1/vaults, /v1/skills, /v1/machine_pools), POST for updates and actions, {data, next_page} lists, the Anthropic error envelope and Idempotency-Key on creates. They are listed in the API reference. The official SDKs have no methods for them, but their generic get / post use the same client, key, headers, retries and errors:
Fields BMA adds to Anthropic objects are top-level bma_* properties, for example bma_sequence on events. The SDKs return them as unknown fields (event.bma_sequence in Python, (event as any).bma_sequence in TypeScript), and request fields can be sent with extra_body (Python) or body (TypeScript). The full list is on Use the official Anthropic SDK.

Install bma-sdk

The clients read BMA_API_KEY, BMA_BASE_URL (the API origin) and BMA_PROJECT_ID, and never the ANTHROPIC_* variables, so an Anthropic key is never sent to BMA. Go needs 1.25 or newer, TypeScript Node.js 20 or newer (ESM), Python 3.10 or newer.

Send and stream (resumable)

The usual pattern opens the stream first, then sends. A caller that sends first (a worker that subscribes on its own schedule, a reconnecting backend) must not open a live-only stream afterwards: the executor can write the turn’s first frames before the stream opens, and they are lost. SendAndStream (Go), sendAndStream (TypeScript) and send_and_stream (Python) send the events, read bma_resume_cursor from the send response (the session’s last event sequence before the send) and open the resumable stream with Last-Event-ID set to it, so frames written before you subscribed are not lost. A reconnect before the first durable frame reuses the cursor.
  • Within one sequence the user.message can come after session.status_running; the stream continues after the cursor, so it contains the message.
  • The id in the send response is the input (ain_…). Match it to the user.message on the stream through bma_input_id.
  • With no cursor (an idempotent replay whose input is not admitted yet) the stream starts at Last-Event-ID: 0 and replays the session; replayed is true, so pick your turn by bma_input_id. A send without a user.message, such as an interrupt, streams from the server’s default position (new events only).
  • Over plain HTTP, send first, then GET /v1/sessions/{id}/events/stream with the header Last-Event-ID: <bma_resume_cursor>.

Keep keys on your server

Run the SDK only in your backend. A browser, desktop app or phone talks to your backend; for live connections (remote desktop, terminal) your backend mints a single-use ticket with the calls above and hands only that ticket to the client. See Desktop & computer use.

Executors

To connect your own machine or agent loop to BMA, use bma-executor-sdk. It is a separate SDK with its own protocol.