Gemini API Tool Retrievalの使い方:tool_search・defer_loading・料金体系

Gemini Interactions API(v1beta)のプレビュー機能であるTool Retrievalを、tool_searchとdefer_loadingで有効化する手順を解説します。サーバー側・クライアント側の2つの検索モードの比較、Google公式ブログとドキュメントで食い違う対応4モデルと400エラーの対処、リモートMCPやステートレス会話の制約、トークン課金と暗黙的プレフィックスキャッシュの損益分岐点まで整理しています。

目次
Gemini API Tool Retrievalの使い方:tool_search・defer_loading・料金体系

Gemini Interactions API(v1beta)でTool Retrievalがプレビュー提供され、tool_search と defer_loading を使ってツールのパラメータースキーマを必要なときだけ読み込めるようになりました。多数の独自関数やリモートMCPサーバーをGeminiに接続している開発者が対象であり、利用はInteractions APIに限定されます(generateContent は非対応です)。2026-11-20時点で試すには、ドキュメント記載の4モデル(gemini-4-hydrogen、gemini-4-argon、gemini-3.8-flash、gemini-3.6-flash)のいずれかで v1beta/interactions を呼び出し、{"type": "tool_search"} を追加したうえで、常用するツールは最初から読み込み、必要なときだけ使うツールに defer_loading: true を設定します。

最初に適切なAPIルートを選ぶ

Googleは2026年11月19日にGoogle公式ブログでTool Retrievalを発表し、AI StudioのTool retrievalドキュメントに設定手順を公開しました。この機能はInteractions APIプレビュー(v1beta)専用のため、現在利用しているエンドポイントによって即時導入できるかどうかが決まります。

ルートアカウントと提供地域課金単位Tool Retrieval対応状況選ぶ基準
公式Gemini Interactions API(v1beta)提供対象地域のGoogle AI Studio APIキー(gemini-4-argon はPaid Tier必須)入力・キャッシュ・出力それぞれ1Mトークンあたり(gemini-4-hydrogen、gemini-3.8-flash、gemini-3.6-flash はStandard Free Tier利用可)プレビュー対応(tool_search、defer_loading、リモート mcp_server)大規模なツール群を持ち、v1beta/interactions を直接呼び出せる場合
公式Gemini generateContent API同じGoogle AI Studioアカウントと提供対象地域入力・キャッシュ・出力それぞれ1Mトークンあたり非対応安定したツールが~20個未満、対応するGemini 3や2.5モデルで明示的キャッシュが必要、またはまだ移行できない場合
従量課金APIゲートウェイ(BetterTokenなど)自身で登録したBetterTokenアカウントと、コンソールで作成したAPIキー各モデルの現行課金単位に従い、従量課金残高から利用分を差し引きInteractions APIはドキュメント未記載、Tool Retrieval対応は未検証複数モデルにわたり、ドキュメント記載のネイティブGemini generateContent またはOpenAI互換Chat Completionsを使い続ける場合(モデルごとのツール対応はBetterTokenドキュメントを確認)

Interactions APIへ移行せず、標準のGemini generateContent やOpenAI互換Chat Completionsを使い続ける場合は、BetterTokenのGemini APIリファレンスを確認して、対応エンドポイントやモデルID、モデルごとのツール対応状況を把握できます。

対応モデルとGemini 4の400エラー

2026年11月19日のGoogle発表ブログでは、Tool RetrievalはすべてのGemini 4モデルを含むGemini 3.6以降のモデルで動作すると説明し、Latest Gemini modelsページへリンクしています。そのページには、gemini-4-carbon、gemini-4-neon、gemini-4-hydrogen、gemini-4-argon の4つのGemini 4モデルが掲載されています。

しかし2026-11-20現在、公式のTool retrieval対応モデル一覧に記載されているモデルIDは次の4つのみです。

  • gemini-4-hydrogen
  • gemini-4-argon
  • gemini-3.8-flash
  • gemini-3.6-flash

2026-11-20時点で、gemini-4-carbon と gemini-4-neon はTool Retrievalドキュメントには掲載されていません。非対応モデルに defer_loading を送信すると、deferred loading is not supported for this model というメッセージとともにHTTP 400 エラーが返ります。

導入検証は、GoogleがTool Retrievalのサンプル全般で使用している gemini-4-hydrogen から始めるのが確実です。Flash系モデルから移行する場合は、Gemini 4 Hydrogenの料金と移行ガイドも参照できます。ワークフローが gemini-4-carbon に依存している場合は、defer_loading を有効にする前に v1beta 上の実際の挙動を検証するか、静的なツール読み込みを維持したままGemini 4 Carbon APIの料金と移行ガイドを確認してください。

サーバー側検索とクライアント側検索の比較

Interactions APIは、排他的な2つの検索モードに対応しています。既定のサーバー側検索と、クライアント側検索(execution: "client")です。どちらも初期プロンプトからスキーマを除外しますが、遅延、実装負荷、ツール登録の方法が異なります。

比較軸静的ツール読み込みサーバー側検索クライアント側検索
スキーマがモデルに届く仕組みすべて事前に送信Geminiが遅延スキーマを必要に応じて読み込みアプリが function_result でスキーマを返却
必要な検索コード不要不要独自の検索・順位付け・絞り込み処理
ツールの事前宣言必要必要不要
リモートMCP対応対応対応(mcp_server に defer_loading: true)非該当
追加のネットワーク往復なしなし(1回のAPI呼び出し内で完結)検索1回につき1往復
適した用途~20個未満の安定したツール群規模が大きく構成が固定のツール群、または複数MCPサーバー独自レジストリ、ユーザー別権限、会話途中の動的ツール追加

1リクエストあたり宣言できる tool_search は1つだけです。サーバー側とクライアント側の tool_search を同一リクエストに混在させると、Cannot specify both client-side and server-side tool_search tools. というエラーが返ります。

サーバー側検索とリモートMCPの設定

サーバー側検索には v1beta APIバージョンが必要です。Google公式ブログのコード例では api_version が省略されていますが、公式のTool retrievalガイドではプレビュー版Tool Retrievalに v1beta が必須と明記されています。Pythonでは genai.Client(http_options={"api_version": "v1beta"})、JavaScriptでは new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } }) で初期化します。

BashでGemini APIキーを端末に表示せずに読み込み、https://generativelanguage.googleapis.com/v1beta/interactions へ POST リクエストを送信します。以下の例では、遅延読み込み対象のローカル関数(convert_currency)と、Googleがドキュメントで公開しているデモ用天気MCPサーバー(https://gemini-api-demos.uc.r.appspot.com/mcp)を組み合わせています。

read -rs GEMINI_API_KEY && export GEMINI_API_KEY

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Check the temperature in London and convert 100 USD to EUR.",
    "tools": [
      {"type": "tool_search"},
      {
        "type": "function",
        "name": "convert_currency",
        "description": "Convert an amount from one currency to another using live mid-market rates.",
        "short_description": "Convert an amount between currencies.",
        "defer_loading": true,
        "parameters": {
          "type": "object",
          "properties": {
            "amount": {"type": "number"},
            "from": {"type": "string"},
            "to": {"type": "string"}
          },
          "required": ["amount", "from", "to"]
        }
      },
      {
        "type": "mcp_server",
        "name": "weather_service",
        "url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
        "defer_loading": true
      }
    ]
  }'

tools 配列を組み立てるときは、次の4つのルールを守ります。

  • サーバー側の tool_search オブジェクトには、name、description、parameters を指定しません。
  • 遅延対象のすべての function に完全な parameters スキーマを含めます。読み込まれないスキーマには課金されません。一方、パラメーターを省いたツールは検索後に空のスキーマで返るため、モデルが呼び出せなくなります。
  • 任意の short_description は defer_loading: true と併用する場合にのみ使用し、長い description の代わりに簡潔な遅延一覧へ表示させます。
  • リモートMCPサーバーはStreamable HTTPエンドポイントのみ接続できます(SSEサーバーは非対応です)。サーバー名には - を含めず、snake_case を使用します(Remote MCPドキュメント準拠)。リモートサーバーのハンドシェイクやスキーマ検証で失敗する場合は、MCPサーバー連携のトラブルシューティングガイドを確認してください。

サーバー側レスポンスの確認方法

サーバー側検索が成功すると、同じAPI呼び出しのレスポンス内にある steps に tool_search_call と tool_search_result ステップが含まれ、その後に実際のツール呼び出しが続きます。デモサーバーの get_weather のようなリモートMCPツールの場合、APIがリモート実行まで行い、同じレスポンス内で mcp_server_tool_call と mcp_server_tool_result ステップを返します。

独自関数の実行が必要な場合は、steps 内の function_call 項目を直接確認します。Googleのドキュメントでは、function_call ステップが存在しても status が常に requires_action になるとは限らないと注意喚起しているため、status == "requires_action" だけに依存しないでください。ローカルで関数を実行し、次のターンで function_result を送信します。

クライアント側検索の設定

ツール一覧がユーザー権限や社内名前空間、あるいはセッション開始後に追加される連携先に依存する場合は、execution: "client" を使います。クライアント側の tool_search 定義では name と description の両方が必須です(どちらかを省くと 400 エラーになります)。また、そのリクエスト内のどのツールにも defer_loading を設定してはいけません。

以下のPythonコードは、実運用のレジストリを検索する代わりに固定の関数宣言を返す最小のプロトコル例です。実行結果として followup.steps から {"user_id": 123} を伴う get_billing_history の function_call ステップが出力されれば、往復フローが正しく機能しています。

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

tools = [
    {
        "type": "tool_search",
        "execution": "client",
        "name": "search_tool_registry",
        "description": "Search internal tool namespaces such as billing and support when needed.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "namespace": {"type": "string"},
            },
            "required": ["query"],
        },
    }
]

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Look up the billing history for user 123.",
    tools=tools,
)

for step in interaction.steps:
    if step.type == "function_call" and step.name == "search_tool_registry":
        # Minimal protocol example: replace with your own registry or permission filter.
        matches = [
            {
                "type": "function",
                "name": "get_billing_history",
                "description": "Retrieve billing history for a given user.",
                "parameters": {
                    "type": "object",
                    "properties": {"user_id": {"type": "integer"}},
                    "required": ["user_id"],
                },
            }
        ]
        followup = client.interactions.create(
            model="gemini-4-hydrogen",
            previous_interaction_id=interaction.id,
            tools=tools,
            input=[
                {
                    "type": "function_result",
                    "name": step.name,
                    "call_id": step.id,
                    "result": matches,
                }
            ],
        )
        for next_step in followup.steps:
            if next_step.type == "function_call":
                print(next_step.name, next_step.arguments)

function_result.result 配列には、シリアライズしたJSON文字列ではなく、JSONオブジェクトとして完全な関数宣言を格納します。あわせて検索時の function_call と一致する name と call_id を含めます。クライアント側検索で一致するツールが見つからない場合は、該当なしである旨とモデルが検索できる対象一覧を短いテキストで返し、クエリを調整できるようにします。

マルチターン状態・ステートレス再生・よくあるエラー

2ターン目以降の連携エラーの多くは、プレビュー版における次の3つの制約に起因します。

  • 毎回のリクエストで完全な tools 配列を再送する。 Interactions APIは previous_interaction_id を渡すとステップ履歴を保持しますが、リクエスト間でツール宣言までは保持しません。後続ターンでツールを省くと、未宣言のツールを見落としたり、サーバー側モードで内部の retriever: 呼び出しが出力されたりします。
  • 読み込み済みツールはアンロードできず、サーバー側検索の不一致はテキストで返る。 モデルが一度読み込んだツールのスキーマは、その会話が終わるまでコンテキストに残り続けます。また、サーバー側クエリがどの遅延ツールにも一致しない場合、構造化された検索エラーではなく通常のテキスト応答が返るため、tool_search_result で検索失敗を判定しないでください。
  • store=false の場合はステップと署名をそのまま循環させる。 ステートレスな後続リクエストでは、input に全ステップ履歴を渡し、完全な tools 配列も再送します。レスポンスのすべてのステップ(tool_search_call、tool_search_result、thought、function_call)を元の順序と signature を保ったまま変更せずに追加し、その後に新しい function_result を続けます。function_result だけを送ると検索コンテキストが失われ、400 エラーが発生します。古いSDKは tool_search_call と tool_search_result を未知のステップとして扱いフィールドを欠落させるため、これらを認識するSDKバージョンを使ってください。システム指示や他ツールの出力に名前を明記したツールは遅延対象にせず常時読み込みのままにしておかないと、モデルが検索なしで呼び出して function_result で失敗する恐れがあります。

Googleのドキュメントでは、非対応モデル、defer_loading 指定時のサーバー側 tool_search 欠落、defer_loading: true なしの short_description、クライアント側の name や description の省略、ステートレス履歴の欠落、signature 値の削除に対してHTTP 400 レスポンスが記載されています。ドキュメント記載の各エラーメッセージの原因と対処は次のとおりです。

ドキュメント記載のエラーメッセージ原因対処法
deferred loading is not supported for this model対応一覧外のモデルに defer_loading を送信したgemini-4-hydrogen、gemini-4-argon、gemini-3.8-flash、gemini-3.6-flash のいずれかへ切り替える
tool_search tool must be specified when using defer_loading.function または mcp_server に defer_loading: true があるが、リクエストに tool_search がない{"type": "tool_search"} を追加するか、defer_loading を削除する
When defer_loading is set on a FunctionDeclaration, a Tool with tool_search must also be provided in the request.関数に defer_loading: true があるが、サーバー側 tool_search がない(execution: "client" のみ宣言した、または後続リクエストで tool_search を省いた場合など)クライアント側モードでは defer_loading を外す。サーバー側モードでは {"type": "tool_search"} を含む完全な tools 配列を再送する
Cannot specify both client-side and server-side tool_search tools.サーバー側とクライアント側の tool_search を同時に指定した1リクエストにつき tool_search は1件のみ宣言する
ToolSearch name must not be specified when execution mode is SERVER_SIDE.サーバー側 tool_search に name を設定した(description と parameters でも同様のエラーが返る)該当フィールドを削除する。execution: "client" に切り替える場合は name と description の両方を設定し、全ツールから defer_loading を外す
short_description can only be set if defer_loading is truedefer_loading: true がない関数に short_description を設定したdefer_loading: true を付けるか、short_description を削除する
Server side tool call context must be circulated when using deferred loading functions.ステートレスリクエストの履歴に遅延ツールの function_result はあるが、それを読み込んだ tool_search_call と tool_search_result が含まれていないすべての tool_search_call と tool_search_result ステップを signature を含めて変更せずに返送する
Server side tool call context must be circulated ... Missing circulated context for functions: FUNCTION_NAME(全ステップ返送時にも発生)会話内の tool_search で読み込んでいない遅延関数をモデルが呼び出した(システム指示や別ツール出力に名前が出た場合が多い)名前を直接言及するツールは遅延読み込みにしない
Tool call part is missing thought_signature. / Tool response part is missing thought_signature.ステートレスリクエストで、tool_search_call(呼び出し側)または tool_search_result(応答側)の signature フィールドを省いて返送した両方の検索ステップを signature 値を保ったまま返送する

課金フィールド・プレフィックスキャッシュ・損益分岐点の試算

Tool Retrievalに追加の機能料金はかかりません。すべてのトークンはGemini APIの料金ページにある通常の入力・キャッシュ・出力単価で課金されます。2026-11-20時点で、gemini-4-hydrogen のPaid Tier単価は1Mトークンあたり入力$1.50、キャッシュ入力$0.075、出力(思考トークンを含む)$7.50です。gemini-4-hydrogen、gemini-3.8-flash、gemini-3.6-flash ではStandard Free Tierが利用できます。一方、gemini-4-argon はPaid Tier専用で、2026年11月30日までは1Mトークンあたり入力$2.00・キャッシュ$0.10・出力$10.00ですが、2026年12月1日からは$4.00 / $0.20 / $20.00に引き上げられます。

トークン消費量を把握するには、各レスポンスの usage に含まれる5つのフィールドを確認します。

  • total_input_tokens:リクエスト内での最初のモデル呼び出しのプロンプト全体。入力テキスト、会話履歴、システム指示、遅延しないツールのスキーマ、固定長の tool_search 指示ブロック、および遅延ツールの1行一覧(name と short_description、または description の1文目で、Googleの初期テストでは遅延ツール1件あたり約26トークン)が含まれます。
  • total_tool_use_tokens:サーバー側ツールの実行後(各サーバー側ツール検索を含む)にAPIが同一リクエスト内で追加実行するモデル呼び出しのプロンプト合計。毎回フルコンテキストと新たに読み込んだスキーマを再送信し、入力単価で課金されます。1ターン内で複数回検索すると、その回数だけパスが増えます。
  • total_cached_tokens:暗黙的キャッシュから提供されたプロンプト部分。通常入力単価ではなくキャッシュ単価で課金されます。
  • total_output_tokens:生成された応答トークン。出力単価で課金されます。
  • total_thought_tokens:生成された思考トークン。出力単価で課金されます。

プレフィックスキャッシュの最小トークン閾値に注意

Context cachingドキュメントによると、Interactions APIが対応するのは暗黙的キャッシュのみで、明示的キャッシュはInteractions APIおよびGemini 4モデルでは利用できません。取得したスキーマはプロンプト冒頭ではなくモデルが読み込んだ位置に追加されるため、システム指示やツール一覧、過去のターンはターンをまたいで変化しないプレフィックスとして維持されます。このプレフィックスがモデルの最小キャッシュ可能サイズを超えると、各サーバー側検索で発生する追加モデル呼び出しも含め、後続リクエストが暗黙的キャッシュにヒットする場合があります。実際にキャッシュから処理されたトークン数は total_cached_tokens で確認できます。

ただし2026-11-20現在、Tool Retrieval対応の4モデルはすべて暗黙的キャッシュに最低 4,096入力トークン を必要とします。完全なツールスキーマを含めていたからこそ4,096トークンを超えていたプロンプトの場合、ツールを遅延読み込みにすると最小サイズを下回り、キャッシュが効かなくなる可能性があります。また、Gemini 4モデルのマルチターンやエージェントループでは、新しいリクエストが少なくとも2,050トークンを追加した場合にのみ前回リクエスト全体がキャッシュされます(モデル出力、思考、関数結果はいずれもこの追加総量に計上されます)。追加分が2,050トークン未満の場合、前回リクエスト末尾の2,050トークンが通常の入力単価で再処理されます。

Tool Retrievalでトークンが減るケースと増えるケース

Googleのドキュメントでは、400トークンのツールを2つ読み込み、1回目のリクエストで function_call を返して2回目で function_result を渡す2リクエスト構成の例示試算(丸め値、出力トークンとキャッシュ除外)が示されています。

例示シナリオ(Googleドキュメント試算)静的読み込み(入力トークン)Tool Retrieval(入力+ツール利用トークン)差し引き結果
ツール200個(各400トークン)、コンテキスト2,000トークン2 × (2,000 + 80,000) = 164,000リクエスト1:7,350 + 検索パス 8,150、リクエスト2:8,150 = ~23,650入力側トークンを~86%削減
ツール10個(各400トークン)、コンテキスト30,000トークン2 × (30,000 + 4,000) = 68,000リクエスト1:30,410 + 検索パス 31,210、リクエスト2:31,210 = ~92,830入力側トークンが~37%増加

ツールの遅延読み込みが効果を発揮するのは、ツール群が大きく、ほとんどのターンで使うツールがごく一部にとどまる場合です。ツール数が少ない場合や、長い会話で毎ターンのように検索が走る場合は、サーバー側検索の追加パス(total_tool_use_tokens)のコストが削減分を上回る可能性があります。使用頻度の高いツールは最初から読み込み、頻度の低いロングテール群だけを遅延対象にしたうえで、全面導入前に実際のトラフィックで total_input_tokens、total_tool_use_tokens、total_cached_tokens と実際の請求額を計測してください。

LLM ワークフローを最適化しませんか?

単一 API でモデルを接続し、キーと AI コストを管理できます。

無料で始める