面向智能体开发的 Agents API 文档页位于 OpenAI（开放人工智能）开发者站点，路径是 developers.openai.com/api/docs/guides/agents-api/overview。页面开头说明，完整文档索引收录在 llms.txt 中，而在任一文档页地址后追加 .md，就能取到对应的 Markdown 版本，便于把内容送进各类开发工具与自动化流程。

Agents API

通过托管的 Codex harness 构建可持续运行的云端 agent。

Agents API 让应用通过 OpenAI 托管的 API 访问 Codex harness。

OpenAI 负责会话、编排、上下文压缩和恢复；应用提供工具，并选择执行环境。

Agent 可以在沙箱中运行，执行代码、编辑文件、连接 MCP 服务器并生成产物。

定价

模型用量按所选模型的 API 价格计费。OpenAI 工具使用标准价格，OpenAI 托管的沙箱使用标准容器价格。

试用示例

可以试这些完整示例：

• 在 OpenAI 托管的沙箱中创建并运行一个目录树脚本。
• 用子 agent 比较发布说明，把结果合并成一个答案。

完整应用示例：

• 事件响应 agent：调查告警并请求批准恢复操作。
• Slack bot：用接入的工作工具调查请求。
• 数据分析师：用只读 SQL 回答数仓问题。
• GitHub issue 调查员：复现报告的 bug 并在 GitHub 上分享发现。
• 文档审查员：用策略技能和专家 agent 审查文档。

核心概念

Agents API 围绕四个主要概念构建：

• Agent： agent 可用的模型、指令、工具和 MCP 服务器。
• Environment： 可选的沙箱或计算机，agent 在其中访问文件、加载技能并运行命令。
• Session： agent 的持久实例，负责处理任务并响应输入。
• Events 和 items： 发送给 agent 的输入，以及会话期间产生的输出。

一个会话的完整流程

从快速开始中的 OpenAI 托管沙箱入手：

1. 创建会话。 配置 agent；OpenAI 负责为其准备环境。
2. 交给它一项任务。 环境就绪后，用户输入开启一轮工作。
3. 跟进进度。 流式输出，或用 webhook 得知 agent 何时完成或需要输入。
4. 继续或引导。 向同一会话发送新任务，或在当前这轮中引导 agent。

使用 OpenAI 托管的会话时，应用负责发送输入、接收事件，OpenAI 负责运行 agent，并准备和管理其沙箱。环境设置和限制见环境选项。

托管 harness 提供的能力

托管的 Codex harness 支持：

• 在沙箱中运行命令和代码。
• 应用相关技能和指令。
• 通过工具或 MCP 连接外部数据。
• 在 agent 工作过程中进行引导。
• 总结此前工作，管理上下文窗口。
• 把工作拆成子任务并委派给子 agent。
• 从上次中断处恢复会话。

API key 权限和 SDK 设置见快速开始的前置条件。创建会话时配置这些能力：agent 使用 gpt-6-astra，指令要求它用 OpenAI 文档 MCP 和网页搜索准确回答技术问题，并在有用时把独立调研任务委派给子 agent；工具包括程序化工具调用、指向 https://developers.openai.com/mcp 的 MCP 连接和网页搜索；多 agent 开启，最多 4 个并发子 agent；环境为自托管，工作目录 /workspace，能力目录 /workspace/capabilities/skills；输入是让 agent 调研如何把 MCP 服务器接到 OpenAI agent 上、检查近期更新并总结推荐配置。

运行时对比见 Agents 概览。

Agents API 会保留会话状态，因此可以跨轮继续工作，不必重建对话上下文。不再需要时，可以删除会话和已发布的产物。Agents API 目前仅支持美国的数据驻留，不支持零数据保留（ZDR）。选择自托管沙箱并不会让 Agents API 符合 ZDR 条件。数据驻留与保留的细节见 OpenAI 平台中的数据控制。

社区对 OpenAI 新代理接口反应分化，多数人质疑沙盒安全与订阅绑定造成的供应商锁定，少数人认可其抽象并期待替代命令行。

认为沙盒安全限制不可信

• 用户指出沙盒虽提供禁用或限制网络选项，但此前已有代理篡改系统文件绕过规则的前科，且有人讽刺这等于程序化窃取数据，认为隔离承诺不可靠（较多人） > 这种机制简直是为程序化窃取你的数据量身定做（@chairhairair）

认为这是供应商锁定且不应脱离现有订阅

• 新接口无法使用现有 OpenAI 订阅，只有大公司负担得起，用户更希望拿到已付费的推理令牌而非被推进封闭生态（较多人） > 别再搞供应商锁定了，先把我们付过钱的推理令牌给出来（@monneyboi）

认可沙盒抽象但更倾向自托管或自建环境

• 不少开发者觉得沙盒加插件的抽象不错，但出于避免锁定或成本考虑，选择用自有虚拟机或自托管沙盒实现类似能力，认为本地运行可见中间过程更重要（较多人） > 在普通虚拟机里跑已有不错效果，你未必需要把自己锁进他们的服务（@andrewchambers）

欢迎用 API 替代命令行或认为无需超出原有接口

• 部分人表示早该提供 API 以免去命令行操作，也有公司实践表明基于现有回复接口加简单 SDK 脚本化工作流已足够，不必另起炉灶（少数人） > 早就需要这个了，希望它能让我们直接调 API 而不是碰命令行（@colesantiago）

对定价计时与额度消耗感到困惑和不满

• 开发者抱怨无论任务大小都狂耗订阅额度，且会话环境计费单位模糊，担心被动持续扣费而无主动关闭手段（少数人） > 现在随便一个小请求都要吃掉我一周配额的百分之一，实在想退订了（@spwa4）

认为代理运行时接口仍未收敛且与文档脱节

• 有用户指出官方比较页遗漏了灵活的应用服务器模式，实际成功工具常偏离文档指引，且展示案例链接失效，反映生态尚早（较多人） > 连官方的代理对比页都没列最灵活的本地应用服务器，大家显然还在摸索正确接口（@jumploops）

有价值的补充

• 沙盒网络访问实为三档：全开、全禁、仅允白名单，但白名单可能因底层逃逸失效。
• 非模型厂商的代理服务可随时选用市场最优模型（如 GLM 5.3 Flash），不必绑死自家前沿模型，这对多数代理场景更实际。
• 自托管沙盒选项已埋入文档，可缓解供应商切换成本。
• 在常规虚拟机中配合远程控制即可从手机操控代码助手，作为个人助理体验极佳。