ジェミニ 3.8 Flashでのファンクションコーリング: call_id、反復ツールループ、そしてテスト方法

Gemini 3.8 Flashは2026年9月2日に出荷され、Googleはこのモデルを「ツールを反復的に呼び出す」ように設計しました。難しいタスクでは、すべてを一度に推測するのではなく、ツールを呼び出し、結果を確認し、必要に応じて追加の呼び出しを行います。これはエージェントにとって朗報ですが、3.7 Flash向けにツールループを調整していた場合は注意が必要です。特に重要なAPIの変更は、すべての関数結果にcall_idとnameの両方が必要なこと、そして主要な実装方法がgenerateContentからInteractions APIに移ったことです。

今すぐApidogを試す

このガイドでは、Interactions APIによる2ターンのツール呼び出し、従来のgenerateContent形式、新モデルがより多くのターンとトークンを消費する理由、毎日実行できるテスト設定を紹介します。ツールのバックエンドをモックし、2つのターンを連鎖させ、call_idのラウンドトリップをアサートします。

モデルの概要は、Gemini 3.8 Flashとは何かを参照してください。以下のフィールド名は、Googleの関数呼び出しドキュメントに基づいています。

すべてのリクエストはJSONを使ったプレーンなHTTPです。アプリケーションに組み込む前に、Apidogでリクエストを構築・デバッグできます。

Gemini 3.8 Flashの関数呼び出し概要

項目	Gemini 3.8 Flash
モデルID	gemini-3.8-flash（安定版、プレビューサフィックスなし）
主要API	Interactions API（POST /v1beta/interactions）。generateContentもレガシーAPIとして完全にサポート
ツール宣言	tools: [{"type": "function", "name", "description", "parameters"}]
モデルの呼び出し	id、name、argumentsを含むfunction_callステップ
あなたの応答	call_idとname（両方必須）、およびprevious_interaction_idを含むfunction_result
思考レベル	thinking_levelのlow / medium（デフォルト） / high。minimalは検証エラー
ツール使用スコア	Tau3-Bankingで45%。3.7 Flashより12ポイント向上（Artificial Analysis、独立機関）
トークンコスト	AAインデックスでタスクあたり約48k出力トークン。3.7 Flashより30%増加
価格	2026年12月31日まで、100万トークンあたり入力$0.75 / 出力$3.75。思考トークンは出力として課金

ステップ1：ツールを宣言する

Interactions APIでは、ツールをフラットなオブジェクトとして定義します。typeにはfunctionを指定し、name、モデルが呼び出しタイミングを判断するためのdescription、parameters配下のJSONスキーマを設定します。

説明は具体的に書きましょう。「注文IDから現在の配送状況を調べる」は適切ですが、「注文ヘルパー」では意図しないタイミングに呼び出される可能性があります。

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Where is order A1029 right now?",
    "generation_config": {"thinking_level": "low"},
    "tools": [{
      "type": "function",
      "name": "get_order_status",
      "description": "Look up the current shipping status of an order by its ID.",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    }]
  }'

この例では、単一の照会なのでthinking_levelをlowにしています。デフォルトのmediumに上げるタイミングは、思考レベルガイドで確認できます。

temperatureは設定していません。GoogleのGemini 3向けガイダンスでは、デフォルトの1.0を推奨しています。値を下げるとループの原因になる可能性があるため、ツールループでは特に注意してください。

ステップ2：function_callステップを読み取る

Interactions APIは単一メッセージではなく、インタラクションのidと実行ステップのリストを返します。ステップにはモデルの思考、ツール呼び出し、最終的なmodel_outputなどが含まれます。

モデルがツールを必要と判断すると、model_outputの代わりにfunction_callステップが返ります。

{
  "type": "function_call",
  "id": "call_8f2d...",
  "name": "get_order_status",
  "arguments": {"order_id": "A1029"}
}

必要なフィールドは次の3つです。

• id：次のターンでcall_idとして返すハンドル
• name：実行する関数名。結果でも同じ値を返す
• arguments：すでにパースされたJSON

argumentsは、ツールを実行する前に独自のルールで検証してください。モデルは宣言したスキーマには従いますが、注文IDが5文字であることまでは知りません。

同時に、レスポンス上部のインタラクションidも保存します。次のターンではprevious_interaction_idとして使用します。

ステップ3：call_idとname付きで結果を返す

関数を実行したら、inputにfunction_resultを指定して2回目のリクエストを送信します。Gemini 3.8 Flashでは、call_idとnameの両方が必須です。どちらかを省略するとリクエストは失敗します。

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "previous_interaction_id": "<interaction id from step 2>",
    "input": [{
      "type": "function_result",
      "name": "get_order_status",
      "call_id": "call_8f2d...",
      "result": [{"type": "text", "text": "{\"status\":\"in_transit\",\"eta\":\"2026-09-05\"}"}]
    }]
  }'

resultはコンテンツパートのリストです。テキストパートでは、ツール結果をJSON文字列として渡します。

previous_interaction_idが前のターンを参照するため、サーバーは元のプロンプト、ツール宣言、モデルの推論を保持しています。これらを再送する必要はありません。

2回目のレスポンスもステップのリストです。

• model_outputで終わる場合：処理完了。SDKではテキストをinteraction.output_textから取得できます。
• 別のfunction_callを含む場合：次のツールを実行し、同じループを続けます。

Pythonでは、次のような流れになります。

client.interactions.create(
    model="gemini-3.8-flash",
    input=...,
    ...
)

client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=...,
    input=[{
        "type": "function_result",
        ...
    }]
)

Python SDKの利用、APIキー、ストリーミング、トークン使用量については、Gemini 3.8 Flash APIのハウツーを参照してください。

従来のgenerateContentとの違い

既存のGeminiコードの多くは、現在もmodels/gemini-3.8-flash:generateContentを呼び出しています。GoogleはこのAPIを「完全にサポートされたまま」と説明しており、廃止日は設定していません。

用語は異なりますが、契約は同じです。

• ツール：functionDeclarationsで宣言
• モデルの呼び出し：functionCallパート
• ツール結果：functionResponseパート

従来形式では、モデルのfunctionCallパートにidが含まれます。functionResponseでは、nameとresponseに加えて、同じ値を自身のidフィールドに設定して返します。これはInteractions APIのcall_idと同じ契約で、フィールド名が異なるだけです。

GoogleのGemini 3向けガイダンスでも、IDと名前の両方が必須と明記されています。

実装上の違いは2つあります。

1. generateContentはステートレスです。会話履歴を自分で管理し、モデルのfunctionCallパートや返された思考シグネチャを含む完全なcontentsを毎ターン送信します。
2. 思考レベルはgeneration_config.thinking_levelではなく、generationConfig.thinkingConfig.thinkingLevelで設定します。

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

思考トークンはusageMetadata.thoughtsTokenCountに表示され、出力トークンとして課金されます。

新規プロジェクトで選択できる場合は、サーバーサイドで状態を管理できるInteractions APIを推奨します。履歴の再送時にシグネチャやcall_idが欠落するバグを減らせます。

3.8 Flashがツールを反復的に呼び出す理由

Googleの発表記事によると、Gemini 3.8 Flashは複雑なタスクで追加の推論ステップを実行し、ツールを反復的に呼び出します。途中で小さな推論ステップを挟み、作業結果を検証することもあります。

Googleは、長時間の実行や複雑なタスクでは意図的により多くのトークンを使用できると説明しています。

Artificial Analysisの測定では、タスクあたりの出力トークンは約48kで、3.7 Flashより30%増加しました。同じトークン単価の場合、タスクあたりのコストは次のとおりです。

• high：$0.58（3.7 Flashは$0.40）
• medium：$0.41
• low：$0.24

ツールループでは、タスクあたりのfunction_callステップが増える可能性があります。メリットとして、Artificial AnalysisのTau3-Bankingツール使用評価は45%となり、3.7 Flashから12ポイント向上しました。一方、上限のないループは以前より長く実行されます。

ループを制御する4つの方法

適用する順番は次のとおりです。

1. ハーネスに最大ターン数を設定する

タスクごとにfunction_callステップ数を数え、上限に達したら停止します。単一の照会では6〜10ターンが開始点として妥当です。エージェントコーディングでは、必要に応じて増やします。

上限に達した場合は、ツールなしの最終ターンを送信するか、ユーザーにエラーを返します。モデル自体はターン数を制限しません。

1. ルートごとにthinking_levelを選ぶ

• 単一ホップの照会：low
• 複数ステップの作業：medium（デフォルト）
• 追加検証が有効な場合：high

minimalは送信しないでください。3.8 Flashでは検証エラーになります。

1. クライアントとループの両方にタイムアウトを設定する

Geminiリクエストにはリクエスト単位のタイムアウト、ツールループにはタスク単位のウォールクロックを設定します。Artificial Analysisでは、高推論実行の平均はタスクあたり2.5分、lowでは0.8分でした。

1. ツールをべき等にする

反復モデルは同じツールを再試行する可能性があります。get_order_statusは複数回呼び出しても安全にし、返金やメール送信など副作用のある処理には確認ステップを設けてください。

追加ターンの予算を確保できない場合は、完全にサポートされている3.7 Flashを構成フラグの背後に残す方法を3.7から3.8 Flashへの移行ガイドで確認できます。

思考シグネチャ、並列呼び出し、構造化出力

思考シグネチャ

Gemini 3モデルは推論にシグネチャを付加します。保存型のInteractionsフローでは、previous_interaction_idがシグネチャを処理します。

store: falseを設定したステートレス構成やgenerateContentを使用する場合は、すべてのパートタイプについて、思考ブロックとシグネチャを受信した状態のまま正確に返送してください。トリミング、並べ替え、再シリアライズは避けます。シグネチャは不透明な値で、編集すると無効になります。

保存型とステートレス型のトレードオフは、GoogleのInteractions APIドキュメントにまとめられています。

並列呼び出し

レスポンスはリストなので、独立した複数の照会を同時に実行するため、複数のfunction_callステップが返されることがあります。

Googleの関数呼び出しドキュメントによると、Gemini 3モデルは各呼び出しに一意のIDを返します。これにより、結果を任意の順序で返せます。

同じinput配列内で、呼び出しごとに1つのfunction_resultを返してください。それぞれを固有のcall_idで対応付けます。

nameだけで照合してはいけません。同じ関数を2回呼び出した場合でも、2つの異なるcall_idが必要です。

構造化出力

3.8 Flashは、同じモデル上で構造化出力と関数呼び出しをサポートします。実装では、ループ用のツールと最終回答用のJSONスキーマを組み合わせると扱いやすくなります。

ループを終了するmodel_outputを散文ではなく機械可読形式にできるため、後続処理が安定します。設定方法はGoogleの関数呼び出しおよび構造化出力のドキュメントを参照してください。

ツールを呼び出すためだけのダミー関数を宣言し、そのargumentsを読む方法は避けてください。モデルがツール不要と判断した時点で処理が破綻します。

Googleは3.8 Flash向けにComputer use（プレビュー）も提供しています。画面操作より構造化APIが適しているケースは、Computer useと構造化APIの比較を参照してください。

Apidogでツールループをテストする

ツールループの主な破綻箇所は、ツール宣言、IDのラウンドトリップ、最終回答の3つです。Apidogを使えば、実際のバックエンドに接続せずに検証できます。

1. ツールのバックエンドをモックする

GET /orders/{order_id}エンドポイントを定義し、モックサーバーを有効にします。

固定のレスポンスボディを設定します。

{"status": "in_transit", "eta": "2026-09-05"}

毎回同じ入力になるため、モデルの最終回答の変化とデータベースの変化を切り分けられます。テスト環境ではモックURL、本番環境では実際のサービスを参照するようにハーネスを構成してください。

2. テストシナリオで2つのターンを連鎖させる

GEMINI_API_KEYを環境変数として保存し、x-goog-api-keyヘッダーから{{GEMINI_API_KEY}}として参照します。

次の3ステップでシナリオを作成します。

• ステップA：プロンプトとget_order_status宣言を使い、/v1beta/interactionsへPOSTします。インタラクションのid、function_callステップのidとname、arguments.order_idを変数に抽出します。
• ステップB：{{order_id}}を使ってモックエンドポイントへGETします。ここが「関数を実行する」ステップです。
• ステップC：call_idに{{call_id}}、nameに{{tool_name}}、previous_interaction_idに{{interaction_id}}を設定します。ステップBのボディをテキストパートとしてfunction_resultに含め、再度POSTします。

3. 重要な項目をアサートする

次の条件をテストに追加します。

• ステップAがHTTP 200を返し、typeがfunction_callで、nameがget_order_statusのステップを含む。
• arguments.order_idがA1029と一致する。これにより、モデルがプロンプトを解析し、スキーマを守ったことを確認できる。
• ステップCがHTTP 200を返し、typeがmodel_outputのステップで終了する。2回目のfunction_callがないことも確認する。
• 最終テキストにin_transitが含まれる。モデルが推測ではなくツール結果を使ったことを確認できる。
• generateContentでも同じシナリオを実行し、各thinking_levelについてusageMetadata.thoughtsTokenCountに上限を設定する。これにより、推論の増加によるコスト上昇を請求前に検出できる。

シナリオは毎日実行するようにスケジュールしてください。モデルはサイレントアップデートで挙ガイド](https://apidog.com/jp/blog/how-to-test-ai-agents-api?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation)を参照してください。[Apidogをダウンロード](https://apidog.com/download?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation)して、コストをかける前に無料ティアでシナリオを構築できます。

よくある質問

Gemini 3.8 Flashでcall_idは必須ですか？

はい。

Interactions APIでは、すべてのfunction_resultにcall_idとnameが必要です。generateContentでは、すべてのfunctionResponseに呼び出しのidとnameが必要です。

名前だけを送信する古いコードは、Gemini 3モデルでは失敗します。

3.8 Flashのツールループが3.7より多くのターンを実行するのはなぜですか？

設計によるものです。Googleは、モデルがツールを反復的に呼び出し、長時間の実行や複雑なタスクでより多くのトークンを使えると説明しています。

ハーネスでターン数を制限し、thinking_levelを下げてください。レベルごとの測定コストは、思考レベルガイドで確認できます。

関数呼び出しにgenerateContentをまだ使用できますか？

はい。GoogleはgenerateContentをレガシーと呼んでいますが、廃止日は設定しておらず、「完全にサポートされ続けている」と説明しています。

思考シグネチャを含む履歴は自分で管理し、このAPIでidと表記される呼び出しID、およびnameを適切に返してください。

thinking_levelのminimalはツールで動作しますか？

いいえ。3.8 Flashでは検証エラーになります。lowを使用してください。

ツールを多用するタスクのコストはどのくらいですか？

2026年12月31日までの料金は、100万トークンあたり入力$0.75、出力$3.75です。思考トークンは出力として課金されます。

Artificial Analysisの測定値では、タスクあたりのコストは次のとおりです。

• high：$0.58
• medium：$0.41
• low：$0.24

実際のタスクによって異なるため、トークン数をアサートして測定してください。

ループを上限付きで出荷する

Gemini 3.8 Flashの関数呼び出しで守る契約はシンプルです。

1. ツールを宣言する。
2. function_callステップを読み取る。
3. previous_interaction_idを指定し、call_idとnameの両方を含むfunction_resultを返す。

3.8 Flashで変わったのは、モデルがループを継続する意欲です。本番環境へ移行する前に、ハーネスへ次の制御を追加してください。

• ターン数の上限
• ルートごとのthinking_level
• リクエストとタスクのタイムアウト
• べき等なツール実装
• モックバックエンドによる自動テスト
• IDのラウンドトリップに対するアサーション

GoogleのWhat’s new in Gemini 3.8 Flashには移行メモがあります。モデルの詳細は、Gemini 3.8 Flashとは何かを参照してください。