AI 编程约 9 分钟

OpenAI Agents API 怎么用：从建 Key 到跑通沙箱

AI 指南·更新于 2026-09-14·◉ 0 浏览

OpenAI Agents API 于 2026 年 9 月 10 日公测，官方托管沙箱让你不用自己搭运行环境。本文按官方快速开始整理：Key 权限、四步跑通、成功判断、报错速查与多 Agent 进阶。

想让自己的应用拥有一个"在云端自己写代码、自己跑脚本、干完活把结果交回来"的 Agent，现在不需要自己搭运行环境了。OpenAI 在 2026 年 9 月 10 日开放 Agents API 公测：官方托管 Codex 执行环境（hosted sandboxes），你只需要一个 API key 和几行代码。整个流程跑通大约 15 分钟，写好一段脚本就能看到 Agent 真实在沙箱里创建文件、执行命令。

本文按官方 Agents API 快速开始实测路径整理，代码示例均可直接复制。发布信息来自 OpenAI 开发者社区公告。

开始前要准备什么

三样东西，缺一不可：

OpenAI Platform 账号和一个应用 API key：在 platform.openai.com/api-keys 创建。
正确的 key 权限：官方快速开始明确要求给这个 key 授予 api.agents.read 和 api.agents.write（会话操作），外加 api.responses.write(模型推理)。权限不全是最常见的第一步报错原因。
安装 OpenAI SDK：Python 用 pip install --upgrade openai，JavaScript 用 npm install openai。

两个安全提醒来自官方文档：一是 API key 要放在服务端，绝不能下发到沙箱里；二是请求需要 OpenAI-Beta: agents=v1 请求头，用官方 SDK 会自动带上，直接写 curl 时要手动加。

四步跑通第一个托管沙箱 Agent

第 1 步：创建会话

用 beta.agents.sessions.create 建一个会话，指定模型、指令，并把环境设为 openai_hosted（OpenAI 托管沙箱）。Python 示例：

from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
        stream=True,
    ) as events:
        for event in events:
            print(event.to_json(indent=None), flush=True)

这一行 environment={"type": "openai_hosted"} 就是托管沙箱的开关：OpenAI 会替你准备好一台隔离的容器机器，Agent 在里面执行代码。

第 2 步：运行并观察事件流

运行脚本后，终端会持续输出事件 JSON。Agent 会自己创建 tree.py、执行它、把目录树结果报回来。这里有个官方特别强调的判断技巧：看到 agent.session.turn.completed 不代表全部成功，它只表示这一轮结束了，你还要核对 Agent 上报的执行结果；如果事件以 turn.failed、turn.cancelled 或 session.failed 结尾，说明这轮失败或被取消了。

第 3 步：继续对话（延续会话）

把事件流里的 session_id 存下来，就可以给同一个会话追加任务，比如"给 tree.py 加一个最大深度参数再跑一遍"。会话状态由 OpenAI 保存，不用每次重建上下文，这是 Agents API 和裸调模型接口最大的体验差异。

第 4 步：清理

不需要的会话用 client.beta.agents.sessions.delete(session_id) 删掉。官方提醒：删除前先把沙箱里要留的文件取出来，否则会一起丢。

怎么确认跑通了

三个检查点，全过才算成功：

事件流里出现 agent.session.turn.completed，且没有任何 *.failed 事件。
Agent 报告的输出里有真实的目录树，且包含它自己创建的 tree.py。
用同一个 session_id 追加一个新任务，Agent 能接上文继续干。

常见报错与卡点速查

现象	原因	解法
401 或权限类报错	key 缺 `api.agents.*` 权限	回到 API key 设置补授 `api.agents.read/write` 和 `api.responses.write`
curl 调用报未知 header	缺 Beta 头	手动加 `OpenAI-Beta: agents=v1`（SDK 用户不受影响）
流中断后任务"消失"	流断开但会话还在	按官方文档用 session 检索接口找回会话和已保存的产出，不要盲目重试
turn.completed 但结果不对	完成不等于每个工具都成功	检查事件里的工具调用结果，必要时在 instructions 里要求逐步汇报
沙箱里拿不到 key	官方设计如此	key 只留在你的服务端，需要凭证时用官方的 vaults 机制

下一层：多 Agent 与自带环境

跑通基础流程后，官方文档里还有几条值得继续挖的路：

多 Agent 协作：创建会话时开启 multi_agent: {"enabled": true, "max_concurrent_subagents": 4}，主 Agent 可以把独立任务派给并行的子 Agent，参考多 Agent 文档。
自带沙箱：不放心数据出域的话，把 environment 换成 self_hosted，用自己的机器跑，也支持接 E2B、Modal、Daytona、Runloop、Vercel、Cloudflare 等第三方沙箱。
工具生态：会话里可以配 web_search、MCP 服务器、skills 插件包，指令写法可参考站内的 Codex 完整指南和 Codex MCP 配置教程。

计费上要心里有数：Agents API 本身不加收费用（官方社区公告原话"没有额外费用"），你为模型 token 和工具付费；但托管沙箱按容器规格收容器费（例如 1GB 规格 $0.03、4GB $0.12、16GB $0.48、64GB $1.92，每 20 分钟一个计费单元，来自官方定价页）。如果对 Agent 概念还不熟，可以先读什么是 AI Agent补齐背景。

常见问题 FAQ

Agents API 是免费的吗？

API 本身免费，按模型 token 和工具正常计费；使用 OpenAI 托管沙箱时另外收容器费，费率见官方定价页。

需要先学 Agents SDK 吗？

不需要。Agents API 走 HTTP/SDK 调用即可上手；两者定位不同，选型对比可以看我们的 Agents API 与 Agents SDK 区别一文。

我的代码和数据会被 OpenAI 看到吗？

用托管沙箱时代码在 OpenAI 的容器里执行；对数据驻留有要求可以选 self_hosted 环境，但官方文档写明 Agents API 目前仅支持美国数据驻留、不支持零保留（ZDR）。

国内开发者能用 Agents API 吗？

接口本身没有地区限制，但需要能访问 OpenAI 服务的网络与支付渠道；对数据出境敏感的团队建议评估 self-hosted 沙箱方案。

作者：AI345

最后更新于 2026 年 9 月