AIエージェント向けAPIの仕様設計：入出力・エラー・評価の実践ガイド
約1分で読めます
AIエージェント向けAPIの設計では、操作名や入力形式だけでなく、いつ使えるか、結果をどう解釈するか、失敗後に何をしてよいかまで仕様に含めます。まず一つの業務操作を選び、機械が検証できる入出力と、人が判断できる説明をそろえましょう。
この記事では、API提供者や連携開発者に向けて、既存APIをエージェントが利用する際の仕様とツール定義の作り方を、検索APIの例で解説します。
この記事の要点
- 仕様は操作の意味まで定義する：名前や型に加え、利用条件、対象範囲、返却値の意味を明記します。
- API仕様とツール定義を対応させる：APIの入力・出力と、モデルに提示する名前・説明・スキーマの食い違いを防ぎます。
- 結果の完全性を伝える：検索結果が空なのか、取得に失敗したのか、続きを取得できるのかを区別します。
- 再試行の可否を決めて返す：書き込みの結果が不明な場合は、無条件に再送せず、状態照会や担当者への引き渡しを優先します。
- 実タスクで評価する：仕様の形式チェックだけで終えず、曖昧な依頼や異常系を含めて、ツール選択から結果の扱いまで検証します。
AIエージェント向けAPI仕様で定めること
エージェント向けの仕様では、APIを呼び出すプログラムだけでなく、どの操作を選び、どの値を渡すかを判断するモデルにも必要な情報を渡します。API自体の契約と、モデルに見せるツール定義は別物ですが、互いに整合している必要があります。
例えば、商品を検索するAPIなら「商品を取得する」だけでは不十分です。商品名の部分一致なのか、販売中の商品だけが対象なのか、一度に何件返すのかを示します。結果を取得できなかった場合と、対象商品が存在しない場合も分けます。
OpenAPI仕様では、操作の概要や説明、操作を識別するoperationId、パラメータ、応答などを記述できます。一方、モデルにツールを提示する方法は利用する実装によって異なります。Anthropicのツール定義では、名前、説明、JSON Schemaによる入力定義などを使います。
OpenAPIの文書を置くだけで、モデルが自動的にすべての操作を理解・実行できるわけではありません。 実行環境がどの操作を公開し、説明やスキーマをどう変換するかまで確認します。
操作名と説明を設計する
操作名と説明は、モデルが似たツールの中から適切なものを選ぶための手がかりです。内部の略語だけで命名せず、何を、どの条件で行い、何を返すかが分かるようにします。Anthropicの設計ガイドも、操作の境界を明確にし、入力や出力の曖昧さを減らすことを勧めています。
例えば、searchという名前だけでは、商品、顧客、注文のどれを検索するのか分かりません。search_products_by_nameのように対象と条件を示し、次の情報を説明に含めます。
- 目的：商品名の一部を使って商品を探します。
- 対象：検索可能な商品の範囲と、販売終了品の扱いを示します。
- 入力：検索語の意味、必須・任意の区別、文字数や指定可能な条件を示します。
- 結果：商品ID、表示名、続きの有無など、実際に返す情報を示します。
- 使わない場面：商品IDで詳細を取得する場合は、別の詳細取得操作を使うと明記します。
説明を長くすること自体が目的ではありません。複数の操作を比較したとき、使い分けに必要な差が伝わるかを確かめます。説明の文言は実装の制限と一致させ、文章上の注意だけをアクセス制御の代わりにしないでください。
入力スキーマと具体例を用意する
入力スキーマでは、必須項目、型、許容範囲を機械が検証できる形にします。あわせて各項目の説明に、型だけでは分からない業務上の意味を記載します。
以下は、商品名による検索ツールの入力部分の例です。API全体のOpenAPI文書ではなく、ツール定義に渡すJSON Schemaを表しています。数値や検索条件は説明用であり、実際のAPIの仕様ではありません。
{
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "商品名の一部。商品IDでは検索しません。"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 10,
"description": "1ページに返す最大件数。"
},
"cursor": {
"type": "string",
"description": "前回の応答に含まれた次ページ用の値。初回は省略します。"
}
},
"required": ["query"],
"additionalProperties": false
}例えば{"query":"ノート","limit":10}は初回の検索、{"query":"ノート","limit":10,"cursor":"次ページの値"}は続きの取得です。実際には、応答から受け取った値をそのまま使います。検索条件が変わったときに前のカーソルを再利用できるかも、API側で定義してください。
スキーマと実装を一致させる
- 必須値：モデルに渡すスキーマとAPI側の必須条件をそろえます。固定値を実行側で補うなら、その責任を明記します。
- 省略時の値：
defaultを記載しただけで値が自動挿入されるとは限りません。省略を受け付ける実装か、実行側が補うのかを決めます。 - 日付・単位：日付の形式やタイムゾーン、金額の通貨、距離の単位などを明示します。
- IDの意味：ユーザーが入力する表示名と、APIが必要とするIDを区別します。IDが不明なら、先に検索する手順を用意します。
- 入力例：実際に有効な値を使い、任意項目の省略や複数条件の組み合わせも示します。
ツール側でスキーマに合う入力を生成できても、それが業務上正しいとは限りません。実行側でも型、範囲、対象と利用権限を検証します。
応答は結果の意味と取得範囲を伝える
応答の設計では、モデルが次の判断に必要な情報を取り出せることと、取得できた範囲を誤解しないことを重視します。必要な項目を返しつつ、結果の省略や続きがある場合は、その状態も伝えます。
例えば、商品検索の応答を次のように定義できます。これも架空の設計例です。
{
"status": "success",
"items": [
{"product_id": "p-123", "name": "方眼ノート"}
],
"next_cursor": "次ページの値"
}この例では、itemsが空で正常終了していれば「条件に一致する商品なし」と判断できます。一方、取得に失敗した応答を空のitemsだけで返すと、該当商品がないのか、検索できなかったのかを区別できません。next_cursorがある場合も、最初のページだけを全件と扱わないようにします。
応答に含めるべき情報
- 識別子と表示名：後続操作に使うIDと、人が確認する名前を区別して返します。
- 結果の範囲：検索条件、取得件数、続きの有無を示します。総件数を返せない場合は、推測して埋めません。
- 時点と鮮度：更新時刻や取得時刻が判断に必要なら、それぞれの意味とタイムゾーンを明示します。
- 部分的な結果：一部のデータだけ取得できた場合、成功した範囲と未取得の範囲を分けます。
- 省略の有無：結果を切り詰めた場合は、その事実と続きを取得する方法を伝えます。
Anthropicのガイドは、エージェントが使う文脈を圧迫しないよう、ページ分割、範囲指定、絞り込みなどを検討しています。ただし、単に出力を短くするのではなく、必要な判断材料や取得範囲を失わないことが大切です。
エラーと実行状態を分けて設計する
エラー応答には、何が起きたかだけでなく、入力を直すのか、待つのか、確認に回すのかを判断するための情報を含めます。エラーの表現は実際のAPI契約に合わせ、HTTPステータスだけで再送可能と判断しないようにします。
検索APIの入力が無効だった場合、例えば次のように返せます。
{
"status": "error",
"error": {
"code": "INVALID_QUERY",
"message": "検索語を1文字以上で指定してください。",
"next_action": "correct_input"
}
}codeはプログラムが分類するための値、messageは問題の説明、next_actionはこの例で実装側が定義した次の対応です。存在しないフィールドを外部APIが返すと仮定せず、ラッパー側で追加する場合も変換規則を決めます。内部のスタックトレースや認証情報は、モデルへの応答に含めない設計にします。
書き込みは「結果不明」を独立した状態にする
検索と違い、登録や送信のような操作では、応答を受け取れなくても処理が完了している可能性があります。したがって、状態は少なくとも完了、未実行と確認できた状態、結果不明を区別します。実際に未実行と判断するには、接続先が提供する照会結果などの根拠が必要です。
- 入力不備：不足や形式の誤りを返し、修正できる箇所を示します。
- 権限不足：同じ入力の自動再送では解決しない状態として扱い、必要な担当者へ引き渡します。
- 一時的な障害：操作が安全に再試行でき、接続先が許容する場合に限って、待機・回数・期限に上限を設けます。
- 書き込みの結果不明：操作IDなどで状態を照会し、確認できなければ自動再送せずに引き渡します。
Google Cloudの再試行ガイドも、再試行の判断では応答に加えて操作のべき等性を確認するよう説明しています。べき等キーを使う場合は、接続先の対象操作、保持期間、同じキーと異なる内容が送られた場合の挙動を確認します。キーを付けるだけで、どのAPIでも重複を防げるわけではありません。
API仕様とツール定義を対応させる手順
既存APIをエージェントから使う場合は、APIをすべて公開するのではなく、代表的な業務に必要な操作から対応付けます。検索ツールを例に、次の順で仕様を作ります。
- 業務上の目的を決める：「商品名から候補を探し、担当者に候補を提示する」といった完了条件を定めます。この段階では登録や注文を含めません。
- 既存APIの契約を読む：検索方法、必須パラメータ、返却項目、ページ分割、制限、エラーを確認します。文書が不十分なら、提供元に確認し、実装の挙動と照合します。
- ツールの境界を決める：公開する検索操作と詳細取得操作を分け、どちらを使うかを説明します。APIの引数とツールの引数の対応も記録します。
- 入力と出力を定義する：必須項目、型、制約に加え、ID、結果の範囲、続き、エラーを表現します。APIが返さない情報を、推測で補わないようにします。
- 実行側の規則を定める：スキーマ検証、利用者の権限確認、呼び出し上限、外部応答の扱いを実装します。取得したページや本文に含まれる命令を、そのまま実行側への指示として扱わないようにします。
- 変更時の影響を確認する：APIの項目変更に合わせてツール定義、変換処理、入力例、テストを更新します。古いクライアントを使う場合の扱いも決めます。
例えばAPIがname_containsという検索条件を受け取り、ツールにはqueryを公開するなら、実行側で両者を対応付けます。ツールの説明が「完全一致」と書かれている一方、APIが部分一致で検索するなら、呼び出しは成功しても利用者の意図と異なる結果になります。形式の一致に加え、検索の意味の一致までテストしてください。
外部サービスの契約を変えられない場合でも、連携側でツールの説明、入力検証、応答の整理を設計できます。ただし、元のAPIにない検索条件や状態照会を、説明を書き換えるだけで追加することはできません。
公開前に評価する：仕様どおりに使えるか
APIの正常応答だけでは、エージェントが適切なツールを選び、取得範囲を正しく説明できるかは分かりません。実際の利用に近い依頼を用意し、選択・入力・実行・結果の解釈を一続きで評価します。Anthropicの評価ガイドも、現実の利用に基づくタスクと検証可能な結果を用意する方法を紹介しています。
商品検索で試したいケース
- 正常系：「方眼ノートを探して」という依頼から、検索ツールを選び、適切な検索語を渡せるか確認します。
- 条件が曖昧：商品名だけでは対象を絞れない依頼で、存在しない条件を勝手に補わず、必要に応じて確認できるかを見ます。
- 該当なし：正常な空結果を「検索に失敗した」と誤認せず、取得範囲とともに伝えられるか確認します。
- 続きあり：最初のページだけを全件と説明せず、必要な場合に続きの取得を判断できるかを見ます。
- 入力エラーと権限不足：修正可能な入力と、担当者による対応が必要な状態を区別できるかを確認します。
- 書き込みの結果不明：別途書き込みを公開する場合、タイムアウト後に新しい操作を自動実行せず、照会または停止に進むかを試します。
評価では、正しい最終回答だけでなく、誤ったツールの選択、無効な引数、不要な再呼び出し、結果不明時の停止を記録します。比較する際は、同じテストデータと判定条件を使い、ツールの説明やスキーマを変更する前後で結果を見ます。
本番データに影響する操作は、実行を模擬できる環境で試してください。仕様の形式チェック、APIの契約テスト、エージェントを含む評価はそれぞれ異なる問題を見つけるため、いずれか一つだけで置き換えないようにします。
まとめ
AIエージェント向けAPIの仕様では、操作を呼び出せることに加えて、操作を選ぶための説明、検証可能な入力、解釈できる結果、失敗時の次の対応をそろえます。APIの契約とツール定義を対応させ、実装が守る制約とモデルに伝える説明を一致させましょう。
まずは読み取り専用の操作を一つ選び、入力例、空結果、ページの続き、エラーを含むテストを作ってください。既存の仕様との差分が分かれば、書き込み操作を追加する前に、結果不明時の状態照会と停止方法も設計できます。
よくある質問
AIエージェント向けAPIと通常のAPIは何が違いますか？
特別な通信方式が必須というわけではありません。エージェントが操作を選び、入力を組み立て、結果を解釈できるように、操作の目的や制約、返却値の意味、失敗時の対応を明確にする点を重視します。
OpenAPI仕様があれば、エージェントはAPIを使えますか？
OpenAPIはAPIの操作や入出力を記述する助けになりますが、仕様書だけで実行できるとは限りません。実行環境が必要な操作をツールとして公開し、モデルに渡す説明と入力スキーマを用意する必要があります。
既存APIを変更せずにエージェント向けの仕様を作れますか？
連携側でAPIを呼び出すツールを作り、説明やスキーマ、結果の整理を追加できます。ただし、元のAPIにない機能や保証を作れるわけではありません。元のAPIの契約と変換後の説明が一致しているか確認します。
エラーには再試行の指示を書けば十分ですか？
いいえ。操作が安全に再試行できるかを、接続先の仕様と実行結果から判断する必要があります。特に書き込みの結果が不明な場合は、状態を照会し、確認できなければ停止して担当者に引き渡します。
API仕様の品質はどう評価しますか？
形式の検証に加え、実際の依頼を使って、正しい操作の選択、入力、結果の解釈、異常時の停止を試します。空結果やページの続きなど、正常応答でも誤解しやすいケースを含めることが大切です。