OpenAI Agents API 2026 完全解説：AI Agent はどうツールを呼ぶのか？JSON Schema、Tool Calling、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 がループを回す。副作用はホストかサンドボックスに残る。重みの中にはない。

ツールは呼べる。呼ぶのはモデルではない

公開ベータ後、POST /v1/agents/sessions 一つで長時間 Agent を立てられる。注文照会、リポジトリ読み、subagent 委任。副作用は本物だ。

「直接呼ぶ」は主語を間違える。モデルは MCP ソケットを持たず、サンドボックスを spawn せず、業務 API も叩かない。出すのは検証可能なオブジェクトだ。実行するのは管理 harness と、選んだ Environment だ。

• 宣言：agent.tools に function、MCP、web_search を置く。
• 提案：モデルは function_call を出す。名前と引数オブジェクト。
• 実行：harness がサービスツール、あなたの handler、またはサンドボックスのコマンドを動かす。

Agent、Tool Calling、Function Calling がまだ一つの語なら、先に AI Agent 完全ガイド。本稿は一点だけ扱う。Agents API がこの JSON 鎖をどうホストするか。

9 月 10 日のベータが渡したもの

OpenAI は率直だ。Codex と ChatGPT for Work の同じ harness を API にした。モデル側はよく 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 包装ではない。Agent、Environment、Session、Events / Items という session 資源だ。

骨格は今も JSON Tool Calling

API 名は変わった。四つの跳びは変わらない：

1. 宣言：agent.tools[] が function Schema、MCP、組み込みツールを出す。
2. 提案：モデルが名前と引数を埋める。実行しない。
3. 門：harness か handler が検証し、allowlist し、人を待つか決める。
4. 書き戻し：tool result が次の見える item になる。

session 作成はだいたいこの形。注文は架空だ。本物の秘密や社内 URL を公開サイトに貼らない：

{
  "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 を返して」ではない

ループをホストしても、広い 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 にする：返金や状態変更は enum。
• 余分なキーを閉じる：additionalProperties: false。広いオブジェクトはもう一枚の扉。
• 確認はホストが書く：モデルは create_refund を提案できる。allowed: true を状態に書いてはいけない。

ツールとワークフローはリポジトリの Schema にする。チャットの約束にしない。門の並べ方は JSON Schema と AI Agent ワークフロー。

Workflow は四つのオブジェクト。prompt 鎖ではない

公式は Agents API を四概念に畳む。工学ではどれも JSON：

• Agent：モデル、instructions、tools、MCP。能力表。
• Environment：hosted / self_hosted のサンドボックス。ファイル、コマンド、skills はここ。
• Session：継続できる実体。状態はサーバ側。history を自分で組まない。
• Events / Items：入力、tool call、結果、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 で調整する。同時実行には上限を。上限がなければ token と副作用が扇状に広がる。

差は誰がループを回すか

誰が賢いかではない。オーケストレーションがどこに住むか：

API を選ぶ前に主語を選ぶ。ループを自分で持つか。詳しい比較は次稿。本稿は一点だけ見る：入口を替えても JSON 呼び出し鎖は残る。

見るのはオブジェクト。「完了」という文ではない

session が終わったあと、最後の自然文を審理しない。軌跡を審理する。

• agent.tools、function_call、function_call_result を 整形。名前と引数が思った跳びか見る。
• JSONPath 抽出 で name、arguments、server_url を抜く。散文を目で追わない。
• 先週通った session 軌跡と JSON Diff。ループが流れたら、先にツール表と引数の形を見る。モデルを責めるのはその後。
• compact 後の要約でもキーフィールドが残ること。order_id を落とすと次の跳びが間違う。
• 注文、セッション、社内 MCP URL を公開フォーマッタに貼らない。JSONSort はブラウザローカル。こうしたオブジェクトを読む場所だ。

軌跡が再構築できれば、session は振り返れる。それが本番の入場券。飾りではない。

落とし穴

• 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[] がなければ何も呼べない。

Agents API と Responses API、どちらから始めるか？

長いループ、文脈圧縮、subagent を OpenAI に任せたいなら Agents API。毎ステップのモデル呼び出しを自分で持ちたいなら Responses API。ループを自プロセスに残すなら Agents SDK。

Agents API でも JSON Schema は要るか？

要る。管理ループは編制だけ。function 引数、MCP inputSchema、状態オブジェクトは今も絞る。広い Schema に自動ループを足すと、扉はより開く。

Session、Turn、Item の違いは？

Session は継続できる実体。Turn は一つのユーザ入力で始まる仕事。Item はその区間の入力、tool call、結果、subagent 調整。監査は item。最後の文ではない。

Agent に本番 DB や本番返金を触らせてよいか？

本番の副作用を第一跳に置かない。隔離環境と狭い Schema で下書きさせ、確認はホストが書く。秘密と解放は人の戦略門。

結論

Agents API が「ツールを直接呼ぶ」——その文は半分だけ正しい。正しい半分：もうループを手書きしない。間違った半分は主語。主語は 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 初回公開