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

ほとんどのAPIは、ドキュメントを読み、サンプルを閲覧し、スタックトレースでデバッグを行う人間の開発者のために構築されています。2026年現在、APIトラフィックの大部分はAIエージェントによるものですが、彼らは人間とは異なる方法でAPIとやり取りします。

これが、私たちがTokenLabの統合AI APIを「賢くあろうとせず、有益であれ」という一つの原則に基づいて再設計した理由です。私たちはこの結果を「Agent-First API Design（エージェントファーストなAPI設計）」と呼び、これによりユーザーの無駄なトークン消費を60%以上削減することに成功しました。

重要なポイント

• Agent-First API設計では、エラーレスポンスに構造化された機械可読なヒントを追加することで、AIエージェントがWeb検索や人間の助けを借りずに自己修正できるようにします。
• 自動修正ではなく、代替案を提示します。did_you_mean、suggestions、retryableといったフィールドにより、エージェントは決定を代行されるのではなく、情報に基づいた判断を下せるようになります。
• すべての提案は本番データに基づいているため、オフラインのモデルや非推奨のモデルが候補リストに表示されることはありません。
• ヒントフィールドは追加型で後方互換性があるため、既存のOpenAI互換クライアントは変更なしでそのまま動作し続けます。

Agent-First API Designとは何か？

Agent-First API設計とは、レスポンス（特にエラーレスポンス）を構造化し、AIエージェントが何が問題であったかを理解し、会話を中断することなく修正できるようにすることを意味します。

従来のAPIエラー：

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

Agent-First APIエラー：

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

従来のAPIでは、エージェントはWebを検索し、ドキュメントを見つけ、HTMLを解析し、推測しなければなりませんでした。Agent-First APIであれば、ワンステップで自己修正が完了します。

なぜ従来のAPIはAIエージェントに対して失敗するのか

エージェントが典型的なAPIアグリゲーターに初めてアクセスしたときに何が起こるかを見てみましょう：

Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API:   400 {"error": {"message": "Model not found"}}
Agent: (searches the web for "tokenlab 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-5.5"}
API:   200 ✓

6つのステップ、複数のネットワークリクエスト、数百もの無駄なトークン。これはエージェントが偶然正しいドキュメントURLを推測できた「成功ルート」の場合です。

Agent-First設計の場合：

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

2つのステップ、Web検索はゼロ。エージェントはエラーレスポンスのみから自己修正を行いました。

核となる原則：知性はモデル側に残す

モデル名を自動修正したり、黙って類似モデルにルーティングしたり、レコメンデーションエンジンを後付けしたりするような「賢い」APIを作りたくなる誘惑があります。私たちはそれらすべてを拒否しました。

エージェントが model: "gpt5.5" を送信したとき、その意図は実際には分かりません。新しいGPTリリースが存在するか確認しているだけかもしれません。厳しい予算制限があるのかもしれません。特定のモデルしかサポートしていない特定の機能が必要なのかもしれません。gpt-5.5 への自動ルーティングは、コスト、品質、機能を黙って変更してしまい、エージェントはその変更に気づくことさえありません。

より良いアプローチは、迅速かつ有益に失敗することです。エージェントにすべてのデータを与え、判断を委ねるのです。

4つのAgent-First API設計パターン

パターン1：モデルが見つからない → あいまい検索による提案

{
  "error": {
    "code": "model_not_found",
    "did_you_mean": "gpt-5.5",
    "suggestions": [
      {"id": "gpt-5.5"},
      {"id": "gemini-3.5-flash"},
      {"id": "claude-sonnet-5"}
    ],
    "hint": "Did you mean 'gpt-5.5'? 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": "gemini-3.5-flash", "estimated_cost_usd": 0.02},
      {"id": "deepseek-v4-flash", "estimated_cost_usd": 0.01}
    ],
    "hint": "Insufficient balance. Try a cheaper model or top up."
  }
}

単に「資金不足」と言うのではなく、エージェントに対して正確な残高、必要な金額、現在利用可能な安価なモデルを伝えます。エージェントは、人間の介入なしに自律的により安価なAIモデルへダウングレードできます。コストのしきい値をハードコーディングする前に、TokenLabモデルディレクトリで現在のモデルごとの価格を確認してください。

パターン3：全チャネル失敗 → ライブ代替案

{
  "error": {
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-5", "status": "available"},
      {"id": "gpt-5.5", "status": "available"}
    ],
    "hint": "All channels for 'claude-opus-4-8' 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-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages

私たちはエージェントに「これは成功したが、より良い方法がある」と伝えています。次の呼び出しでネイティブエンドポイントに切り替えることで、OpenAI互換フォーマットでは公開されていない拡張推論やプロンプトキャッシングなどの機能を利用できるようになります。

これらのヒントはレスポンスボディではなくヘッダーに配置されます。ボディはOpenAIやAnthropicの仕様に厳密に従う必要があるためです。ヘッダーは、既存の解析ロジックを壊すことのない安全な拡張ポイントです。

エージェントの「カンニングペーパー」としての /v1/models レスポンス

私たちは /v1/models レスポンスの各モデルエントリに3つのフィールドを追加しました：

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

既存のフィールド（価格、機能、エイリアス、最大トークン数）と組み合わせることで、エージェントは単一のAPI呼び出しから完全に情報に基づいたモデル選択を行えます。完全なライブカタログはTokenLabモデルディレクトリ（2026-07-07時点）で確認でき、現在Claude Sonnet 5、GPT-5.5、Gemini 3.5 Flashといった最新のフロンティアモデルを含む300以上のモデルがチャット、画像、動画、音声のカテゴリでリストされています。本記事の数値が最新であると仮定せず、必ず該当ページで現在の価格と可用性を確認してください。

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

私たちは api.tokenlab.sh/llms.txt に、API全体を網羅した機械可読な概要である動的な llms.txt を提供しています。これには以下が含まれます：

• 動作するコードを含む初回呼び出しテンプレート
• ハードコーディングではなく、利用データから自動生成された一般的なモデル名
• パラメータを含む全12のエンドポイント
• モデル探索のためのフィルタパラメータ

最初のAPI呼び出しの前にこのファイルを読み込むエージェントは、初回でリクエストを成功させる可能性が飛躍的に高まります。

知識駆動ではなく、データ駆動で

システム内のすべての提案は本番データから得られます。did_you_mean のエイリアスマップは、リクエストログにおける30日間の実際の model_not_found エラーからシードされました。モデルの提案は実際の利用状況に基づいてソートされています。llms.txt 内の「一般的なモデル名」リストは手動管理ではなく、データベースから生成されます。

私たちはすべてのモデルのミスをRedisのソート済みセットで追跡しています。誤字が十分なヒット数を蓄積すると、エイリアスマップに昇格されます。モデルがオフラインになると、すべての提案リストから自動的に削除されます。GPT-5.5、Claude Sonnet 5、Gemini 3.5 Flashのような新しいモデルリリースが重なるスケジュールで登場する現在、システムが自動的に調整され、陳腐化を防ぐことは非常に重要です。

成功をもたらした設計上の制約

私たちは「新しいエンドポイントを作らない、新しいSDKを作らない、破壊的変更を行わない」というルールを設けました。すべてを既存のOpenAI互換エラーフォーマット内に収める必要がありました。新しいフィールドはオプションであるため、それらを無視するクライアントは以前と全く同じ体験を得られます。

この制約により、誰も採用しようとしない複雑な新しいAPIを構築するのではなく、エージェントの自己修正に実際に役立つものについて、精度を追求することが強制されました。

Agent-First設計を自身のAPIに適用する方法

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

1. すべてのエラーをアクション可能なものにする。何が問題で、なぜ発生し、次に何をすべきかを明記する。
2. 自動修正ではなく、代替案を提示する。エージェントに情報に基づいた判断を委ねる。
3. 文章ではなく、構造化されたフィールドを使用する。did_you_mean は解析可能ですが、文章の中に埋め込まれた「...という意味ですか？」は解析できません。
4. 提案を実際のデータに基づかせる。本番環境の利用パターンは、陳腐化するハードコーディングされたリストよりも優れています。
5. llms.txt、OpenAPI仕様、または構造化されたモデルリストを通じて、機械可読な探索手段を提供する。
6. 後方互換性を維持する。新しいヒントフィールドは追加型であるべきで、決して破壊的であってはならない。

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

ほとんどのチームは、1週間でAPI全体を再設計する必要はありません。小さな出発点から始めるのが効果的です：

1. 最もボリュームの多いエラーに、1つか2つの機械可読なヒントフィールドを追加する。
2. /v1/models または同等の探索エンドポイントをよりリッチで明示的なものにする。
3. llms.txt のような、機械可読な概要を1つ公開する。
4. curlだけでなく、実際のエージェントクライアントを使用して完全なループをテストする。

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

FAQ

Agent-First API設計とは何ですか？

エラーレスポンスに構造化された機械可読なヒント（did_you_mean、suggestions、hintなどのフィールド）を含めることで、AIエージェントが人間の介入やドキュメント参照なしに自己修正できるようにするアプローチです。

Agent-FirstはDeveloper-First API設計とどう違いますか？

Developer-First APIは人間の読みやすさ（明確なメッセージ、優れたドキュメント、役立つ例）を最適化します。Agent-First APIはその上に構造化フィールドを追加し、機械がエラーを解析してプログラム的に対処できるようにします。

Agent-First設計は既存のクライアントを壊しますか？

いいえ。フィールドは追加型です。did_you_mean や suggestions を探さない既存のクライアントは、それらを単に無視し、これまで通りに動作し続けます。

---

TokenLabは、モデルディレクトリにリストされている単一のAPIを通じて、GPT-5.5、Claude Sonnet 5、Gemini 3.5 Flashなどの現在のフロンティアモデルを含む300以上のAIモデルへの統合アクセスを提供します。無料で開始し、1ドルのスタータークレジットでAgent-First APIをテストしてください。