Gemini 3.8 Flashは2026年9月2日に出荷され、Googleはこれを「ツールを反復的に呼び出す」ように構築しました。つまり、難しいタスクでは、すべてを一発で推測するのではなく、呼び出しを行い、結果を確認し、さらに別の呼び出しを行います。これはエージェントにとって朗報であり、3.7 Flash向けにツールループを調整していた人々にとっては新たな頭痛の種となります。何よりも重要なAPIの詳細は2つあります。すべての関数結果にはcall_idとnameの両方が含まれている必要があり、ループを実行する主要な方法は、generateContentではなく、Interactions APIになりました。
このガイドでは、Interactions APIでの2ターンフロー全体を説明し、おそらくまだ実行しているであろう従来のgenerateContentの形式を示し、新しいモデルがツールにより多くのターンとトークンを費やす理由を解説し、毎日実行できるテスト設定で締めくくります。具体的には、ツールのバックエンドをモックし、両方のターンを連鎖させ、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はレガシーだが完全にサポート |
| ツール宣言 | 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では、ツールはフラットなオブジェクトです。functionという`type`、`name`、モデルがいつ呼び出すべきかを判断するために読み取る`description`、そして`parameters`の下にJSONスキーマがあります。説明は具体的に記述してください。「注文IDによる現在の配送状況を調べる」という説明は適切なタイミングで呼び出されますが、「注文ヘルパー」という説明はランダムに呼び出される可能性があります。
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-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"]
}
}]
}'
このリクエストには2つの意図的な選択があります。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なので、何かを実行する前に独自のルールに対して検証してください。モデルはあなたが宣言した形式で入力しますが、あなたの注文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-api-key: $GEMINI_API_KEY" \
-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`が以前のターンを指しているため、サーバーはすでに元のプロンプト、ツール宣言、およびモデルの推論を保持しています。これらを再送する必要はありません。応答は別のステップリストです。それがmodel_outputで終わる場合、あなたは完了であり、SDKはテキストを`interaction.output_text`として公開します。もしそれが別の`function_call`を保持している場合、ステップ2に戻ります。このループが全体のパターンです。
Pythonでは、フローはclient.interactions.create(model="gemini-3.8-flash", input=..., ...)であり、同じJSONフィールドをキーワード引数として渡し、次に`previous_interaction_id`と`function_result`リストを`input`として2回目の`create`を行います。もしこのエンドポイントが初めてである場合は、Gemini 3.8 Flash APIのハウツーでキー、ストリーミング、およびトークン使用量の読み取りについて説明されています。
従来のgenerateContentの同等機能
既存のGeminiコードのほとんどはまだmodels/gemini-3.8-flash:generateContentを呼び出しており、Googleはこれが「完全にサポートされたまま」であり、廃止日は設定されていないと述べています。語彙は異なりますが、ルールは同じです。ツールは`functionDeclarations`の下で宣言され、モデルは`functionCall`部分で応答し、あなたは`functionResponse`部分で回答します。従来の形式では、モデルの`functionCall`部分に`id`が含まれ、あなたの`functionResponse`部分はその自身の`id`フィールドで、`name`と`response`とともに同じ値をエコーバックする必要があります。これはInteractions APIの`call_id`と同じ契約であり、異なるフィールド名を使用しているだけです。GoogleのGemini 3のガイダンスでは、idとnameの両方が必須であることが明示されています。
2つの実用的な違いがあります。まず、`generateContent`はステートレスなので、会話を自分で管理します。つまり、モデルの`functionCall`部分や返された思考シグネチャを含む完全な`contents`履歴が毎ターン送り返されます。次に、思考は`generation_config.thinking_level`ではなく`generationConfig.thinkingConfig.thinkingLevel`の下で構成されます。
{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}
思考トークンは応答のusageMetadata.thoughtsTokenCountとして表示され、出力として課金されます。新しいプロジェクトで2つのAPIのどちらかを選択する場合、Interactionsを選んでください。サーバーサイドの状態管理により、再送された履歴にシグネチャやcall_idが欠落しているといった種類のバグが解消されます。
3.8 Flashがツールを反復的に呼び出す理由と、ループを制限する方法
Googleの発表記事によると、このモデルは「より懸命に働く」とされています。複雑なタスクでは、「追加の推論ステップを実行し、ツールを反復的に呼び出し」、途中で「より小さな推論ステップ」を踏んでその作業を検証します。Googleはまた、このモデルが「長時間の実行や複雑なタスクにおいて、意図的に多くのトークンを使用できる」と述べています。Artificial Analysisは、その効果を測定しました。彼らのインデックスでは、タスクあたり約48kの出力トークンを使用し、3.7 Flashと比較して30%増加しています。同じトークン単価で、highでのタスクあたりのコストは0.58ドルに対し、3.7 Flashでは0.40ドルでした。Mediumは0.41ドル、lowは0.24ドルでした。
ツールループの場合、これはタスクあたりのfunction_callステップが増えることを意味します。利点は明らかで、AAのツール使用評価であるTau3-Bankingは12ポイント上昇して45%になりました。欠点は、上限のないループが8月よりも長く実行されるようになったことです。適用する順序での4つの制御策は次のとおりです。
- ハーネス内の最大ターン数。タスクあたりの
function_callステップ数を数え、選択した制限で停止させます。ルックアップの場合は6～10が妥当な開始範囲で、エージェントコーディングの場合はそれ以上です。制限に達したら、ツールなしで最終ターンを送信するか、ユーザーにエラーを返します。モデル自体は制限しません。 - ルートごとの
thinking_level。ルックアップや単一ホップのツールにはlow、複数ステップの作業にはmedium（デフォルト）、追加の検証が有効な場合にのみhighを使用します。`minimal`は送信しないでください。3.8 Flashは検証エラーを返します。 - 両側でのタイムアウト。Gemini呼び出しにはリクエストごとのタイムアウトを、ループにはタスクごとのウォールクロックを設定します。AAの高推論実行は、タスクあたり平均2.5分、lowでは0.8分でした。
- べき等なツール。反復モデルは再試行します。`get_order_status`は2回呼び出しても安全なようにし、副作用のあるもの（返金、送信など）は確認ステップを必要とするようにします。
もし予算が追加のターンを吸収できない場合、3.7から3.8 Flashへの移行ガイドでは、完全にサポートされ続けている3.7 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. テストシナリオで両方のターンを連鎖させます。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は200を返し、
typeがfunction_callであり、nameがget_order_statusに等しいステップを含んでいます。 - 抽出された
arguments.order_idがA1029と等しいことで、モデルがプロンプトを解析し、スキーマを尊重したことが証明されます。 - ステップCは200を返し、
typeがmodel_outputであり、2番目のfunction_callがないステップで終了します。これは、送信したcall_idとnameが受け入れられ、ループが1ラウンドで完了したことを証明します。 - 最終テキストに
in_transitが含まれていることで、モデルが自身の推測ではなくツール結果を使用したことが証明されます。 - 同じシナリオを
generateContentに対して実行する場合、thinking_levelごとにusageMetadata.thoughtsTokenCountに上限を追加します。これにより、「より懸命に働く」ことによるコスト増加が請求書に届く前に捕捉されます。
シナリオを毎日実行するようにスケジュールしてください。モデルの挙動はサイレントアップデートによって変化し、先週1ラウンドで完了したループが2ラウンド必要になることがあります。AIエージェントAPIテストガイドでは、多段階アサーションについて詳しく説明しています。Apidogをダウンロードして、費用をかける前に無料ティアでシナリオを構築できます。
よくある質問
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はこれをレガシーと呼んでいますが、廃止日は設定されておらず「完全にサポートされ続けている」と述べています。思考シグネチャを含め、履歴は自分で管理し、呼び出しID（このAPIでは`id`と表記）と`name`も引き続き適用されます。
thinking_levelの「minimal」はツールで動作しますか？ いいえ。3.8 Flashでは検証エラーを返します。lowを使用してください。
ツールを多用するタスクのコストはどのくらいですか？ 2026年12月31日までのトークンごとの料金は、入力100万トークンあたり0.75ドル、出力100万トークンあたり3.75ドルで、思考は出力として課金されます。Artificial Analysisは、彼らのインデックスで、highでタスクあたり0.58ドル、mediumで0.41ドル、lowで0.24ドルと測定しました。あなたのタスクは異なるため、トークン数をアサートして測定してください。
ループを上限付きで出荷する
ツールを宣言し、function_callステップを読み取り、previous_interaction_idの下にcall_idとnameの両方を含むfunction_resultを返します。これが全体の契約です。Gemini 3.8 Flashで変わったのは、モデルのループ実行意欲です。そのため、ハーネスは本番環境に移行する前に、ターン制限、ルートごとのthinking_level、およびタイムアウトが必要です。バックエンドをモックし、2つのターンを連鎖させ、IDのラウンドトリップをアサートし、実行をスケジュールしてください。GoogleのWhat’s new in Gemini 3.8 Flashページには移行メモがあり、柱となるガイドにはモデルに関するその他のすべてが記載されています。