Agent-First API Design: AI AgentsのためのAPI構築

ほとんどのAPIは、ドキュメントを読み、サンプルをブラウズし、スタックトレースでデバッグする人間の開発者向けに設計されています。しかし、2026年において最も急速に成長しているAPIコンシューマーはAIエージェントであり、彼らは人間とは全く異なる方法でAPIと対話します。

これは、私たちがLemonDataの統合AI APIを、「賢くなるのではなく、情報を提供する」というシンプルな原則に基づいて再設計した物語です。その結果が、私たちが「エージェントファーストなAPI設計」と呼ぶものであり、これによりユーザーの無駄なtoken消費を60%以上削減することに成功しました。

エージェントファーストなAPI設計とは？

エージェントファーストなAPI設計とは、AIエージェントが外部の助けを借りずに何が問題だったのかを理解し、修正できるように、APIレスポンス（特にエラーレスポンス）を構造化することを意味します。

従来のAPIエラー:

{"error": {"message": "Model not found"}}

エージェントファーストなAPIエラー:

{
  "error": {
    "code": "model_not_found",
    "message": "Model 'gpt5' not found",
    "did_you_mean": "gpt-4o",
    "suggestions": [{"id": "gpt-4o"}, {"id": "gpt-4o-mini"}],
    "hint": "Use GET /v1/models to list all available models."
  }
}

その違いは何でしょうか？従来のAPIでは、エージェントはウェブを検索し、ドキュメントを見つけ、HTMLを解析し、推測する必要があります。エージェントファーストなAPIであれば、ワンステップで自己修正が可能です。

なぜ従来のAPIはAIエージェントにとって不十分なのか

AIエージェントが一般的なAPIアグリゲーターを初めて利用する際に何が起こるか見てみましょう。

Agent: POST /v1/chat/completions {"model": "gpt5"}
API:   400 {"error": {"message": "Model not found"}}
Agent: (searches the web for "lemondata models list")
Agent: (fetches a docs page, maybe the wrong one)
Agent: (parses HTML, finds a model name)
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API:   200 ✓

6つのステップ。複数のネットワークリクエスト。何百もの無駄なtoken。そしてこれは、エージェントが正しいドキュメントのURLを推測できたという「ハッピーパス」の場合です。

エージェントファースト設計の場合：

Agent: POST /v1/chat/completions {"model": "gpt5"}
API:   400 {"did_you_mean": "gpt-4o", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API:   200 ✓

2つのステップ。ウェブ検索はゼロ。エージェントはエラーレスポンスだけで自己修正しました。

基本原則：インテリジェンスはモデル側に留める

「賢い」APIを作りたいという誘惑に駆られることがあります。モデル名を自動修正したり、似たモデルにサイレントにルーティングしたり、推奨エンジンを追加したりすることです。私たちはそれらすべてを拒否しました。

エージェントが model: "gpt5" を送信したとき、その意図は分かりません。GPT-5が存在するかテストしているのかもしれません。予算の制約があるのかもしれません。あるいは特定の機能が必要なのかもしれません。gpt-4o への自動ルーティングは、エージェントが知らないうちにコスト、出力品質、機能をサイレントに変更してしまいます。

正しいアプローチは、素早く失敗し、情報を提供した上で失敗することです。エージェントにすべてのデータを与え、判断を委ねるのです。

4つのエージェントファーストなAPI設計パターン

パターン1：モデルが見つからない → 曖昧な候補の提案

{
  "error": {
    "code": "model_not_found",
    "did_you_mean": "gpt-4-turbo",
    "suggestions": [
      {"id": "gpt-4o"},
      {"id": "gpt-4o-mini"},
      {"id": "claude-sonnet-4-5"}
    ],
    "hint": "Did you mean 'gpt-4-turbo'? Use GET /v1/models to list all available models."
  }
}

did_you_mean フィールドは、本番データからの静的なエイリアスマッピング、正規化された文字列マッチング、および制限付き編集距離の3層の解決ロジックを使用しています。すべての候補はライブのモデルリストに対して検証されるため、現在オフラインのモデルを提案することはありません。

パターン2：残高不足 → 予算を考慮した代替案

{
  "error": {
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-4o-mini", "estimated_cost_usd": 0.02},
      {"id": "deepseek-chat", "estimated_cost_usd": 0.01}
    ],
    "hint": "Insufficient balance. Try a cheaper model or top up."
  }
}

単に「お金が足りません」と言う代わりに、エージェントに現在の残高、必要な金額、そして現在の予算で購入可能なモデルを正確に伝えます。これにより、エージェントは人間の介入なしに、自律的により安価なAIモデルにダウングレードできます。

パターン3：すべてのチャネルが失敗 → 稼働中の代替案

{
  "error": {
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-5", "status": "available"},
      {"id": "gpt-4o", "status": "available"}
    ],
    "hint": "All channels for 'claude-opus-4-6' temporarily unavailable. Retry in 30s or try an alternative."
  }
}

alternatives リストは静的なものではありません。チャネルのヘルスデータに対するライブクエリであるため、エージェントは現在実際に動作しているものに関するリアルタイムの情報を得ることができます。

パターン4：レート制限 → 正確なリトライタイミング

{
  "error": {
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "limit": "1000/min",
    "remaining": 0,
    "hint": "Rate limited. Retry after 8s."
  }
}

推測は不要です。恣意的な値から始まる指数バックオフも不要です。エージェントは正確な待ち時間を把握できます。レート制限を効果的に処理する方法の詳細については、AI APIレート制限ガイドをご覧ください。

成功レスポンスにもヒントを含める

エージェントが Claude モデルを使用して /v1/chat/completions を呼び出すと、レスポンスには以下が含まれます。

X-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-LemonData-Native-Endpoint: /v1/messages

私たちはエージェントに「これは成功しましたが、より良い方法があります」と伝えています。エージェントは次回の呼び出しでネイティブエンドポイントに切り替えることができ、OpenAI互換フォーマットでは利用できない extended thinking や prompt caching などの機能にアクセスできるようになります。

ボディは OpenAI/Anthropic の仕様に従う必要があるため、これらはレスポンスボディではなくヘッダーに配置しています。ヘッダーは安全な拡張ポイントです。

エージェントのチートシートとしての /v1/models レスポンス

私たちは /v1/models レスポンスのすべてのモデルに3つのフィールドを追加しました。

category: チャットモデル、画像生成、動画モデル、または音声。名前から推測する必要はもうありません。
pricing_unit: tokenごと、画像ごと、秒ごと、またはリクエストごと。コスト見積もりに不可欠です。
cache_pricing: アップストリームの prompt cache 価格とプラットフォームのセマンティックキャッシュ割引。

既存のフィールド（価格、機能、エイリアス、最大token数）と組み合わせることで、エージェントは1回のAPIコールから、十分な情報に基づいたモデル選択の決定を下すことができます。

llms.txt：エージェントが最初に読むべきもの

私たちは api.lemondata.cc/llms.txt で、API全体のマシンリーダブルな概要である動的な llms.txt を提供しています。これには以下が含まれます。

動作するコードを含む初回コール用テンプレート
一般的なモデル名（ハードコードではなく、使用データから自動生成）
パラメータを含む全12個のエンドポイント
モデル発見のためのフィルタパラメータ

初めてのAPIコールの前にこのファイルを読み込むエージェントは、おそらく初回で正しく実行できるでしょう。

ナレッジ駆動ではなくデータ駆動

私たちのシステムのすべての提案は、本番データに基づいています。did_you_mean のエイリアスマップは、リクエストログにある30日間の実際の model_not_found エラーから生成されました。モデルの提案は実際の使用パターンによってソートされています。llms.txt の「一般的なモデル名」はデータベースから生成されます。

すべてのモデルミスを Redis のソート済みセットで追跡しています。スペルミスが一定のヒット数に達すると、エイリアスマップに昇格します。モデルがオフラインになると、すべての提案から自動的に消えます。システムは自ら改善していくのです。

それを成功させた設計上の制約

私たちは1つのルールを定めました。新しいエンドポイントを作らない、新しい SDK を作らない、破壊的変更を行わない、ということです。すべては既存の OpenAI 互換のエラーフォーマット内で動作しなければなりませんでした。新しいフィールドはオプションであるため、それらを無視するクライアントは以前と同じエクスペリエンスを得られます。

この制約により、誰も採用しないような精巧な新しいAPIを構築するのではなく、エージェントが自己修正するのに実際に役立つ情報は何かを正確に突き止めることができました。

自身のAPIにエージェントファースト設計を適用する方法

AIエージェントが利用するAPIを構築している場合：

すべてのエラーを実行可能（actionable）にする。何が間違っていたのか、なぜか、そして次に何をすべきかを含める。
自動修正するのではなく、代替案を提案する。エージェントに情報に基づいた決定をさせる。
文章ではなく構造化されたフィールドを使用する。did_you_mean は解析可能ですが、文字列内の「Did you mean...」は解析困難です。
提案を実際のデータに基づかせる。本番環境の使用パターンは、ハードコードされたリストに勝ります。
llms.txt、OpenAPI スペック、または構造化されたモデルリストを通じて、マシンリーダブルな発見手段を提供する。
後方互換性を維持する。新しいヒントフィールドは追加的なものであるべきで、決して破壊的であってはなりません。

すべてを書き直さずにどこから始めるべきか

ほとんどのチームは、1週間でAPI全体を再設計する必要はありません。

実践的な出発点はもっと小規模です：

最もボリュームの多いエラーに、1つか2つのマシンリーダブルなヒントフィールドを追加する
/v1/models または同等のモデル発見エンドポイントをより豊かで明示的なものにする
llms.txt のようなマシンリーダブルな概要を1つ公開する
curl だけでなく、1つのエージェントクライアントでループ全体をテストする

すでにゲートウェイレイヤーを介して運用している場合は、統合AIゲートウェイガイドが、なぜそのコントロールプレーンが重要なのかを示しています。まだ直接的な OpenAI 互換の統合を行っている場合は、エージェントフレンドリーな動作を追加する前に、マイグレーションガイドから始めるのが最も簡単です。

FAQ

エージェントファーストなAPI設計とは何ですか？

エージェントファーストなAPI設計とは、エラーレスポンスに構造化されたマシンリーダブルなヒントを含めることで、AIエージェントが人間の介入や外部ドキュメントの参照なしに自己修正できるようにするアプローチです。

エージェントファーストはデベロッパーファーストなAPI設計とどう違うのですか？

デベロッパーファーストなAPIは、明確なエラーメッセージ、優れたドキュメント、役立つサンプルなど、人間の読みやすさを最適化します。エージェントファーストなAPIは、マシンがプログラムで解析して実行できる構造化されたフィールド（did_you_mean、suggestions、hint）を追加します。

エージェントファースト設計は既存のクライアントを壊しますか？

いいえ。エージェントファーストなフィールドは追加的なものであるため、既存のクライアントはそれらを無視して、変更なしで動作し続けることができます。

LemonData はどのようにエージェントファースト設計を実装していますか？

LemonData の統合AI APIゲートウェイは、300以上のすべてのモデルに構造化されたエラーヒントを追加しています。すべてのエラーレスポンスには実行可能な提案が含まれており、llms.txt エンドポイントはマシンリーダブルなAPI発見手段を提供します。

LemonData は、単一の API を通じて 300 以上の AI モデルへの統合アクセスを提供します。エージェントファーストな API をテストするには、無料でお試しください。1ドルのスタータークレジットが付属しています。

Agent-First API Design: AIエージェントが真に理解できるAPIを構築する方法