OpenAPI 3.1 は「JSON が通る」だけでは曖昧な tool 契約を止める

要点

要点まとめ

AI に tool を渡す事故は、『JSON の形は合っていたのに、違う接続先へ送った』『読むだけのつもりが更新操作だった』『認証の強さを勘違いした』で起きる。OpenAPI 3.1 の価値は、その曖昧さを引数の形だけでなく接続先と権限まで含めて減らせる点にある。
仕様は `servers`、`paths`、`security` などで、『どこへ送り』『何の操作で』『どの認証を前提にするか』を分けて表せる。つまり tool 定義を『関数の引数説明』から『操作契約』へ戻せる。
3.1 では JSON Schema とのつなぎ方も整理され、validator ごとの解釈ズレを減らしやすくなっている。structured output や tool schema を厳密に扱いたい時にも効く。
読後にやるべきことは、schema の形だけで安心せず、server、response、security まで含めた全体契約として自分の tool 定義を見直すことだ。

続けて読む

読み終えたら次へ

この1本で終わらせず、同じ目的・同じテーマ・近い原典へ進めます。

同じ目的で読む 仕事で安全に使いたい

権限、秘密情報、監査、失敗時の扱いを確認したい人向け。

同じテーマで読む AIエージェント

ツール利用、MCP、Agent SDK、長時間タスク、実行責任の設計。

次の記事 Programmatic Tool Calling は「まとめ処理」と「承認が要る実行」を混ぜるなと迫る

この guide の核心は、tool を複数つないで楽をすること自体ではなく、どの段階ならコードに任せてよく、どの段階は人やアプリ側の明示的な判断を残すべきかを切り分ける点にある。

読解

何が変わったのか

OpenAPI 3.1 の root object では、`servers` が接続先、`paths` が使える endpoint 群、`security` が API 全体の認証前提を持ちます。各 path の `Operation Object` は単一操作を表し、個別に request と response、必要なら operation ごとの security override を持てます。また 3.1 では `jsonSchemaDialect` が root に置けて、Schema Object 側の `$schema` と組み合わせながら JSON Schema の方言を明示できます。これは『validator は通るが別ツールでは解釈がずれる』という曖昧さを減らす方向です。さらに `Server Object` は base URL を、`Security Requirement Object` は実行に必要な security scheme や scope を明示します。つまり『何を呼ぶか』だけでなく『どこへ、どの資格で呼ぶか』まで契約に含める仕様です。

日本の文脈

なぜ重要か

日本の実装現場では、OpenAPI を client 自動生成のためだけに使い、agent や plugin 連携では schema 部分だけ抜き出して済ませがちです。しかしそのやり方だと、server 切り替え、認可 scope、optional auth、webhook のような重要な境界が抜け落ちます。 AI 導入担当者にも意味があります。tool 接続の事故は model の賢さ不足だけでなく、契約の省略からも起きます。OpenAPI 3.1 を『ドキュメント形式』ではなく interface contract として読むと、どこを model 任せにせず固定すべきかが見えやすくなります。

技術ポイント

技術的ポイント

`OpenAPI Object` は root object で、`servers`、`paths`、`components`、`security` など API 全体の契約を持ちます。引数 schema だけではありません。
`Server Object` は base URL を表します。相対 URL の解決先にも関わるため、tool bridge では『どこへ飛ぶか』を曖昧にしないための基本要素です。
`Operation Object` は path 上の単一 API 操作を表します。method ごとの挙動差、request body、response、operation 単位の security override を切り分けられます。
`Security Requirement Object` は、どの security scheme が必要か、OAuth2 ならどの scope が要るかを表します。認証を docs 外の口約束にしないための部品です。
`jsonSchemaDialect` と Schema Object の `$schema` は、どの JSON Schema dialect で解釈するかを明示します。structured outputs や tool schema で validator 差分を減らす助けになります。

用語

英日キーワード

英語	日本語	補足
OpenAPI Object	OpenAPI ルート定義	API 全体の入口になる最上位オブジェクト。servers、paths、security などを持つ。
Server Object	接続先定義	base URL など接続先情報を表す仕様要素。
Operation Object	操作定義	1 つの endpoint 操作ごとの request、response、auth 差分を表す。
Security Requirement Object	認証要件定義	どの security scheme や scope が必要かを表す仕様要素。
Schema Object	スキーマ定義	request や response の構造を表す仕様要素。validator 差分の確認にも関わる。
jsonSchemaDialect	JSON Schema 方言指定	どの JSON Schema 仕様で解釈するかを示す指定。
interface contract	インターフェース契約	引数だけでなく接続先、認証、返り値まで含む操作上の約束事。

試す

試すなら

今使っている tool 定義から、引数 schema 以外に server URL、method、auth scope、response contract が抜けていないか棚卸しする。
読み取り系と書き込み系の operation を別 operation として明示し、同じ自然言語説明に埋め込まない。
OpenAPI を持っているなら、agent 連携前に `security` と `servers` を見直し、開発環境 URL や過剰 scope が残っていないか確認する。
structured output の validator 差分で詰まるなら、Schema Object と JSON Schema dialect を先に固定する。

注意

注意点

この仕様は広く、すべてを一度に覚える必要はありません。ただし AI tool 連携で最低限落としてはいけないのは `servers`、`security`、operation ごとの差分です。
OpenAPI があるだけで安全になるわけではありません。実際の policy、credential 配布、runtime 側の権限制御は別途必要です。
JSON Schema 互換性は改善されていますが、各 tool や validator の実装差は残りえます。仕様準拠を前提にしすぎず、実動作確認も必要です。

この記事は役に立ちましたか

公益的に続けるため、役に立った点や読みづらかった点だけを短く送れます。メールアドレスは不要です。