OpenAI Agents API 接中转前怎么验：会话、MCP、沙箱与计费兼容清单

如果你准备把 AI 编程代理、自动化研究或长任务 Agent 接到第三方中转 API，最近新增的一个问题是：渠道能返回 OpenAI 模型文本，是否就代表它兼容 OpenAI Agents API？

答案通常是否定的。

OpenAI 在 2026 年 9 月 10 日发布 Agents API，官方 SDK 同期加入 beta.agents 命名空间。它与只发送一轮 /v1/responses 请求的集成不同：应用需要创建和继续 Session，接收事件流，处理工具结果，还可能涉及 MCP、沙箱、文件、Artifacts、Vault、子 Agent 和长任务恢复。

因此，渠道页面上写着“支持 OpenAI”或“支持 GPT-6 Astra”，最多只能说明模型或某条基础接口可能可用，不能直接推出 Agents API 的控制面、执行环境和事件协议也能工作。下面按实际接入顺序拆开核对。

本文资料核验时间：2026 年 9 月 17 日（UTC）。文中没有假定任何第三方中转站已经开通 Agents API，也没有把一次成功请求当作长期可用性证明。

先理解：Agents API 不是 Responses API 的一个别名

OpenAI 官方把三种运行方式分开：

运行方式	谁负责 Agent 循环	状态保存在哪里	适合什么场景
Agents API	OpenAI 托管 Codex harness	OpenAI 管理 Session、Turn 和 Item	希望少写编排代码、运行长任务
Agents SDK	应用自己的运行时	应用存储或 SDK Session	需要自己控制部署、审批和工作流
Responses API	应用直接控制	应用手动串联历史或使用 Conversation	直接调用模型，或自行构建 Agent

Agents API 的核心资源不是一段文本，而是一组有生命周期的对象：

• Agent：模型、指令、工具和 MCP 配置。
• Environment：可选的 OpenAI 托管沙箱、自建环境或 none。
• Session：可以跨多轮继续工作的持久会话。
• Turn、Event、Item：任务执行过程、实时事件和保存后的历史项目。

这一区分对中转用户很重要。一个渠道即使能把 model: "gpt-6-astra" 转发到 /v1/responses，也可能没有实现 /v1/agents/sessions，更不一定能保存 Session 或转发 Agents API 的事件类型。

第一关：确认渠道是否真的实现 Agents API 路径

官方 JavaScript SDK 7.15.0 在 2026 年 9 月 10 日加入 Agents API，底层资源包括 Agents、Sessions、Environments 和 Vaults。SDK 代码还会为相关请求自动添加：

OpenAI-Beta: agents=v1

最小的官方快速开始请求是创建 Session 并让它流式返回：

curl --no-buffer --fail-with-body \
  https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -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, run it, and show me the output.",
    "stream": true
  }'

核验中转渠道时，不要只测试普通聊天。至少要确认以下项目：

核验项	需要观察什么
基础路径	是否明确支持 /v1/agents 和 /v1/agents/sessions，而不只是 /v1/chat/completions 或 /v1/responses
Beta 头	是否保留 OpenAI-Beta: agents=v1，以及渠道是否会错误删除或改写该头
资源生命周期	能否创建、读取、更新、删除 Agent 和 Session
分页	Session 的 Items、Turns、Agents 列表是否保留游标分页字段
流式响应	是否返回完整的 Agents 事件，而不是只抽取最终文本
错误语义	turn.failed、turn.cancelled、session.failed 是否仍能被客户端区分
SDK 行为	官方 SDK 指向自定义 baseURL 后，beta.agents 是否仍能正常工作

如果渠道只给出一个“OpenAI 兼容地址”，但没有列出这些路径和限制，应把它标记为“基础模型接口待核验”，不要写成“Agents API 已支持”。

第二关：流式事件不能只取最后一段文本

Agents API 的 Session 事件流用于跟踪环境连接、Turn 生命周期、工具调用和输出进度。官方文档列出的事件包括：

agent.session.environment.connected
agent.session.turn.created
agent.session.turn.in_progress
agent.session.turn.item.added
agent.session.turn.output_text.delta
agent.session.turn.completed
agent.session.idle

失败也有不同层级：

• agent.session.turn.failed：某一轮失败。
• agent.session.turn.cancelled：某一轮被取消。
• agent.session.environment.failed：执行环境失败。
• agent.session.failed：Session 生命周期失败。
• error：流或 API 层面的错误。

这意味着客户端不能用“收到 HTTP 200”或“看到 agent.session.idle”判断任务成功。官方快速开始明确提醒：一个完成的 Turn 不保证每个工具都成功；如果流提前断开，应先读取 Session 保存的 Items，再决定是否恢复或重试。

中转兼容性测试至少包含三种情况：

1. 正常流式任务，确认 turn.completed、idle 和输出增量的顺序没有改变。
2. 工具或环境失败，确认失败事件不会被渠道包装成普通文本。
3. 客户端主动断线后，通过 Session 和 Items 恢复，而不是盲目重新创建任务。

这也是为什么只用 SDK 里的 response.output_text 做冒烟测试不够：它可能掩盖事件缺失、重连失败和中途工具错误。

第三关：MCP 的连接位置决定中转能不能碰到它

Agents API 的 MCP 连接有两条不同路径：

MCP 连接方式	实际发起连接的位置	是否需要 Environment
HTTP，connection_origin: "service"	OpenAI 服务	否
HTTP，connection_origin: "environment"	Session 的执行环境	是
stdio	Session 环境内启动进程	是

例如，远程 HTTP MCP 可以由 OpenAI 服务直接连接：

{
  "type": "mcp",
  "server_label": "docs",
  "transport": {
    "type": "http",
    "server_url": "https://example.com/mcp"
  },
  "connection_origin": "service",
  "required": true
}

如果 MCP 服务位于内网，或者需要在沙箱中启动本地进程，就必须选择 Environment 侧连接。此时，中转服务即便能转发模型请求，也未必能提供对应的网络出口、进程启动和环境生命周期管理。

MCP 官方 2026-07-28 规范还要求客户端认真处理授权和工具语义：HTTP MCP 的授权基于 OAuth 相关发现与 Resource Indicators；tools/list 支持分页和缓存；tools/call 的结果还可能包含 isError 或要求额外输入。对渠道的实际核验应包括：

• 是否保留 MCP 工具的完整名称、描述和 JSON Schema。
• 工具列表变化时，是否能处理 listChanged 或缓存失效。
• 工具业务失败时，是否保留 isError，而不是把 HTTP 200 当成执行成功。
• 远程 MCP 的 OAuth、Bearer Token 或渠道自己的凭证注入是否有清晰边界。
• MCP 是由服务端连接，还是由 Environment 连接；两者不要混为一谈。

尤其要问清楚：中转站说的“支持 MCP”，究竟是它自己的网关能连接 MCP，还是它仅仅把模型请求中的工具字段原样转发。两者不是同一件事。

第四关：沙箱、文件和凭证不是模型能力

Agents API 支持三种环境思路：

• none：不执行命令、不使用工作区文件，适合回答问题或调用远程工具。
• openai_hosted：由 OpenAI 创建并管理沙箱，Agent 可以运行命令、编辑文件和生成 Artifacts。
• self_hosted：应用负责启动和维护自己的执行环境，Executor 连接到 Session。

因此需要把“模型支持”与“执行环境支持”分成两张表。以 AI 编程代理为例，下面这些能力都不应由模型名称推断：

能力	额外要核对的对象
执行 Shell	Environment 类型、Executor 连接和命令结果事件
修改文件	工作区挂载、文件读取和 Artifact 下载
访问私有网络	出网策略、连接位置和允许的目标域名
使用第三方 API	MCP 授权、Vault 或凭证代理
自建沙箱	环境启动、重连、停止和未完成任务处理

OpenAI 的沙箱安全文档建议为不同用户或工作负载隔离执行环境，限制出站网络，并把应用 API Key 放在沙箱之外。文档还把应用权限和 Executor 的环境密钥分开：应用侧需要管理 Session 的权限，而环境密钥只用于连接执行环境，不能替代其他 API 授权。

对中转渠道来说，这会产生一个实际边界：如果它只代理模型请求，就不能自动获得你的私有网络、沙箱文件或第三方凭证。需要执行代码的 Agent，仍然要明确谁提供 Environment，谁负责隔离和回收资源。

第五关：把费用拆成模型、工具、沙箱和整条任务

OpenAI Agents API 官方定价说明把费用拆成几类：模型用量按所选模型的 API 价格计算；OpenAI 工具按标准工具价格计算；OpenAI 托管沙箱按标准容器价格计算。

同时，长任务可能包含多次模型调用、工具调用、重试和子 Agent。官方 Observability 文档提醒，Session 或 Turn 中记录的 usage 是 best-effort，可能暂时为 null，后续数值也可能变化；它不能直接当作最终账单。

所以，比较中转渠道时不要只问“倍率是多少”，而要建立一张任务级账本：

费用或用量	建议记录
模型请求	模型、输入、缓存输入、输出、推理输出、Service Tier
工具请求	工具类型、调用次数、是否由 OpenAI 托管、是否有单独费率
沙箱执行	环境类型、运行时长、容器或计算费用
MCP	连接位置、请求次数、第三方服务费用和授权方式
子 Agent	subagent_id、所属 Turn、各自 usage
重试与恢复	触发原因、是否重复执行副作用工具、是否重复计费

OpenAI Node SDK 7.17.0 于 2026 年 9 月 16 日发布，新增 Responses 流中的 compaction progress 事件；同一版本的 SDK 变更还包含对托管 Agent turn 中 credit_balance_exhausted 错误的识别。它们提醒开发者：长任务的“正在压缩上下文”“余额耗尽”“环境失败”和“模型输出完成”是不同状态，网关或客户端不应把它们合并成一个模糊的失败码。

如果某个渠道只展示一次请求的输入输出 token，却无法解释 Session、子 Agent、工具和沙箱费用，至少应该把它归类为“账单信息不完整”，而不是直接按单价排序。

一套可以直接执行的上线前测试表

准备把 Agents API 接入中转渠道时，可以按以下顺序验收：

A. 路径与鉴权

• /v1/agents、/v1/agents/sessions 路径可访问。
• OpenAI-Beta: agents=v1 被保留。
• Session 创建、读取、删除权限可分别验证。
• 应用 Key 与沙箱 Executor Key 没有混用。

B. 会话与事件

• 创建 Session 后能收到环境连接和 Turn 生命周期事件。
• 流断开后能通过 Session Items 恢复。
• Turn 失败、取消、环境失败和整个 Session 失败能区分。
• 子 Agent 的 Turn 和 usage 不会丢失。

C. 工具与 MCP

• 函数工具调用能回传参数和结果，Agent 能继续当前 Turn。
• MCP tools/list 的分页、缓存和变更通知行为可用。
• MCP tools/call 的 isError 和额外输入结果不被吞掉。
• 远程 MCP 与 Environment MCP 的连接位置符合预期。
• OAuth、Vault、Header 和环境变量的注入范围可审计。

D. 环境与安全

• none、托管沙箱和自建环境的能力差异已记录。
• 文件、Artifact、Shell 和网络出口逐项测试。
• 私密凭证不出现在 Prompt、日志、沙箱文件或错误信息中。
• 自建环境能处理断线、重连和停止前的未完成工作。

E. 成本与恢复

• 记录每个 Turn 的模型、工具、沙箱和子 Agent 用量。
• credit_balance_exhausted 等余额错误能被用户看懂。
• 长任务压缩事件不会被当作最终答案。
• 具有副作用的工具不会因网络重试而无条件重复执行。
• 渠道展示的价格、倍率、缓存计费和工具费用可以逐项对账。

最后的判断：先确定“兼容层”，再选择渠道

OpenAI Agents API 的价值在于把 Session、编排、上下文压缩、工具和执行环境组合起来；这也使它比单轮文本接口更难被“兼容”两个字概括。

可以把渠道分成三个等级：

1. 模型接口兼容：能调用某个模型，可能支持 Chat Completions 或 Responses。
2. Agent 请求兼容：能转发 Agents API 的路径、Beta 头、Session 和事件。
3. Agent 运行时兼容：除请求和事件外，还能正确处理 MCP、沙箱、凭证、Artifacts、恢复和任务级账单。

多数用户真正需要的是先明确自己属于哪一级。只做问答或远程工具调用，可以先检查 environment: none 和 MCP service 连接；要做 AI 编程代理，则必须继续核验沙箱、文件、网络和权限；要把它用于生产任务，还要把事件恢复、工具副作用和成本归因加入验收。

在 RouterHub 的平台目录中筛选相关渠道时，建议把“支持模型”“支持 Responses API”“支持 Agents API”“支持 MCP”“是否提供执行环境”分开记录。这样比看到一个模型名或一个低倍率就做决定，更接近真实的接入风险。

参考来源

• OpenAI Agents API 概览
• OpenAI Agents API 架构
• OpenAI Agents API 快速开始
• OpenAI Agents API：MCP 连接
• OpenAI Agents API：沙箱安全
• OpenAI Agents API：可观测性
• OpenAI API 定价
• openai-node v7.15.0 发布说明：加入 Agents API
• openai-node v7.17.0 发布说明：加入 compaction progress events
• MCP 2026-07-28 授权规范
• MCP 2026-07-28 Tools 规范