プロンプトとスコープ
人間の開発者向けに設計されたプロジェクト管理APIを、AIエージェントが確実に呼び出せるものへと転換してください。操作の記述、入力、出力、ページネーション、エラー、書き込み確認、レート制限、およびセキュリティについて説明してください。このプロンプトは、IETFの2026年6月のInternet-Draft「Agent-Friendly HTTP API Profile」を参照しています。これは情報提供（Informational）であり、まだ策定中のものです。新しいプロトコル、アイデンティティ、または認可メカニズムを定義するものではありません。
面接官がテストしていること
- 機械可読な記述を事後ドキュメントではなく契約（コントラクト）として扱うこと。
- 安定した名前、厳格なスキーマ、制限されたレスポンス、およびカーソルページネーションによって誤った選択を減らすこと。
- エラー、リトライ、冪等性、プレビュー、および取り消し（undo）を実行可能なシグナルにすること。
- APIの使いやすさを、エージェントのアイデンティティ、認可、およびプロンプトインジェクションのセキュリティから切り離すこと。
回答前に確認すべき質問
- エージェントはOpenAPI、MCPツールレイヤー、またはカスタムカタログのどれを通じてAPIを検出（ディスカバリ）しますか？
- どの操作が読み取り専用で、どの操作が通知、課金、または状態変更を伴いますか？
- レスポンスにはフィールド選択、カーソルページネーション、および最大ページサイズが必要ですか？
- クライアントは冪等性キーを提供し、タイムアウト後に元の結果を取得できますか？
- 返されるフィールドのうち、制御フィールドから分離する必要がある信頼できないユーザーコンテンツを含むものはどれですか？
30秒の回答フレームワーク
APIの記述とHTTPの動作を1つの入力契約として扱います。操作名は安定させ意図が明確なものにし、未知の入力プロパティを拒否し、フィールド選択を備えた小さなレスポンスを返し、コレクションはカーソルでページネーションします。エラーには安定したコード、リトライ可能性、次のアクションを含めます。書き込みは冪等性キー、プレビュー、確認、および取り消しをサポートします。サーバーは制限、認可、および監査を強制します。セキュリティの判断をエージェントに委ねることはできません。IETFのドキュメントはドラフトのチェックリストであり、認証プロトコルではありません。
ステップバイステップの詳細解説
1. APIレイヤーとツールレイヤーを分離する
OpenAPIおよび同様の機械可読な記述はAPIレイヤーに属し、MCPやその他のツール呼び出しプロトコルはツールレイヤーに属します。複数のツールレイヤーが再利用できるように、まず安定した検証可能なAPI契約を構築します。単一のエージェントのプロンプトやツール名だけをセキュリティ境界にしてはなりません。
2. 判別しやすい操作を設計する
Operation IDは安定しており、短く、意図が明確である必要があります。大規模なツールサーフェスでは、task_create や task_update のようにエンティティを先頭にした名前の方が、共通の create_ プレフィックスよりも区別しやすい場合があります。記述には、操作を使用すべき場合と使用すべきでない場合、その副作用、および不足している識別子を取得するためのルックアップ操作を明記する必要があります。
3. 入力と出力を制約する
入力スキーマは必須フィールド、クローズドな列挙型、長さ、配列の制限を定義し、未知のプロパティを拒否する必要があります。レスポンスはデフォルトで小さくし、フィールド選択または詳細度指定をサポートする必要があります。クライアントがより少ないデータを要求することに依存してはなりません。コストとコンテキスト使用量の制御はサーバー側で行います。
{
"name": "task_create",
"description": "Create a task; notifies the assignee.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"required": ["project_id", "title", "idempotency_key"],
"properties": {
"project_id": {"type": "string"},
"title": {"type": "string", "maxLength": 200},
"priority": {"type": "string", "enum": ["low", "medium", "high"]},
"idempotency_key": {"type": "string", "maxLength": 128}
}
}
}4. 読み取りとページネーションを回復可能にする
エージェントにオフセットを計算させるのではなく、不透明な（opaque）カーソルを返します。カーソルをクエリにバインドして有効期限を設定し、すぐに使用できる次のアクションとともに next_cursor を返します。安定した順序付け、条件付きリクエスト、およびフィールド選択により、重複転送とコンテキスト使用量を削減します。
5. エラーを機械的に処理可能（actionable）にする
安定したコード、構造化された詳細、および retryable フラグを返します。有用な場合は次の操作へのリンクを含めます。429レスポンスはリトライ遅延を提供し、バリデーションエラーはフィールドを特定し、長時間実行されるジョブはステータスURLを提供する必要があります。自然言語は人間を助けますが、それだけを制御セマンティクスにすることはできません。
{
"type": "https://api.example/problems/rate-limit",
"title": "Too many requests",
"status": 429,
"code": "RATE_LIMITED",
"retryable": true,
"retry_after_seconds": 30
}6. 書き込みを保護する
書き込みは、文書化された有効期間とスコープを持つ冪等性キーを受け入れます。タイムアウト後のリトライでは、重複を作成するのではなく元の結果を返します。高リスクな書き込みでは、ドライラン、確認、または取り消しを提供し、通知、課金、その他の副作用を明記します。サーバーは認可、クォータ、および監査のチェックを引き続き実行します。
7. セキュリティとオブザーバビリティの境界を設定する
間接的なプロンプトインジェクションを減らすために、ユーザーまたはサードパーティのテキストをデータとしてマークし、信頼できる制御フィールドから分離します。レスポンスサイズ、ページサイズ、ポーリング、およびツール名前空間を制限します。高リスクな操作には最小権限と人間による確認を義務付けます。機密コンテンツをログに記録することなく、相関ID、アクター、委任、結果、およびリトライを記録します。
8. 検証と反復改善を行う
固定のタスクセットを使用して、操作選択の精度、パラメータエラー、重複書き込み、回復可能なエラー、平均レスポンスサイズ、コンテキスト使用量、429後の成功率、および確認の網羅率を測定します。記述、スキーマ、エラー、およびレスポンスをバージョン管理します。ドラフトの推奨事項は、標準規格への準拠を約束するのではなく、内部チェックリストとして活用します。
質の高い模範回答
私はAPI記述をプライマリ契約として扱い、それを取り巻くHTTP動作を設計します。Operation IDは安定しており、エンティティと意図を表現します。記述には使用条件、禁止ケース、および副作用を明記します。入力スキーマは未知のフィールドを拒否し、列挙型、長さ、配列、およびページを制約します。コレクションは不透明なカーソルと安定した順序付けを使用し、レスポンスは小さくフィールド選択可能にします。
エラーには安定したコード、リトライ可能性、retry_after、および次のアクションを含めます。書き込みには冪等性キーを必須とし、タイムアウト後には元の結果を返します。高リスクな書き込みはプレビュー、確認、または取り消しをサポートします。サーバーは、エージェントが散文の指示に従うことを信頼するのではなく、認可、レート制限、サイズ制限、および監査を強制します。ユーザーコンテンツは制御フィールドから分離し、ツールプロバイダーは相関IDを持つ個別の名前空間を使用します。
最後に、誤った選択、パラメータエラー、重複書き込み、レスポンスサイズ、リトライの成功、および確認の網羅率についてタスクセットを評価します。IETFのドキュメントは認証や認可プロトコルを持たない2026年6月の情報提供（Informational）ドラフトであるため、内部バージョニングとロールバックを備えた設計チェックリストとして使用します。
よくある間違い
- プロファイルを新しいアイデンティティまたは認可プロトコルと呼ぶこと。
- OpenAPI、スキーマ、エラー、および副作用の仕様を曖昧にしたまま、プロンプトの最適化ばかり行うこと。
- エージェントに対してレスポンスサイズの制限やページネーションのオフセット計算を要求すること。
- リトライ可能な書き込みから冪等性、プレビュー、確認、または取り消しを省くこと。
- 返されたユーザーテキストを信頼できる指示フィールドに配置し、間接的なプロンプトインジェクションを無視すること。
フォローアップの質問と回答
なぜより詳細なドキュメントを書くだけでは不十分なのですか？
エージェントは各ステップで機械可読な記述とレスポンスから選択を行います。安定したフィールド、列挙型、エラーフラグ、およびカーソルは、散文の中に散りばめられたアドバイスよりも実行が容易です。ドキュメントは人間や移行作業にとって引き続き有用です。
セキュリティを担うレイヤーはAPIとMCPのどちらですか？
APIが認証、認可、レート制限、および監査を強制する必要があります。ツールレイヤーは露出、名前空間、および確認を制限できますが、サーバー側のアクセス制御に代わることはできません。
どの書き込みに確認が必要かをどのように判断しますか？
不可逆性、金額、データ開示、外部通知、および権限スコープによって分類します。高リスクな操作はドライランまたは確認トークンを公開します。低リスクな冪等更新は自動的に実行される場合がありますが、サーバーは常にそれらを検証します。
記述がサードパーティのコンテンツによって汚染された場合はどうしますか？
サードパーティのテキストは明示的なデータフィールドに配置し、ツールの定義やパーミッションを変更できないようにします。プロバイダーの名前空間を分離し、フィンガープリントを固定し、バージョンを監査し、サーバー上で認可を再確認します。