Repository Public
1# Function calling with the Gemini API23> [!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.67Function calling lets you connect models to external tools and APIs.8Instead of generating text responses, the model determines when to call specific9functions and provides the necessary parameters to execute real-world actions.10This allows the model to act as a bridge between natural language and real-world11actions and data. Function calling has 3 primary use cases:1213- [**Take Actions:**](https://ai.google.dev/gemini-api/docs/interactions/function-calling#meeting) Interact with external systems using APIs, such as scheduling appointments, creating invoices, sending emails, or controlling smart home devices.14- [**Augment Knowledge:**](https://ai.google.dev/gemini-api/docs/interactions/function-calling#weather) Access information from external sources like databases, APIs, and knowledge bases.15- [**Extend Capabilities:**](https://ai.google.dev/gemini-api/docs/interactions/function-calling#chart) Use external tools to perform computations and extend the limitations of the model, such as using a calculator or creating charts.1617You can browse examples of these use cases below:1819> [!NOTE]20> **Important:** Gemini 3 model APIs now generate a unique `id` for every function call. When returning the result of your executed function to the model, we recommend passing the matching `id` in your `function_result`. If you are using the standard Python or Node.js SDKs, this is handled automatically.2122### Schedule Meeting2324This example shows how to define a function that schedules a meeting with attendees at a specific time, allowing the model to parse user requests and return structured arguments to trigger actions in external systems.2526### Python2728 from google import genai2930 schedule_meeting_function = {31 "type": "function",32 "name": "schedule_meeting",33 "description": "Schedules a meeting with specified attendees at a given time and date.",34 "parameters": {35 "type": "object",36 "properties": {37 "attendees": {"type": "array", "items": {"type": "string"}},38 "date": {"type": "string", "description": "Date (e.g., '2024-07-29')"},39 "time": {"type": "string", "description": "Time (e.g., '15:00')"},40 "topic": {"type": "string", "description": "The meeting topic."},41 },42 "required": ["attendees", "date", "time", "topic"],43 },44 }4546 client = genai.Client()4748 interaction = client.interactions.create(49 model="gemini-3-flash-preview",50 input="Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about Q3 planning.",51 tools=[{"type": "function", **schedule_meeting_function}],52 )5354 for step in interaction.steps:55 if step.type == "function_call":56 print(f"Function to call: {step.name}")57 print(f"Arguments: {step.arguments}")5859### JavaScript6061 import { GoogleGenAI } from '@google/genai';6263 const client = new GoogleGenAI({});6465 const scheduleMeetingFunction = {66 type: 'function',67 name: 'schedule_meeting',68 description: 'Schedules a meeting with specified attendees at a given time and date.',69 parameters: {70 type: 'object',71 properties: {72 attendees: { type: 'array', items: { type: 'string' } },73 date: { type: 'string', description: 'Date (e.g., "2024-07-29")' },74 time: { type: 'string', description: 'Time (e.g., "15:00")' },75 topic: { type: 'string', description: 'The meeting topic.' },76 },77 required: ['attendees', 'date', 'time', 'topic'],78 },79 };8081 const interaction = await client.interactions.create({82 model: 'gemini-3-flash-preview',83 input: 'Schedule a meeting with Bob and Alice for 03/27/2025 at 10:00 AM about Q3 planning.',84 tools: [scheduleMeetingFunction],85 });8687 for (const step of interaction.steps) {88 if (step.type === 'function_call') {89 console.log(`Function to call: ${step.name}`);90 console.log(`Arguments: ${JSON.stringify(step.arguments)}`);91 }92 }9394### REST9596 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \97 -H "x-goog-api-key: $GEMINI_API_KEY" \98 -H 'Content-Type: application/json' \99 -H "Api-Revision: 2026-05-20" \100 -d '{101 "model": "gemini-3-flash-preview",102 "input": "Schedule a meeting with Bob and Alice for 03/27/2025 at 10:00 AM about Q3 planning.",103 "tools": [{104 "type": "function",105 "name": "schedule_meeting",106 "description": "Schedules a meeting with specified attendees at a given time and date.",107 "parameters": {108 "type": "object",109 "properties": {110 "attendees": {"type": "array", "items": {"type": "string"}},111 "date": {"type": "string"},112 "time": {"type": "string"},113 "topic": {"type": "string"}114 },115 "required": ["attendees", "date", "time", "topic"]116 }117 }]118 }'119120### Get Weather121122This example shows how to define a function that retrieves temperature data for a location, enabling the model to call external APIs to answer queries requiring real-time or external information.123124### Python125126 from google import genai127128 weather_function = {129 "type": "function",130 "name": "get_current_temperature",131 "description": "Gets the current temperature for a given location.",132 "parameters": {133 "type": "object",134 "properties": {135 "location": {136 "type": "string",137 "description": "The city name, e.g. San Francisco",138 },139 },140 "required": ["location"],141 },142 }143144 client = genai.Client()145146 interaction = client.interactions.create(147 model="gemini-3-flash-preview",148 input="What's the temperature in London?",149 tools=[weather_function],150 )151152 for step in interaction.steps:153 if step.type == "function_call":154 print(f"Function to call: {step.name}")155 print(f"Arguments: {step.arguments}")156157### JavaScript158159 import { GoogleGenAI } from '@google/genai';160161 const client = new GoogleGenAI({});162163 const weatherFunctionDeclaration = {164 type: 'function',165 name: 'get_current_temperature',166 description: 'Gets the current temperature for a given location.',167 parameters: {168 type: 'object',169 properties: {170 location: {171 type: 'string',172 description: 'The city name, e.g. San Francisco',173 },174 },175 required: ['location'],176 },177 };178179 const interaction = await client.interactions.create({180 model: 'gemini-3-flash-preview',181 input: "What's the temperature in London?",182 tools: [weatherFunctionDeclaration],183 });184185 for (const step of interaction.steps) {186 if (step.type === 'function_call') {187 console.log(`Function to call: ${step.name}`);188 console.log(`Arguments: ${JSON.stringify(step.arguments)}`);189 }190 }191192### REST193194 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \195 -H "x-goog-api-key: $GEMINI_API_KEY" \196 -H 'Content-Type: application/json' \197 -H "Api-Revision: 2026-05-20" \198 -d '{199 "model": "gemini-3-flash-preview",200 "input": "What'\''s the temperature in London?",201 "tools": [{202 "type": "function",203 "name": "get_current_temperature",204 "description": "Gets the current temperature for a given location.",205 "parameters": {206 "type": "object",207 "properties": {208 "location": {"type": "string", "description": "The city name"}209 },210 "required": ["location"]211 }212 }]213 }'214215### Create Chart216217This example shows how to define a function that generates a bar chart from structured data, demonstrating how the model can use external tools to perform computations or create visual assets:218219### Python220221 from google import genai222223 create_chart_function = {224 "type": "function",225 "name": "create_bar_chart",226 "description": "Creates a bar chart given a title, labels, and values.",227 "parameters": {228 "type": "object",229 "properties": {230 "title": {"type": "string", "description": "The title for the chart."},231 "labels": {"type": "array", "items": {"type": "string"}},232 "values": {"type": "array", "items": {"type": "number"}},233 },234 "required": ["title", "labels", "values"],235 },236 }237238 client = genai.Client()239240 interaction = client.interactions.create(241 model="gemini-3-flash-preview",242 input="Create a bar chart titled 'Quarterly Sales' with Q1: 50000, Q2: 75000, Q3: 60000.",243 tools=[create_chart_function],244 )245246 for step in interaction.steps:247 if step.type == "function_call":248 print(f"Function to call: {step.name}")249 print(f"Arguments: {step.arguments}")250251### JavaScript252253 import { GoogleGenAI } from '@google/genai';254255 const client = new GoogleGenAI({});256257 const createChartFunctionDeclaration = {258 type: 'function',259 name: 'create_bar_chart',260 description: 'Creates a bar chart given a title, labels, and values.',261 parameters: {262 type: 'object',263 properties: {264 title: { type: 'string', description: 'The title for the chart.' },265 labels: { type: 'array', items: { type: 'string' } },266 values: { type: 'array', items: { type: 'number' } },267 },268 required: ['title', 'labels', 'values'],269 },270 };271272 const interaction = await client.interactions.create({273 model: 'gemini-3-flash-preview',274 input: "Create a bar chart titled 'Quarterly Sales' with Q1: 50000, Q2: 75000, Q3: 60000.",275 tools: [createChartFunctionDeclaration],276 });277278 for (const step of interaction.steps) {279 if (step.type === 'function_call') {280 console.log(`${step.name}(${JSON.stringify(step.arguments)})`);281 }282 }283284### REST285286 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \287 -H "x-goog-api-key: $GEMINI_API_KEY" \288 -H 'Content-Type: application/json' \289 -H "Api-Revision: 2026-05-20" \290 -d '{291 "model": "gemini-3-flash-preview",292 "input": "Create a bar chart titled '\''Quarterly Sales'\'' with Q1: 50000, Q2: 75000, Q3: 60000.",293 "tools": [{294 "type": "function",295 "name": "create_bar_chart",296 "description": "Creates a bar chart given a title, labels, and values.",297 "parameters": {298 "type": "object",299 "properties": {300 "title": {"type": "string"},301 "labels": {"type": "array", "items": {"type": "string"}},302 "values": {"type": "array", "items": {"type": "number"}}303 },304 "required": ["title", "labels", "values"]305 }306 }]307 }'308309## How function calling works310311312313Function calling involves a structured interaction between your application, the314model, and external functions:3153161. **Define Function Declaration:** Define the function's name, parameters, and purpose to the model.3172. **Call LLM with function declarations:** Send user prompt along with the function declaration(s) to the model.3183. **Execute Function Code (Your Responsibility):** The model *doesn't* execute the function itself. Extract the name and args and execute in your application.3194. **Create User friendly response:** Send the result back to the model for a final, user-friendly response.320321This process can be repeated over multiple turns. The model supports calling322multiple functions in a single turn ([parallel function calling](https://ai.google.dev/gemini-api/docs/interactions/function-calling#parallel_function_calling)) and in323sequence ([compositional function calling](https://ai.google.dev/gemini-api/docs/interactions/function-calling#compositional_function_calling)).324325### Step 1: Define a function declaration326327### Python328329 set_light_values_declaration = {330 "type": "function",331 "name": "set_light_values",332 "description": "Sets the brightness and color temperature of a light.",333 "parameters": {334 "type": "object",335 "properties": {336 "brightness": {337 "type": "integer",338 "description": "Light level from 0 to 100",339 },340 "color_temp": {341 "type": "string",342 "enum": ["daylight", "cool", "warm"],343 "description": "Color temperature",344 },345 },346 "required": ["brightness", "color_temp"],347 },348 }349350 def set_light_values(brightness: int, color_temp: str) -> dict:351 """Set the brightness and color temperature of a room light."""352 return {"brightness": brightness, "colorTemperature": color_temp}353354### JavaScript355356 const setLightValuesTool = {357 type: 'function',358 name: 'set_light_values',359 description: 'Sets the brightness and color temperature of a light.',360 parameters: {361 type: 'object',362 properties: {363 brightness: { type: 'number', description: 'Light level from 0 to 100' },364 color_temp: { type: 'string', enum: ['daylight', 'cool', 'warm'] },365 },366 required: ['brightness', 'color_temp'],367 },368 };369370 function setLightValues(brightness, color_temp) {371 return { brightness: brightness, colorTemperature: color_temp };372 }373374### Step 2: Call the model with function declarations375376### Python377378 from google import genai379380 client = genai.Client()381382 interaction = client.interactions.create(383 model="gemini-3-flash-preview",384 input="Turn the lights down to a romantic level",385 tools=[set_light_values_declaration],386 )387388 fc_step = next(s for s in interaction.steps if s.type == "function_call")389 print(fc_step)390391### JavaScript392393 import { GoogleGenAI } from '@google/genai';394395 const client = new GoogleGenAI({});396397 const interaction = await client.interactions.create({398 model: 'gemini-3-flash-preview',399 input: 'Turn the lights down to a romantic level',400 tools: [setLightValuesTool],401 });402403 const fcStep = interaction.steps.find(s => s.type === 'function_call');404 console.log(fcStep);405406The model returns a `function_call` step with `type`, `name`, and `arguments`:407408 type='function_call'409 name='set_light_values'410 arguments={'color_temp': 'warm', 'brightness': 25}411412### Step 3: Execute the function413414### Python415416 fc_step = next(s for s in interaction.steps if s.type == "function_call")417418 if fc_step.name == "set_light_values":419 result = set_light_values(**fc_step.arguments)420 print(f"Function execution result: {result}")421422### JavaScript423424 const fcStep = interaction.steps.find(s => s.type === 'function_call');425426 let result;427 if (fcStep.name === 'set_light_values') {428 result = setLightValues(fcStep.arguments.brightness, fcStep.arguments.color_temp);429 console.log(`Function execution result: ${JSON.stringify(result)}`);430 }431432### Step 4: Send result back to model433434### Python435436 final_interaction = client.interactions.create(437 model="gemini-3-flash-preview",438 input=[439 {440 "type": "function_result",441 "name": fc_step.name,442 "call_id": fc_step.id,443 "result": [{"type": "text", "text": json.dumps(result)}],444 }445 ],446 tools=[set_light_values_declaration],447 previous_interaction_id=interaction.id,448 )449450 print(final_interaction.output_text)451452### JavaScript453454 const finalInteraction = await client.interactions.create({455 model: 'gemini-3-flash-preview',456 input: [{457 type: 'function_result',458 name: fcStep.name,459 call_id: fcStep.id,460 result: [{ type: 'text', text: JSON.stringify(result) }]461 }],462 tools: [setLightValuesTool],463 previous_interaction_id: interaction.id,464 });465466 console.log(finalInteraction.output_text);467468### Stateless function calling469470You can also use function calling in stateless mode by managing the conversation history on the client side and setting `store=false`.471472In stateless mode, you must pass the full history of the conversation in the `input` field of each subsequent request. This history must include:4731. The initial `user_input` step.4742. All model-generated steps returned in Turn 1 (including `thought` and `function_call` steps) exactly as received.4753. The `function_result` step containing the output of your executed function.476477### Python478479 from google import genai480 import json481482 client = genai.Client()483484 history = [485 {486 "type": "user_input",487 "content": [{"type": "text", "text": "Turn the lights down to a romantic level"}]488 }489 ]490491 interaction = client.interactions.create(492 model="gemini-3-flash-preview",493 store=False,494 input=history,495 tools=[set_light_values_declaration],496 )497498 for step in interaction.steps:499 history.append(step.model_dump())500501 fc_step = next(s for s in interaction.steps if s.type == "function_call")502 if fc_step.name == "set_light_values":503 result = set_light_values(**fc_step.arguments)504505 history.append({506 "type": "function_result",507 "name": fc_step.name,508 "call_id": fc_step.id,509 "result": [{"type": "text", "text": json.dumps(result)}],510 })511512 final_interaction = client.interactions.create(513 model="gemini-3-flash-preview",514 store=False,515 input=history,516 tools=[set_light_values_declaration],517 )518519 print(final_interaction.output_text)520521### JavaScript522523 import { GoogleGenAI } from "@google/genai";524525 const client = new GoogleGenAI({});526527 async function main() {528 const history = [529 {530 type: "user_input",531 content: [{ type: "text", text: "Turn the lights down to a romantic level" }]532 }533 ];534535 const interaction = await client.interactions.create({536 model: "gemini-3-flash-preview",537 store: false,538 input: history,539 tools: [setLightValuesTool],540 });541542 history.push(...interaction.steps);543544 const fcStep = interaction.steps.find(s => s.type === 'function_call');545 let result;546 if (fcStep.name === 'set_light_values') {547 result = setLightValues(fcStep.arguments.brightness, fcStep.arguments.color_temp);548 }549550 history.push({551 type: 'function_result',552 name: fcStep.name,553 call_id: fcStep.id,554 result: [{ type: 'text', text: JSON.stringify(result) }]555 });556557 const finalInteraction = await client.interactions.create({558 model: 'gemini-3-flash-preview',559 store: false,560 input: history,561 tools: [setLightValuesTool],562 });563564 console.log(finalInteraction.output_text);565 }566567 await main();568569### REST570571 # Turn 1: Send request with tools and store: false572 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \573 -H "x-goog-api-key: $GEMINI_API_KEY" \574 -H 'Content-Type: application/json' \575 -H "Api-Revision: 2026-05-20" \576 -d '{577 "model": "gemini-3-flash-preview",578 "store": false,579 "input": [580 {581 "type": "user_input",582 "content": "Turn the lights down to a romantic level"583 }584 ],585 "tools": [{586 "type": "function",587 "name": "set_light_values",588 "description": "Sets the brightness and color temperature of a light.",589 "parameters": {590 "type": "object",591 "properties": {592 "brightness": {"type": "integer", "description": "Light level from 0 to 100"},593 "color_temp": {"type": "string", "enum": ["daylight", "cool", "warm"]}594 },595 "required": ["brightness", "color_temp"]596 }597 }]598 }')599600 # Extract model steps (thought, function_call)601 MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')602603 # Extract function call details to execute604 FC_NAME=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .name')605 FC_ID=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .id')606607 # Assume local execution returns: {"brightness": 25, "colorTemperature": "warm"}608 RESULT="{\"brightness\": 25, \"colorTemperature\": \"warm\"}"609610 # Reconstruct history for Turn 2611 HISTORY=$(jq -n \612 --argjson first_input '[{"type": "user_input", "content": "Turn the lights down to a romantic level"}]' \613 --argjson model_steps "$MODEL_STEPS" \614 --arg fc_name "$FC_NAME" \615 --arg fc_id "$FC_ID" \616 --arg result "$RESULT" \617 '$first_input + $model_steps + [{"type": "function_result", "name": $fc_name, "call_id": $fc_id, "result": [{"type": "text", "text": $result}]}]')618619 # Turn 2: Send the full history620 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \621 -H "x-goog-api-key: $GEMINI_API_KEY" \622 -H 'Content-Type: application/json' \623 -H "Api-Revision: 2026-05-20" \624 -d "{625 \"model\": \"gemini-3-flash-preview\",626 \"store\": false,627 \"input\": $HISTORY,628 \"tools\": [{629 \"type\": \"function\",630 \"name\": \"set_light_values\",631 \"description\": \"Sets the brightness and color temperature of a light.\",632 \"parameters\": {633 \"type\": \"object\",634 \"properties\": {635 \"brightness\": {\"type\": \"integer\"},636 \"color_temp\": {\"type\": \"string\"}637 },638 \"required\": [\"brightness\", \"color_temp\"]639 }640 }]641 }"642643## Function declarations644645A function declaration is passed as a tool and includes:646647- `type` (string): Must be `"function"` for custom functions.648- `name` (string): Unique function name (use underscores or camelCase).649- `description` (string): Clear explanation of the function's purpose.650- `parameters` (object): Input parameters the function expects.651 - `type` (string): Overall data type, such as `object`.652 - `properties` (object): Individual parameters with type and description.653 - `required` (array): Mandatory parameter names.654655## Function calling with thinking models656657Gemini 3 and 2.5 series models use an internal ["thinking"](https://ai.google.dev/gemini-api/docs/interactions/thinking) process that improves function calling.658The SDKs automatically handle [thought signatures](https://ai.google.dev/gemini-api/docs/interactions/thought-signatures) for you.659660## Parallel function calling661662Call multiple functions at once when they are independent:663664### Python665666 power_disco_ball = {"type": "function", "name": "power_disco_ball", "description": "Powers the disco ball.",667 "parameters": {"type": "object", "properties": {"power": {"type": "boolean"}}, "required": ["power"]}}668 start_music = {"type": "function", "name": "start_music", "description": "Play music.",669 "parameters": {"type": "object", "properties": {"energetic": {"type": "boolean"}, "loud": {"type": "boolean"}}, "required": ["energetic", "loud"]}}670 dim_lights = {"type": "function", "name": "dim_lights", "description": "Dim the lights.",671 "parameters": {"type": "object", "properties": {"brightness": {"type": "number"}}, "required": ["brightness"]}}672673 client = genai.Client()674675 interaction = client.interactions.create(676 model="gemini-3-flash-preview",677 input="Turn this place into a party!",678 tools=[power_disco_ball, start_music, dim_lights],679 generation_config={"tool_choice": "any"},680 )681682 for step in interaction.steps:683 if step.type == "function_call":684 args = ", ".join(f"{key}={val}" for key, val in step.arguments.items())685 print(f"{step.name}({args})")686687### JavaScript688689 const powerDiscoBall = { type: 'function', name: 'power_disco_ball', description: 'Powers the disco ball.',690 parameters: { type: 'object', properties: { power: { type: 'boolean' } }, required: ['power'] } };691 const startMusic = { type: 'function', name: 'start_music', description: 'Play music.',692 parameters: { type: 'object', properties: { energetic: { type: 'boolean' }, loud: { type: 'boolean' } }, required: ['energetic', 'loud'] } };693 const dimLights = { type: 'function', name: 'dim_lights', description: 'Dim the lights.',694 parameters: { type: 'object', properties: { brightness: { type: 'number' } }, required: ['brightness'] } };695696 const interaction = await client.interactions.create({697 model: 'gemini-3-flash-preview',698 input: 'Turn this place into a party!',699 tools: [powerDiscoBall, startMusic, dimLights],700 generation_config: { tool_choice: 'any' },701 });702703 for (const step of interaction.steps) {704 if (step.type === 'function_call') {705 console.log(`${step.name}(${JSON.stringify(step.arguments)})`);706 }707 }708709## Compositional function calling710711Chain multiple function calls together for complex requests (e.g., get location712first, then get weather for that location).713714### Python715716 get_weather_forecast_declaration = {717 "type": "function",718 "name": "get_weather_forecast",719 "description": "Gets the current weather temperature for a given location.",720 "parameters": {721 "type": "object",722 "properties": {723 "location": {"type": "string", "description": "The location"},724 },725 "required": ["location"],726 },727 }728729 set_thermostat_temperature_declaration = {730 "type": "function",731 "name": "set_thermostat_temperature",732 "description": "Sets the thermostat to a desired temperature.",733 "parameters": {734 "type": "object",735 "properties": {736 "temperature": {737 "type": "integer",738 "description": "The temperature in Celsius",739 },740 },741 "required": ["temperature"],742 },743 }744745 client = genai.Client()746747 interaction = client.interactions.create(748 model="gemini-3-flash-preview",749 input="If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise 18°C.",750 tools=[751 get_weather_forecast_declaration,752 set_thermostat_temperature_declaration,753 ],754 )755756 for step in interaction.steps:757 if step.type == "function_call":758 print(f"Function to call: {step.name}")759 print(f"Arguments: {step.arguments}")760 elif hasattr(step, "content") and step.content:761 for part in step.content:762 if hasattr(part, "text"):763 print(part.text)764765## Function calling modes766767Control how the model uses tools using `tool_choice` in `generation_config`:768769- `auto` (Default): Model decides whether to call a function or respond directly.770- `any`: Model is constrained to always predict a function call.771- `none`: Model is prohibited from making function calls.772- `validated` (Preview): Model ensures function schema adherence.773774### Python775776 generation_config = {777 "tool_choice": {778 "allowed_tools": {779 "mode": "any",780 "tools": ["get_current_temperature"]781 }782 }783 }784785### JavaScript786787 const generation_config = {788 tool_choice: {789 allowed_tools: {790 mode: 'any',791 tools: ['get_current_temperature']792 }793 }794 };795796### REST797798 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \799 -H "x-goog-api-key: $GEMINI_API_KEY" \800 -H 'Content-Type: application/json' \801 -H "Api-Revision: 2026-05-20" \802 -d '{803 "model": "gemini-3-flash-preview",804 "input": "What is the temperature in Boston?",805 "tools": [{806 "type": "function",807 "name": "get_current_temperature",808 "description": "Gets the current temperature for a given location.",809 "parameters": {810 "type": "object",811 "properties": {812 "location": {"type": "string"}813 },814 "required": ["location"]815 }816 }],817 "generation_config": {818 "tool_choice": {819 "allowed_tools": {820 "mode": "any",821 "tools": ["get_current_temperature"]822 }823 }824 }825 }'826827## Multi-tool use828829You can enable multiple tools, combining built-in tools with function calling in830the same request. Gemini 3 models can combine built-in tools with function831calling out-of-the-box in Interactions. Passing `previous_interaction_id`832automatically circulates the built-in tool context.833834### Python835836 from google import genai837 import json838839 client = genai.Client()840841 get_weather = {842 "type": "function",843 "name": "get_weather",844 "description": "Gets the weather for a requested city.",845 "parameters": {846 "type": "object",847 "properties": {848 "city": {849 "type": "string",850 "description": "The city and state, e.g. Utqiaġvik, Alaska",851 },852 },853 "required": ["city"],854 },855 }856857 tools = [858 {"type": "google_search"},859 get_weather 860 ]861862 interaction = client.interactions.create(863 model="gemini-3-flash-preview",864 input="What is the northernmost city in the United States? What's the weather like there today?",865 tools=tools866 )867868 for step in interaction.steps:869 if step.type == "function_call":870 print(f"Function call: {step.name} (ID: {step.id})")871 result = {"response": "Very cold. 22 degrees Fahrenheit."}872 interaction_2 = client.interactions.create(873 model="gemini-3-flash-preview",874 previous_interaction_id=interaction.id,875 tools=tools,876 input=[{877 "type": "function_result",878 "name": step.name,879 "call_id": step.id,880 "result": [{"type": "text", "text": json.dumps(result)}]881 }]882 )883884 print(interaction_2.output_text)885886### JavaScript887888 import { GoogleGenAI } from '@google/genai';889890 const client = new GoogleGenAI({});891892 const weatherTool = {893 type: 'function',894 name: 'get_weather',895 description: 'Gets the weather for a given location.',896 parameters: {897 type: 'object',898 properties: {899 location: { type: 'string', description: 'The city and state, e.g. San Francisco, CA' }900 },901 required: ['location']902 }903 };904905 const tools = [906 {type: 'google_search'}, // Built-in tool907 weatherTool 908 ];909910 let interaction = await client.interactions.create({911 model: 'gemini-3-flash-preview',912 input: "What is the northernmost city in the United States? What's the weather like there today?",913 tools: tools914 });915916 for (const step of interaction.steps) {917 if (step.type === 'function_call') {918 console.log(`Function call: ${step.name} (ID: ${step.id})`);919 const result = {response: "Very cold. 22 degrees Fahrenheit."};920 const interaction_2 = await client.interactions.create({921 model: 'gemini-3-flash-preview',922 previous_interaction_id: interaction.id,923 tools: tools,924 input: [{925 type: 'function_result',926 name: step.name,927 call_id: step.id,928 result: [{ type: 'text', text: JSON.stringify(result) }]929 }]930 });931932 console.log(interaction_2.output_text);933 }934 }935936## Multimodal function responses937938For Gemini 3 series models, you can include multimodal content in939the function response parts that you send to the model. The model can process940this multimodal content in its next turn to produce a more informed response.941942To include multimodal data in a function response, include it as one or more content blocks in the `result` field of the `function_result` step. Each content block must specify its `type` (e.g., `"text"`, `"image"`).943944The following example shows how to send a function response containing image data back to the model in an interaction:945946### Python947948 import base64949 from google import genai950 import requests951952 client = genai.Client()953954 tool_call = next(s for s in interaction.steps if s.type == "function_call")955956 image_path = "https://goo.gle/instrument-img"957 image_bytes = requests.get(image_path).content958959 base64_image_data = base64.b64encode(image_bytes).decode("utf-8")960961 final_interaction = client.interactions.create(962 model="gemini-3-flash-preview",963 previous_interaction_id=interaction.id,964 input=[965 {966 "type": "function_result",967 "name": tool_call.name,968 "call_id": tool_call.id,969 "result": [970 {"type": "text", "text": "instrument.jpg"},971 {972 "type": "image",973 "mime_type": "image/jpeg",974 "data": base64_image_data,975 },976 ],977 }978 ],979 )980981 print(final_interaction.output_text)982983### JavaScript984985 import { GoogleGenAI } from "@google/genai";986987 const ai = new GoogleGenAI({});988989 const toolCall = interaction.steps.find(s => s.type === 'function_call');990991 const base64ImageData = "BASE64_IMAGE_DATA";992993 const finalInteraction = await ai.interactions.create({994 model: 'gemini-3-flash-preview',995 previous_interaction_id: interaction.id,996 input: [{997 type: 'function_result',998 name: toolCall.name,999 call_id: toolCall.id,1000 result: [1001 { type: 'text', text: 'instrument.jpg' },1002 {1003 type: 'image',1004 mime_type: 'image/jpeg',1005 data: base64ImageData,1006 }1007 ]1008 }]1009 });10101011 console.log(finalInteraction.output_text);10121013### REST10141015 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1016 -H "x-goog-api-key: $GEMINI_API_KEY" \1017 -H 'Content-Type: application/json' \1018 -H "Api-Revision: 2026-05-20" \1019 -d '{1020 "model": "gemini-3-flash-preview",1021 "previous_interaction_id": "INTERACTION_ID",1022 "input": [1023 {1024 "type": "function_result",1025 "name": "get_image",1026 "call_id": "call_123",1027 "result": [1028 {"type": "text", "text": "instrument.jpg"},1029 {1030 "type": "image",1031 "mime_type": "image/jpeg",1032 "data": "BASE64_IMAGE_DATA"1033 }1034 ]1035 }1036 ]1037 }'10381039## Function calling with Structured output10401041For Gemini 3 series models, combine function calling with1042[structured output](https://ai.google.dev/gemini-api/docs/interactions/structured-output) for1043consistently formatted responses.10441045## Remote MCP (Model Context Protocol)10461047Interactions API supports connecting to remote MCP servers to give the model access to external tools and services. You provide the server `name` and `url` in the tools configuration.10481049When using Remote MCP, be aware of the following constraints:10501051- **Server types**: Remote MCP only works with Streamable HTTP servers. SSE (Server-Sent Events) servers are not supported.1052- **Model support**: Remote MCP does not work with Gemini 3 models at this time. Support for Gemini 3 is coming soon.1053- **Naming** : MCP server names should not include the `-` character. Use `snake_case` server names instead.10541055| Field | Type | Required | Description |1056|---|---|---|---|1057| `type` | `string` | Yes | Must be `"mcp_server"`. |1058| `name` | `string` | No | A display name for the MCP server. |1059| `url` | `string` | No | The full URL for the MCP server endpoint. |1060| `headers` | `object` | No | Key-value pairs sent as HTTP headers with every request to the server (for example, authentication tokens). |1061| `allowed_tools` | `array` | No | Restrict which tools from the server the agent may call. |10621063### Example10641065### Python10661067 from google import genai10681069 client = genai.Client()10701071 interaction = client.interactions.create(1072 model="gemini-2.5-flash",1073 input="Check the status of my last server deployment.",1074 tools=[1075 {1076 "type": "mcp_server",1077 "name": "Deployment Tracker",1078 "url": "https://mcp.example.com/mcp",1079 "headers": {"Authorization": "Bearer my-token"},1080 }1081 ]1082 )10831084### JavaScript10851086 import { GoogleGenAI } from '@google/genai';10871088 const client = new GoogleGenAI({});10891090 const interaction = await client.interactions.create({1091 model: 'gemini-2.5-flash',1092 input: 'Check the status of my last server deployment.',1093 tools: [1094 {1095 type: 'mcp_server',1096 name: 'Deployment Tracker',1097 url: 'https://mcp.example.com/mcp',1098 headers: { Authorization: 'Bearer my-token' }1099 }1100 ]1101 });11021103### REST11041105 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1106 -H "Content-Type: application/json" \1107 -H "x-goog-api-key: $GEMINI_API_KEY" \1108 -H "Api-Revision: 2026-05-20" \1109 -d '{1110 "model": "gemini-2.5-flash",1111 "input": "Check the status of my last server deployment.",1112 "tools": [1113 {1114 "type": "mcp_server",1115 "name": "Deployment Tracker",1116 "url": "https://mcp.example.com/mcp",1117 "headers": {"Authorization": "Bearer my-token"}1118 }1119 ]1120 }'11211122## Stream tool calls11231124When using tools with streaming, the model generates function calls as a1125sequence of `step.delta` events on the stream. Tool arguments can be streamed1126as partial arguments using `arguments`. You must aggregate these deltas to1127reconstruct the complete tool calls before executing them.11281129### Python11301131 import json1132 from google import genai11331134 client = genai.Client()11351136 weather_tool = {1137 "type": "function",1138 "name": "get_weather",1139 "description": "Gets the weather for a given location.",1140 "parameters": {1141 "type": "object",1142 "properties": {1143 "location": {"type": "string", "description": "The city and state"}1144 },1145 "required": ["location"]1146 }1147 }11481149 stream = client.interactions.create(1150 model="gemini-3-flash-preview",1151 input="What is the weather in Paris?",1152 tools=[weather_tool],1153 stream=True1154 )11551156 current_calls = {}1157 tool_calls = []11581159 for event in stream:1160 if event.event_type == "step.start":1161 if event.step.type == "function_call":1162 current_calls[event.index] = {1163 "id": event.step.id,1164 "name": event.step.name,1165 "arguments": ""1166 }1167 if hasattr(event.step, "arguments") and event.step.arguments:1168 if isinstance(event.step.arguments, dict):1169 current_calls[event.index]["arguments"] = json.dumps(event.step.arguments)1170 else:1171 current_calls[event.index]["arguments"] = event.step.arguments1172 elif event.event_type == "step.delta":1173 if event.delta.type == "arguments":1174 if event.index in current_calls:1175 current_calls[event.index]["arguments"] += event.delta.partial_arguments1176 elif event.delta.type == "text":1177 print(event.delta.text, end="", flush=True)11781179 elif event.event_type == "interaction.completed":1180 for index, call in current_calls.items():1181 args = call["arguments"]1182 if args:1183 args = json.loads(args)1184 else:1185 args = {}11861187 tool_calls.append({1188 "type": "function_call",1189 "id": call["id"],1190 "name": call["name"],1191 "arguments": args1192 })11931194 print(f"\nFinal tool calls ready to execute:")1195 print(json.dumps(tool_calls, indent=2))11961197### JavaScript11981199 import { GoogleGenAI } from '@google/genai';12001201 const client = new GoogleGenAI({});12021203 const weatherTool = {1204 type: 'function',1205 name: 'get_weather',1206 description: 'Gets the weather for a given location.',1207 parameters: {1208 type: 'object',1209 properties: {1210 location: { type: 'string', description: 'The city and state' }1211 },1212 required: ['location']1213 }1214 };12151216 const stream = await client.interactions.create({1217 model: 'gemini-3-flash-preview',1218 input: 'What is the weather in Paris?',1219 tools: [weatherTool],1220 stream: true,1221 });12221223 const currentCalls = new Map();1224 let toolCalls = [];12251226 for await (const event of stream) {1227 const evType = event.event_type;1228 if (evType === 'step.start') {1229 if (event.step.type === 'function_call') {1230 currentCalls.set(event.index, {1231 id: event.step.id,1232 name: event.step.name,1233 arguments: ''1234 });1235 if (event.step.arguments) {1236 if (typeof event.step.arguments === 'object') {1237 currentCalls.get(event.index).arguments = JSON.stringify(event.step.arguments);1238 } else {1239 currentCalls.get(event.index).arguments = event.step.arguments;1240 }1241 }1242 }1243 } else if (evType === 'step.delta') {1244 if (event.delta.type === 'arguments') {1245 if (currentCalls.has(event.index)) {1246 currentCalls.get(event.index).arguments += event.delta.partial_arguments;1247 }1248 } else if (event.delta.type === 'text') {1249 process.stdout.write(event.delta.text);1250 }1251 } else if (evType === 'interaction.completed' || evType === 'interaction.complete') {1252 toolCalls = Array.from(currentCalls.values()).map(call => ({1253 type: 'function_call',1254 id: call.id,1255 name: call.name,1256 arguments: call.arguments ? JSON.parse(call.arguments) : {}1257 }));1258 console.log('\nFinal tool calls ready to execute:');1259 console.log(JSON.stringify(toolCalls, null, 2));1260 }1261 }12621263### REST12641265 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \1266 -H "Content-Type: application/json" \1267 -H "x-goog-api-key: $GEMINI_API_KEY" \1268 -H "Api-Revision: 2026-05-20" \1269 -d '{1270 "model": "gemini-3-flash-preview",1271 "input": "What is the weather in Paris?",1272 "tools": [{1273 "type": "function",1274 "name": "get_weather",1275 "description": "Gets the weather for a given location.",1276 "parameters": {1277 "type": "object",1278 "properties": {1279 "location": {"type": "string", "description": "The city and state"}1280 },1281 "required": ["location"]1282 }1283 }],1284 "stream": true1285 }'12861287## Best practices12881289- **Function and Parameter Descriptions:** Be clear and specific.1290- **Naming:** Use descriptive names without spaces or special characters.1291- **Strong Typing:** Use specific types (integer, string, enum).1292- **Tool Selection:** Keep active set to 10-20 tools maximum.1293- **Prompt Engineering:** Provide context and instructions.1294- **Validation:** Validate function calls before executing.1295- **Error Handling:** Implement robust error handling.1296- **Security:** Use appropriate authentication for external APIs.12971298## Notes and limitations12991300- Only a [subset of the OpenAPI schema](https://ai.google.dev/api/rest/v1beta/cachedContents#FunctionDeclaration) is supported.1301- For `any` mode, the API may reject very large or deeply nested schemas.1302- Supported parameter types in Python are limited.