Repository Public
1> [!NOTE]2> **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.34Gemini allows the combination of [built-in tools](https://ai.google.dev/gemini-api/docs/tools), such5as `google_search`, and [function calling](https://ai.google.dev/gemini-api/docs/function-calling)6(also known as *custom tools*) in a single interaction by preserving and exposing7the context history of tool calls. Built-in and custom tool combinations allow8for complex, agentic workflows where, for example, the model can ground itself9in real-time web data before calling your specific business logic.1011Here's an example that enables built-in and custom tool combinations with12`google_search` and a custom function `getWeather`:1314### Python1516 # This will only work for SDK newer than 2.0.017 from google import genai1819 client = genai.Client()2021 getWeather = {22 "type": "function",23 "name": "getWeather",24 "description": "Gets the weather for a requested city.",25 "parameters": {26 "type": "object",27 "properties": {28 "city": {29 "type": "string",30 "description": "The city and state, e.g. Utqiaġvik, Alaska",31 },32 },33 "required": ["city"],34 },35 }3637 # The Interactions API manages context automatically across tool calls.38 # The model will first use Google Search, then call getWeather.39 interaction = client.interactions.create(40 model="gemini-3.8-flash",41 input="What is the northernmost city in the United States? What's the weather like there today?",42 tools=[43 {"type": "google_search"},44 getWeather,45 ],46 )4748 # Process steps: the interaction contains search results and a function call49 for step in interaction.steps:50 if step.type == "function_call":51 print(f"Function call: {step.name} with args: {step.arguments}")52 # In a real application, you would execute the function here53 # and provide the result back to the model.5455### JavaScript5657 // This will only work for SDK newer than 2.0.058 import { GoogleGenAI } from '@google/genai';5960 const client = new GoogleGenAI({});6162 const getWeather = {63 type: "function",64 name: "getWeather",65 description: "Get the weather in a given location",66 parameters: {67 type: "object",68 properties: {69 location: {70 type: "string",71 description: "The city and state, e.g. San Francisco, CA"72 }73 },74 required: ["location"]75 }76 };7778 // The Interactions API manages context automatically across tool calls.79 // The model will first use Google Search, then call getWeather.80 const interaction = await client.interactions.create({81 model: "gemini-3.8-flash",82 input: "What is the northernmost city in the United States? What's the weather like there today?",83 tools: [84 { type: "google_search" },85 getWeather,86 ],87 });8889 // Process steps: the interaction contains search results and a function call90 for (const step of interaction.steps) {91 if (step.type === "function_call") {92 console.log(`Function call: ${step.name} with args: ${JSON.stringify(step.arguments)}`);93 // In a real application, you would execute the function here94 // and provide the result back to the model.95 }96 }9798### Java99100 import com.google.genai.Client;101 import com.google.genai.gaos.models.interactions.CreateModelInteraction;102 import com.google.genai.gaos.models.interactions.Function;103 import com.google.genai.gaos.models.interactions.GoogleSearch;104 import com.google.genai.gaos.models.interactions.Interaction;105 import com.google.genai.gaos.models.interactions.InteractionsInput;106 import com.google.genai.gaos.models.interactions.Model;107 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;108 import java.util.Arrays;109 import java.util.HashMap;110 import java.util.Map;111112 Client client = new Client();113114 Map<String, Object> parameters = new HashMap<>();115 parameters.put("type", "object");116117 Function customFunc =118 Function.builder()119 .name("get_user_location")120 .description("Retrieves user current location.")121 .parameters(parameters)122 .build();123124 CreateModelInteraction params =125 CreateModelInteraction.builder()126 .model(Model.of("gemini-3.8-flash"))127 .input(InteractionsInput.of("What is the weather like where I am right now?"))128 .tools(Arrays.asList(customFunc, new GoogleSearch()))129 .build();130131 Interaction interaction =132 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();133134 System.out.println(interaction.outputText().orElse(""));135136### REST137138 # Specifies the API revision to avoid breaking changes when they become default139 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \140 -H "Content-Type: application/json" \141 -H "x-goog-api-key: $GEMINI_API_KEY" \142 -d '{143 "model": "gemini-3.8-flash",144 "input": "What is the northernmost city in the United States? What'\''s the weather like there today?",145 "tools": [146 { "type": "google_search" },147 {148 "type": "function",149 "name": "getWeather",150 "description": "Get the weather in a given location",151 "parameters": {152 "type": "object",153 "properties": {154 "location": {155 "type": "string",156 "description": "The city and state, e.g. San Francisco, CA"157 }158 },159 "required": ["location"]160 }161 }162 ]163 }'164165## How it works166167Gemini 3 models use *tool context circulation* to enable built-in and custom168tool combinations. Tool context circulation makes it possible to preserve and169expose the context of built-in tools and share it with custom tools in the same170interaction.171172### Enable tool combination173174- Include the [`function_declarations`](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations), along with the built-in tools you want to use, to trigger the combination behavior.175176### API returns steps177178In an interaction response, the API returns separate steps for built-in tool179calls and function (custom tool) calls:180181- **Built-in tool steps**: The API manages these automatically, preserving context across turns.182- **Function call steps** : The API returns `function_call` steps for your custom functions. You execute the function and provide the result back.183184### Critical fields in returned steps185186Certain fields in the returned steps are critical to maintaining tool context and enabling tool combinations:187188- **`id`** : Found on `function_call` and `function_response` steps. A unique identifier that maps a call to its response.189- **`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.190191**Managing these fields:**192193- **Stateful Mode (Recommended)** : When you use `previous_interaction_id`, the server automatically handles both `id` and `signature` fields.194- **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.195196### Tool-specific data197198Some built-in tools return user-visible data arguments specific to the tool199type.200201| Tool | User visible tool call args (if any) | User visible tool response (if any) |202|---|---|---|203| **google_search** | `queries` | `search_suggestions` |204| **google_maps** | `queries` | `places` `google_maps_widget_context_token` |205| **url_context** | `urls` URLs to be browsed | `status`: Browse status `retrieved_url`: URLs browsed |206| **file_search** | None | None |207208## Tokens and pricing209210Note that built-in tool call parts in requests are counted towards211`prompt_token_count`. Since these intermediate tool steps are now visible and212returned to you, they are part of the conversation history. This is only the213case for *requests* , not *responses*.214215The Google Search tool is an exception to this rule. Google Search already216applies its own pricing model at the query level, so tokens are not217double-charged (see the [Pricing](https://ai.google.dev/gemini-api/docs/pricing) page).218219Read the [Tokens](https://ai.google.dev/gemini-api/docs/tokens) page for more information.220221## Limitations222223- Default to `validated` mode (`auto` mode is not supported) when tool context circulation is enabled.224- 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.225226## Supported tools227228Standard tool context circulation applies to server-side (built-in) tools.229Code Execution is also a server-side tool, but has its own built-in solution to230context circulation. Computer Use and function calling are client-side tools,231and also have built-in solutions to context circulation.232233| Tool | Execution side | Context Circulation Support |234|---|---|---|235| [Google Search](https://ai.google.dev/gemini-api/docs/google-search) | Server-side | Supported |236| [Google Maps](https://ai.google.dev/gemini-api/docs/maps-grounding) | Server-side | Supported |237| [URL Context](https://ai.google.dev/gemini-api/docs/url-context) | Server-side | Supported |238| [File Search](https://ai.google.dev/gemini-api/docs/file-search) | Server-side | Supported |239| [Code Execution](https://ai.google.dev/gemini-api/docs/code-execution) | Server-side | Supported (built in, uses `code_execution` and `code_execution_result` steps) |240| [Computer Use](https://ai.google.dev/gemini-api/docs/computer-use) | Client-side | Supported (built in, uses `function_call` and `function_response` steps) |241| [Custom functions](https://ai.google.dev/gemini-api/docs/function-calling) | Client-side | Supported (built in, uses `function_call` and `function_response` steps) |242243## What's next244245- Learn more about [Function calling](https://ai.google.dev/gemini-api/docs/function-calling) in the Gemini API.246- Explore the supported tools:247 - [Google Search](https://ai.google.dev/gemini-api/docs/google-search)248 - [Google Maps](https://ai.google.dev/gemini-api/docs/maps-grounding)249 - [URL Context](https://ai.google.dev/gemini-api/docs/url-context)250 - [File Search](https://ai.google.dev/gemini-api/docs/file-search)