OpenAI Agents API vs Responses API：2026 AI Agent 开发者应该如何选择？从 JSON Tool Calling、Structured Output 到多 Agent 协作完整对比

阅读前速览

入口	一句话	你持有什么
Agents API	OpenAI 跑 Codex harness	Session / Environment
Responses API	你自己打模型、自己转循环	input / output items
Agents SDK	循环留在你的进程	runner / handoff
JSON 链	工具名、参数、结果仍是对象	call_id / Schema

先选主语：要不要自己持有循环。换入口，JSON 调用链还在。

选的是谁跑循环，不是谁更聪明

2026 年 GPT-6 Astra 的工具调用已经走 Responses。Agents API 是另一层：托管 session、压缩上下文、派 subagent。两套入口共用同一条 JSON 链，主语不同。

• 要自己控每一步：审批、重试、把 function_call_output 写回——用 Responses API。
• 要跨小时任务、托管恢复、沙箱和 subagent：用 Agents API。
• 循环必须留在自己进程，又想要现成 runner：用 Agents SDK，底层仍常打 Responses。

Agents API 本身怎么调工具，见 OpenAI Agents API 完整解析。若 Agent 和 Function Calling 还糊在一起，先读 AI Agent 完整指南。

两个 API 各管一层

Responses API 是低层：/v1/responses。你给 input，收回一组 typed items：message、reasoning、function_call。GPT-6 Astra 指南 的工具调用要求走这条。Structured Output 写在 text.format，不再是 Chat Completions 的 response_format。

Agents API 是托管 harness：POST /v1/agents/sessions。你声明 Agent、Tools、Environment；OpenAI 跑循环、compact、恢复。function 要你回结果时，session 发 requires_action，你按 turn_id / call_id 交 tool_result。

Agents SDK 不是第三套协议。它是你进程里的 runner：handoff、审批、存储由你管，模型调用往往仍落在 Responses。官方也写明：Session、SDK session、Responses conversation、sandbox 是四份不同资源。

Tool Calling：同一条链，两套回写

Responses 上，你每轮自己 responses.create。工具表和最终卡片可以写在同一次请求里：

{
  "model": "gpt-6-astra",
  "input": "Look up order A-1042.",
  "tools": [
    {
      "type": "function",
      "name": "lookup_order",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
        },
        "required": ["order_id"],
        "additionalProperties": false
      }
    }
  ],
  "text": {
    "format": {
      "type": "json_schema",
      "name": "order_card",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" },
          "status": { "enum": ["paid", "pending", "void"] }
        },
        "required": ["order_id", "status"],
        "additionalProperties": false
      }
    }
  }
}

模型若要查单，output 里会出现独立的 item，用 call_id 把调用和结果钉在一起：

{
  "output": [
    {
      "type": "function_call",
      "call_id": "call_3c91",
      "name": "lookup_order",
      "arguments": "{\"order_id\":\"A-1042\"}"
    }
  ]
}

你的应用执行函数，再把结果当作下一次 input 的一条 item 送回去：

{
  "type": "function_call_output",
  "call_id": "call_3c91",
  "output": "{\"status\":\"paid\",\"amount\":99.00}"
}

Agents API 把这几轮收进 session。创建时一次声明工具、沙箱和是否开 multi_agent：

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [
      { "type": "function", "name": "lookup_order", "parameters": {
        "type": "object",
        "properties": { "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" } },
        "required": ["order_id"],
        "additionalProperties": false
      }},
      { "type": "web_search" }
    ],
    "multi_agent": { "enabled": true, "max_concurrent_subagents": 3 }
  },
  "environment": { "type": "hosted", "workspace_directory": "/workspace" },
  "input": [{ "role": "user", "content": [{ "type": "input_text", "text": "Look up A-1042." }] }]
}

轮到你的 function，harness 停在 required_actions。回写不是 function_call_output，而是带 turn_id 的 tool result：

{
  "type": "tool_result",
  "turn_id": "turn_2",
  "call_id": "call_3c91",
  "success": true,
  "output": "{\"status\":\"paid\"}"
}

名字不同，门一样：Schema 决定什么能进执行。MCP 那一行只是另一张工具表，边界见 MCP Tool Schema vs Function Calling。

Structured Output：收的是最终卡片，不是工具参数

Responses 把最终形状放在 text.format。这管的是模型最后吐给用户的对象，不管工具参数。工具参数仍要自己的 Schema。口径见 AI 为什么需要 JSON Schema。

• Responses：text.format.json_schema + strict: true 锁最终卡片。
• Agents API：循环托管了，最终产物仍该有 Schema；function / MCP 参数各自收紧。
• 两边都成立：Structured Output 不是门禁。金额、确认、放行仍由宿主写。

常见错法是只锁最终卡片，把 lookup_order 留成宽 object。卡片漂亮，副作用已经走了。

多 Agent：托管扇出，还是自己 handoff

「多 Agent 协作」不是第三种智能，是谁持有编排：

• Agents API：multi_agent.enabled，subagent 自带上下文，主 Agent 用 create / wait / interrupt。默认并发要设上限。
• Agents SDK：handoff 对象在你的 runner 里，审批和存储你说了算。
• Responses：没有内置 subagent。你要自己把多个 responses.create 串成图，或把状态放进 Conversations。

handoff 该是可审计的 JSON，不是一句「请交给账单组」。怎么收成 Schema，见 JSON Schema 与 AI Agent 工作流。

一张表看完三个入口

官方对比表可以再压成工程问题：

没有「更好的 API」。只有「主语在不在你这边」。

四步决定入口

不要从品牌页选。按这四问选：

1. 业务副作用能不能离开你的进程？退款、改库必须你点头，先 Responses 或 SDK。
2. 任务会不会跨过一个上下文窗口？会，而且你不想自己 compact，才需要 Agents API。
3. 要不要沙箱里跑命令、读文件？要，Agents API 的 Environment 是现成的；Responses 你自己准备执行世界。
4. 要不要并行 subagent？要且不想自建编排，开 Agents API 的 multi_agent，并写死并发上限。

四个「要」都落在托管侧，再进 Agents API。有一个「必须自己握着」，就从 Responses 起。SDK 是第三种：循环在你这，胶水少写一点。

对比之前，先把两段 JSON 摊开

选错入口，多半是没看对象。把两条轨迹放在一起看。

• 把 Responses 的 output[] 和 Agents 的 session items 格式化，确认 call_id 对得上。
• 用 JSONPath 提取 抽出 name、arguments、text.format，不要靠眼睛扫文档。
• 同一笔订单在两种入口下的轨迹 JSON Diff。漂了，先看回写形状，再怪模型。
• 最终卡片 Schema 和工具参数 Schema 要分开审。锁卡片不锁参数，等于只装修门面。
• 订单和内网 MCP 不要贴进公共格式化站。JSONSort 在浏览器本地跑。

两段轨迹都能重建，你才知道自己在选入口，而不是在选口号。

常见误区

• 以为 Agents API 取代了 Responses。官方把它们写成两个起点。Astra 的 tool calling 仍走 Responses。
• 把 Session 和 Conversation 当成同一个资源。删一份不会自动清另一份。
• 只给最终卡片 Schema，工具参数放宽。副作用发生在 function_call 被执行时。
• 开 multi_agent 却不设并发上限。托管扇出一样烧 token、放大副作用。
• 用 SDK 却以为自己不用再写门禁。runner 替你转循环，不替你校验金额。
• 按演示视频选 API。演示里循环被藏起来了。先问主语在哪。

FAQ

2026 年新项目该从哪个 API 开始？

默认从 Responses 起：你看得见每一跳。只有任务要跨窗口、要托管沙箱或 subagent，再把循环交给 Agents API。

GPT-6 Astra 能不能只用 Agents API、不碰 Responses？

可以只开 Agents session。但 Astra 的底层 tool calling 文档仍指向 Responses。短链路、Structured Output、自己转循环，继续用 Responses。

Structured Output 能不能代替 Tool Calling？

不能。Structured Output 锁最终对象。Tool Calling 锁副作用。退款、查单、改文件走工具 JSON；给用户看的卡片走 text.format。

多 Agent 是不是必须上 Agents API？

不是。SDK 的 handoff、你自己串的多次 Responses，都是多 Agent。Agents API 只是把扇出做成托管能力。

两套 API 能混用吗？

能，但资源不要混。用 Responses 抽结构化卡片，用 Agents session 跑长任务。Session、Conversation、sandbox 分开建、分开删。

结论

Agents API 和 Responses API 不是两代产品。一个托管循环，一个把循环交给你。JSON Tool Calling、Structured Output、多 Agent，都只是这条链上的不同对象。

先写清主语：这跳该不该离开你的进程。再选入口。模型会换；call_id 和 Schema 应该先稳定。

延伸阅读

• OpenAI Agents API 完整解析 Session、Tool Calling、Schema 怎么接
• AI Agent 是什么？完整指南 运行时与 JSON 契约
• AI 为什么需要 JSON Schema Schema / Function Calling / Structured Output
• JSON Schema 与 Agent 工作流 把工具和状态收成 Schema
• MCP Tool Schema vs Function Calling 工具 JSON 的协议边界
• JSONSort 本地工具箱 格式化、校验、Diff
• 全部文章 更多 JSON 与 AI 开发笔记

更新记录： 2026-09-21 首次发布