重要なポイント

• Gemini 3.5 Flashで最も高くつくミスは、構文エラーではなく、気づきにくいデフォルト設定です。

• 多くのコーディングエージェントでは、low は人々が思っている以上に適したデフォルトです。

• GitHub Copilotを介した重いエージェントループは、14倍の課金係数によって大幅に高額になる可能性があります。

• We0 AIでは、モデル選択はワークフローの一部にすぎません。残りは、製品がどのように説明され、提示され、発見されるかです。

Gemini 3.5 Flash 開発者ガイド：3つのAPIトラップと実用的なMCPエージェント

gemini-3.5-flash は簡単に呼び出せそうに見えます。

だからこそ、過小評価しやすいのです。プレビュー時代のコードから少し移行しただけでも、目に見えるエラーを一切出さないまま、出力品質の低下、異なるコスト特性、より高額なマルチターンループを引き起こす可能性があります。

このガイドでは、特に重要な3つのトラップ、それを回避するコードの形、そしてすぐに応用できる実用的なMCPスタイルのエージェントループに焦点を当てます。

トラップ1：thinking_level のデフォルトが High から Medium に下がった

これは何もクラッシュしないため危険です。

古いコードを移植してもリクエストはそのまま返ってきますが、モデルはもはや想定していた推論レベルでは動いていません。

旧来と新しいメンタルモデルの比較

値

役割

使用する場面

minimal

最小限の推論

オートコンプリート、分類、単発の補完

low

コードおよびエージェント的タスク向けに再調整

コーディングエージェント、MCPツールループ、複数ステップのワークフロー

medium

新しいデフォルト — バランス型

一般向けチャット、一般的なQ&A

high

最大限の推論努力

高度な推論、新しい問題のデバッグ、数学、計画立案

ありがちなミス

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=prompt,
)

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=prompt,
)

2つ目のスニペットは動作しますが、デフォルト設定はもはや同じではありません。

より安全な移行方法

from google import genai
import os

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=prompt,
    config={
        "thinking_config": {
            "thinking_level": "high"  # or "low" for coding agents
        }
    },
)

直感に反する推奨事項

多くのコーディングエージェントのワークフローでは、high ではなく low から始めてください。

実務上の理由はシンプルです：

• より高速

• より低コスト

• ツール中心のコーディングループでは、しばしば十分に良い、または同等の性能になる

トラップ2：GitHub CopilotはGemini 3.5 Flashを14倍で課金する

これはこの記事で最もコストの高いトラップです。

問題はモデルの定価ではありません。GitHub Copilot内のプレミアムリクエスト倍率です。Flashがエージェント的に使われるようになると、コスト構造は急速に変化します。

そのため、多くのチームは経路を分けています：

• 軽量な対話型利用はCopilot内にとどめる

• 重いループやバッチ型ワークフローは直接API経由で処理する

アーキテクチャそのものがコスト管理になります。

トラップ3：思考保持によりマルチターンのトークン料金が自動的に膨らむ

Gemini 3.5 Flashは、ターンをまたいで内部推論を引き継ぎます。

これにより一貫性は向上しますが、その思考が後続ターンのトークン計算に含まれ続ける可能性もあります。

長いエージェントループでは、これによってトークン使用量が大幅に増えることがあります。

実用的な対策

• 明確なフェーズの区切りでチャットをリセットする

• 重要なことだけを要約して引き継ぐ

• 安定した指示やツール定義にはプロンプトキャッシュを使う

• 時間の経過とともに、thoughtsトークンとpromptトークンの比率を監視する

Gemini 3.5 Flashで動作するMCPエージェント

元記事には非常に有用なエンドツーエンドのパターンが含まれています。1つのファイル読み取りツール、1つのURL取得ツール、標準的な関数宣言の形式、そしてツールの応答をモデルに返すループです。

ツール定義

import os
import httpx
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

read_file = types.FunctionDeclaration(
    name="read_file",
    description="Read a local file and return its contents as text.",
    parameters={
        "type": "object",
        "properties": {
            "path": {
                "type": "string",
                "description": "Absolute path to the file"
            }
        },
        "required": ["path"],
    },
)

fetch_url = types.FunctionDeclaration(
    name="fetch_url",
    description="Fetch a URL and return the response body as text.",
    parameters={
        "type": "object",
        "properties": {
            "url": {
                "type": "string",
                "description": "Fully-qualified URL"
            }
        },
        "required": ["url"],
    },
)

エージェントループのパターン

tools = types.Tool(function_declarations=[read_file, fetch_url])

def execute_tool(call):
    if call.name == "read_file":
        return Path(call.args["path"]).read_text(encoding="utf-8")
    if call.name == "fetch_url":
        return httpx.get(call.args["url"], timeout=15).text[:50000]
    raise ValueError(f"Unknown tool: {call.name}")

def run_agent(task: str, max_turns: int = 8):
    history = [types.Content(role="user", parts=[types.Part(text=task)])]

    for _ in range(max_turns):
        response = client.models.generate_content(
            model="gemini-3.5-flash",
            contents=history,
            config=types.GenerateContentConfig(
                tools=[tools],
                thinking_config=types.ThinkingConfig(thinking_level="low"),
            ),
        )

        if not response.function_calls:
            return response.text

        history.append(response.candidates[0].content)
        tool_results = []
        for call in response.function_calls:
            result = execute_tool(call)
            tool_results.append(
                types.Part(
                    function_response=types.FunctionResponse(
                        id=call.id,
                        name=call.name,
                        response={"result": result},
                    )
                )
            )
        history.append(types.Content(role="tool", parts=tool_results))

小さいながらも非常に重要な移行ルールは、関数レスポンスが元の呼び出しの id と name の両方に一致している必要があるということです。

代わりに Antigravity を使うべきタイミング

プロトタイプであれば、ツールループを手作業で構築しても問題ありません。ですが本番環境では、オーケストレーション、キャッシュ、ルーティング、リトライ、可観測性をすぐに自前で作り直すことになります。

だからこそ、より重要な問いは単に「このモデルを組み込めるか」ではなく、「自分でどれだけのエージェント基盤を抱えることになるのか」です。

クイック移行チェックリスト

gemini-3-flash-preview から gemini-3.5-flash に移行する場合は、次の項目を明示的に確認してください。

• モデル ID を慎重に置き換える

• thinking_level を意図して設定する

• 評価で正当化されない限り、古いサンプリング上書きを削除する

ツールレスポンス内の id と name を一致させる

• response.usage_metadata.thoughts_token_count を確認する

• 依存している未サポート API がまだある場合は preview を維持する

• 移行前後で評価を実行する

• Copilot の課金計測を直接 API コストと比較する

Gemini 3.5 Flash を自分のツールで試す

目的が単なるプロンプトのテストではなく、ファイル、リポジトリ、API、ドキュメント、エージェントワークフローをまとめて接続することであれば、通常は生のモデルエンドポイントだけでは足りません。

We0 AI では、その同じ原則をさらに一歩進めています。エージェントワークフローは作業の半分にすぎません。残りは、ドキュメント、FAQ、製品ページ、ショーケースコンテンツ、SEO / GEO の接点を通じて、プロダクトを理解しやすく、検索されやすく、推奨されやすく、コンバージョンしやすくすることです。

FAQ

Python から Gemini 3.5 Flash を呼び出すには？

呼び出し自体は短く書けます。重要なのは、移行によって出力品質が気づかないうちに低下しないよう、thinking_level を明示的に設定することです。

thinking_level の値には何がありますか？

• minimal はごく軽いタスク向け

• low はコーディングとエージェント型ワークフロー向け

• medium はコンシューマー向けの標準的なデフォルト

• high はより難しい推論と深い計画向け

なぜ Gemini 3.5 Flash は GitHub Copilot 内だとコストが高くなるのですか？

課金倍率によって経済性が変わるからです。エージェントの重い利用では、ベースモデルの価格以上に、それがコスト全体を左右することがあります。

思考保持とは何ですか？

これは、モデルが内部推論をターンをまたいで引き継ぐことです。マルチターンでの一貫性向上に役立ちますが、その一方で、時間とともにトークンコストが増加する可能性も高まります。

Gemini 3.5 Flash は MCP に適していますか？

はい。特に、ツールのスキーマ、レスポンスのマッチング、thinking_level、およびトークン予算が注意深く扱われている場合はそうです。