エージェントファーストなAPI設計：AIエージェントが真に理解できる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: (ウェブで "lemondata models list" を検索)
Agent: (ドキュメントページを取得、おそらく間違ったページ)
Agent: (HTMLをパースし、モデル名を見つける)
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）やプロンプトキャッシュなどの機能にアクセスできるようになります。
レスポンスボディはOpenAI/Anthropicの仕様に従うため、これらはボディではなくヘッダーに配置しています。ヘッダーは安全な拡張ポイントです。
エージェントのチートシートとしての /v1/models レスポンス
私たちは、/v1/modelsレスポンスのすべてのモデルに3つのフィールドを追加しました：
category— チャットモデル、画像生成、動画モデル、あるいは音声か？名前から推測する必要はもうありません。pricing_unit— tokenごと、画像ごと、秒ごと、リクエストごと。コスト見積もりに不可欠です。cache_pricing— アップストリームのプロンプトキャッシュ価格にプラットフォームのセマンティックキャッシュ割引を加えたもの。
既存のフィールド（価格、機能、エイリアス、最大token数）と組み合わせることで、エージェントは1回のAPIコールから、十分な情報に基づいたモデル選択の決定を下すことができます。
llms.txt：エージェントが最初に読むべきもの
私たちはapi.lemondata.cc/llms.txtで動的なllms.txtを提供しています。これはAPI全体のマシンリーダブルな概要です。これには以下が含まれます：
- 動作するコードを含む初回コール用テンプレート
- 一般的なモデル名（ハードコードではなく使用データから自動生成）
- パラメータを含む全12個のエンドポイント
- モデル発見のためのフィルタパラメータ
最初のAPIコールの前にこのファイルを読み込むエージェントは、おそらく一回で正しく実行できるでしょう。
知識ベースではなくデータ駆動型
私たちのシステムのすべての提案は本番データに基づいています。did_you_meanのエイリアスマップは、リクエストログにある30日間の実際のmodel_not_foundエラーから生成されました。モデルの提案は実際の使用パターンによってソートされます。llms.txtの「一般的なモデル名」はデータベースから生成されます。
私たちはすべてのモデルミスをRedisのソート済みセットで追跡しています。スペルミスが十分なヒット数を蓄積すると、エイリアスマップに昇格します。モデルがオフラインになると、すべての提案から自動的に消えます。システムは自ら改善していくのです。
成功をもたらした設計上の制約
私たちは1つのルールを定めました。「新しいエンドポイントを作らない、新しいSDKを作らない、破壊的変更を行わない」ことです。すべてが既存のOpenAI互換のエラーフォーマット内で動作しなければなりませんでした。新しいフィールドはオプションであり、それらを無視するクライアントは以前と同じエクスペリエンスを得られます。
この制約により、誰も採用しないような精巧な新しいAPIを構築するのではなく、エージェントが自己修正するのに実際に役立つ情報は何かを正確に突き止めることができました。
自身のAPIにエージェントファースト設計を適用する方法
AIエージェントが利用するAPIを構築しているなら：
- すべてのエラーを実行可能にする — 何が間違っていたか、なぜか、次に何をすべきかを含める
- 代替案を提案し、自動修正しない — エージェントに情報に基づいた決定をさせる
- 散文ではなく構造化フィールドを使用する —
did_you_meanはパース可能ですが、文字列内の「Did you mean...」は不可能です - 提案を実際のデータに基づかせる — 本番環境の使用パターンは、ハードコードされたリストに勝ります
- マシンリーダブルな発見手段を提供する —
llms.txt、OpenAPIスペック、または構造化されたモデルリスト - 後方互換性を維持する — 新しいヒントフィールドは追加的であるべきで、決して破壊的であってはなりません
FAQ
エージェントファーストなAPI設計とは何ですか？
エージェントファーストなAPI設計とは、エラーレスポンスに構造化されたマシンリーダブルなヒントを含めることで、AIエージェントが人間の介入や外部ドキュメントの参照なしに自己修正できるようにするアプローチです。
エージェントファーストは開発者ファーストなAPI設計とどう違うのですか？
開発者ファーストのAPIは、人間にとっての読みやすさを最適化します（明確なエラーメッセージ、優れたドキュメント、役立つサンプル）。エージェントファーストのAPIは、マシンがプログラムでパースして実行できる構造化フィールド（did_you_mean、suggestions、hint）を追加します。
エージェントファースト設計は既存のクライアントを壊しますか？
いいえ。エージェントファーストのフィールドは追加的なものであり、JSONレスポンス内の余分なフィールドに過ぎません。それらを知らないクライアントは単に無視するだけです。既存の統合は変更なしに機能し続けます。
LemonDataはどのようにエージェントファースト設計を実装していますか？
LemonDataの統合AI APIゲートウェイは、300以上のすべてのモデルに構造化されたエラーヒントを追加しています。すべてのエラーレスポンスには実行可能な提案が含まれており、llms.txtエンドポイントはマシンリーダブルなAPI発見手段を提供します。
LemonDataは、単一のAPIを通じて300以上のAIモデルへの統合アクセスを提供します。エージェントファーストなAPIをlemondata.ccでお試しください。
