Agents API reference

Every HTTP route the sandbox server serves once the agents capability group is on. The group is off by default. All 70 routes below are implemented and each one has a test. Two runtimes have a local backend: Codex (binary codex) and Qwen Code (binary qwen). claude-code, cursor and command are declared adapters with no local backend: GET /v1/agents/runtimes reports implemented: false for them, and a request that selects one gets 404 agents.not_implemented_locally whose body points at GET /v1/agents/runtimes.

This is not sb.agent.*. Usage and the worked case are in Agents API. Field-level refusals are in Hosted agents. This page lists parameters and responses per route.

Endpoints are declared in server-sdk/src/agent_sandbox/server/endpoints.py; handlers are mounted in routes_agents.py.

Common conventions

Turn the group on:

export ABX_SERVER_ENABLED_GROUPS=agents      # or server.groups: [agents] in template.yaml
python -m agent_sandbox.server serve --port 9000

Error envelope:

{
  "error": {
    "message": "explanation",
    "type": "invalid_request_error",
    "param": "field name or null",
    "code": "agents.not_implemented_locally"
  }
}

type is not_found_error for 404. A variant the server cannot honor is 400 with x-should-retry: false. A route with no local capability, and a request that selects a runtime that is not implemented, is 404 with code agents.not_implemented_locally, x-should-retry: false, and x_agent_sandbox.runtimes pointing at /v1/agents/runtimes. A disabled endpoint is 404 endpoint_disabled with a rule that names the layer that turned it off.

List envelope (every route the tables below call a list):

{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

Main fields of the session object agent.session: id, object, agent (id, name, model, instructions, tools, multi_agent.enabled, reasoning, service_tier, text), created_at, environment (type=self_hosted, id, workspace_directory), status, metadata, usage, vault_ids, error, required_actions, last_active_at, x_agent_sandbox.

Adapter selection order: the header X-ABX-Adapter, or the body adapter / runtime, or agent.model / model being exactly codex, openai-codex, qwen-code, qwen, qwen_code or qwencode. A model id such as gpt-5 is passed to the selected CLI and does not select an adapter. With none of them the first in product order is used: codex. default / agents.default in ABX_AGENTS_DEFAULT or ABX_AGENTS_CONFIG changes that default. GET /v1/agents/runtimes?order=asc lists codex, qwen-code, then the declared-only adapters. Lists default to order=desc. default: true marks the current default regardless of array index. A declared adapter that is not implemented (claude-code, cursor, command) is 404 agents.not_implemented_locally; so is an unknown name. Each route can be enabled on its own; the endpoint ids have the default scope agents:use, see Fine-grained capabilities.

The CLIs are not in the base image. Install one when you need it:

npm install -g @openai/codex
npm install -g @qwen-code/qwen-code

Sessions, events, items, turns

POST /v1/agents/sessions

Creates a session. 200, the body is an agent.session.

environment.type is always self_hosted. workspace_directory defaults to /workspace.

GET /v1/agents/sessions

List. Besides paging, the query accepts agent_id (filter by definition id). 200, a list of agent.session.

GET /v1/agents/sessions/{id}

Path parameter id. 200, one agent.session. Missing is 404 resource_not_found.

POST /v1/agents/sessions/{id}

Updates metadata only. agent, vault_ids, environment or any other key in the body is 400. 200, the updated agent.session.

DELETE /v1/agents/sessions/{id}

Deletes the session and clears the artifact snapshots. 200:

{ "id": "agsess_...", "object": "agent.session.deleted", "deleted": true, "x_agent_sandbox": {} }

POST /v1/agents/sessions/{id}/events

Queues a turn. 202, empty body.

input_image and input_file are 400. Input sent during a turn queues a new turn (queued_not_steered); it is never written into the running process.

GET /v1/agents/sessions/{id}/events

SSE, Accept: text/event-stream. Query after: without it the stream follows from now until that turn ends; after=0 or after=evt_<seq> replays and closes. The frame id is the runtime sequence number.

GET /v1/agents/sessions/{id}/items

GET /v1/agents/sessions/{id}/turns

GET /v1/agents/sessions/{id}/turns/{turn_id}

GET /v1/agents/sessions/{id}/turns/{turn_id}/items

All are lists. For an item with type=message, content[].type is output_text and content[].text is the CLI text. In the local case Codex's text is hello-from-fake-codex and Qwen Code's is hello-from-fake-qwen.

GET /v1/agents/runtimes

200, a list with every declared runtime. Implemented ones come first (codex, qwen-code), then the declared-only adapters. Each entry:

Artifacts, traces, subagents

multi_agent.enabled=true is still 400.

Environments, files, templates

POST /v1/agents/environments

Body: type must resolve to self_hosted. A bare { "type": "openai_hosted" } is converted to self_hosted and noted in x_agent_sandbox.differences. openai_hosted with configuration is 400.

400: network, packages, setup_commands, plugins, skills, desktop, container_size, capability_directories. 200, an environment object. No container is provisioned.

GET /v1/agents/environments

List. 200.

GET /v1/agents/environments/{environment_id}

200, one environment, or 404.

POST /v1/agents/environments/{environment_id}/files

Body: path and the content. The path is relative to the workspace. A symlink is 400. An existing file with different content is 400 agents.file_exists. Writing .git/, .codex/, .claude/, .cursor/, .qwen/, .qoder/, .ssh/, or .mcp.json, AGENTS.md, QWEN.md, a shell rc file, is 400 agents.path_refused. Size limit ABX_AGENTS_MAX_FILE_BYTES, default 10 MiB. 200.

GET /v1/agents/environments/{environment_id}/files

200 list. Regular files only. Query page is an opaque paging token; the next page is in next.

Environment templates

A template is applied to an environment through environment_template_id on a session or environment.

Executor routes that are refusals

Agent definitions

POST /v1/agents

200. id looks like agent_.... MCP header values are "***" in the response.

GET /v1/agents

200 list.

GET /v1/agents/{agent_id}

200, or 404 resource_not_found with param=agent_id.

POST /v1/agents/{agent_id}

Updates in place. Omitted fields are unchanged. adapter or runtime in the body is 400: a definition cannot change runtime. 200. A running session keeps the copy it started with.

DELETE /v1/agents/{agent_id}

200: { "id", "object": "agent.deleted", "deleted": true }. Existing sessions are not stopped.

Vaults and credentials

Vaults live in memory. Each owner may hold at most ABX_AGENTS_MAX_VAULTS (100 by default).

Credentials:

auth allows static_bearer, or mcp_oauth with an access token. 400: environment_variable, mcp_oauth.refresh, networking.unrestricted, limited hosts other than the credential's host, an mcp_server_url that is not https or points at a private network, a token containing a newline.

Once attached through a session's vault_ids, a credential is injected only into an MCP tool whose scheme, host and port all match, as an Authorization header in the child process environment, never in argv. When two credentials match, credential_id is required. A credential that is deleted or past expires_at makes the next event 400 agents.credential_unavailable or agents.credential_expired.

Responses

POST /v1/responses treats one CLI turn as one response. The object of a success is response.

400: a non-MCP entry in tools, conversation, prompt, a text.format other than text, any include, service_tier other than auto|default, tool_choice other than auto, input_image, input_file, assistant history, unknown parameters. temperature, top_p and max_output_tokens are ignored and listed in the response header X-Agent-Sandbox-Ignored-Params.

Output items are only what the CLI actually produced: message, reasoning, command_execution, mcp_call, and tool_call (with tool_name) for other tools. web_search_call, function_call, code_interpreter_call and local_shell_call never appear. When the CLI reports no usage, usage is null.

Idempotency-Key replays the first response. A different body is 409.

Models, files, webhooks

Webhooks. The signing secret whsec_... is returned once, on creation and on rotation.

Route index

All 70 routes. Endpoint ids are the ones GET /capabilities and the policy use. The four marked refusal exist to explain with a typed 404 that the server has no such capability (agents.not_implemented_locally); they are declared, counted and tested like the rest.

End-to-end coverage

Parameters and responses of definitions, environments, vaults, responses and webhooks are as in the tables above.