Gemini 3.5 Flash のデベロッパー ガイド

Gemini 3.5 Flash は、Gemini 3 ファミリーの高速で費用対効果の高い強力なモデルです。パフォーマンスや価値を損なうことなく、プロに近いエージェント機能を実現するように設計されたこのモデルは、Gemini API を使用するデベロッパーと、Gemini Enterprise Agent Platform を使用する企業向けに一般提供（GA）されています。

このドキュメントでは、3.5 Flash の新機能、使用するタイミング、3.5 Flash への移行方法について説明し、3.5 Flash のクイックスタートを提供します。

Gemini ファミリーにおける位置付け

次の表は、3.5 Flash、3.1 Pro、3.1 Flash-Lite の仕様の一部を比較したものです。

サポートされている機能、ツール、使用オプションの完全なリストについては、3.5 Flash モデルのページをご覧ください。

ユースケースの内訳

Agentic Workflows に推奨される戦略では、階層型アプローチを使用して品質、速度、費用を最適化します。

• Gemini Pro: 初期ルートの計画、複雑な問題解決、難しいコーディング、重要な意思決定など、深い推論が必要となる複雑な認知タスク用に予約します。
• Gemini Flash: 実行タスク、ツール呼び出し、中間推論ステップの主要な「主力」として使用し、パフォーマンスと効率の最適なバランスを実現します。
• Gemini Flash-Lite: 速度と費用が最優先される、大量の低レイテンシのプリプロセス タスクと構造タスク（インテント ルーティング、データ抽出、タグ付け、分類など）にデプロイします。

Gemini 3.5 Flash の新機能

Gemini 3.5 Flash では、Gemini モデルのラインナップに次の変更と改善が加えられています。

• 持続的な最先端のパフォーマンス: 大規模なエージェント タスクとコーディング タスクに最適化された、Google の最もインテリジェントな Flash モデル。
• エージェントによる実行: サブエージェントのデプロイ、問題解決、大規模な高速エージェント ループ。
• コーディングの改善: 反復的なコーディング サイクル、迅速な探索、プロトタイピングにより、代替パスをテストし、ソリューションを動的に探索します。
• 長期: マルチステップ ワークフローとツールを大規模に使用します。
• 思考の保持: モデルは、マルチターンの会話全体で中間推論を自動的に保持します。API の変更は不要です。
• 新しいデフォルトの思考レベル: デフォルトの思考レベルが HIGH から MEDIUM に変更されました。
• LOW の思考の改善: 少ないステップで済むコードタスクとエージェント タスクの思考レベルが大幅に改善され、低いレイテンシとコストで高い品質を実現します。

詳しくは、主な変更点をご覧ください。

クイックスタート

始める前に、アプリケーションのデフォルト認証情報（ADC）または API キーを使用して Agent Platform に対する認証を行う必要があります。詳細については、Gemini Enterprise Agent Platform を使ってみるをご覧ください。

次のコードブロックで、PROJECT_ID はプロジェクト ID に置き換えます。

インストール

最新の google-genai SDK を使用していることを確認します。

pip install --upgrade google-genai

基本的なリクエスト

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
  model="gemini-3.5-flash",
  contents="How does AI work?",
)
print(response.text)

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

主な変更点

このセクションでは、Gemini 3.5 Flash で導入された次の変更について詳しく説明します。

• 新しいデフォルトの思考レベル（MEDIUM）
• 思考の保持
• 非推奨: サンプリング パラメータ
• 非推奨: thinking_budget

新しいデフォルトの思考レベル

Gemini 3 モデルのデフォルトの思考レベルが MEDIUM になりました。これは、Gemini 3 Flash のプレビュー版の HIGH から変更されたものです。思考レベル MEDIUM は、幅広いタスクで優れた結果をもたらし、高速で費用対効果も高くなります。

サポートされている思考レベルは次のとおりです。

• MINIMAL: ほとんどのクエリで「思考なし」の設定と一致します。モデルは、コーディングなどの複雑なタスクに対して、最小限の思考しか行わない場合があります。チャット アプリケーションや高スループット アプリケーションのレイテンシを最小限に抑えます。
• LOW: ほとんどのタスクで高速かつ低コストの軽量な推論。
• MEDIUM: （デフォルト）推論を必要とするほとんどのタスクに適したバランス重視の設定。
• HIGH: 推論を最大化して、タスクのパフォーマンスを最適化します。モデルが最初のトークンを生成するまでに MEDIUM 設定よりも時間がかかることがありますが、出力はより徹底的になります。

たとえば、モデルが複数のステップで推論する必要がある論理パズル、数学の文章問題、トリッキーなシナリオには HIGH を使用します。

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="A farmer has chickens and rabbits. There are 35 heads and 94 legs. How many chickens and how many rabbits does he have? Show your step-by-step logic.",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH
       )
   ),
)
print(response.text)

thinking_level パラメータは省略可能です。省略した場合、3.5 Flash はデフォルト設定（MEDIUM）を使用します。

思考の保持

モデルは、マルチターンの会話全体で中間推論を自動的に維持します。会話履歴に存在する場合、推論コンテキストは自動的に引き継がれ、反復的なデバッグやコードのリファクタリングなどの複雑な複数ステップのタスクのパフォーマンスが向上します。API の変更は不要です。

以前のターンの考えがデフォルトで保持されるようになりました。サービスは、会話コンテキストをモデルに渡す前に、会話コンテキストから思考履歴をクリアしなくなりました。

会話履歴を送信する場合は、前のターンと一貫性を持たせてください。コンテキスト全体（思考、関数呼び出し、レスポンス）を含めるか、完全に省略します。コンテキストが部分的であると、モデルのパフォーマンスが低下する可能性があります。

非推奨: サンプリング パラメータ

次のサンプリング パラメータは、Gemini 3 モデルでは推奨されなくなりました。

• temperature
• top_p
• top_k

モデルは最適な結果を得るために独自のサンプリングを管理します。すべてのリクエストからこれらのパラメータを削除します。決定論を確保するには、特定のユースケースの明示的なルールを含むシステム指示を定義します。

非推奨: thinking_budget

すべての Gemini 3 モデルで、未加工の数値 thinking_budget パラメータがサポートされなくなりました。代わりに thinking_level 文字列列挙型を使用してください。

# ⚠️ Before (not recommended)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="MEDIUM")
)

ベスト プラクティス

このセクションでは、3.5 Flash を使用する際の次のベスト プラクティスについて説明します。

• 関数呼び出しに厳密なレスポンス マッチングを使用する
• 関数レスポンス parts にマルチモーダル コンテンツを含める
• 関数レスポンスでインライン指示を使用する
• 不要なツール呼び出しを減らす

関数呼び出しに厳密なレスポンス一致を使用する

レスポンスが一致しない場合、ほとんどの場合、モデルは finish_reason: STOP の空のレスポンスを返します。常に次の規則に従ってください。

• id を含める: すべての FunctionResponse には、対応する FunctionCall の id を含める必要があります。
• name の一致: レスポンスの name は、呼び出しの name と一致する必要があります。
• 一致数: 受信した FunctionCall ごとに 1 つの FunctionResponse を返します。

次のコードは、正しい関数呼び出しの例です。

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

関数レスポンス parts にマルチモーダル コンテンツを含める

関数レスポンスの外部で画像を提供すると、思考の漏洩などの予期しないモデルの動作が発生し、品質が低下する可能性があります。関数呼び出しの概要に記載されている推奨事項に沿って、モデルに送信する関数レスポンス部分にマルチモーダル コンテンツを含めます。モデルは、次のターンでこのマルチモーダル コンテンツを処理して、より多くの情報に基づいたレスポンスを生成できます。

次に例を示します。

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

関数レスポンスでインライン指示を使用する

プラットフォームの手順を関数レスポンスとともに後続の parts として提供すると、思考の漏洩などの予期しないモデルの動作が発生し、品質が低下する可能性があります。代わりに、2 つの改行で区切って関数レスポンス テキストの末尾に追加します。

次に例を示します。

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

不要なツール呼び出しを減らす

ツール呼び出しの過剰な使用が発生した場合は、次の 2 つの手法で最小限に抑えることができます。

1. 思考レベルを下げる: 思考レベルが高いほど、モデルはより多くのツールを使用して探索と検証を行うため、レベルを下げることでツール呼び出しを減らすことができます。

2. システム指示を追加する: 思考レベルを調整しても過剰な使用が続く場合は、ツールの使用を制限するプロンプトを検討してください。次に例を示します。

   You have a limited action budget of <n> tool calls. Use them efficiently.
   

3.5 Flash または 3.1 Pro から 3.6 Flash に移行する

3.5 Flash または 3.1 Pro から 3.6 Flash に移行するには、次の操作を行います。

1. モデル ID を更新する: API 呼び出しのモデル文字列を gemini-3.6-flash に変更します。
2. 新しい Gemini 3 ファミリーの API ルールに合わせてコードを調整する: Gemini 3.6 Flash は、Gemini 3 ファミリー全体で確立されたパラメータ ルールと API 規約を厳密に適用します。
   • 温度、Top-K、Top-P を削除する: これらのカスタム パラメータをペイロードから削除します。エラーは発生しませんが、モデルはそれらを完全に無視します。代わりに、thinking_level パラメータまたは json_schema 構造化出力を使用して、出力の決定性を制御します。
   • 頻度ペナルティとプレゼンス ペナルティを削除する: 頻度ペナルティまたはプレゼンス ペナルティのカスタム構成を削除して、API 呼び出しでランタイム エラーが発生しないようにします。
   • チャット統合でモデルの事前入力が試行されないようにする: メッセージの履歴配列を確認して、API ペイロードが空のユーザー ターンまたはモデルターンで終わっていないことを確認します。履歴配列の最後のオブジェクトが「model」ロール（GenerateContent API）または「model_output」タイプ（Interactions API）である場合は、厳密な検証エラーが発生しないようにシーケンスを再構築します。
   • thinking_level を使用: 非推奨の thinking_budget パラメータのインスタンスを削除し、代わりに thinking_level を使用します。
   • 厳密な関数呼び出し規約を適用する: FunctionResponse は、前の FunctionCall の id、name、実行回数と厳密に一致する必要があります。インラインの指示を追加する必要がある場合は、関数レスポンス テキストの内部に直接配置し、2 つの改行（\n\n）で区切ります。
3. ワークフローのシフトを考慮する:
   • アプリケーションが複数ターンの会話ループに依存している場合は、ワークフローをテストして、モデルの新しいステップの簡潔さが早期終了を引き起こさないことを確認します。
   • フロントエンド エージェントまたは基本的なスクリプト エージェントを構築する場合は、モデルの事前プログラマティック検査に対する新しいバイアスにより、不要な探索的 execute_code 呼び出しが発生していないかモニタリングします。

ツール前のテキスト要件の回避策

プロンプトで、ツール呼び出しを行う直前にモデルが構造化テキスト（XLM、YAML、JSON など）（<UPDATE>...</UPDATE> など）を出力する必要がある場合、ツール呼び出しが Malformed_Function_Call エラーで失敗することがあります。この問題を解決するには、次のいずれかの回避策を使用します。

• （推奨）モデルに、ツール前のメモを未加工のテキストではなく、専用の update() 関数呼び出し内に配置するように指示します。実装の詳細な手順については、次のセクションをご覧ください。
• 構造化テキストではなく、マークダウン ヘッダー（# UPDATE、## PLAN など）としてメモを作成するようにモデルに指示します。
• ツール呼び出しの前にモデルがテキストを出力することを要求しないでください。

推奨される解決策: 作業メモを専用の関数呼び出しでラップする

元の手順の代わりに、次の手順を行います。

Before calling a tool, in every response you MUST first output a single
`<UPDATE>` part as specified, don't skip this part or any of required sub-tags
within `<UPDATE>`.

更新された次の手順を使用します。

Before calling any other tool, in every response you MUST first call `update`
with all required parameters (previous_step, plan, next_step, external).

お客様のリクエストで古い <UPDATE> XML 形式へのすべての参照を更新します。次に、更新関数に対応する関数宣言を追加します。

{
  "name": "update",
  "description": "Update working notes (previous step analysis, plan, next step, external note).",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {
        "type": "STRING",
        "description": "Key findings and outcomes since the previous step."
      },
      "plan": {
        "type": "STRING",
        "description": "The current status of the plan."
      },
      "next_step": {
        "type": "STRING",
        "description": "Brief explanation of the immediate next action according to the plan."
      },
      "external": {
        "type": "STRING",
        "description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
      }
    },
    "required": [
      "previous_step",
      "plan",
      "next_step",
      "external"
    ]
  }
}

モデルは同じステップで 2 つの呼び出しを行います。構造化された XML を置き換える update() 呼び出しと、実行する実際の関数呼び出しです。

参考情報

• Gemini 3.5 Flash モデルのページ
• 入門ノートブック