如何使用 OpenAI Agents API？

OpenAI Agents API 替你运行 OpenAI 开源的 Codex harness。你发送 POST https://api.openai.com/v1/agents/sessions，带上 OpenAI-Beta: agents=v1 header、一份 agent 定义和一个任务；OpenAI 负责运行模型与 tool 循环、保存 session，并可以按需提供一个 sandbox。Agents API 本身不收费：你只需为 token、tool 以及托管容器时长付费（1 GB 到 16 GB 的 sandbox 规格，每 20 分钟 session 为 $0.03 到 $0.48）。它于 2026 年 9 月 10 日进入公测，OpenAI 在 9 月 29 日的 DevDay 上新增了 computer use。

下文依次介绍：第一次通过 REST 建立 session、进度 event、MCP tools、subagent，以及 computer use 的审批流程。想了解它与 OpenAI 其他 agent 形态的对比，请阅读 Agents API vs Responses API vs Agents SDK；本次发布的其他内容见 DevDay 2026 汇总。所有调用都是普通 HTTP，因此在编写应用代码之前，你就可以用 Apifox 发送它们。

OpenAI Agents API 一览

来源：Introducing the Agents API、Agents API 概览，以及定价页面。

四个核心概念

文档围绕四个组成部分构建这套 API：

• Agent：模型、instructions、tools 和 MCP server。可以内联传入，也可以保存下来并复用它的 agent_id。
• Environment：可选的 sandbox 或 computer，agent 在其中读取文件、执行命令。
• Session：agent 的持久化实例，保存配置、对话和已保存的工作成果。
• Events 与 items：event 实时汇报进度；item 则是已保存的消息和 tool 调用。

发给空闲 session 的消息会开启一个新的 turn；在 turn 进行中发送的消息则会引导它。harness（按照架构页面的说法，即运行模型与 tool 循环的托管 Codex 实例）还会负责上下文压缩，因此无需你配置。

选择 environment

environment.type 决定命令在哪里运行：

• none：不提供计算资源。远程 MCP server 和你的 function tool 仍可正常工作；内置的 Bash、apply-patch、workspace 文件以及 executor MCP 则不可用。
• openai_hosted：OpenAI 管理一个装有 Python 和 Node.js 的 Linux sandbox，路径为 /workspace。把 container_size 设为 small（1 GB）、medium（默认，4 GB）或 large（16 GB），并把 network.access 设为 enabled、disabled，或设为 restricted 并带上 allowed_domains。turn 结束时，/workspace/outputs 中的文件会成为 artifact。空闲且没有 keep-alive 的 sandbox 可能在一小时后被删除。
• self_hosted：你自己的基础设施。你在笔记本、容器或远程 sandbox 上运行 codex exec-server，它使用单独的 environment key 向外建立连接。

发布公告列出了 sandbox 合作伙伴 Blaxel、Cloudflare、Daytona、DigitalOcean、E2B、Modal、Oracle、Runloop 和 Vercel；自托管指南还补充了 AWS Lambda MicroVMs。

通过 REST 创建你的第一个 session

导出一个具备上述权限的密钥并设为 OPENAI_API_KEY，然后用一个小规格容器发送快速入门任务：

curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted", "container_size": "small" },
    "input": "Create tree.py, a script that prints a tree of the files in the current directory. Run it and show the output.",
    "stream": true
  }'

设置为 stream: true 后，响应就是第一个 turn 的 event stream。请从中保存 session ID；后续生命周期都使用同一个资源：

JavaScript SDK 采用相同的结构。下面这个版本改编自发布公告，增加了 tool、subagent 和 vault：

import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [{ type: "web_search" }],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: [process.env.VAULT_ID],
  environment: { type: "openai_hosted" },
  input: "Summarize breaking changes in the latest release notes.",
});
console.log(session.id);

跟踪进度：stream 还是 webhooks

Streaming。在发送 input 之前先打开 GET /v1/agents/sessions/{id}/events?stream=true（Accept: text/event-stream），以免错过早期的 event。请留意：

• agent.session.turn.output_text.delta 和 agent.session.turn.output_text.done，用于输出文本
• agent.session.turn.completed、agent.session.turn.failed 或 agent.session.turn.cancelled，表示最终结果
• agent.session.requires_action，当 agent 需要 function 结果、连接 environment，或需要 computer use 审批时触发

三个坑：agent.session.idle 并不意味着 turn 成功，已完成的 turn 也可能包含失败的 tool 调用，而关闭 stream 并不会停止任务。stream 不会重放错过的 event，因此断连之后要重新打开一个 stream，并重新获取 session 及其 items。

Webhooks。订阅 agent.session.created、agent.session.action_required、agent.session.in_progress、agent.session.idle 和 agent.session.failed。注意命名差异：stream 里叫 requires_action，webhook 里叫 action_required。载荷不包含调用细节，因此你的 handler 需要去获取 session 并读取 required_actions。逐一验证签名（webhook 签名验证）；长时间运行的 API 操作一文解释了为什么 webhook 适合耗时数分钟的任务。

MCP tools、tool search、programmatic tool calling 与 subagent

MCP。把一个 server 加入 agent.tools：

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" },
  "required": true
}

默认情况下由 OpenAI 建立连接（connection_origin: "service"），因此该 server 必须能被 OpenAI 访问到。对于内网 server，使用 connection_origin: "environment"；也可以使用 stdio 在 sandbox 中启动一个。凭据方面，可以为单个 session 传入 transport.authorization，也可以挂载一个 vault 凭据（static_bearer 或 mcp_oauth），并通过 vault_ids 指定。

Tool search。当模型支持 tool search 时，MCP tools 会被自动发现。如果 function tool 很多，可以添加 {"type": "tool_search"} 并把相应 function 标记为 defer_loading: true。

Programmatic tool calling。默认开启：agent 会获得一个 exec tool，在隔离的 V8 运行时中执行 JavaScript，因此它能循环调用 tool，并在结果进入上下文之前裁剪掉过大的部分。可用 {"type": "programmatic_tool_calling", "enabled": false} 关闭它。

Subagent。设置 multi_agent: {"enabled": true, "max_concurrent_subagents": 3}（默认上限为 6）。subagent 共享 environment 的文件系统，并继承 MCP tools 和 web search，但不能使用 function tool。主 agent 的 turn 中，subagent_id 为 null。

Computer use：DevDay 新增的能力

computer use 为 agent 提供一个托管浏览器。把该 tool 和一个 desktop 加入托管 environment：

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [{ "type": "computer_use", "include_screenshots": true }]
  },
  "environment": {
    "type": "openai_hosted",
    "desktop": { "enabled": true },
    "network": { "access": "enabled" }
  }
}

浏览器在访问每一个新的网站 origin 之前都需要用户批准，公开站点也不例外。收到 agent.session.requires_action 时，获取 session 并找到 computer_use_approval_request 条目。其中嵌套的 request.type 属于以下两种之一：

• browser_origin_access：展示 origin 和 reason，然后提交 approve、deny 或 cancel。
• browser_authentication：一个登录表单，包含 fields、可选的登录 options 以及 credential_origin。用用户填写的值提交 action: "submit"，或提交 action: "cancel"。

两种应答都通过 events 接口回传：

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "type": "agent.session.input.computer_use_approval_request_result",
    "request_id": "REQUEST_ID",
    "response": { "type": "browser_origin_access", "decision": "approve" }
  }]}'

浏览器操作会以 computer_use_call item 的形式出现，带有 id、turn_id、title、status 和 output；当 include_screenshots 开启且有可用截图时，该 item 会携带一张 base64 编码的 JPEG 截图。不要让截图进入日志，它们可能暴露账号数据。

computer use 指南提示了以下注意事项：

• 批准 origin 不等于确认具体操作。批准某个站点并不会让 agent 在每次购买或删除前都征求同意。如果你需要这种保护，请把浏览器限制在无法执行这类操作的资源上，或改用你自己掌控的浏览器运行时。
• 登录支持邮箱、密码和验证码。不支持 passkey 和二维码登录。
• 只有主 agent 能发起认证请求。subagent 不能。
• 禁用凭据提交的自动重试（SDK 中为 maxRetries: 0，curl 中为 --retry 0）。
• 202 只表示已接受，并不代表跳转或登录成功。认证请求在五分钟后过期。
• 批准 origin 不会覆盖网络策略。还需要在 network 中放行该站点及其重定向域名。

回顾文章称 computer use「通过 API 提供，并在 Codex 和 ChatGPT Work 的 Pro 500 及 Enterprise 中提供」。想用同一个模型做 UI 驱动的测试，请参阅 GPT-6 Astra computer use for API testing。

把 API 交给 agent，而不是 UI

对于没有 API 的软件，浏览器只是退而求其次的方案。如果这套系统由你掌控，就把它封装成一个 MCP server：有类型的 tool、无需 origin 提示、结果可校验。Computer use vs structured APIs 讨论了其中的取舍，而 Apifox MCP Server 会把你的 API 定义提供给编写封装层的编码助手。

写代码之前先在 Apifox 中测试 Agents API

该 API 仍处于 beta 阶段，因此先手动在 Apifox 中确认每次调用的形态：

1. 创建一个 Apifox 环境，包含 OPENAI_API_KEY、VAULT_ID 和 SESSION_ID。在每个请求上发送 Bearer {{OPENAI_API_KEY}} 和 OpenAI-Beta: agents=v1。
2. 发送不带 stream 的创建 session 请求，断言状态码为 2xx 且 id 非空，并把 id 提取到 SESSION_ID。
3. 以 SSE 请求打开 event stream，从第二个请求发送 input，观察 event 陆续到达。
4. 把审批和取消的载荷保存为请求，以便重放每个 required_actions 场景。
5. 把它们串联成一个测试场景，并用 Apifox CLI 在 CI 中运行。

AI agent API 测试指南提供了针对非确定性输出的断言写法，可以照着实践。

FAQ

OpenAI Agents API 免费吗？没有平台费用，但你需要为模型 token、tool 调用和托管容器时长付费。

哪些模型可用于 Agents API？文档中的示例（包括每个 computer use 示例）都使用 gpt-6-astra。这些页面没有列出其他受支持的模型，因此请先自行测试你的模型。

Agents API 支持零数据保留（Zero Data Retention）吗？不支持。它仅支持美国数据驻留，即使使用自托管 sandbox 也不符合 ZDR 要求。

它与 Agents SDK 或 Responses API 有何不同？SDK 在你的应用内运行循环；Responses API 则是你围绕它自行构建循环的那次模型调用。详见完整对比。

从一个只读 session 开始

先从一个只读的 session 开始，加入一个 MCP server，然后在默认拒绝的审批 handler 之后再加上 computer use。如果反过来是希望 ChatGPT 对你自己的 server 发出的事件做出响应，对应的能力就是 MCP Events。

HiFox：将 Agent 变成真正的队友

另外，我们也在思考，AI 如何从个人提效走进团队协作。

HiFox 是一个让人和 AI Agent 在同一个工作现场协作的平台：你可以像给同事分派任务一样指派 Agent，在任务看板中跟踪进度、查看结果，让 Agent 成为团队里的队友。

👉 立即体验 HiFox：https://hifox.com

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，
欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。