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 (organizationbma_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.
/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.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 BMAcode and a retryable flag: *bmarest.APIError (via CheckResponse), BmaApiError (via unwrap), BmaApiError in Python.
Artifacts and files
Artifacts the agent produces are downloaded withDownloadArtifact / 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.