OpenAI 推出 Agents API：一次调用，在云端跑起 Codex 同款 Agent

OpenAI 正式发布处于公开测试阶段（Public Beta）的 Agents API。对于正在开发或计划落地 AI Agent 的团队来说，它提供了一个官方托管的调度底座（harness）和执行环境，让开发者可以用单次 API 调用构建并运行能够在生产环境长期执行的云端 Agent。

从对话框到长程任务：OpenAI 这次发布了什么？

在构建 Agent 时，要让模型像真实工程师一样排查线上故障、处理多文件代码或调用外部系统，开发者以往常常要自己写很多衔接逻辑：手写 prompt 链、自行管理工具调用、处理上下文窗口超限问题，并自行维护代码执行的容器和权限。

OpenAI 在把 Codex 和 ChatGPT for Work 推广到全球数百万用户的过程中，摸清了长时间运行的 Agent 在实践中需要什么：实用 Agent 需要能够管理上下文、高效使用工具并协调子 Agent 的调度底座（harness），也需要能可靠地连续运行数天、让 Agent 在其中读写文件、运行代码并保存中间结果的基础设施。

通过 Agents API，OpenAI 把驱动 Codex 的同一套 harness 和基础设施开放给开发者。以往需要自己编写 prompt 链和管理工具调用的工作流，现在可以收拢到一个标准 API 调用中：开发者只需指定任务、模型、工具和环境，会话管理、编排、上下文压缩与恢复等复杂逻辑均由 OpenAI 托管的 Codex harness 负责。

在费用方面，Agents API 本身没有额外的平台管理费，开发者只需按实际消耗为 Agent 使用的模型 token 和内置工具付费；如果选择 OpenAI 托管沙箱，容器算力则按照标准容器费率结算。

一次 API 调用构建云端 Agent

在 Agents API 中，创建并运行一个具备多任务协同能力的 Agent 只需发起一次会话创建请求。官方发布页给出了如下 JavaScript 示例：

import OpenAI from "openai";

const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [
      {
        type: "mcp",
        server_label: "observability",
        transport: {
          type: "http",
          server_url: "https://observability.example.com/mcp",
        },
      },
    ],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: ["vault_YOUR_VAULT_ID"],
  environment: {
    type: "openai_hosted",
    capability_directories: ["/workspace/capabilities/skills"],
  },
  input:
    "Investigate service-api’s elevated 5xx rate over the last 30 minutes. " +
    "Delegate deployment, error, and dependency analysis to subagents. " +
    "Save findings, evidence, and recommended mitigation in /workspace/outputs.",
});

这段代码清晰展示了各个核心要素的协同方式：

• agent.model：指定底座模型，此处使用 gpt-6-astra。
• agent.tools：声明 Agent 可调用的工具。示例中配置了一个 mcp 类型的工具，通过 HTTP transport 连接外部可观测性服务 observability。
• agent.multi_agent：开启多 Agent 委派支持，并设置 max_concurrent_subagents: 3，允许主 Agent 最多同时派发 3 个 Subagent 并行工作。
• vault_ids：官方示例中包含了 ["vault_YOUR_VAULT_ID"]，但发布页和所附开发者文档都没有解释这个参数的用途。
• environment：指定计算沙箱。此处采用 openai_hosted（OpenAI 托管沙箱），并通过 capability_directories 指定了 /workspace/capabilities/skills 目录（开发者文档指出，skills、plugins 与 capability_directories 均可用于为托管沙箱中的 Agent 注入预置能力）。
• input：传给 Agent 的初始任务指令。该任务要求排查 service-api 过去 30 分钟 5xx 错误率升高的问题，将部署、报错与依赖分析分别交给 Subagent 处理，并将最终发现、证据与缓解建议存入 /workspace/outputs 目录。

在这个工作流中，托管的 Codex harness 负责驱动模型、管理会话并编排 Subagent；工具通过 MCP 与外部系统交互；代码和分析任务在沙箱中运行；最终结果存入 /workspace/outputs，回合结束时会自动发布为不可变产物。

核心架构拆解：框架与环境的分工

要理解 Agents API，首先要看清它在系统架构上的职责划分。OpenAI 官方架构展示了三方角色的分工：

在这套架构下，职责清晰划分为三部分：

1. 你的应用（Application）：向 Agents API 发送任务，接收返回的事件流（Events）与输出结果。
2. 托管 Codex Harness（Managed Codex Harness）：由 OpenAI 托管与维护，负责运行模型、协调工具调用、维护会话状态、调度上下文与管理子 Agent。
3. 计算沙箱（Sandbox）：由 OpenAI 或你的服务商提供，Agent 在其中读写文件、执行 Shell 命令与运行代码。

四个核心概念与生命周期

在官方的 Agents API 概览（overview） 中，整个系统围绕四个核心概念展开：

• Agent：包含分配给 Agent 的模型、指令（instructions）、工具以及 MCP 服务器配置。
• Environment：可选的沙箱或计算环境。Agent 在该环境中访问文件、加载技能（skills）并执行命令。
• Session：一个持久存在的 Agent 实例，负责执行具体任务并响应后续输入。
• Events 和 items：在整个会话期间发送给 Agent 的输入内容，以及 Agent 执行过程中产生的一系列事件和输出项。

一个完整的会话生命周期包含四个步骤：

1. 创建会话（Create a session）：应用提交 Agent 配置，OpenAI 为其准备环境（这是用 OpenAI 托管沙箱时的情形；用自托管沙箱时，执行环境由你自己启动并连回来）。
2. 给定任务（Give it a task）：环境就绪后，传入任务输入即可开启一个工作回合（Turn）。
3. 跟进进展（Follow progress）：通过事件流实时监听输出，或使用 Webhook 获知 Agent 何时完成工作、何时需要人工输入。
4. 继续或引导（Continue or steer）：可以在同一会话中继续指派后续任务，或在当前回合中途向 Agent 提供引导。

选择适配业务的沙箱环境

不同的工作负载对算力、存储和部署形态有不同需求。在 Agents API 中，开发者可以根据场景选择适合的沙箱：

• OpenAI 托管沙箱（OpenAI-hosted）：适合想快速上手、高效扩展的场景。该沙箱复用了驱动 Codex 和 ChatGPT 的同一套沙箱基础设施。OpenAI 负责调配与管理该环境，为 Agent 提供包含 Python、Node.js 及命令行工具的 Linux 工作区（工作目录为 /workspace）。
• 生态沙箱合作方（Sandbox Partners）：OpenAI 与多家生态服务商建立了一等集成（详见 自托管与合作方沙箱指南），包括 Modal、Cloudflare、Daytona、Blaxel、Runloop、Vercel、Oracle、E2B、DigitalOcean。
• 自托管沙箱（Self-hosted）：如果希望使用自己掌控的算力，可以在本地电脑、自建容器或云服务器中运行执行环境。

合作方沙箱主要满足三类需求：

1. 全托管环境或部署在企业 VPC 内部；
2. 特定的文件与密钥存储机制；
3. 不同的 CPU、GPU 和内存配置，以匹配具体工作流对性能、冷启动与成本的要求。

需要说明的是，合作方沙箱走的同样是自托管沙箱的连接机制，只是由合作服务商来提供运行机器。

自托管沙箱的连接机制与安全边界

自托管沙箱让代码和文件运行在你信任的机器上，并且所有连接均为由内向外发起（Outbound）。但需要特别注意其合规边界：会话状态和编排逻辑依然由 OpenAI 云端维护。Agents API 目前仅支持美国数据驻留、不支持零数据保留（ZDR），选择自托管沙箱并不能让会话符合 ZDR 要求。

自托管沙箱的具体配置与运行流程如下。先在内部容器或机器中安装 Codex CLI：

mkdir -p /workspace
npm install -g @openai/codex@alpha

执行端组件是 Codex CLI 自带的守护进程 codex exec-server（执行器，executor），启动命令为：

codex exec-server \
  --remote "<session.environment.remote_url>" \
  --environment-id "<session.environment.id>"

其网络与凭据设计具备以下安全特性：

• 纯出站网络连接：环境通过 HTTPS（https://api.openai.com）注册，随后通过 WebSocket（wss://codex-cloud-environments.chatgpt.com）与 OpenAI 建立长连接接收命令并回传结果，内网无需对外开放任何入站端口。
• 受限凭据隔离：注入自托管沙箱的环境变量应使用专用的受限环境密钥 CODEX_API_KEY（在平台 Dashboard 创建时将其他权限全部设为 None）。该密钥只能用来连接环境，不能执行任何其他 API 操作。Agent 生成的代码能读取到它，因此切勿将其写入源码、镜像或日志，需要时应及时轮换或吊销。
• 工作负载隔离：由于处于同一沙箱环境内的 Agent 能访问同样的文件和凭据，务必按照用户或具体工作负载严格隔离不同的运行环境。

调度底座的核心能力：Codex Harness 的关键机制

OpenAI 在推广 Codex 的过程中摸清了长时间运行的 Agent 在实践中需要什么，并将这些能力沉淀到了 harness 中。

Harness 按版本随模型升级

想要充分发挥新模型的能力，往往意味着要改动自己的调度框架（harness），占用本该用来改进应用的时间。Agents API 在每次模型发布时，都会按版本提供与之匹配的能力。OpenAI 负责将 harness 与模型协同维护并持续改进，帮助 Agent 在每次升级中获得更好的表现。

官方发布页列举了 harness 最近几项改进的典型例子（这并非完整特性清单，而是近期重点改进的方向）：自动上下文压缩、更高效的工具使用（工具搜索与程序化调用）、以及多 Agent 协同。

自动上下文压缩（Compaction）：跨多个窗口持续推进任务

Agent 连续运行并频繁调用工具时，历史记录容易逼近模型的单次窗口上限。

为支持模型连续工作数小时，Agents API 提供了原生的上下文管理能力（详见 上下文压缩指南）。当会话接近上下文上限时，系统会自动压缩早先的上下文内容，保留后续继续工作所需的信息。开发者无需自行实现压缩逻辑，即可构建跨越多个上下文窗口的工作流。

注：文中链接的压缩指南以 Responses API 为例讲解压缩机制；发布页没有展开 Agents API 里压缩的具体格式。

工具搜索（Tool Search）：按需加载工具定义

如果一开始就将所有工具的完整定义全部载入模型上下文，不仅未用到的定义会白白占用宝贵的上下文空间，改动工具定义还可能导致此前已缓存的前缀失效。

工具搜索指南 指出，该机制让模型可以根据需要动态搜索并加载工具定义。新发现的工具会被追加到上下文末尾，从而保护前序已缓存的内容不受影响。

在 Agents API 中，工具搜索的配置规则如下：

• MCP 工具：当模型与服务商支持工具搜索时，Agents API 会自动对 MCP 工具应用延迟加载并自动开启工具搜索，开发者无需做额外配置。
• 自定义函数工具：默认情况下仍为一次性全量加载（eager loading）。若希望按需发现，需要在 agent.tools 数组中声明 {"type": "tool_search"}，并在需要延迟加载的函数上逐个标记 defer_loading: true。
• 延迟加载范围：对于标记了延迟加载的单个函数，模型在初始时仍能看到其名称和功能描述，主要推迟载入的是其具体的参数结构（parameter schema）。（这一条出自工具搜索指南的 Responses API 部分。）
• （注：关于“建议将每个命名空间内的工具数量少于 10 个”，属于 Responses API 文档给出的性能建议）。

程序化工具调用（Programmatic Tool Calling）：在隔离运行时中过滤与聚合

在传统调用模式下，Agent 每调用一次工具，其返回的全部原始数据都要直接写入上下文。如果工具返回大量无用数据，上下文很快就会被填满。

程序化工具调用指南 描述了一种新模式：模型可以编写 JavaScript 代码来编排自己的工具。在 Agents API 中，程序化工具调用默认开启（若需停用需显式设置 enabled: false）。

其运行时环境具有严格的边界：

• 代码在独立且隔离的 V8 运行时中运行，支持顶级 await；
• 运行时没有直接网络访问、没有 Node.js、不能安装第三方包、没有通用文件系统，两次程序执行之间也不保留状态；
• 代码只能通过当前请求中启用的工具与外部系统交互，并通过 text(...) 或 image(...) 输出结果。

借助这一机制，模型可以在隔离环境中运行循环、条件判断，或同时调用多个已启用的工具。假设一个排查任务需要分析 100 条日志并统计频次：在传统模式下，包含 100 条日志的完整 JSON 必须全量放入上下文；而在程序化调用中，代码可以在 V8 运行时内部完成过滤、去重与统计，只把最终的简短统计结果返回给模型上下文。这种方式可以减少进入上下文的中间数据，具体能节省多少 token 取决于具体任务形态。

在工程落地时，应根据任务特征合理选择直接调用或程序化调用：

• 单次查询或单一操作：推荐直接调用（Direct tool calling）
• 需要代码进行过滤、拼接、排序、去重、聚合或校验的多条结果：推荐程序化工具调用（Programmatic Tool Calling），由代码返回精简结构化结果
• 具有可预测数据流的依赖调用：推荐程序化工具调用，由代码推导后续参数并明确边界与失败处理
• 自适应搜索或语义评估（每步结果均需模型重新判断）：推荐直接调用，使每次结果都能实时影响模型的下一步决策
• 写入操作或需要审批的高敏感动作：默认推荐直接调用，以保持清晰明确的权限与确认边界
• 最终引用校验或原生制品校验：推荐直接调用，除非程序能完整保留原生输出并验证每项必填项 发布页特别说明，Agents API 支持 MCP、自定义函数以及网页搜索等内置工具。例如，可以通过以下配置挂载 OpenAI 官方文档的 MCP 服务：

"agent": {
  "tools": [
    {
      "type": "mcp",
      "server_label": "openai_docs",
      "transport": {
        "type": "http",
        "server_url": "https://developers.openai.com/mcp"
      }
    },
  ]
}

多 Agent 并行协同（Multi-Agent Subagents）：分工与并行委派

对于复杂的分析或比对工作，Agents API 提供了原生的多 Agent 支持（详见 多 Agent 文档）：

"agent": {
  "model": "gpt-6-astra",
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 3,
  }
}

在多 Agent 机制下：

• 主 Agent（协调者）负责分解任务并委派给 Subagent 并行工作。
• 并发限制参数 max_concurrent_subagents 默认值为 6（不包括协调者），可根据需要自定义为正整数。
• 调度底座（harness）会自动提供创建、发消息、等待和打断 Subagent 的内置工具，开发者无需自行声明这些工具。
• 适用场景：适合彼此独立的任务（如独立审查不同的文档或分别排查故障的不同根因），每个子任务需具备明确的问题和预期产出。短任务或具有前后依赖的步骤应保留在主 Agent 中执行。
• 文件协同注意事项：每个 Subagent 拥有独立的上下文窗口以保持任务专注；但当连接到沙箱时，所有 Agent 共享同一个沙箱文件系统。如果多个 Agent 需要修改同一批文件，必须在流程上明确协调机制。

限制说明（来自多 Agent 文档）：Subagent 会继承主会话配置的 MCP 工具（包含其访问凭据与允许工具列表）以及网页搜索配置，也可以使用沙箱环境内的文件和命令行工具；但Subagent 目前不支持函数工具（Function Tools）。

编辑建议：如果业务中存在需要交给 Subagent 处理的自定义逻辑，建议将其封装为 MCP 服务或沙箱内的命令行脚本。

开源底座：Codex Harness

驱动 Agents API 的是开源的 Codex harness。协调模型调用、工具使用与上下文管理的核心调度逻辑，均可在公开代码库 openai/codex 中查看与学习。通过 Agents API，OpenAI 负责在云端运营和维护该 harness，开发者无需自行搭建和维护底座即可直接使用。

官方最小示例（quickstart）

在官方 快速入门指南（quickstart） 中，使用 Python SDK（beta.agents 命名空间）拉起一个具备代码执行与文件操作能力的会话，代码如下：

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)

在这段代码的执行流程中，系统完成以下动作：

1. 环境准备：OpenAI 在云端为该会话调配 openai_hosted 沙箱环境，工作目录为 /workspace。
2. 代码生成与执行：Agent 在工作区内创建 tree.py 文件，并在沙箱终端中运行该脚本，获取目录树输出。
3. 跟进事件流与状态确认：客户端通过事件流监听进展。当回合结束时，系统会发出 agent.session.turn.completed 事件，但这并不保证每个工具调用都成功执行，仍需检查 Agent 汇报的实际执行结果。如果收到 turn.failed、turn.cancelled 或 session.failed，则表示回合失败或被取消；仅凭 agent.session.idle 状态并不能代表任务成功。若流意外中断，应先取回会话及已保存的 items，再决定是否重试。
4. 产物归档与保留：如果任务生成了报告或数据图表，只要写入 /workspace/outputs 目录，在回合完成时就会被发布为不可变产物（Immutable Artifacts）。即使沙箱后续因闲置被清理，这些产物副本依然可供下载。在清理并删除会话之前，应先下载所需的文件。

托管沙箱的环境配置与网络控制

根据 OpenAI 托管沙箱配置指南，沙箱提供了细致的环境定制能力：

• 预装配置：可通过 packages 安装 Python、系统或 npm 依赖；通过 setup_commands 在 Agent 启动前按序执行预备 Shell 命令（若 setup 命令返回非零退出码，Agent 将不会启动）；通过 files 上传初始文件；通过 env 设置环境变量（但系统保留名称如 PATH、CODEX_*、OPENAI_API_KEY 等会被拒绝）；以及通过 skills、plugins 和 capability_directories 加载预置功能。
• 网络出站控制：若在配置中不声明 network，沙箱默认允许向外出站访问（enabled）。若需收紧网络权限，可将 network.access 设为 disabled（完全禁止出站连接）或 restricted（受限出站）。在 restricted 模式下，allowed_domains 需配置 1 到 100 个精确的主机名（如 api.example.com，不支持通配符、协议头、路径或端口，每个子域名和重定向目标都要单独列出）。需要注意的是，托管的 stdio MCP 服务器目前要求网络模式必须为 enabled。
• 后台运行机制：关闭客户端的事件流连接并不会取消沙箱中正在执行的任务。

客户怎么说（发布页上的客户自述）

在发布页中，OpenAI 披露了 8 家早期采用者的自述评价。其中 Ciridae、Hypha 与 SafetyKit 提供了迁移前后的量化指标，其余团队则分享了在各自场景中的工程体验：

• Ciridae（Jack Weissenberger，CTO）· Subagent 工作流（未说明具体业务）：评测分数从 0.71 提升至 0.85，延迟降低到原来的 1/4。Subagent 流开箱即用，大幅简化了过去自行编排与观测 Subagent 的繁重工作。
• Hypha（Serhii Shchoholiev，Lead Engineer）· 金融服务：在金融服务领域赢得客户信任至关重要。通过将 harness 与沙箱解耦，失败的 Agent 响应减少了 86%，让客户更有信心在生产环境中使用。
• SafetyKit（Bhavyansh Sabharwal，Member of Technical Staff）· 案件审核流程（Case review）：案件审核流程迁移到 Agents API 后，单案成本降低 60%，延迟更低，token 效率明显改善，同时效果保持不变。
• WithCoverage（Cole Striler，Director of Engineering）· 复杂多步工作流：过去需要编写 prompt 链并自行管理工具调用，现在能像 Codex 在笔记本电脑上运行那样直接在代码中使用 Agent，解决了多个本来需要自建 Agent 基础设施的问题。
• Dwelly（Dmitry Khanukov，Co-founder & CTO）· 突发型工作负载：测试中最突出的是处理突发负载的能力。可以将工作分发给几百个 Agent 异步运行并在稍后收集结果，在业务高峰之间无需让基础设施空转。
• deepsense.ai（Maks Operlejn，Senior ML Engineer）· 真实代码库里的工程任务：Agent 在一个真实的、活跃的代码库中完成了功能实现、独立审查、问题修复以及真实的浏览器验证，整体工程质量表现很强。
• Nash.ai（Aziz Alghunaim，Co-founder & CTO）· 全球物流配送调度：部署了数千个长期运行的 Agent，管理数亿次配送。Agents API 提供了持久会话与编排层（负责管理上下文、恢复与多步执行），而 Nash 自身提供连接物理世界的工具与执行环境，使 Agent 能够跨越数小时或数天持续协同与恢复。
• Long Lake（Rasmus Wissmann，CTO）· 跨行业 AI 平台（Nexus）：Agents API 提供 harness，而环境、上下文与交互体验仍由企业掌控。借助 Nexus 平台，可以在数小时内在从住宅服务到建筑设计的多个行业中搭建起 Agent。

计费构成与技术限制

在将业务接入 Agents API 之前，需要清楚其费用构成与当前阶段的技术约束。

计费构成

发布页说明，Agents API 本身不收额外费用，只按 Agent 实际用掉的 token 和工具付费；各项单价见价格页面：

• 模型 Token 费用：按照所选底座模型的标准 API 费率计费。以示例中的 gpt-6-astra 为例（短上下文价格），未缓存输入 $10.00 / 1M token，缓存输入 $1.00，缓存写入 $12.50，输出 $50.00；长上下文价格更高（输入 $20.00、缓存输入 $2.00、缓存写入 $25.00、输出 $75.00）。（注：若关注价格表中的 gpt-5.6-sol，其输入为 $4.00 / 1M，输出为 $20.00 / 1M，但该价格为促销费率，至少持续至 2026 年 11 月 21 日，且当前官方材料尚未确认 Agents API 是否支持该模型）。
• 内置工具调用费：内置网页搜索为每千次调用 $10.00，搜索内容所引入的 token 按所选模型的输入费率另计。（注意：价格表中的文件检索 File search 工具调用费仅适用于 Responses API，不适用于 Agents API）。
• 容器算力费（仅适用于 OpenAI 托管沙箱）：
  • 1 GB 规格：$0.03 / 20 分钟
  • 4 GB 规格：$0.12 / 20 分钟
  • 16 GB 规格：$0.48 / 20 分钟
  • 64 GB 规格：$1.92 / 20 分钟 价格页没有说明 GB 指哪项资源，也没说明托管沙箱默认用哪一档。符合条件（Eligible）的容器会话按分钟计费，单次会话起步计费时长为 5 分钟。OpenAI 的容器费只针对托管沙箱；用自托管或合作方沙箱时，算力由你自己或服务商承担。

技术与合规限制

根据官方开发者文档，当前版本存在以下明确的边界与约束：

• 数据驻留与零数据保留（ZDR）限制： 开发者文档明确声明，Agents API 当前仅支持美国数据驻留（US data residency），并且不支持零数据保留（Zero Data Retention, ZDR）；即便选择自托管沙箱，也不会变成符合 ZDR 要求。 编辑理解：这是因为会话状态管理、编排与 harness 调度仍集中在 OpenAI 云端。如果业务要求 ZDR，文档提到 Responses API 的部分能力（如服务端压缩配合 store=false、程序化工具调用）支持 ZDR 工作流，但 ZDR 需先为组织或项目开启；如果要求美国以外的数据驻留，材料没有给出 Agents API 的替代方案。
• 沙箱生命周期与 1 小时闲置清理： OpenAI 托管沙箱文档指出，连接中的沙箱会自动接收保活信号（回合之间亦然）。若沙箱的活动与保活信号均停止达 1 小时，沙箱可能会被删除（该超时时长不可自定义）。因此，需要持久保存的文件必须存入 /workspace/outputs 目录，该目录下的文件在回合完成时会发布为不可变产物，沙箱过期后依然可供下载。
• 删除会话时的 409 冲突： 在沙箱正在初始化或执行命令时，调用 SDK 的 client.beta.agents.sessions.delete 可能会返回 HTTP 409 Conflict。生产环境代码需加入重试机制并设定最大重试次数。此外，关闭事件流连接并不会取消后台任务。

落地选型与实践清单

环境选型建议（编辑整理，依据开发者文档）

在选择 Agent 的执行环境时，可对照以下条件进行筛选：

1. 合规硬门槛评估：如果你的业务场景强制要求零数据保留（ZDR），或者要求数据必须驻留在美国境外，目前无法使用 Agents API。需要 ZDR 的，可以评估 Responses API 中支持 ZDR 的工作流（需先为组织或项目开启 ZDR）；需要美国以外数据驻留的，材料没有给出替代方案。
2. 追求快速验证与低维护成本：优先选择 OpenAI 托管沙箱（OpenAI-hosted）。由官方自动调配 Linux 环境，并支持通过 restricted 或 disabled 收紧网络出站策略。受控的网络策略并不意味着必须自建沙箱。
3. 需要专有算力、特定镜像或内网访问：选择 自托管沙箱（Self-hosted） 或 生态沙箱合作方（Sandbox Partners）。适合需要定制特定系统依赖、使用专用 GPU 算力、挂载私有存储或必须置于自有 VPC 内部的场景。

生产就绪检查清单（Checklist）

在将 Agents API 接入生产环境前，建议对照官方规范进行逐项确认：

• [ ] 密钥权限与环境隔离：
  • 主应用 API 密钥（需具备 api.agents.read/write 与 api.responses.write 权限）保存在沙箱环境之外。
  • 自托管沙箱仅持有受限环境密钥 CODEX_API_KEY，在平台创建时其他权限均设为 None，仅保留环境连接权限。
  • 针对不同用户或不同工作负载严格隔离运行环境，避免共享环境内的文件与凭据泄露。
• [ ] 网络出站策略收敛：
  • 使用 OpenAI 托管沙箱时，若未显式配置 network，系统默认允许向外出站访问。如需收紧，应主动配置为 disabled 或 restricted。
  • 在 restricted 模式下，需在 allowed_domains 中逐一配置精确的主机名（1–100 个，不支持通配符，重定向目标需一并列入）。
  • 注意：托管的 stdio MCP 服务器当前要求网络必须设为 enabled。
• [ ] 产物持久化：
  • 任务生成的核心数据、报告和代码文件已明确要求写入 /workspace/outputs 目录。该目录内容会在回合完成时固化为不可变产物，避免沙箱闲置删除后丢失。在调用会话删除接口前，先下载所需文件。
• [ ] 多 Agent 机制适配：
  • 确认任务拆分属于相互独立的工作；若多个 Subagent 共享沙箱，修改同批文件时需设计明确的协作顺序。
  • Subagent 继承 MCP 工具与网页搜索，但不支持普通函数工具（function tools）。
• [ ] 异常与断线容错处理：
  • 监听事件流中的 turn.completed、turn.failed、turn.cancelled 与 session.failed。注意 turn.completed 并不保证每个工具都调用成功，必须检查 Agent 汇报的实际执行结果；单纯收到 agent.session.idle 并不代表任务成功。
  • 事件流意外断开时，按照文档指引“取回会话及已保存的 items”以恢复状态，不要盲目重复新建会话。

公测与开始使用

Agents API 现已向所有开发者公开测试（Public Beta）。在公测期间，OpenAI 将根据开发者反馈进行快速迭代并推进至正式版（GA），在此期间 API 接口可能会有所调整。

使用 Agents API 没有额外的平台费用，开发者仅需为模型 token、使用的内置工具以及托管沙箱容器算力付费。

开发者可以参考官方文档进一步了解与上手：

• 阅读 Agents API 概览（overview） 了解完整架构与核心概念；
• 按照 快速入门（quickstart） 运行首个 Agent 会话。使用 cURL 发起请求时，需在请求头中显式添加 OpenAI-Beta: agents=v1（官方 SDK 会自动附带该请求头）；主应用 API Key 需具备 api.agents.read/write 和 api.responses.write 权限。