「設計するかどうかにかかわらず、すべての 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エージェント#

業務設計書のリスク欄を埋めようとしたら ８個出てきた 書きながら怖くなる でも走り出してから怖くなるより 書いてから怖くなる方が たぶん傷が浅い

業務設計書を書くと やる前にハードルが見える 「ここで詰まりそう」が事前にわかれば 打ち手を３つ手前に置いておける 書かずに動くと 詰まってから考え始める 面倒だけど 書いてから動いた方が、後で見ると速い

人生を変える環境設計は、結局2つしかありません。 やりたい行動を簡単にする。やめたい行動を面倒にする。読書したいなら本を近くへ。SNSを減らしたいならスマホを遠くへ。運動したいなら靴を出しておく。お菓子を減らしたいなら買わない。習慣化は、「自分をコントロールする技術」ではなく、「選択肢をコントロールする技術」です。