「設計するかどうかにかかわらず、すべての API チームはいずれエージェントのコンシューマーを抱える」——Pinecone エンジニアによるエージェントフレンドリー API 設計の論考が秀逸です。 Designing Agent-Friendly APIs エージェント向け API 設計の6原則を紹介するこの記事から、特に重要な3つのポイントを深掘りします。 🔴 注目1: エラーメッセージが「指示」になるかどうか `"Invalid request"` というエラーを返すだけでは、エージェントはバジェット（トークン予算）を無駄に消費しながら推測を繰り返します。正しい設計は「何が・なぜ・どう直す」の3要素をセットにすること。`"Response is too large. To reduce the size, try a lower top_k value."` のように具体的な回復手順を含めれば、エージェントは次のコールで自己修正できます。RFC 9457 Problem Details で機械可読エラーコードを安定提供し、認証エラーは「欠如」と「不正」を別コードに分けることも重要です。 🔵 注目2: エンドポイント1:1でのMCPサーバー化は失敗する 大規模 API をそのまま MCP サーバーに変換すると、エージェントはファーストコール以前に「数十万トークン」を消費しかねません。Cloudflare は `search()` と `execute()` の2つのツールだけで 2,500 エンドポイントへのアクセスを約 1,000 トークンで実現しています。`list_users` + `list_events` + `create_event` という3エンドポイントの代わりに `schedule_event` 1本を提供する——ワークフロー単位でエージェント面を製品として設計することが本質です。 🟡 注目3: TTFSC（Turns-to-First-Successful-Call）という新指標 著者は Claude Sonnet 5 をコールドな状態で Pinecone の API に当てた実験を公開しています。全3試行で無人成功、ファーストコールまでの中央値は **6ターン・約$0.30・約90秒**。生の REST を選んだエージェントはわずか3ターンで成功した一方、Python SDK を選んだエージェントはターンの「ほぼ半分」を call signature の解読に費やしました。廃止済みパッケージ名のインストールを試みたのは古いモデルで、現行世代は直接モダン API へ向かいました——LLMの学習データに刷り込まれた旧 API 形状が如何に影響するかを示す実例です。 エージェントはこれまで開発者が暗黙に吸収してきたコストを「可視化・課金可能・チャーン誘発」な経済コストとして外部化します。AX（Agent Experience）はDXと並ぶ必須の設計軸になりつつあります。 #APIデザイン# #AIエージェント#