OpenAI Agents API 2026 完整解析：Agents API 如何让 AI Agent 直接调用工具？JSON Schema、Tool Calling 与 Agent Workflow 数据结构详解

阅读前速览

概念	一句话	落在哪
Agents API	OpenAI 托管的 Codex harness	sessions.create / agent
Tool Calling	模型提议工具名和参数	function_call / arguments
JSON Schema	能进循环的参数形状	parameters / additionalProperties
Workflow	会话、回合、条目、交接	session / turn / items

先记住分工：你声明 Agent、Tools、Environment；OpenAI 跑循环。副作用仍在宿主或沙箱，不在权重里。

能调工具。调的不是模型自己

Agents API 公测后，一条 POST /v1/agents/sessions 就能拉起长期运行的 Agent：查订单、读仓库、派 subagent。这些副作用是真的。

「直接调用」这个词会把主语写错。模型不持有 MCP 连接，不 spawn 沙箱进程，也不自己打你的业务 API。它只生成可校验的对象。真正执行的是托管 harness，以及你选的 Environment。

• 声明：你在 agent.tools 里放 function、MCP、web_search。
• 提议：模型发出 function_call，名字加参数对象。
• 执行：harness 调服务端工具、你的 function handler，或沙箱里的命令。

若 Agent、Tool Calling、Function Calling 还糊成一个词，先读 AI Agent 完整指南。本文只谈一件事：Agents API 怎样把这条 JSON 链托管起来。

9 月 10 日公测交了什么

OpenAI 的原文写得很直：把驱动 Codex 和 ChatGPT for Work 的同一套 harness 交给开发者。模型侧常见是 GPT-6 Astra 指南。你付的是 token 和工具用量，API 本身不加一层费。

• 托管循环：session、编排、恢复，不用自己写 LangChain 胶水。
• 上下文压缩：接近窗口上限时自动 compact，跨多个窗口续跑。
• Tool search + programmatic tool calling：按需加载工具定义，并行调用，只把相关结果回写上下文。
• MCP / function / web_search：工具表可以混挂。
• Subagents：multi_agent.enabled，默认并发上限可设，默认文档值常见为 6。

OpenAI DevDay 2026 预测 写过 Structured Outputs 和 Function Calling 的预测。公测落地的不是又一个 chat completion 包装，而是 session 资源：Agent、Environment、Session、Events / Items。

JSON Tool Calling 才是同一条骨架

换了 API 名字，四跳没变：

1. 声明：agent.tools[] 给出 function Schema、MCP server、内置工具。
2. 提议：模型填工具名和参数。它不执行。
3. 门禁：harness 或你的 handler 校验、做 allowlist、决定等不等待人。
4. 回写：tool result 变成下一轮可见的 item。

一次 session 创建，官方形状大致是这样。下面用虚构订单，不要把真实密钥或内网地址贴进公共站点：

{
  "agent": {
    "model": "gpt-6-astra",
    "instructions": "Look up orders. Confirm before any refund.",
    "tools": [
      { "type": "programmatic_tool_calling" },
      {
        "type": "function",
        "name": "lookup_order",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      },
      {
        "type": "mcp",
        "server_label": "orders",
        "transport": {
          "type": "http",
          "server_url": "https://orders.example.com/mcp"
        }
      }
    ],
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 3
    }
  },
  "environment": {
    "type": "hosted",
    "workspace_directory": "/workspace"
  },
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Look up order A-1042." }
      ]
    }
  ]
}

循环转起来之后，模型发出的仍是一段对象，不是一段「请查一下订单」的散文：

{
  "type": "function_call",
  "id": "call_3c91",
  "name": "lookup_order",
  "arguments": "{\"order_id\":\"A-1042\"}"
}

MCP 那一项只是另一张工具表的写法，协议边界见 MCP Tool Schema vs Function Calling。Coding Agent 在沙箱里跑命令，形状仍是 JSON，见 AI Coding Agent 与 JSON 调用链。

JSON Schema 才是门，不是「请输出 JSON」

Agents API 不会因为托管了循环，就把宽 object 变安全。口径见 AI 为什么需要 JSON Schema：prompt 影响它填什么；Schema 决定什么能进执行。

{
  "name": "lookup_order",
  "description": "Look up an order by ID",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "pattern": "^[A-Z]-\\d{4}$"
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

一份能挡事的 function Schema 至少要有四件事：

• 收紧类型：order_id 用 pattern，不要裸 string。
• 枚举金额与动作：退款、改状态必须 enum。
• 关掉多余键：additionalProperties: false。宽对象等于多开一扇门。
• 确认字段由宿主写：模型可以提议 create_refund，不能自己把 allowed: true 写进状态。

把工具和工作流收成仓库里的 Schema，而不是聊天记录里的约定。流程怎么串，见 JSON Schema 与 AI Agent 工作流。

Agent Workflow 是四类对象，不是一段 prompt 链

官方把 Agents API 收成四个概念。工程上它们都是 JSON：

• Agent：模型、instructions、tools、MCP。这是能力表。
• Environment：hosted / self_hosted 沙箱，文件、命令、skills 住在这里。
• Session：可续跑的实例。状态保存在服务端，不必自己拼 history。
• Events / Items：输入、tool call、tool result、subagent 协调动作。

一笔可审计的工作流，看起来应该像对象，而不是最后一句「已经办好了」：

{
  "session_id": "sess_9f2a",
  "turn": 2,
  "items": [
    { "type": "function_call", "name": "lookup_order", "id": "call_3c91" },
    { "type": "function_call_result", "call_id": "call_3c91", "status": "paid" }
  ],
  "state": {
    "order_id": "A-1042",
    "status": "paid"
  },
  "next": {
    "tool": "create_refund",
    "allowed": false,
    "reason": "missing_confirmation"
  }
}

Subagent 有自己的上下文。主 Agent 用 create / message / wait / interrupt 这类 item 协调。默认并发要设上限；不设上限，账单和副作用都会扇出。

和 Responses API、Agents SDK 差在谁跑循环

不是谁更聪明，而是编排住在哪：

选 API 之前先选主语：你要不要自己持有循环。完整对比下一篇再写。本篇只要求你看懂：换入口，JSON 调用链还在。

你该检查对象，不是「Agent 已完成」

Session 跑完之后，审的不是最后一句自然语言。审的是轨迹。

• 把 agent.tools、function_call、function_call_result 格式化，看名字和参数是不是你以为的那一下。
• 用 JSONPath 提取 抽出 name、arguments、server_url，不要靠眼睛扫散文。
• 和上周能过的 session 轨迹 JSON Diff。循环漂了，先看工具表和参数形状，再怪模型。
• compact 之后的摘要也要能对上关键字段。压缩丢了 order_id，下一跳就会填错。
• 订单、会话、内网 MCP 地址不要贴进公共格式化站。JSONSort 在浏览器本地跑，适合看这些对象。

轨迹能重建，session 才能复盘。这是 Agents API 能进生产的前提，不是锦上添花。

常见误区

• 以为 Agents API 让模型自己执行了工具。执行权在 harness 和 Environment。
• 把宽 object 交给托管循环。托管不等于门禁。
• 打开 multi_agent 却不设并发上限。subagent 会扇出 token 和副作用。
• 把 Session 当成又一次 chat completion。状态、恢复、compact 都是一等对象。
• 用 prompt 代替 Schema。口径必须能校验。
• 把 hosted sandbox 当成 Zero Data Retention。官方写明：自建沙箱也不让 Agents API 变成 ZDR。

FAQ

Agents API 是让模型直接调用工具吗？

是让模型直接发出工具 JSON。执行仍在托管 harness、你的 function handler 或沙箱。没有 tools[]，它调不了任何东西。

和 Responses API 比，我该从哪开始？

要 OpenAI 帮你跑长期循环、压上下文、派 subagent，用 Agents API。要自己控每一步模型调用，用 Responses API。要循环留在自己进程里，用 Agents SDK。

JSON Schema 在 Agents API 里还需要吗？

需要。托管循环只负责编排。function 参数、MCP inputSchema、状态对象仍然要收紧。宽 Schema 加上自动循环，等于把门开得更大。

Session、Turn、Item 有什么差别？

Session 是可续跑的实例。Turn 是一次用户输入启动的工作。Item 是这一段里的输入、tool call、结果或 subagent 协调动作。审计看 item，不要只看最后一句。

能不能让 Agent 直接碰生产库或生产退款？

不要把生产副作用交给第一跳。让它在隔离环境和收紧 Schema 里起草，确认字段由宿主写。密钥和放行仍是人的战略门。

结论

Agents API 让 Agent「直接调用工具」——这句话只对一半。它对的是你不再手写循环；错的是主语。主语是 harness，谓语是执行，宾语是模型填出来的 JSON。

从今天起，少争论它「会不会自己做」。先把 Agent、Tools、Session items 和 Schema 写进仓库。模型会换；这条 JSON Tool Calling 链应该先稳定。

延伸阅读

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

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