This document introduces function calling, covering how it works, its features, and best practices for implementation. Function calling, also known as tool use, provides the LLM with definitions of external tools (for example, a Function calling enables two primary use cases: For more use cases and examples that use function calling, see Use cases. The following models support function calling: You can specify up to 512 Define your functions in the OpenAPI schema format. For best practices for function declarations, including tips for names and descriptions, see Best practices. For Open Models, see the user guide. To use function calling, perform the following tasks: Declare a The following examples submit a prompt and function declaration to the Gemini models. When using the Python SDK, you can declare a function schema either manually with a dictionary or automatically with the You can specify the schema either manually using a Python dictionary or automatically with the Alternatively, you can declare the function automatically with the This example demonstrates a text scenario with one function and one prompt. Before trying this sample, follow the Node.js setup instructions in the Vertex AI quickstart using client libraries. For more information, see the Vertex AI Node.js API reference documentation. To authenticate to Vertex AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. This example demonstrates a text scenario with one function and one prompt. Learn how to install or update the Go. To learn more, see the SDK reference documentation. Set environment variables to use the Gen AI SDK with Vertex AI: This example demonstrates a text scenario with one function and one prompt. Before trying this sample, follow the C# setup instructions in the Vertex AI quickstart using client libraries. For more information, see the Vertex AI C# API reference documentation. To authenticate to Vertex AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. Before trying this sample, follow the Java setup instructions in the Vertex AI quickstart using client libraries. For more information, see the Vertex AI Java API reference documentation. To authenticate to Vertex AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. If the model determines that it needs a function's output, the response from the model contains the function name and the parameter values to use for the call. The following example shows a model response to the prompt "What is the weather like in Boston?". The model suggests calling the Call the external API and pass the API output back to the model. The following example uses synthetic data to simulate a response payload from an external API and submits the output back to the model. For best practices related to API calls, see Validate API calls. If the model proposes several parallel function calls, your application provides all of the responses back to the model. To learn more, see Parallel function calling. The model might determine that the output of another function is necessary for responding to the prompt. In this case, the response that your application receives from the model contains another function name and another set of parameter values. If the model determines that the API response is sufficient for responding to the user's prompt, it creates a natural language response and returns it to your application. Your application then passes the response to the user. The following is an example of a natural language response: When calling functions with thinking enabled, you'll need to get the Viewing thought signatures isn't required, but you will need to adjust Step 2 to return them along with the result of the function execution so it can incorporate the thoughts into its final response: When returning thought signatures, follow these guidelines: Learn more about limitations and usage of thought signatures, and about thinking models in general, on the Thinking page. For prompts such as "Get weather details in Boston and San Francisco?", the model might propose several parallel function calls. For a list of models that support parallel function calling, see Features and limitations. This example demonstrates a scenario with one To learn more about the request parameters, see Gemini API. The following command demonstrates how you can provide the function output to the model. Replace my-project with the name of your Google Cloud project. The natural language response created by the model is similar to the following: This example demonstrates a scenario with one Replace my-project with the name of your Google Cloud project. The following command demonstrates how you can provide the function output to the model. Instead of allowing the model to choose between a natural language response and a function call, you can force it to predict only function calls. This is known as forced function calling. You can also provide the model with a full set of function declarations but restrict its responses to a subset of these functions. The following example forces the model to predict only Function declarations are compatible with the OpenAPI schema. The following attributes are supported: The following example uses a Python dictionary to declare a function that takes both object and array parameters: The following example uses a Python dictionary to declare a function that takes an integer The following JSON function declaration uses the Usage notes: The following code sample declares a function that multiplies an array of numbers and uses Write clear and detailed function names, parameter descriptions, and instructions. Use strongly typed parameters. If the parameter values are from a finite set, add an Use system instructions. When using functions with date, time, or location parameters, include the current date, time, or relevant location information (for example, city and country) in the system instruction. This provides the model with the necessary context to process the request accurately, even if the user's prompt lacks details. Provide detailed user prompts{: #prompt-bp }. For best results, prepend the user prompt with the following details: Set the generation configuration{: #generation-config-bp }. For the temperature parameter, use Validate API calls{: #invoke-api-bp }. If the model proposes a function call that would send an order, update a database, or otherwise have significant consequences, validate the function call with the user before executing it. Thought signatures should always be used with function calling for best results. The pricing for function calling is based on the number of characters in the text inputs and outputs. To learn more, see Vertex AI pricing. Text input (prompt) refers to the user prompt for the current conversation turn, the function declarations for the current conversation turn, and the history of the conversation. The history of the conversation includes the queries, the function calls, and the function responses of previous conversation turns. Vertex AI truncates the history of the conversation at 32,000 characters. Text output (response) refers to the function calls and the text responses for the current conversation turn. You can use function calling for the following tasks: Additional use cases include the following: Interpret voice commands: Create functions that correspond with in-vehicle tasks. For example, you can create functions that turn on the radio or activate the air conditioning. Send audio files of the user's voice commands to the model, and prompt the model to convert the audio into text and identify the function that the user wants to call. Automate workflows based on environmental triggers: Create functions to represent processes that can be automated. Provide the model with data from environmental sensors and prompt it to parse and process the data to determine whether one or more of the workflows should be activated. For example, a model could process temperature data in a warehouse and choose to activate a sprinkler function. Automate the assignment of support tickets: Provide the model with support tickets, logs, and context-aware rules. Prompt the model to process all of this information to determine who the ticket should be assigned to. Call a function to assign the ticket to the person suggested by the model. Retrieve information from a knowledge base: Create functions that retrieve academic articles on a given subject and summarize them. This approach enables the model to answer questions about academic subjects and provide citations for its answers. See the API reference for function calling. Learn about Vertex AI Agent Engine.get_current_weather function). When processing a prompt, the model determines if a tool is needed and, if so, outputs structured data specifying the tool to call and its parameters (for example, get_current_weather(location='Boston')). Your application then executes this tool, feeds the result back to the model, and allows it to complete its response with dynamic, real-world information or the outcome of an action. This approach bridges the LLM with your systems and extends its capabilities.
Features and limitations
FunctionDeclarations.How to create a function calling application
Step 1: Submit the prompt and function declarations to the model
Tool in a schema format that's compatible with the OpenAPI schema. For more information, see Schema examples.from_func helper. The following table compares these two methods.
Declaration Method Description Pros Cons Manual (Python dictionary) Define the function schema explicitly using a Python dictionary that conforms to the OpenAPI specification. Provides full control over the schema, which is ideal for complex or non-standard function definitions. More verbose and requires manual updates if the Python function signature changes. Automatic ( from_func)Generate the schema automatically from a Python function's signature and docstring. Concise, less error-prone, and automatically stays in sync with the Python function. Offers less granular control over the generated schema and might not support all complex schema features. REST
PROJECT_ID=myproject LOCATION=us-central1 MODEL_ID=gemini-2.0-flash-001 curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \ -d '{ "contents": [{ "role": "user", "parts": [{ "text": "What is the weather in Boston?" }] }], "tools": [{ "functionDeclarations": [ { "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city name of the location for which to get the weather.", "default": { "string_value": "Boston, MA" } } }, "required": [ "location" ] } } ] }] }' Python
from_func helper function. The following example demonstrates how to declare a function manually.import vertexai from vertexai.generative_models import ( Content, FunctionDeclaration, GenerationConfig, GenerativeModel, Part, Tool, ToolConfig ) # Initialize Vertex AI # TODO(developer): Update the project vertexai.init(project="PROJECT_ID", location="us-central1") # Initialize Gemini model model = GenerativeModel(model_name="gemini-2.0-flash") # Manual function declaration get_current_weather_func = FunctionDeclaration( name="get_current_weather", description="Get the current weather in a given location", # Function parameters are specified in JSON schema format parameters={ "type": "object", "properties": { "location": { "type": "string", "description": "The city name of the location for which to get the weather.", "default": { "string_value": "Boston, MA" } } }, }, ) response = model.generate_content( contents = [ Content( role="user", parts=[ Part.from_text("What is the weather like in Boston?"), ], ) ], generation_config = GenerationConfig(temperature=0), tools = [ Tool( function_declarations=[get_current_weather_func], ) ] ) from_func helper function as shown in the following example:def get_current_weather(location: str = "Boston, MA"): """ Get the current weather in a given location Args: location: The city name of the location for which to get the weather. """ # This example uses a mock implementation. # You can define a local function or import the requests library to call an API return { "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy", "icon": "partly-cloudy", "humidity": 65, "wind": { "speed": 10, "direction": "NW" } } get_current_weather_func = FunctionDeclaration.from_func(get_current_weather) Node.js
Node.js
Go
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
C#
C#
Java
Java
get_current_weather function with the parameter Boston, MA. candidates { content { role: "model" parts { function_call { name: "get_current_weather" args { fields { key: "location" value { string_value: "Boston, MA" } } } } } } ... } Step 2: Provide the API output to the model
REST
PROJECT_ID=myproject MODEL_ID=gemini-2.0-flash LOCATION="us-central1" curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \ -d '{ "contents": [ { "role": "user", "parts": { "text": "What is the weather in Boston?" } }, { "role": "model", "parts": [ { "functionCall": { "name": "get_current_weather", "args": { "location": "Boston, MA" } } } ] }, { "role": "user", "parts": [ { "functionResponse": { "name": "get_current_weather", "response": { "temperature": 20, "unit": "C" } } } ] } ], "tools": [ { "function_declarations": [ { "name": "get_current_weather", "description": "Get the current weather in a specific location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city name of the location for which to get the weather." } }, "required": [ "location" ] } } ] } ] }' Python
function_response_contents = [] function_response_parts = [] # Iterates through the function calls in the response in case there are parallel function call requests for function_call in response.candidates[0].function_calls: print(f"Function call: {function_call.name}") # In this example, we'll use synthetic data to simulate a response payload from an external API if (function_call.args['location'] == "Boston, MA"): api_response = { "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy" } if (function_call.args['location'] == "San Francisco, CA"): api_response = { "location": "San Francisco, CA", "temperature": 58, "description": "Sunny" } function_response_parts.append( Part.from_function_response( name=function_call.name, response={"contents": api_response} ) ) # Add the function call response to the contents function_response_contents = Content(role="user", parts=function_response_parts) # Submit the User's prompt, model's response, and API output back to the model response = model.generate_content( [ Content( # User prompt role="user", parts=[ Part.from_text("What is the weather like in Boston?"), ], ), response.candidates[0].content, # Function call response function_response_contents # API output ], tools=[ Tool( function_declarations=[get_current_weather_func], ) ], ) # Get the model summary response print(response.text) It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies.
Function calling with thoughts
thought_signature from the model response object and return it when you send the result of the function execution back to the model. For example:Python
# Call the model with function declarations # ...Generation config, Configure the client, and Define user prompt (No changes) # Send request with declarations (using a thinking model) response = client.models.generate_content( model="gemini-2.5-flash", config=config, contents=contents) # See thought signatures for part in response.candidates[0].content.parts: if not part.text: continue if part.thought and part.thought_signature: print("Thought signature:") print(part.thought_signature) Python
# Create user friendly response with function result and call the model again # ...Create a function response part (No change) # Append thought signatures, function call and result of the function execution to contents function_call_content = response.candidates[0].content # Append the model's function call message, which includes thought signatures contents.append(function_call_content) contents.append(types.Content(role="user", parts=[function_response_part])) # Append the function response final_response = client.models.generate_content( model="gemini-2.5-flash", config=config, contents=contents, ) print(final_response.text)
Parallel function calling
REST
get_current_weather function. The user prompt is "Get weather details in Boston and San Francisco?". The model proposes two parallel get_current_weather function calls: one with the parameter Boston and the other with the parameter San Francisco. { "candidates": [ { "content": { "role": "model", "parts": [ { "functionCall": { "name": "get_current_weather", "args": { "location": "Boston" } } }, { "functionCall": { "name": "get_current_weather", "args": { "location": "San Francisco" } } } ] }, ... } ], ... } Model request
PROJECT_ID=my-project MODEL_ID=gemini-2.0-flash LOCATION="us-central1" curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \ -d '{ "contents": [ { "role": "user", "parts": { "text": "What is difference in temperature in Boston and San Francisco?" } }, { "role": "model", "parts": [ { "functionCall": { "name": "get_current_weather", "args": { "location": "Boston" } } }, { "functionCall": { "name": "get_current_weather", "args": { "location": "San Francisco" } } } ] }, { "role": "user", "parts": [ { "functionResponse": { "name": "get_current_weather", "response": { "temperature": 30.5, "unit": "C" } } }, { "functionResponse": { "name": "get_current_weather", "response": { "temperature": 20, "unit": "C" } } } ] } ], "tools": [ { "function_declarations": [ { "name": "get_current_weather", "description": "Get the current weather in a specific location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city name of the location for which to get the weather." } }, "required": [ "location" ] } } ] } ] }' Model response
[ { "candidates": [ { "content": { "parts": [ { "text": "The temperature in Boston is 30.5C and the temperature in San Francisco is 20C. The difference is 10.5C. \n" } ] }, "finishReason": "STOP", ... } ] ... } ] Python
get_current_weather function. The user prompt is "What is the weather like in Boston and San Francisco?".import vertexai from vertexai.generative_models import ( Content, FunctionDeclaration, GenerationConfig, GenerativeModel, Part, Tool, ToolConfig ) # Initialize Vertex AI # TODO(developer): Update the project vertexai.init(project="my-project", location="us-central1") # Initialize Gemini model model = GenerativeModel(model_name="gemini-2.0-flash") # Manual function declaration get_current_weather_func = FunctionDeclaration( name="get_current_weather", description="Get the current weather in a given location", # Function parameters are specified in JSON schema format parameters={ "type": "object", "properties": { "location": { "type": "string", "description": "The city name of the location for which to get the weather.", "default": { "string_value": "Boston, MA" } } }, }, ) response = model.generate_content( contents = [ Content( role="user", parts=[ Part.from_text("What is the weather like in Boston and San Francisco?"), ], ) ], generation_config = GenerationConfig(temperature=0), tools = [ Tool( function_declarations=[get_current_weather_func], ) ] ) function_response_contents = [] function_response_parts = [] # You can have parallel function call requests for the same function type. # For example, 'location_to_lat_long("London")' and 'location_to_lat_long("Paris")' # In that case, collect API responses in parts and send them back to the model for function_call in response.candidates[0].function_calls: print(f"Function call: {function_call.name}") # In this example, we'll use synthetic data to simulate a response payload from an external API if (function_call.args['location'] == "Boston, MA"): api_response = { "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy" } if (function_call.args['location'] == "San Francisco, CA"): api_response = { "location": "San Francisco, CA", "temperature": 58, "description": "Sunny" } function_response_parts.append( Part.from_function_response( name=function_call.name, response={"contents": api_response} ) ) # Add the function call response to the contents function_response_contents = Content(role="user", parts=function_response_parts) function_response_contents response = model.generate_content( contents = [ Content( role="user", parts=[ Part.from_text("What is the weather like in Boston and San Francisco?"), ], ), # User prompt response.candidates[0].content, # Function call response function_response_contents, # Function response ], tools = [ Tool( function_declarations=[get_current_weather_func], ) ] ) # Get the model summary response print(response.text) Go
Forced function calling
Mode Description AUTOThe default model behavior. The model decides whether to predict function calls or a natural language response. ANYThe model is constrained to always predict a function call. If allowed_function_names is not provided, the model picks from all of the available function declarations. If allowed_function_names is provided, the model picks from the set of allowed functions. NONEThe model must not predict function calls. This behaviour is equivalent to a model request without any associated function declarations. get_weather function calls. Python
response = model.generate_content( contents = [ Content( role="user", parts=[ Part.from_text("What is the weather like in Boston?"), ], ) ], generation_config = GenerationConfig(temperature=0), tools = [ Tool( function_declarations=[get_weather_func, some_other_function], ) ], tool_config=ToolConfig( function_calling_config=ToolConfig.FunctionCallingConfig( # ANY mode forces the model to predict only function calls mode=ToolConfig.FunctionCallingConfig.Mode.ANY, # Allowed function calls to predict when the mode is ANY. If empty, any of # the provided function calls will be predicted. allowed_function_names=["get_weather"], ) ) ) Function schema examples
type, nullable, required, format, description, properties, items, enum, anyOf, $ref, and $defs. Remaining attributes are not supported.Function with object and array parameters
extract_sale_records_func = FunctionDeclaration( name="extract_sale_records", description="Extract sale records from a document.", parameters={ "type": "object", "properties": { "records": { "type": "array", "description": "A list of sale records", "items": { "description": "Data for a sale record", "type": "object", "properties": { "id": {"type": "integer", "description": "The unique id of the sale."}, "date": {"type": "string", "description": "Date of the sale, in the format of MMDDYY, e.g., 031023"}, "total_amount": {"type": "number", "description": "The total amount of the sale."}, "customer_name": {"type": "string", "description": "The name of the customer, including first name and last name."}, "customer_contact": {"type": "string", "description": "The phone number of the customer, e.g., 650-123-4567."}, }, "required": ["id", "date", "total_amount"], }, }, }, "required": ["records"], }, )
Function with enum parameter
enum parameter:set_status_func = FunctionDeclaration( name="set_status", description="set a ticket's status field", # Function parameters are specified in JSON schema format parameters={ "type": "object", "properties": { "status": { "type": "integer", "enum": [ "10", "20", "30" ], # Provide integer (or any other type) values as strings. } }, }, )
Function with ref and def
ref and defs attributes:{ "contents": ..., "tools": [ { "function_declarations": [ { "name": "get_customer", "description": "Search for a customer by name", "parameters": { "type": "object", "properties": { "first_name": { "ref": "#/defs/name" }, "last_name": { "ref": "#/defs/name" } }, "defs": { "name": { "type": "string" } } } } ] } ] }
ref and defs without the $ symbol.ref attribute must refer to a direct child of defs; no external references.defs (self-reference) is limited to two.from_func with array parameterfrom_func to generate the FunctionDeclaration schema.from typing import List # Define a function. Could be a local function or you can import the requests library to call an API def multiply_numbers(numbers: List[int] = [1, 1]) -> int: """ Calculates the product of all numbers in an array. Args: numbers: An array of numbers to be multiplied. Returns: The product of all the numbers. If the array is empty, returns 1. """ if not numbers: # Handle empty array return 1 product = 1 for num in numbers: product *= num return product multiply_number_func = FunctionDeclaration.from_func(multiply_numbers) """ multiply_number_func contains the following schema: {'name': 'multiply_numbers', 'description': 'Calculates the product of all numbers in an array.', 'parameters': {'properties': {'numbers': {'items': {'type': 'INTEGER'}, 'description': 'list of numbers', 'default': [1.0, 1.0], 'title': 'Numbers', 'type': 'ARRAY'}}, 'description': 'Calculates the product of all numbers in an array.', 'title': 'multiply_numbers', 'property_ordering': ['numbers'], 'type': 'OBJECT'}} """
Best practices for function calling
book_flight_ticket function could have the description book flight tickets after confirming users' specific requirements, such as time, departure, destination, party size and preferred airline.enum field instead of putting the set of values into the description. If the parameter value is always an integer, set the type to integer rather than number.
You are a flight API assistant to help with searching flights based on user preferences.Don't make assumptions on the departure or destination airports. Always use a future date for the departure or destination time.Ask clarifying questions if not enough information is available.0 or another low value. This instructs the model to generate more confident results and reduces hallucinations.Use thought signatures
Pricing
Use cases of function calling
Use Case Example description Example link Integrate with external APIs Get weather information using a meteorological API Notebook tutorial Convert addresses to latitude/longitude coordinates Notebook tutorial Convert currencies using a currency exchange API Codelab Build advanced chatbots Answer customer questions about products and services Notebook tutorial Create an assistant to answer financial and news questions about companies Notebook tutorial Structure and control function calls Extract structured entities from raw log data Notebook tutorial Extract single or multiple parameters from user input Notebook tutorial Handle lists and nested data structures in function calls Notebook tutorial Handle function calling behavior Handle parallel function calls and responses Notebook tutorial Manage when and which functions the model can call Notebook tutorial Query databases with natural language Convert natural language questions into SQL queries for BigQuery Sample app Multimodal function calling Use images, videos, audio, and PDFs as input to trigger function calls Notebook tutorial
What's next
Introduction to function calling
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-21 UTC.