Reliability and Routing2026年7月27日Flatkey Team

Gemini API for AI Agents: 本番統合チェックリスト

Gemini 搭載エージェント向けの本番チェックリスト。安定したエンドポイント、制御されたモデル切り替え、ツールの安全性、再試行、フォールバックルーティング、コストの可視化をカバーします。

エージェントを Gemini API に接続するのは簡単です。モデル、ツール、トラフィック、予算が変化してもその統合を安定して維持することが、本番運用上の課題です。

エージェントのワークフローでは、API 呼び出しはより長いシステムの中の 1 ステップにすぎません。プランナーがアクションを選び、モデルが引数を生成または検証し、ツールが実行され、メモリが更新され、さらに別のモデルが結果をレビューすることもあります。壊れやすいエンドポイント、気づかれないモデル変更、制御されていないリトライ、あるいはコストシグナルの欠如は、チェーン全体を壊す可能性があります。

このチェックリストでは、Gemini を活用したエージェントを成功したデモから本番統合へ移行する方法を示します。リリース後に重要となる 3 つの判断に焦点を当てます: エンドポイントの安定性、制御されたモデル切り替え、コストの可視化。

1 つの表で見る本番対応状況

領域	本番での最小ルール	収集すべき証跡
エンドポイント	ベース URL と認証情報は環境設定に保持する	デプロイ先ランタイムからのスモークテスト
モデル選択	正確なモデル ID または承認済みエイリアスの許可リストを使用する	有効なモデルを示す設定記録
エージェントツール	実行前にツール引数を検証する	提案、承認、却下された呼び出しのログ
構造化出力	スキーマを適用し、無効なレスポンスを処理する	代表的なプロンプトを使った契約テスト
リトライ	一時的な失敗のみを、上限とジッター付きで再試行する	リトライ回数、最終ステータス、総レイテンシ
フォールバック	別のモデルを使用できる条件を定義する	ログ内のルーティングポリシーとフォールバック理由
コスト	トークン、リクエスト、モデル、ワークフローステップを記録する	実行ごとおよび機能ごとのコストレポート
セキュリティ	プロバイダーの認証情報はサーバー側で、スコープを限定して保持する	キーの所有者、環境、ローテーション日、アクセスポリシー

1. Gemini を直接依存にするか、ルーティングされた機能にするかを決める

Gemini を直接統合すると、チームはプロバイダーのネイティブ SDK と機能セットを利用できます。アプリケーションが Gemini 固有の機能に依存しており、チームがプロバイダー固有のコードを維持することに慣れている場合には、これが適切な選択になることがあります。

API ゲートウェイは、Gemini がより広いエージェントシステムの中の 1 つの機能にすぎない場合に、より有用です。エージェント開発者は、分類用の高速モデル、計画用のより強力なモデル、フォールバック用の別プロバイダー、そして画像または動画用の別モデルを必要とすることがよくあります。各ステップが異なる認証情報、エンドポイント、レスポンス形式、請求アカウントを持つと、運用作業は急速に増大します。

コードを増やす前に境界を定義してください:

直接プロバイダー境界: アプリケーションコードが Gemini 固有のエンドポイント、モデル名、エラー、SDK の動作を把握する。
ゲートウェイ境界: アプリケーションコードは 1 つの安定した API 表面を呼び出し、プロバイダー選択とモデル変更はルーティング設定の中に保持する。
ハイブリッド境界: Gemini ネイティブ機能は直接 API を使い、移植可能なチャット、ツール、構造化出力のステップはゲートウェイを使う。

目的は、すべてのプロバイダー差分を隠すことではありません。目的は、プロバイダー変更がエージェントのオーケストレーションコード全体に広がらないようにすることです。

運用上のトレードオフを比較している場合は、AI Gateway for Automation Builders と Unified AI API: When One Access Layer Beats Separate Provider Accounts をお読みください。

2. エンドポイントと認証情報をアプリケーションロジックの外に置く

本番用エンドポイントや API キーを、エージェント、ツール定義、リポジトリ、ブラウザバンドル、またはプロンプト設定にハードコードしないでください。これらはデプロイ環境またはシークレットマネージャーに保管してください。

Gemini を直接統合する場合は、Google の最新の API キーのガイダンスに従い、キーはサーバー側に保持してください。ルーティングされた統合の場合は、ゲートウェイのキーとベース URL も同じ種類の保護された設定に保持してください。

OpenAI 互換クライアントを使うと、通信境界を明示できます。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url=os.environ["AI_GATEWAY_BASE_URL"],
)

Flatkey では、OpenAI 互換のベース URL は https://router.flatkey.ai/v1 です。Flatkey API クイックスタートでは、最初のリクエストとログ確認を順を追って説明しています。

本番テストは、ノートパソコン上だけでなく、デプロイ先の環境から実行する必要があります。そうすることで、シークレットの不足、外向きネットワークの制限、誤ったベース URL、環境固有のモデルアクセスを検出できます。

3. モデルポリシーをプロンプトコードから分離する

Google の Gemini モデルのドキュメントでは、モデルとライフサイクル段階が区別されています。利用可能性や推奨モデルの選択は変わる可能性があるため、エージェントはプランナー、ワーカー、評価器、バックグラウンドジョブにモデル文字列を散在させるべきではありません。

代わりに、1 つのモデルポリシーオブジェクトを作成してください。

{
  "planner": "APPROVED_GEMINI_MODEL",
  "tool_worker": "APPROVED_FAST_MODEL",
  "reviewer": "APPROVED_REVIEW_MODEL",
  "fallbacks": ["APPROVED_FALLBACK_MODEL"],
  "policy_version": "2026-07-27"
}

再現性が重要な場合は、正確なモデル識別子を使用してください。意図的に、より新しいモデルへ移動しうるエイリアスを使う場合は、それを運用上の判断として扱ってください。文書化し、監視し、挙動が変わったときには回帰テストを実行してください。

許可リストは次の点に答えられる必要があります。

どのモデルが本番データを受け取れるか？
どのワークフロー役割が各モデルを使えるか？
どのモデル機能が必要か？
1 ステップあたりの許容可能な最大コストとレイテンシはどれか？
現在のモデルポリシーを変更できるのは誰か？

4. エージェントが実際に使う機能をテストする

基本的なテキスト応答だけでは、エージェント統合が本番対応であることは証明できません。ワークフローで使う機能の正確な組み合わせをテストしてください。

ツール呼び出し

Gemini は関数呼び出しをサポートしていますが、モデルが提案した引数は依然としてアプリケーション側の検証を通過しなければなりません。すべてのツール呼び出しを信頼できない入力として扱ってください。

各ツールについて:

必須フィールド、型、範囲、および許可された値を検証する。
モデルの意図とは別に、認可を確認する。
副作用のある再試行の前に、冪等性保護を追加する。
提案された呼び出し、検証結果、実行結果、および相関IDをログに記録する。
破壊的な操作や金銭的に重要な操作には確認を必須にする。

構造化出力

別のシステムが応答を消費する場合は、構造化出力を使用してください。JSONのように見える文字列は契約ではありません。応答をスキーマに照らして検証し、拒否や途中打ち切りを処理し、必須フィールドが欠けている場合にどうするかを定義してください。

長いコンテキストとマルチモーダル入力

エージェントがドキュメント、画像、音声、または長い履歴を送信する場合は、実際のペイロードサイズでテストしてください。レイテンシ、トークン使用量、アップロード動作、および障害回復を測定します。短いプロンプトのベンチマークが本番経路を予測できると仮定しないでください。

5. リトライはエージェント全体の実行単位で設計する

リトライは信頼性を向上させますが、エージェントにはすでにループが含まれている場合があります。ツールのリトライの内側でモデルのリトライが発生し、その内側でワークフローのリトライが起きると、リクエスト数とコストが増大する可能性があります。

次のような制限付きポリシーを使用してください:

一時的なトランスポート障害と、対象となるレート制限応答を再試行する。
ジッター付きの指数バックオフを使用する。
最大試行回数と最大経過時間を設定する。
入力を変更しないまま、無効なツール引数やスキーマ失敗を自動再試行しない。
操作が冪等であるか、または冪等性キーを持つ場合を除き、副作用のあるツールを再試行しない。
1つのエージェント実行IDの下で、すべての試行を記録する。

Googleは現在のGemini APIのレート制限を公開しています。プロバイダーの制限はワークロード戦略ではないため、アプリケーション側でも独自の同時実行、キュー、予算の制限で自衛する必要があります。

6. モデル切り替えを明示的かつ可逆にする

「フォールバック」は「何かが返るまでランダムなモデルを試す」という意味であってはなりません。モデルが異なると、ツール引数、フォーマット、安全性の挙動、レイテンシ、コストも異なり得ます。

本番環境のフォールバックポリシーでは、次の項目を明示すべきです:

決定	ポリシーに関する例示的な質問
トリガー	フォールバックはタイムアウト、レート制限、プロバイダーエラー、または検証失敗で実行されるか?
互換性	フォールバックは同じツールと出力スキーマをサポートしているか?
品質	同じエージェント回帰テストに合格しているか?
予算	プライマリモデルの1実行あたりコストを超える可能性があるか?
制限	1回の実行で許可されるモデル切り替え回数は何回か?
証跡	フォールバックしたモデルと理由はログで見えるか?

モデル変更は、急いだコードデプロイではなく、構成フラグまたはルーティングルールで展開してください。まずはシャドウテストまたは少量のトラフィック比率で開始し、タスク成功率とコストを比較してから拡大します。ロールバック用に以前のモデルポリシーを利用可能にしておいてください。

ここでAPIゲートウェイアーキテクチャは運用リスクの低減に役立ちます。アプリケーションは1つのアクセスパターンを維持しつつ、その背後で承認済みのルートだけが変更されます。

7. ワークフローステップ単位でコストを測定する

請求書の合計では遅すぎるうえ、粒度も粗すぎます。エージェントチームは、どのワークフロー、テナント、機能、モデル、そしてリトライ経路が支出を生み出したのかを把握する必要があります。

少なくとも次を記録してください。

エージェント実行 ID とワークフロー名。
テナント、環境、機能。
モデルとプロバイダールート。
利用可能な場合は、入力、出力、キャッシュ済みトークンの各フィールド。
リクエスト数、リトライ数、フォールバック数。
ツール呼び出し回数とエンドツーエンドの総レイテンシ。
各ステップおよび全体実行の推定コストまたは記録済みコスト。

Gemini のレスポンスには使用情報が含まれており、Google はトークンカウントに関するガイダンスを提供しています。ダッシュボードが単一プロバイダーの命名に依存しないよう、これらのフィールドを 1 つの内部使用スキーマにマッピングしてください。

次に、3 つのレベルで予算を追加します。

ステップ単位: 1 つのプランナーやレビュアーが不合理な量を消費するのを防ぐ。
実行単位: エージェントタスク全体にわたるループ、リトライ、フォールバックを抑制する。
期間単位: テナント、チーム、プロジェクト、または環境ごとにアラートを出すか、スロットリングする。

トラフィックを変更する前に、現在のモデル料金を確認してください。Flatkey の料金ページには、プラットフォーム経由で利用可能なモデルの最新カタログと料金表示が掲載されています。

8. モデルを切り替える前に回帰テストスイートを構築する

アプリケーションコードに変更がなくても、モデルの切り替えはソフトウェア変更です。実際の承認済みケースから小さな評価セットを作成してください。

次を含めてください。

成功結果が既知の通常リクエスト。
明確化が必要な曖昧な入力。
無効なツール引数。
取得したコンテンツ内のプロンプトインジェクション試行。
長いコンテキストおよびマルチモーダルのケース。
プロバイダーのタイムアウトとシミュレートされたレート制限。
構造化出力のエッジケース。
エージェントが実行するのではなく停止すべきタスク。

評価は回答品質以上の項目で行ってください。ツール選択、引数の妥当性、タスク完了、ポリシー遵守、レイテンシ、トークン、コスト、そして人間へのエスカレーション率を測定します。

割り当てられた役割に対する受け入れ基準を満たした場合にのみ、モデルを昇格させてください。より高速なモデルでも、リトライやツールのミスが増えれば、ワークフローレベルではより高コストになる可能性があります。

9. 本番の可観測性と責任分担を追加する

すべての失敗したエージェント実行は、機密情報やセンシティブなプロンプト内容を不必要に露出させることなく追跡可能であるべきです。

次のような構造化メタデータをログに記録してください。

{
  "agent_run_id": "run_…",
  "workflow": "support_resolution",
  "step": "tool_worker",
  "model_policy_version": "2026-07-27",
  "model": "APPROVED_GEMINI_MODEL",
  "route": "primary",
  "attempt": 1,
  "status": "success",
  "latency_ms": 0,
  "input_tokens": 0,
  "output_tokens": 0,
  "estimated_cost_usd": 0
}

エンドポイント、認証情報、モデルポリシー、プロンプト、ツール権限、予算、インシデント対応について責任者を割り当ててください。所有者がいなければ、ダッシュボードは制御システムではなく問題の記録簿になります。

10. 最終ローンチチェックリストを実行する

本番トラフィックが Gemini 搭載のエージェントに到達する前に、次を確認してください。

デプロイ済みランタイムが設定されたエンドポイントに到達できる。
シークレットはサーバーサイドで、スコープが限定され、ローテーション可能である。
モデル ID は 1 つのバージョン管理されたポリシーに含まれている。
すべてのツールが引数と認可を検証する。
副作用を伴うツールには、冪等性または確認制御がある。
構造化レスポンスはスキーマに対して検証される。
リトライはエージェント実行全体で上限が設定されている。
フォールバックのトリガー、互換モデル、制限が文書化されている。
使用量とコストはワークフローの各ステップに帰属付けされる。
ステップごと、実行ごと、定期的な予算が存在する。
回帰テストはツール、スキーマ、失敗、停止条件をカバーしている。
モデル変更とルーティング変更のためのロールバック経路がある。
ログには、モデル、ルート、試行回数、フォールバック理由、ポリシーのバージョンが表示される。
チームは現在の Gemini API ドキュメントと現在のモデル価格を確認済みである。

A stable integration is an operating model, not one API call

AI エージェントにとって最良の Gemini API 統合は、コード行数が最も少ないものではありません。チームが安全に監視し、変更し、ロールバックできるものです。

エンドポイントをアプリケーションの外に置き、モデルポリシーを一元化し、実際のエージェント機能をテストし、リトライに上限を設け、フォールバックを明示し、コストをワークフローステップ単位で計測します。これらの制御により、モデル更新のたびにアプリケーション移行を発生させることなく、新しいモデルを採用できます。

エージェントのロードマップに複数のモデルファミリーが含まれる場合は、Flatkey API クイックスタートから始め、価格を比較し、どの Gemini 固有機能を直接利用し続けるべきか、どの移植可能なワークロードを 1 つの安定したゲートウェイ経由で実行すべきかを判断してください。