beeos-ai/bma-sdk is generated from the BMA contracts. Only authentication, error decoding, the event stream and verified artifact downloads are handwritten. It has two parts: The standard /v1 routes (agents, environments, sessions, events, files, memory stores) are intentionally not wrapped: use the official Anthropic SDK for those, and bma-sdk only for what BMA adds.

Install

Authenticate

The native client sends a BMA API key (organization bma_org_v1_… or personal bma_pat_v1_…) as Authorization: Bearer. The base URL includes /api/v1. Always pass it: the built-in default (https://api.bma.beeos.ai/v1) is not live; on staging use https://api.staging.bma.beeos.ai/api/v1.
Native routes are scoped by organization and project ids (/orgs/{orgID}/projects/{projectID}/…); GET /me returns the organizations a personal key can see.

Run a session on an existing agent

Create a session, send input, and stream its events.
Stream frames are agent_event (durable, with a sequence), tool_call_update, model_output_delta (preview) and error. Resume with lastEventId / LastEventID / last_event_id set to the last sequence you processed.

Errors

Every language turns non-2xx responses into one error type with the HTTP status, the BMA code and a retryable flag: *bmarest.APIError (via CheckResponse), BmaApiError (via unwrap), BmaApiError in Python.

Artifacts and files

Artifacts the agent produces are downloaded with DownloadArtifact / downloadArtifact / download_artifact, which refuse content larger than the limit you pass and verify the recorded size and sha256. Project files are uploaded once (POST /files) and mounted into sessions (POST …/sessions/{sessionID}/resources); see Files & outputs.

Managed Agents extensions

FacadeExtensionsClient talks to the /v1 origin (without /v1) with the org API key as x-api-key and the project as x-bma-project-id.
The package also exports the extension field types: ModelConfigOverride (agent.model.api_url/api_key/api_format), MCPServerBMAAuth (mcp_servers[].bma_auth), IDEMPOTENCY_KEY_HEADER, and bmaSequence(event) / bma_sequence(event) / EventBMASequence to read the resume cursor from an Anthropic SDK event.

Compatibility