Quickstart

BMA serves the Anthropic Managed Agents API under /v1: agents, environments, sessions and events, with the same paths, request headers and event stream as the official SDKs. This guide uses plain curl, or the official Anthropic SDK for Python or TypeScript with base_url pointed at BMA. You create an agent and an environment, start a session, read what the agent does as a stream of events, and send a second message.

Before you start

You need the values from the introduction:

export BMA_BASE_URL="https://api.staging.bma.beeos.ai"   # API origin, without a path
export BMA_API_KEY="bma_org_v1_..."             # organization API key
export BMA_PROJECT_ID="proj_..."                # project to work in

and the name of a model configured in your project. The examples use deepseek-flash; ask the BMA team which names are configured.

Install the SDK

pip install anthropic

npm install @anthropic-ai/sdk

# curl and jq only

The examples were run against the official anthropic 2.6.0 (Python) and @anthropic-ai/sdk 1.6.0 (TypeScript). The TypeScript examples are ES modules: run them with a TypeScript runner such as tsx.

Create a client

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. x-bma-project-id selects the project; it is optional when the key sees only one.

import os
import time

from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["BMA_API_KEY"],
    base_url=os.environ["BMA_BASE_URL"],  # the API origin; the SDK adds /v1
    default_headers={"x-bma-project-id": os.environ["BMA_PROJECT_ID"]},
)
run = int(time.time())  # agent and environment names are unique in a project

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.BMA_API_KEY!,
  baseURL: process.env.BMA_BASE_URL!, // the API origin; the SDK adds /v1
  defaultHeaders: { "x-bma-project-id": process.env.BMA_PROJECT_ID! },
});
const run = Date.now(); // agent and environment names are unique in a project

API="$BMA_BASE_URL/v1"
H=(
  -H "x-api-key: $BMA_API_KEY"
  -H "anthropic-version: 2023-06-01"
  -H "anthropic-beta: managed-agents-2026-04-01"
  -H "x-bma-project-id: $BMA_PROJECT_ID"
  -H "content-type: application/json"
)
RUN=$(date +%s)   # agent and environment names are unique in a project

Create an agent and an environment

An agent is the model, the instructions and the tools. An environment describes the machines its sessions run on. Neither starts anything: a machine is created when a session first needs one. See Agents and Environments.

agent = client.beta.agents.create(
    name=f"quickstart-{run}",
    model="deepseek-flash",
    system="You are an engineering assistant. Use bash to run shell commands.",
    tools=[{"type": "agent_toolset_20260401"}],
)
environment = client.beta.environments.create(
    name=f"quickstart-env-{run}",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

const agent = await client.beta.agents.create({
  name: `quickstart-${run}`,
  model: "deepseek-flash",
  system: "You are an engineering assistant. Use bash to run shell commands.",
  tools: [{ type: "agent_toolset_20260401" }],
});
const environment = await client.beta.environments.create({
  name: `quickstart-env-${run}`,
  config: { type: "cloud", networking: { type: "unrestricted" } },
});

AGENT_ID=$(curl -sS --fail-with-body -X POST "$API/agents" "${H[@]}" -d '{
  "name": "quickstart-'$RUN'",
  "model": "deepseek-flash",
  "system": "You are an engineering assistant. Use bash to run shell commands.",
  "tools": [{"type": "agent_toolset_20260401"}]
}' | jq -r .id)

ENV_ID=$(curl -sS --fail-with-body -X POST "$API/environments" "${H[@]}" -d '{
  "name": "quickstart-env-'$RUN'",
  "config": {"type": "cloud", "networking": {"type": "unrestricted"}}
}' | jq -r .id)

Start a session

A session is one conversation of an agent in an environment. Its event log is durable: it survives machine loss and reconnects. See Sessions & events.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="quickstart",
)

const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  title: "quickstart",
});

SESSION_ID=$(curl -sS --fail-with-body -X POST "$API/sessions" "${H[@]}" \
  -d '{"agent": "'$AGENT_ID'", "environment_id": "'$ENV_ID'", "title": "quickstart"}' | jq -r .id)

Send a message and stream the reply

Every step of the agent is an event: agent.message carries the model’s text, agent.tool_use and agent.tool_result the tool calls, and session.status_idle ends the turn. The stream delivers events emitted after it opens, so open it first, then send.

def ask(text: str) -> None:
    with client.beta.sessions.events.stream(session.id) as stream:
        client.beta.sessions.events.send(
            session.id,
            events=[{"type": "user.message", "content": [{"type": "text", "text": text}]}],
        )
        for event in stream:
            if event.type == "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text)
            elif event.type == "session.status_idle":
                break


ask("Run `uname -a` and tell me what machine you are on.")

async function ask(text: string) {
  const stream = await client.beta.sessions.events.stream(session.id);
  await client.beta.sessions.events.send(session.id, {
    events: [{ type: "user.message", content: [{ type: "text", text }] }],
  });
  for await (const event of stream) {
    if (event.type === "agent.message") {
      for (const block of event.content) if (block.type === "text") console.log(block.text);
    } else if (event.type === "session.status_idle") {
      break;
    }
  }
}

await ask("Run `uname -a` and tell me what machine you are on.");

curl -sS --fail-with-body -X POST "$API/sessions/$SESSION_ID/events" "${H[@]}" -d '{
  "events": [{"type": "user.message", "content": [{"type": "text", "text": "Run `uname -a` and tell me what machine you are on."}]}]
}'

# a stream opened while the turn runs starts at that turn's message; stop at the end of the turn
curl -sSN "$API/sessions/$SESSION_ID/events/stream" "${H[@]}" -H "accept: text/event-stream" 2>/dev/null \
  | sed '/^event: session.status_idle/q'

The agent’s machine is created on its first tool call, so the first turn waits for the sandbox to start. Machines are described in Machines.If the connection drops, reconnect with the Last-Event-ID header. Every durable event carries bma_sequence; send the last one you processed (Last-Event-ID: 3), or the id of the last SSE frame, and the stream continues after it. Last-Event-ID: 0 replays the whole session.

Send a follow-up

The session keeps the conversation: send another message the same way.

ask("Now list the files in /tmp.")

await ask("Now list the files in /tmp.");

curl -sS --fail-with-body -X POST "$API/sessions/$SESSION_ID/events" "${H[@]}" -d '{
  "events": [{"type": "user.message", "content": [{"type": "text", "text": "Now list the files in /tmp."}]}]
}'

curl -sSN "$API/sessions/$SESSION_ID/events/stream" "${H[@]}" 2>/dev/null \
  | sed '/^event: session.status_idle/q'

Read the history and clean up

The event log is durable: list it any time. Archiving the session ends it and releases its machine; its history stays readable. Archive the agent and the environment when you are done.

for event in client.beta.sessions.events.list(session.id):
    print(event.type)

client.beta.sessions.archive(session.id)
client.beta.agents.archive(agent.id)
client.beta.environments.archive(environment.id)

for await (const event of client.beta.sessions.events.list(session.id)) {
  console.log(event.type);
}

await client.beta.sessions.archive(session.id);
await client.beta.agents.archive(agent.id);
await client.beta.environments.archive(environment.id);

curl -sS "$API/sessions/$SESSION_ID/events?limit=100" "${H[@]}" | jq -r '.data[] | "\(.bma_sequence) \(.type)"'

curl -sS -X POST "$API/sessions/$SESSION_ID/archive" "${H[@]}" > /dev/null
curl -sS -X POST "$API/agents/$AGENT_ID/archive" "${H[@]}" > /dev/null
curl -sS -X POST "$API/environments/$ENV_ID/archive" "${H[@]}" > /dev/null

Next steps

Sessions & events

Event types, listing, resuming a stream

Machines

When machines start, pause, and get rebuilt

Desktop & computer use

Watch a desktop, take over, attach a terminal

SDKs

The official SDKs, the BMA extensions and when you need bma-executor-sdk

Get started

Concepts

Executor & brains

Before you start

Next steps

Sessions & events

Machines

Desktop & computer use

SDKs

​Before you start

​Next steps

Sessions & events

Machines

Desktop & computer use

SDKs

Before you start

Next steps