发布日期：2026-09-14 | 分类：AI与智能服务

OpenAI Agents API 是 OpenAI 于 2026 年 9 月 10 日进入公测的托管型 Agent 运行接口，它把驱动 Codex 的开源 harness 以 API 形式对外开放，由 OpenAI 负责会话、编排、上下文压缩与故障恢复，开发者只需提供任务、模型、工具和运行环境。本文依据 OpenAI 官方公告、开发者文档与 SDK 发布记录，梳理 Agents API 的四个核心概念、它与 Responses API 和 Agents SDK 的分工、三种运行环境的取舍、一次 API 调用启动会话的最小示例，以及公测阶段的计费与数据驻留限制。结论是：Agents API 不额外收费，成本来自模型 token、内置工具和托管沙箱；它适合需要跨多个上下文窗口持续运行、并由服务端保存进度的长任务，而对状态需要完全自控或依赖订阅额度的场景，仍以 Agents SDK 或 Responses API 更合适。文中数据截至 2026 年 9 月 14 日。

Agents API 是什么

Agents API 是 OpenAI 在 2026 年 9 月 10 日以公测形式发布的接口，让应用通过 OpenAI 托管的 API 直接使用 Codex harness，OpenAI 负责会话、编排、上下文压缩与恢复，开发者负责工具和运行环境。发布日期可以在 openai-python SDK 的 v3.13.0 发布记录中核对，该版本于 2026 年 9 月 10 日发布，变更日志只有一条：api: add Agents API。同日发布的 openai-node v7.15.0 也加入了同一功能。

官方文档把 Agents API 拆成四个核心概念：

  • Agent：模型、指令、工具以及 Agent 可用的 MCP 服务器。

  • Environment：可选的沙箱或计算机，Agent 在其中访问文件、加载 skills、执行命令。

  • Session：Agent 的持久化实例，负责处理任务并响应输入。

  • Events 与 Items：发给 Agent 的输入，以及会话过程中产生的输出。

OpenAI 在公告中说明，Agents API 运行在开源的 Codex harness 之上，harness 能力随每次模型发布做版本化更新。近期加入的三项能力是：自动上下文压缩，让工作流跨越多个上下文窗口；按需加载工具定义的 tool search 与支持并行和链式调用的 programmatic tool calling；以及多 Agent 支持，子 Agent 拥有独立上下文，由主 Agent 协调并行工作。

与 Responses API、Agents SDK 的区别

OpenAI 开发者文档把三种 Agent 运行方式并列比较，核心差异在于"Agent 在哪里跑"和"状态由谁保存"。下表整理自官方文档中的 Compare agent runtime options 一节。

维度

Agents API

Agents SDK

Responses API

适用场景

长时间运行、由 OpenAI 托管并保存进度的任务

在自己应用里用自定义工具和工作流构建 Agent

直接调用模型，或从零搭建 Agent

Agent 运行位置

OpenAI 运行托管的 Codex harness

SDK 运行在你的应用内

你的应用，可选托管编排

集成工作量

低

中

高

任务间状态

保存会话配置、turns 与 items

你的存储与 SDK 会话，或 Responses 对话状态

手动历史、响应链或 Conversations

执行环境

OpenAI 托管沙箱、自托管沙箱或无沙箱

你的运行时与沙箱提供方集成

你自己的执行环境

官方文档还提醒，Agents API 会话、Agents SDK 会话、Responses 对话与沙箱是四种彼此独立的资源，各有自己的状态和清理规则，迁移时不能互相替代。

三种运行环境怎么选

Agents API 的架构由 harness、environment 和 application server 三部分组成，其中 harness 是 OpenAI 托管的 Codex 实例，负责跑模型与工具循环并维护会话；environment 是 Agent 执行命令、运行代码、操作文件的地方；application server 是开发者自己的集成代码，负责提交任务、接收事件、处理 function tool。官方架构文档给出的原则是：harness 可以在没有 environment 的情况下工作。

三种环境类型对应三类需求：

  1. none：适合只回答问题或调用外部服务的 Agent。harness 可以自行调用远程 MCP 工具，function tool 则由开发者代码执行并回传结果。此模式下内置的 Bash、apply-patch 工具、工作区文件和 executor MCP 都不可用。

  2. openai_hosted：OpenAI 为会话配置并管理沙箱，开发者声明需要的软件包、文件和网络访问，harness 直接在沙箱内执行命令。公告说明这套沙箱与 Codex、ChatGPT 使用的是同一套隔离机制。

  3. 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 Platform 项目中创建应用密钥，并授予 api.agents.read、api.agents.write 和 api.responses.write 三个权限范围；官方文档同时提醒，密钥不要放进 Agent 的沙箱里。

以下 cURL 示例按官方快速上手文档中的字段整理，模型名为文档示例所用的 gpt-6-astra：

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": "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
  }'

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))

读取事件流时有两条官方给出的判定规则值得记住。第一，看到 agent.session.turn.completed 只说明这一轮结束，不代表每个工具调用都成功，仍需核对 Agent 报告的结果；第二，agent.session.idle 单独出现不等于成功，以 turn.failed、turn.cancelled、session.failed 结尾的事件才是失败信号。任务完成后用 DELETE /v1/agents/sessions/{session_id} 删除会话，删除前先保存需要的文件。

费用怎么算

OpenAI 公告写明，使用 Agents API 本身没有额外费用，成本只来自 token 与工具用量。官方 observability 文档进一步拆解，一次会话的总成本包括根 Agent 与子 Agent 的全部工作，含重试，再加上工具、沙箱算力和第三方服务费用。推理 token 按输出 token 计费，缓存 token 计入输入 token。

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

计费上有两个官方明确标注的坑。其一，会话与 turn 资源上的 usage 字段是尽力而为的估算，可能为 null，且"缺失 usage 不代表零用量，这些计数不是最终账单"。其二，usage 不暴露单独的 cache-write 计数，对有缓存写入定价的模型无法从字段直接推算精确费用；维持一个会话也不保证命中缓存。

国内团队如果通过兼容 OpenAI 接口的推理服务接入多款主流大模型，计量方式会有所不同，例如七牛云企业级 AI Token 套餐以积分计量，基础费率为每千 token 0.004 元，各模型按其单价与基础费率的比值折算积分。

适用场景与公测限制

Agents API 的目标场景是需要服务端保存进度的长任务：代码库级重构、跨多步骤的数据处理、需要子 Agent 并行拆解的研究类任务。官方 overview 文档的示例配置里，multi_agent 开启后可通过 max_concurrent_subagents 限制并发子 Agent 数量，示例值为 4；observability 文档则说明每个命令 item 都带 turn_id，通过 turn 可查到 subagent_id，为 null 即代表根 Agent 的工作，方便做用量归因。

公测阶段有三条限制需要在架构选型前确认：

  • 数据驻留：官方 overview 文档写明，Agents API 目前仅支持美国数据驻留，且不支持 Zero Data Retention；使用自托管沙箱也不改变 ZDR 资格。

  • 可观测性：会话可在 platform.openai.com 的 Agents 日志页按 session ID 查看 turns、工具调用与子 Agent，但"trace 检索和外部 trace 导出不属于公测 API"，普通项目 API Key 拿不到详细 trace。

  • 命令输出截断不上报：observability 文档注明，命令输出被截断时不会有事件提示，依赖命令输出做判断的流程需要自行校验。

小结

Agents API 把 Codex 的 harness 从 CLI 产品变成了可编程的托管服务，开发者用一次 POST 就能拿到带上下文压缩、子 Agent 编排和沙箱执行的长任务 Agent，代价是状态保存在 OpenAI 一侧，且公测期只有美国数据驻留。它与 Agents SDK、Responses API 的分工，OpenAI 开发者文档的运行时对比表已经写得很清楚：托管省力选 Agents API，状态自控选 Agents SDK，只要模型能力选 Responses API。本文事实来源以 OpenAI 官方公告 Introducing the Agents API 与 developers.openai.com 上的 Agents API 文档为准，本文数据截至 2026 年 9 月 14 日。

参考资料