組み込みツールと関数呼び出しを組み合わせる
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 |
placesgoogle_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 ステップを使用) |
次のステップ
- Gemini API の 関数呼び出し の詳細を確認する。
- サポートされているツールを確認する。