OpenAI Agents API实战指南：沙箱选型与多Agent落地

引言

2026年9月10日，OpenAI 正式开启 Agents API 的公测。该接口把驱动 Codex 的开源 Harness 框架以托管API形式对外开放。开发者无需自行搭建 Agent 运行时，由 OpenAI 负责会话编排、上下文自动压缩、故障恢复等底层能力；开发者仅需要定义任务指令、选定模型、配置工具集和运行环境。本文参考 OpenAI 官方公告、开发者文档与 SDK 更新记录，拆解 Agents API 的四大核心概念，对比它与 Responses API、Agents SDK 的分工差异，详解三种运行环境的选型逻辑、调用示例、计费规则，同时梳理公测阶段的约束条件与适配场景。文中所有技术参数、接口特性数据截止至2026年9月14日。

Agents API 定位为托管型 Agent 运行接口。一次API调用就能够启动具备会话持久化能力的最小实例。公测阶段的计费规则与数据留存机制有明确边界。总体来看，Agents API 适合需要跨多个上下文窗口持续执行、并且交由服务端保存任务进度的长任务场景；如果业务需要完全自主管控任务状态，或是自定义调用配额限制，Agents SDK 或者 Responses API 会是更合适的方案。

一、Agents API 核心定义与四大基础概念

Agents API 依托开源 Codex Harness 运行，Harness 的能力会跟随模型版本迭代持续更新。本次公测新增三项关键能力：自动上下文压缩，支持任务流程跨多个上下文窗口执行；按需加载工具定义的 tool search；支持串行与并行调用的可编程工具调用，同时支持多Agent协同，子Agent具备独立上下文，由主Agent统一调度协调。

官方文档将 Agents API 的基础单元拆解为四个核心概念：

1. Agent：模型、指令、工具集与Agent可用MCP服务的组合。开发者在这里定义Agent的基础行为逻辑、可用工具范围。
2. Environment：可选的沙箱或计算环境，Agent在此环境访问文件、加载技能、执行各类指令。
3. Session：Agent持久化运行实例，负责接收任务、执行推理、响应外部输入，是单次任务的载体。
4. Events & Items：传递给Agent的输入信息，以及会话执行过程中产生的输出内容，包括工具返回结果、模型生成文本等。

从底层逻辑上看，开发者不再需要维护循环调度逻辑，Harness会自动处理模型-工具之间的调用循环，并且维护会话的完整生命周期。

二、Agents API、Agents SDK、Responses API 横向对比

OpenAI官方文档并列介绍了三种构建Agent体系的方案，三者最核心差异在于Agent运行载体以及任务状态的保存位置。下表整合官方文档对比信息，清晰区分三者适用边界：

文档特别提示，Agents API会话、Agents SDK会话、Responses对话、沙箱是四类相互独立的资源，各自拥有独立的状态和清理规则，项目迁移时不能直接复用资源。简单总结选型原则：

• 希望快速落地长任务Agent，不想维护Harness与沙箱：优先选择 Agents API；
• 需要深度控制Agent运行逻辑、自定义存储、私有化调度：选择 Agents SDK；
• 仅调用基础模型，简单对话、短任务，自行编写Agent循环逻辑：使用 Responses API。

三、三种运行环境的选型方法

Agents API整体架构分为Harness、Environment、应用服务三部分。Harness是OpenAI托管的Codex实例，负责模型与工具循环，维护会话；Environment是Agent执行代码、读写文件、执行指令的环境；应用服务属于开发者侧，负责接收任务请求、处理工具回调。官方架构文档说明，Harness在不配置Environment的情况下，依然可以独立工作。

三种环境分别匹配三类业务需求：

1. none（无环境）

适合纯问答、调用外部远程服务的Agent。Harness能够直接调用远程MCP工具，函数工具由开发者代码执行并返回结果。该模式下，内置Bash、apply-patch工具、工作区文件、executor MCP均不可用，无法执行本地代码与文件操作。

1. openai_hosted（OpenAI托管沙箱）

由OpenAI负责会话管理、沙箱生命周期管理。开发者只需要声明软件包、文件读写、网络访问权限，Harness直接在沙箱内执行命令。官方说明，这套沙箱机制与Codex、ChatGPT使用同一套隔离体系，安全隔离能力成熟。

1. self_hosted（自托管环境）

适用于私有内网、定制软件、自有基础设施场景。开发者自行启动环境，对接executor组件，由executor执行Harness下发的命令与工具调用请求。开发者全权负责环境供给、连接维护、关停策略、文件持久化管理。

除自建之外，OpenAI公布首批沙箱生态合作伙伴，包含Blaxel、Cloudflare、Daytona、DigitalOcean、E2B、Modal、Oracle、Runloop与Vercel。服务商可以覆盖VPC部署、存储密钥管理，提供不同规格CPU、GPU、内存配置，适配不同算力需求。

四、快速上手：会话创建、代码示例与事件判断规则

创建会话仅需要发送POST请求。所有请求必须携带请求头OpenAI-Beta: agents=v1，官方SDK会自动填充该请求头，使用curl发起请求时需要手动添加。API Key需要在OpenAI平台项目中创建应用密钥，同时授予api.agents.read、api.agents.write和api.responses.write三项权限。密钥严禁写入沙箱环境中。

CURL调用示例：

curl https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-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"},
  "input": "Write a python script that creates a readable tree of the files in the current directory."
}'

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="Write a python script that creates a readable tree of the files in the current directory."
    ):
        pass

开发者读取事件流时，两条关键规则需要重点掌握：

1. 事件agent.session.turn.completed，仅代表本轮推理结束，不等于所有工具调用全部执行成功，业务逻辑仍要校验Agent返回结果。
2. agent.session.id单独存在不代表会话成功；以turn.failed、turn.cancelled、session.failed结尾事件才标识任务失败。任务执行完毕后，可以发送DELETE /v1/agents/sessions/{session_id}删除会话，删除前务必持久化保存业务需要的文件与结果。

五、计费规则拆解

OpenAI公告明确：使用Agents API本身不会收取额外服务费，全部成本来自token消耗和沙箱算力资源。官方可观测文档进一步拆解，单次会话总成本包含主Agent、子Agent的全部推理，包含重试消耗、工具调用开销、沙箱容器算力，以及第三方服务调用费用。推理token、输出token分别计费，缓存token也会计入token统计。

以示例模型gpt-6-astra为例，OpenAI在2026年9月定价：标准短上下文输入token为每百万10美元，缓存输入每百万1美元，输出token每百万50美元。托管沙箱容器按照规格计费，1GB规格容器每20分钟会话收取0.03美元，符合条件的容器会话按分钟计费，最低计费时长5分钟。内置web search工具每次调用收费10美元，检索内容的token继续按照模型费率单独计费。

计费有两个容易踩坑的要点：

1. 返回字段usage是尽力统计，有可能返回null；并且usage字段不包含沙箱缓存读写开销，存在缓存命中场景时，无法依靠此字段精确核算全部费用。
2. 会话持续运行，不代表缓存一定能够命中，缓存的稳定性无法保证。

国内团队如果需要兼容OpenAI接口的推理服务接入多款主流大模型，可以通过koalaapi，一款API gateway，统一做请求转发、用量统计与模型切换，降低多模型项目的对接成本。

六、适用场景与公测阶段限制

Agents API目标场景，是需要服务端持久保存进度的长任务，典型场景包括：代码库重构、多步骤数据处理、多子Agent并行拆解的研究任务。官方示例配置中，开启multi_agent之后，可通过max_concurrent_subagents参数限制并发子Agent数量，示例默认值为4。可观测文档说明，每一条命令item都携带turn_id，通过turn可以追溯对应的subagent_id；当subagent_id为null，则代表该任务是主Agent执行，方便开发者做用量溯源。

公测阶段有三条硬性约束，选型前必须确认：

1. 数据驻留：公测版本仅支持美国区域数据存储，不支持Zero Data Retention；使用托管沙箱也无法改变ZDR相关权限。
2. 可观测性：会话日志在platform.openai.com的Agents页面，可通过session ID查看turn、工具调用、子Agent信息。但是trace检索、外部trace导出不属于公测API能力，普通项目API密钥无法读取完整trace链路。
3. 命令输出截断不上报：当命令输出内容被截断时，不会产生事件提示。业务流程依赖命令输出做判断时，开发者必须自行增加校验逻辑。

七、小结

Agents API把Codex Harness从命令行工具升级为托管服务。开发者只需要一次POST请求，就可以拿到具备自动上下文压缩、子Agent编排、沙箱执行能力的长任务Agent。代价是任务状态保存在OpenAI服务端，公测阶段仅支持美国区域存储。

OpenAI文档已经清晰划分三者分工：想依靠托管能力快速落地长任务，选 Agents API；业务需要自主管控状态、自定义运行逻辑，选 Agents SDK；仅调用基础模型能力，则使用 Responses API。本文全部内容参考OpenAI官方文档、开发者公告，截止时间2026年9月14日。

了解更多：https://koalaapi.com