Agents

An agent defines how work is done; a session is one piece of work. You can define an agent in two ways. Both end up as the same BMA objects.

Managed Agents API (/v1)
Native API (/api/v1)

Use the Anthropic shape: name, model, system, tools, mcp_servers, skills, description, metadata.

{
  "name": "repo-helper",
  "model": "deepseek-flash",
  "system": "You help engineers investigate the acme/api repository.",
  "tools": [{
    "type": "agent_toolset_20260401",
    "configs": [{"name": "bash", "enabled": true, "permission_policy": {"type": "always_ask"}}]
  }]
}

model is the name of a model configured in your project; an object {id, effort} is also accepted.
Every update creates a new version; version on update is an optimistic lock (409 on mismatch).
See compatibility for the fields BMA rejects.

The native API uses an agent config: a YAML or JSON document that is immutable and content-addressed (the same definition returns the same acfg_… id). A profile (aprf_…) is a named pointer to the current config.

version: v1
instruction: |
  Help engineers investigate issues in the acme/api repository.
model:
  provider_config: <provider-name>
  name: deepseek-flash
tools:
  web_search: {}
  ask_question: {}
  run_command:
    permission:
      mode: always_ask
machine_sources:
  - machine_pool_name: <pool-name>

Names (model provider, model, pool, machine) are resolved to immutable ids when the config is created.

Models

BMA calls models through model providers configured in your organization; an agent names one of the project’s configured models. During early access the hosted deployment provides the models; ask the BMA team which names are configured for your project. Per-session model changes are possible through agent_with_overrides on session create (model, reasoning effort, system prompt, and a session-lifetime credential with api_url/api_key/api_format). The key is write-only and never echoed.

Tools

Group	Native tool names	Runs where
Commands and processes	`run_command`, `read_process`, `write_process`, `stop_process`, `list_processes`	On a machine
Machines	`list_machines`, `inspect_machine`, `create_machine`, `delete_machine`	Control plane
Files	`storage_list`, `storage_read`, `storage_write`, `storage_search` (memory stores and artifacts), `storage_upload`, `storage_download` (between machine and BMA)	Control plane / machine
Web	`web_search`, `web_fetch`	Server
People	`ask_question` (see interactions)	Server
Skills	`skill` (see skills)	Server + machine
Subagents	`spawn_agent`, `read_agent`, `send_agent_message`, `stop_agent`, `list_agents`	Server
Custom	any name with `type: custom` and an `input_schema`; your system returns the result	Your code
MCP	`mcp__{server}__{tool}` (see MCP)	MCP server

Through /v1, the Anthropic bash tool maps to run_command. The Anthropic read, write, edit, glob and grep tools are not available yet (Roadmap); the agent edits files with bash. When a config has machine sources, BMA adds the command, process and machine tools automatically; attaching skills adds skill.

Permissions

Each tool has a permission mode:

Mode	Effect
`always_allow`	Runs immediately
`always_ask`	Opens a `permission` interaction and waits for a person

MCP tools default to always_ask. Through /v1, auto is treated as always_ask. With always_ask, BMA asks before creating a machine, so a denied call never provisions anything.

Subagents

A config can declare subagents that the agent may start with spawn_agent (another profile, or a copy of itself), with max_subagents and max_depth limits. A subagent belongs to the session that spawned it: its results and questions return to that session, and it sees only that session’s machines. Subagents are a native-API feature; the /v1 multiagent field is rejected.

Get started

Concepts

Executor & brains

Models

Tools

Permissions

Subagents

​Models

​Tools

​Permissions

​Subagents

Models

Tools

Permissions

Subagents