Repository Public
1# Combine built-in tools and function calling23> [!NOTE]4> **Note** : This version of the page covers the new [Interactions API](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview), which is currently in Beta. 5> For stable production deployments, we recommend you continue to use the `generateContent` API. You can use the toggle on this page to switch between the versions.67> [!NOTE]8> **Preview** : Built-in and custom tools combinations are in [Preview](https://cloud.google.com/products#product-launch-stages) and supported for [Gemini 3](https://ai.google.dev/gemini-api/docs/models#gemini-3) models only.910Gemini allows the combination of [built-in tools](https://ai.google.dev/gemini-api/docs/tools), such11as `google_search`, and [function calling](https://ai.google.dev/gemini-api/docs/interactions/function-calling)12(also known as *custom tools*) in a single interaction by preserving and exposing13the context history of tool calls. Built-in and custom tool combinations allow14for complex, agentic workflows where, for example, the model can ground itself15in real-time web data before calling your specific business logic.1617Here's an example that enables built-in and custom tool combinations with18`google_search` and a custom function `getWeather`:1920### Python2122 # This will only work for SDK newer than 2.0.023 from google import genai2425 client = genai.Client()2627 getWeather = {28 "type": "function",29 "name": "getWeather",30 "description": "Gets the weather for a requested city.",31 "parameters": {32 "type": "object",33 "properties": {34 "city": {35 "type": "string",36 "description": "The city and state, e.g. Utqiaġvik, Alaska",37 },38 },39 "required": ["city"],40 },41 }4243 # The Interactions API manages context automatically across tool calls.44 # The model will first use Google Search, then call getWeather.45 interaction = client.interactions.create(46 model="gemini-3.5-flash",47 input="What is the northernmost city in the United States? What's the weather like there today?",48 tools=[49 {"type": "google_search"},50 getWeather,51 ],52 )5354 # Process steps: the interaction contains search results and a function call55 for step in interaction.steps:56 if step.type == "function_call":57 print(f"Function call: {step.name} with args: {step.arguments}")58 # In a real application, you would execute the function here59 # and provide the result back to the model.6061### JavaScript6263 // This will only work for SDK newer than 2.0.064 import { GoogleGenAI } from '@google/genai';6566 const client = new GoogleGenAI({});6768 const getWeather = {69 type: "function",70 name: "getWeather",71 description: "Get the weather in a given location",72 parameters: {73 type: "object",74 properties: {75 location: {76 type: "string",77 description: "The city and state, e.g. San Francisco, CA"78 }79 },80 required: ["location"]81 }82 };8384 // The Interactions API manages context automatically across tool calls.85 // The model will first use Google Search, then call getWeather.86 const interaction = await client.interactions.create({87 model: "gemini-3.5-flash",88 input: "What is the northernmost city in the United States? What's the weather like there today?",89 tools: [90 { type: "google_search" },91 getWeather,92 ],93 });9495 // Process steps: the interaction contains search results and a function call96 for (const step of interaction.steps) {97 if (step.type === "function_call") {98 console.log(`Function call: ${step.name} with args: ${JSON.stringify(step.arguments)}`);99 // In a real application, you would execute the function here100 // and provide the result back to the model.101 }102 }103104### REST105106 # Specifies the API revision to avoid breaking changes when they become default107 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \108 -H "Content-Type: application/json" \109 -H "x-goog-api-key: $GEMINI_API_KEY" \110 -H "Api-Revision: 2026-05-20" \111 -d '{112 "model": "gemini-3.5-flash",113 "input": "What is the northernmost city in the United States? What'\''s the weather like there today?",114 "tools": [115 { "type": "google_search" },116 {117 "type": "function",118 "name": "getWeather",119 "description": "Get the weather in a given location",120 "parameters": {121 "type": "object",122 "properties": {123 "location": {124 "type": "string",125 "description": "The city and state, e.g. San Francisco, CA"126 }127 },128 "required": ["location"]129 }130 }131 ]132 }'133134## How it works135136Gemini 3 models use *tool context circulation* to enable built-in and custom137tool combinations. Tool context circulation makes it possible to preserve and138expose the context of built-in tools and share it with custom tools in the same139interaction.140141### Enable tool combination142143- Include the [`function_declarations`](https://ai.google.dev/gemini-api/docs/interactions/function-calling#function-declarations), along with the built-in tools you want to use, to trigger the combination behavior.144145### API returns steps146147In an interaction response, the API returns separate steps for built-in tool148calls and function (custom tool) calls:149150- **Built-in tool steps**: The API manages these automatically, preserving context across turns.151- **Function call steps** : The API returns `function_call` steps for your custom functions. You execute the function and provide the result back.152153### Critical fields in returned steps154155Certain fields in the returned steps are critical to maintaining tool context and enabling tool combinations:156157- **`id`** : Found on `function_call` and `function_response` steps. A unique identifier that maps a call to its response.158- **`signature`** : Found on `thought` steps, as well as all tool call (e.g., `function_call`) and result (e.g., `function_response`) steps for Gemini 3+ models. This encrypted context enables **tool context circulation** across interactions.159160**Managing these fields:**161162- **Stateful Mode (Recommended)** : When you use `previous_interaction_id`, the server automatically handles both `id` and `signature` fields.163- **Stateless Mode** : When managing conversation history manually, you must ensure that you pass both the `id` and the `signature` fields back to the model in subsequent requests to validate authenticity and maintain context. The official SDKs handle this automatically if you pass the full response object back to history.164165### Tool-specific data166167Some built-in tools return user-visible data arguments specific to the tool168type.169170| Tool | User visible tool call args (if any) | User visible tool response (if any) |171|---|---|---|172| **google_search** | `queries` | `search_suggestions` |173| **google_maps** | `queries` | `places` `google_maps_widget_context_token` |174| **url_context** | `urls` URLs to be browsed | `status`: Browse status `retrieved_url`: URLs browsed |175| **file_search** | None | None |176177## Tokens and pricing178179Note that built-in tool call parts in requests are counted towards180`prompt_token_count`. Since these intermediate tool steps are now visible and181returned to you, they are part of the conversation history. This is only the182case for *requests* , not *responses*.183184The Google Search tool is an exception to this rule. Google Search already185applies its own pricing model at the query level, so tokens are not186double-charged (see the [Pricing](https://ai.google.dev/gemini-api/docs/pricing) page).187188Read the [Tokens](https://ai.google.dev/gemini-api/docs/interactions/tokens) page for more information.189190## Limitations191192- Default to `validated` mode (`auto` mode is not supported) when tool context circulation is enabled.193- Built-in tools like `google_search` rely on location and current time information, so if your `system_instruction` or `function_declaration.description` has conflicting location and time information, the tool combination feature might not work well.194195## Supported tools196197Standard tool context circulation applies to server-side (built-in) tools.198Code Execution is also a server-side tool, but has its own built-in solution to199context circulation. Computer Use and function calling are client-side tools,200and also have built-in solutions to context circulation.201202| Tool | Execution side | Context Circulation Support |203|---|---|---|204| [Google Search](https://ai.google.dev/gemini-api/docs/interactions/google-search) | Server-side | Supported |205| [Google Maps](https://ai.google.dev/gemini-api/docs/interactions/maps-grounding) | Server-side | Supported |206| [URL Context](https://ai.google.dev/gemini-api/docs/interactions/url-context) | Server-side | Supported |207| [File Search](https://ai.google.dev/gemini-api/docs/interactions/file-search) | Server-side | Supported |208| [Code Execution](https://ai.google.dev/gemini-api/docs/interactions/code-execution) | Server-side | Supported (built in, uses `code_execution` and `code_execution_result` steps) |209| [Computer Use](https://ai.google.dev/gemini-api/docs/interactions/computer-use) | Client-side | Supported (built in, uses `function_call` and `function_response` steps) |210| [Custom functions](https://ai.google.dev/gemini-api/docs/interactions/function-calling) | Client-side | Supported (built in, uses `function_call` and `function_response` steps) |211212## What's next213214- Learn more about [Function calling](https://ai.google.dev/gemini-api/docs/interactions/function-calling) in the Gemini API.215- Explore the supported tools:216 - [Google Search](https://ai.google.dev/gemini-api/docs/interactions/google-search)217 - [Google Maps](https://ai.google.dev/gemini-api/docs/interactions/maps-grounding)218 - [URL Context](https://ai.google.dev/gemini-api/docs/interactions/url-context)219 - [File Search](https://ai.google.dev/gemini-api/docs/interactions/file-search)