Agents API 参考

沙箱服务端在 agents 能力组打开之后提供的全部 HTTP 接口。组默认关闭。下面 70 条路由全部已实现，每条都有测试。有本地后端的运行时只有两个：Codex（二进制 codex）和 Qwen Code（二进制 qwen）。claude-code、cursor 和 command 是已声明、没有本地后端的适配器：GET /v1/agents/runtimes 对它们报告 implemented: false，选中它们的请求返回 404 agents.not_implemented_locally，响应体指向 GET /v1/agents/runtimes。

这不是 sb.agent.*。用法和案例见 Agents API。字段级拒绝的叙述见 托管代理。本页按路由列出参数和响应。

端点声明在 server-sdk/src/agent_sandbox/server/endpoints.py，处理函数挂在 routes_agents.py。

通用约定

打开这一组：

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

错误信封：

{
  "error": {
    "message": "说明",
    "type": "invalid_request_error",
    "param": "字段名或 null",
    "code": "agents.not_implemented_locally"
  }
}

type 在 404 时是 not_found_error。做不到的变体是 400，x-should-retry: false。没有本地能力的路由，以及选中了未实现的运行时，是 404，code 为 agents.not_implemented_locally，x-should-retry: false，x_agent_sandbox.runtimes 指向 /v1/agents/runtimes。端点关闭时是 404 endpoint_disabled，正文带 rule，说明是哪条规则关的。

列表信封（凡是下表写「列表」的）：

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

会话对象 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。

适配器选择顺序：请求头 X-ABX-Adapter，或正文 adapter / runtime，或 agent.model / model 恰好是 codex、openai-codex、qwen-code、qwen、qwen_code、qwencode。gpt-5 这种模型 id 会传给被选中的 CLI，不用于选择适配器。都没有时用产品顺序里的第一个：codex。ABX_AGENTS_DEFAULT 或 ABX_AGENTS_CONFIG 里的 default / agents.default 可以改这个默认。GET /v1/agents/runtimes?order=asc 按 codex、qwen-code 列出。列表默认 order=desc。default: true 标出当前默认，不看数组下标。已声明但未实现的适配器（claude-code、cursor、command）404 agents.not_implemented_locally；不认识的名字同样是 404。每个路由都可以单独放行，端点 id 的默认 scope 是 agents:use，见细粒度能力。

CLI 不在基础镜像里。要用时再装：

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

会话、事件、条目、回合

POST /v1/agents/sessions

创建会话。成功 200，body 是 agent.session。

environment.type 固定为 self_hosted。workspace_directory 默认 /workspace。

GET /v1/agents/sessions

列表。查询参数除分页外还有 agent_id（按定义 id 过滤）。成功 200，列表，元素是 agent.session。

GET /v1/agents/sessions/{id}

路径参数 id。成功 200，一个 agent.session。不存在 404 resource_not_found。

POST /v1/agents/sessions/{id}

只更新 metadata。body 里出现 agent、vault_ids、environment 或其他键是 400。成功 200，更新后的 agent.session。

DELETE /v1/agents/sessions/{id}

删除会话，并清掉产物快照。成功 200：

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

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

排队一轮。成功 202，空 body。

input_image、input_file 是 400。进行中再送输入会排成新回合（queued_not_steered），不会写进正在跑的进程。

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

SSE。Accept: text/event-stream。查询 after：不带则从现在开始跟踪，直到该回合结束；after=0 或 after=evt_<seq> 回放后关闭。帧的 id 是运行时序号。

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

都是列表。条目 type=message 时 content[].type 为 output_text，content[].text 是 CLI 文本。本地案例里 Codex 的文本是 hello-from-fake-codex，Qwen Code 是 hello-from-fake-qwen。

GET /v1/agents/runtimes

成功 200，列表，包含每一个已声明的运行时。已实现的在前（codex、qwen-code），之后是只声明的适配器。每项：

产物、追踪、子代理

multi_agent.enabled=true 仍是 400。

环境、文件、模板

POST /v1/agents/environments

body：type 必须能落到 self_hosted。空的 { "type": "openai_hosted" } 会被转成 self_hosted 并在 x_agent_sandbox.differences 里说明。带配置的 openai_hosted 是 400。

400：network、packages、setup_commands、plugins、skills、desktop、container_size、capability_directories。成功 200，环境对象。不会预置容器。

GET /v1/agents/environments

列表。200。

GET /v1/agents/environments/{environment_id}

200 一个环境，或 404。

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

body：path、内容。路径相对工作目录。符号链接 400。已存在且内容不同是 400 agents.file_exists。写入 .git/、.codex/、.claude/、.cursor/、.qwen/、.qoder/、.ssh/，或 .mcp.json、AGENTS.md、QWEN.md、shell rc，是 400 agents.path_refused。大小上限 ABX_AGENTS_MAX_FILE_BYTES，默认 10 MiB。成功 200。

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

200 列表。只含普通文件。查询 page 为不透明翻页令牌，下一页在 next。

环境模板

通过会话或环境上的 environment_template_id 应用到环境。

明确没有的执行器接口

Agent 定义

POST /v1/agents

成功 200。id 形如 agent_...。MCP 请求头的值响应里是 "***"。

GET /v1/agents

200 列表。

GET /v1/agents/{agent_id}

200 或 404 resource_not_found，param=agent_id。

POST /v1/agents/{agent_id}

原地更新。省略的字段不变。body 里再给 adapter 或 runtime 是 400：定义不能换运行时。成功 200。正在跑的会话保留启动时的副本。

DELETE /v1/agents/{agent_id}

200：{ "id", "object": "agent.deleted", "deleted": true }。不停止已有会话。

Vault 与凭据

Vault 只在内存里。每个所有者默认最多 ABX_AGENTS_MAX_VAULTS（100）个。

凭据：

auth 允许 static_bearer，或带访问令牌的 mcp_oauth。400：environment_variable、mcp_oauth.refresh、networking.unrestricted、凭据主机以外的 limited 主机、不是 https 或指向私网的 mcp_server_url、含换行的令牌。

挂到会话的 vault_ids 上之后，凭据只注入到协议、主机、端口都相同的 MCP 工具，放在子进程环境的 Authorization 头里，不出现在 argv。两个凭据都匹配时必须给出 credential_id。凭据已删或 expires_at 已过，下一事件是 400 agents.credential_unavailable 或 agents.credential_expired。

Responses

POST /v1/responses 把一次 CLI 回合当成一个 response。成功对象的 object 是 response。

400：tools 里非 MCP、conversation、prompt、非 text 的 text.format、任何 include、service_tier 不是 auto|default、tool_choice 不是 auto、input_image、input_file、助手历史、未知参数。temperature、top_p、max_output_tokens 被忽略，列在响应头 X-Agent-Sandbox-Ignored-Params。

输出条目只有 CLI 实际给出的：message、reasoning、command_execution、mcp_call、其他工具的 tool_call（带 tool_name）。不会出现 web_search_call、function_call、code_interpreter_call、local_shell_call。CLI 没报告用量时 usage 是 null。

Idempotency-Key 重放第一次的 response。body 不同是 409。

模型、文件、Webhook

Webhook。签名密钥 whsec_... 只在创建和轮换时返回一次。

路由索引

70 条路由，端点 id 与 GET /capabilities 和策略里用的一致。标 拒绝 的四条存在的目的就是用类型化的 404 说明服务端没有这个能力（agents.not_implemented_locally），不是缺实现。

端到端覆盖

定义、环境、vault、responses、webhook 的参数和响应以上表为准。