Quickstart

This guide uses the Managed Agents–compatible API (/v1) with the official Anthropic SDKs. If you already use Claude Managed Agents, change the base URL, the API key and the project header; BMA serves a subset of that API, listed on the compatibility page.

Before you start

You need the three values from the introduction:

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

and a model name that is configured in your project. The examples use deepseek-flash; replace it with yours.

Install the SDK

pip install anthropic

npm install @anthropic-ai/sdk

go get github.com/anthropics/anthropic-sdk-go

# curl and jq only

The examples were checked against anthropic 2.4.0 (Python), @anthropic-ai/sdk 1.4.0 (TypeScript) and anthropic-sdk-go v1.84.0.

Create a client

Point the client at your BMA origin and select the project with the x-bma-project-id header. anthropic-version and anthropic-beta headers are accepted but not required.

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["BMA_API_KEY"],
    base_url=os.environ["BMA_BASE_URL"],  # without /v1
    default_headers={"x-bma-project-id": os.environ["BMA_PROJECT_ID"]},
)

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

const client = new Anthropic({
  apiKey: process.env.BMA_API_KEY,
  baseURL: process.env.BMA_BASE_URL, // without /v1
  defaultHeaders: { "x-bma-project-id": process.env.BMA_PROJECT_ID! },
});

client := anthropic.NewClient(
	option.WithAPIKey(os.Getenv("BMA_API_KEY")),
	option.WithBaseURL(os.Getenv("BMA_BASE_URL")), // without /v1
	option.WithHeader("x-bma-project-id", os.Getenv("BMA_PROJECT_ID")),
)

H=(-H "x-api-key: $BMA_API_KEY" -H "x-bma-project-id: $BMA_PROJECT_ID" -H "content-type: application/json")

Create an agent

An agent is a reusable definition: model, system prompt and tools. This one may run bash without asking for approval.

agent = client.beta.agents.create(
    name="quickstart-agent",
    model="deepseek-flash",  # a model configured in your project
    system="You are an engineering assistant. Use the bash tool to run commands.",
    tools=[{
        "type": "agent_toolset_20260401",
        "configs": [{
            "name": "bash",
            "enabled": True,
            "permission_policy": {"type": "always_allow"},
        }],
    }],
)

const agent = await client.beta.agents.create({
  name: "quickstart-agent",
  model: "deepseek-flash", // a model configured in your project
  system: "You are an engineering assistant. Use the bash tool to run commands.",
  tools: [
    {
      type: "agent_toolset_20260401",
      configs: [{ name: "bash", enabled: true, permission_policy: { type: "always_allow" } }],
    },
  ],
});

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name:   "quickstart-agent",
	Model:  anthropic.BetaManagedAgentsModelConfigParams{ID: "deepseek-flash"},
	System: anthropic.String("You are an engineering assistant. Use the bash tool to run commands."),
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{
				OfBash: &anthropic.BetaManagedAgentsBashToolConfigParams{
					Enabled: anthropic.Bool(true),
					PermissionPolicy: anthropic.BetaManagedAgentsBashToolConfigParamsPermissionPolicyUnion{
						OfAlwaysAllow: &anthropic.BetaManagedAgentsAlwaysAllowPolicyParam{
							Type: anthropic.BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow,
						},
					},
				},
			}},
		},
	}},
})
if err != nil {
	log.Fatal(err)
}

AGENT=$(curl -sS "$BMA_BASE_URL/v1/agents" "${H[@]}" -d '{
  "name": "quickstart-agent",
  "model": "deepseek-flash",
  "system": "You are an engineering assistant. Use the bash tool to run commands.",
  "tools": [{"type": "agent_toolset_20260401",
             "configs": [{"name": "bash", "enabled": true,
                          "permission_policy": {"type": "always_allow"}}]}]
}' | jq -r .id)

Create an environment

An environment describes where the agent’s machines come from. BMA creates it as a machine pool; no machine starts until a session needs one.

environment = client.beta.environments.create(
    name="quickstart-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

const environment = await client.beta.environments.create({
  name: "quickstart-env",
  config: { type: "cloud", networking: { type: "unrestricted" } },
});

environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
	Name: "quickstart-env",
	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
		OfCloud: &anthropic.BetaCloudConfigParams{
			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
				OfUnrestricted: &anthropic.BetaUnrestrictedNetworkParam{},
			},
		},
	},
})
if err != nil {
	log.Fatal(err)
}

ENV=$(curl -sS "$BMA_BASE_URL/v1/environments" "${H[@]}" -d '{
  "name": "quickstart-env",
  "config": {"type": "cloud", "networking": {"type": "unrestricted"}}
}' | jq -r .id)

Start a session

A session is one conversation with the agent, running in the environment.

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, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
	EnvironmentID: environment.ID,
	Title:         anthropic.String("Quickstart"),
})
if err != nil {
	log.Fatal(err)
}

SESSION=$(curl -sS "$BMA_BASE_URL/v1/sessions" "${H[@]}" \
  -d "{\"agent\": \"$AGENT\", \"environment_id\": \"$ENV\", \"title\": \"Quickstart\"}" | jq -r .id)

Send a message and stream the events

Open the event stream first, then send the message, and read until the session goes idle. The first tool call that needs a machine creates it, so expect a short wait before the first bash result.

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": "Run `uname -a` and tell me which OS you are on."}],
        }],
    )
    for event in stream:
        if event.type == "agent.message":
            print("".join(block.text for block in event.content if block.type == "text"), end="")
        elif event.type == "agent.tool_use":
            print(f"\n[tool] {event.name}")
        elif event.type == "session.status_idle":
            break

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: "Run `uname -a` and tell me which OS you are on." }],
    },
  ],
});

for await (const event of stream) {
  if (event.type === "agent.message") {
    for (const block of event.content) if (block.type === "text") process.stdout.write(block.text);
  } else if (event.type === "agent.tool_use") {
    console.log(`\n[tool] ${event.name}`);
  } else if (event.type === "session.status_idle") {
    break;
  }
}

stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
defer stream.Close()

_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
					Text: "Run `uname -a` and tell me which OS you are on.",
				},
			}},
		},
	}},
})
if err != nil {
	log.Fatal(err)
}

for stream.Next() {
	switch event := stream.Current().AsAny().(type) {
	case anthropic.BetaManagedAgentsAgentMessageEvent:
		for _, block := range event.Content {
			fmt.Print(block.Text)
		}
	case anthropic.BetaManagedAgentsAgentToolUseEvent:
		fmt.Printf("\n[tool] %s\n", event.Name)
	case anthropic.BetaManagedAgentsSessionStatusIdleEvent:
		return
	}
}
if err := stream.Err(); err != nil {
	log.Fatal(err)
}

# terminal 1: stream (Ctrl-C after session.status_idle)
curl -sSN "$BMA_BASE_URL/v1/sessions/$SESSION/events/stream" "${H[@]}"

# terminal 2: send the message
curl -sS "$BMA_BASE_URL/v1/sessions/$SESSION/events" "${H[@]}" -d '{
  "events": [{"type": "user.message",
              "content": [{"type": "text", "text": "Run `uname -a` and tell me which OS you are on."}]}]
}'

You will see session.status_running, an agent.tool_use for bash, its agent.tool_result, the agent.message with the answer, and session.status_idle.

Read the history and clean up

The event log is durable: list it any time, and send another user.message to continue the same conversation.

history = client.beta.sessions.events.list(session.id, limit=100)
print([event.type for event in history.data])

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

const history = await client.beta.sessions.events.list(session.id, { limit: 100 });
console.log(history.data.map((event) => event.type));

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

history, err := client.Beta.Sessions.Events.List(ctx, session.ID, anthropic.BetaSessionEventListParams{
	Limit: anthropic.Int(100),
})
if err != nil {
	log.Fatal(err)
}
for _, event := range history.Data {
	fmt.Println(event.Type)
}

_, _ = client.Beta.Sessions.Archive(ctx, session.ID, anthropic.BetaSessionArchiveParams{})
_, _ = client.Beta.Environments.Delete(ctx, environment.ID, anthropic.BetaEnvironmentDeleteParams{})
_, _ = client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{})

curl -sS "$BMA_BASE_URL/v1/sessions/$SESSION/events?limit=100" "${H[@]}" | jq -r '.data[].type'

curl -sS -X POST "$BMA_BASE_URL/v1/sessions/$SESSION/archive" "${H[@]}" -d '{}'
curl -sS -X DELETE "$BMA_BASE_URL/v1/environments/$ENV" "${H[@]}"
curl -sS -X POST "$BMA_BASE_URL/v1/agents/$AGENT/archive" "${H[@]}" -d '{}'

Archiving an agent in BMA deletes its definition: a later GET /v1/agents/{id} returns 404. See compatibility.

Next steps

Sessions & events

Event types, resuming a stream, idle and requires_action

Approvals & questions

Use always_ask and answer tool confirmations

Machines

When machines start, pause, and get rebuilt

SDKs

When you need bma-sdk or bma-executor-sdk

Get started

Concepts

Executor & brains

Before you start

Next steps

Sessions & events

Approvals & questions

Machines

SDKs

​Before you start

​Next steps

Sessions & events

Approvals & questions

Machines

SDKs

Before you start

Next steps