無料 API の障害に耐える AI Agent の設計
Agent の状態、モデルルーティング、ツール権限、API キーを分離し、プロバイダー障害やクォータ変更で全体が止まらないようにします。
役割を分離する：Agent の契約を一つのモデル API に依存させない
タスク状態、ツールのスキーマ、レビュー規則、プロバイダー用アダプターを別々に管理します。狭く定義した内部リクエスト契約があれば、モデルにスケジューラーや認証情報ストアへの直接アクセスを与えずに、同じタスクを互換性のあるルート間で移せます。
調査役とレビュー役には、異なる優先ルートとフォールバックルートを使います。両方が同じプロバイダーに依存していると、一つのクォータ切れや認証障害によって独立したチェックまで気づかれないまま失われる可能性があります。
失敗の種類でルーティングする：すべての失敗を同じように扱わない
認証エラーなら認証情報を隔離し、レート制限なら上限のあるクールダウンを設け、クォータ切れならより長いルート変更を検討します。タイムアウトが繰り返される場合に限り、しきい値を超えてからサーキットブレーカーを開きます。不正なモデル応答にはスキーマ再試行や別の監査モデルが必要で、API キーの自動ローテーションでは解決しません。
ルートの健全性は役割ごとに測定します。小さな Canary に答えられるプロバイダーでも、厳密な JSON 監査では期待どおりに動かないことがあります。単一の総合スコアでは、こうした失敗モードが隠れてしまいます。
認証情報を守る：ルート選択は自動化し、秘密情報の所有権は移さない
モデルにプロバイダーのシークレットを読ませたり、コピーさせたり、作成させたりしてはいけません。ランタイムが外向きリクエストに認証情報を注入し、結果だけを返します。運用用キーとユーザーの Vault データを分離し、プロバイダーごとにシークレットを分ければ、失効の範囲を小さく保てます。
フォールバック後に全キューを復旧する前に、範囲を限定した Canary を実行します。失敗したジョブと根拠を残し、プロバイダー障害なのか、ソースやプロンプトの問題なのかを運用担当者が見分けられるようにします。
よくある質問
- Q. AI Agent が自動でプロバイダーを切り替えてもよいですか？／A. 切り替え条件が決定的で、タスク契約を移行でき、全量を戻す前にフォールバックを検証するなら可能です。
- Q. モデルに API キーを選ばせたりローテーションさせたりしてよいですか？／A. いいえ。認証情報の選択はモデルのコンテキスト外にある、信頼できるランタイムの責任です。
- Q. Scout と Auditor のルートを分ける理由は？／A. 一つのプロバイダー障害や共通のモデルバイアスが、収集とレビューの両方を損なう可能性を下げるためです。
刊行上の開示
このガイドは、リンクしたプロバイダー文書を複数プロバイダーや API 接続ツールの背景確認に使っています。ルーティング、分離、復旧に関する提案は FreeToken 独自の運用設計であり、ソースを複写せず、人間の編集者が確認しました。