組み込みツールと関数呼び出しを組み合わせる

Gemini では、ツールの呼び出しのコンテキスト履歴を保持して公開することで、組み込みツールgoogle_searchなど)と関数呼び出しカスタムツールとも呼ばれます)を 1 回のインタラクションで組み合わせることができます。組み込みツールとカスタムツールの組み合わせにより、複雑なエージェント ワークフローが可能になります。たとえば、モデルは特定のビジネス ロジックを呼び出す前に、リアルタイムのウェブデータに基づいて自己をグラウンディングできます。

組み込みツールとカスタムツールの組み合わせを有効にする例を次に示します。google_search とカスタム関数 getWeather を使用します。

Python

from google import genai

client = genai.Client()

getWeather = {
    "type": "function",
    "name": "getWeather",
    "description": "Gets the weather for a requested city.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "The city and state, e.g. Utqiaġvik, Alaska",
            },
        },
        "required": ["city"],
    },
}

# The Interactions API manages context automatically across tool calls.
# The model will first use Google Search, then call getWeather.
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the northernmost city in the United States? What's the weather like there today?",
    tools=[
        {"google_search": {}},
        getWeather,
    ],
)

# Process steps: the interaction contains search results and a function call
for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function call: {step.name} with args: {step.arguments}")
        # In a real application, you would execute the function here
        # and provide the result back to the model.

JavaScript

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const getWeather = {
    type: "function",
    name: "getWeather",
    description: "Get the weather in a given location",
    parameters: {
        type: "object",
        properties: {
            location: {
                type: "string",
                description: "The city and state, e.g. San Francisco, CA"
            }
        },
        required: ["location"]
    }
};

// The Interactions API manages context automatically across tool calls.
// The model will first use Google Search, then call getWeather.
const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is the northernmost city in the United States? What's the weather like there today?",
    tools: [
        { googleSearch: {} },
        getWeather,
    ],
});

// Process steps: the interaction contains search results and a function call
for (const step of interaction.steps) {
    if (step.type === "function_call") {
        console.log(`Function call: ${step.name} with args: ${JSON.stringify(step.arguments)}`);
        // In a real application, you would execute the function here
        // and provide the result back to the model.
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
  "model": "gemini-3-flash-preview",
  "input": "What is the northernmost city in the United States? What'\''s the weather like there today?",
  "tools": [
    { "type": "google_search" },
    {
      "type": "function",
      "name": "getWeather",
      "description": "Get the weather in a given location",
      "parameters": {
          "type": "object",
          "properties": {
              "location": {
                  "type": "string",
                  "description": "The city and state, e.g. San Francisco, CA"
              }
          },
          "required": ["location"]
      }
    }
  ]
}'

仕組み

Gemini 3 モデルは、ツール コンテキストの循環を使用して、組み込みツールとカスタムツールの組み合わせを有効にします。 ツール コンテキストの循環により、組み込みツールのコンテキストを保持して公開し、同じインタラクション内のカスタムツールと共有できます。

ツールの組み合わせを有効にする

  • 使用する組み込みツールとともに function_declarations を含めて、組み合わせ動作をトリガーします。

API が返すステップ

インタラクション レスポンスでは、API は組み込みツールの呼び出しと関数(カスタムツール)の呼び出しに対して個別のステップを返します。

  • 組み込みツールのステップ: API はこれらを自動的に管理し、 ターン間でコンテキストを保持します。
  • 関数呼び出しのステップ: API はカスタム関数に対して function_call ステップを返します。関数を実行して、結果を返します。

返されるステップの重要なフィールド

返されるステップの一部のフィールドは、ツール コンテキストを維持し、ツールの組み合わせを有効にするために重要です。

  • id: function_call ステップと function_response ステップにあります。呼び出しをレスポンスにマッピングする一意の識別子。
  • signature: thought ステップと、Gemini 3 以降のモデルのすべてのツール呼び出し(function_call など)と結果(function_response など)のステップにあります。この暗号化されたコンテキストにより、インタラクション間でツール コンテキストの循環 が可能になります。

これらのフィールドの管理:

  • ステートフル モード(推奨): previous_interaction_id を使用すると、サーバーは id フィールドと signature フィールドの両方を自動的に処理します。
  • ステートレス モード: 会話履歴を手動で管理する場合は、信頼性を検証してコンテキストを維持するために、後続のリクエストで id フィールドと signature フィールドの両方をモデルに渡す必要があります。完全なレスポンス オブジェクトを履歴に渡すと、公式 SDK がこれを自動的に処理します。

ツール固有のデータ

一部の組み込みツールは、ツールタイプに固有のユーザーに表示されるデータ引数を返します。

ツール ユーザーに表示されるツール呼び出し引数(存在する場合) ユーザーに表示されるツール レスポンス(存在する場合)
google_search queries search_suggestions
google_maps queries places
google_maps_widget_context_token
url_context urls
閲覧する URL
status: 閲覧ステータス
retrieved_url: 閲覧した URL
file_search なし なし

トークンと料金

リクエストの組み込みツールの呼び出し部分は prompt_token_count にカウントされます。これらのツールの中間ステップが表示され、返されるようになったため、会話履歴の一部となります。これは リクエストの場合のみで、レスポンスの場合は該当しません。

Google 検索ツールはこのルールの例外です。Google 検索では、クエリレベルですでに独自の料金モデルが適用されているため、トークンが二重に課金されることはありません(料金ページをご覧ください)。

詳細については、トークンページをご覧ください。

制限事項

  • ツール コンテキストの循環が有効になっている場合、デフォルトは validated モードです(auto モードは対象外です)。
  • google_search などの組み込みツールは、現在地と現在の時刻の情報に依存しています。そのため、system_instruction または function_declaration.description に競合する現在地と時刻の情報が含まれている場合、ツールの組み合わせ機能が正常に動作しない可能性があります。

サポートされるツール

標準のツール コンテキストの循環は、サーバーサイド(組み込み)ツールに適用されます。コードの実行もサーバーサイド ツールですが、コンテキストの循環には独自の組み込みソリューションがあります。コンピュータの使用と関数呼び出しはクライアントサイド ツールであり、コンテキストの循環に対する組み込みソリューションもあります。

ツール 実行側 コンテキストの循環のサポート
Google 検索 サーバーサイド サポート対象
Google マップ サーバーサイド サポート対象
URL コンテキスト サーバーサイド サポート対象
ファイル検索 サーバーサイド サポート対象
コードの実行 サーバーサイド サポート対象(組み込み、code_execution ステップと code_execution_result ステップを使用)
コンピュータの使用 クライアントサイド サポート対象(組み込み、function_call ステップと function_response ステップを使用)
カスタム関数 クライアントサイド サポート対象(組み込み、function_call ステップと function_response ステップを使用)

次のステップ