Stay organized with collections Save and categorize content based on your preferences.
Function calling, also known as tool use, provides the LLM with definitions of external tools (for example, a get_current_weather function). When processing a prompt, the model intelligently 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, allowing it to complete its response with dynamic, real-world information or the outcome of an action. This effectively bridges the LLM with your systems and extends its capabilities.
Function calling enables two primary use cases:
Fetching data: Retrieve up-to-date information for model responses, such as current weather, currency conversion, or specific data from knowledge bases and APIs (RAG).
Taking action: Perform external operations like submitting forms, updating application state, or orchestrating agentic workflows (e.g., conversation handoffs).
For more use cases and examples that are powered by function calling, see Use cases.
Features and limitationsThe following models support function calling:
Gemini models:
Open models:
You can specify up to 512 FunctionDeclarations
Define your functions in the OpenAPI schema format.
For best practices related to the function declarations, including tips for names and descriptions, see Best practices.
For Open Models, follow this user guide.
To use function calling, perform the following tasks:
Step 1: Submit the prompt and function declarations to the modelDeclare a Tool in a schema format that's compatible with the OpenAPI schema. For more information, see Schema examples.
The following examples submit a prompt and function declaration to the Gemini models.
RESTPROJECT_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"
]
}
}
]
}]
}'
You can specify the schema either manually using a Python dictionary or automatically with the 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],
)
]
)
Alternatively, you can declare the function automatically with the 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)
This example demonstrates a text scenario with one function and one prompt.
Node.jsBefore 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.
GoThis 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:
# 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=TrueC#
This example demonstrates a text scenario with one function and one prompt.
C#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.
Java JavaBefore 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 the output of a particular function, the response that the application receives from the model contains the function name and the parameter values that the function should be called with.
The following is an example of a model response to the user prompt "What is the weather like in Boston?". The model proposes calling the 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
Invoke 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.
RESTPROJECT_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"
]
}
}
]
}
]
}'
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)
For best practices related to API invocation, see Best practices - API invocation.
If the model had proposed several parallel function calls, the application must provide all of the responses back to the model. To learn more, see Parallel function calling example.
The model may determine that the output of another function is necessary for responding to the prompt. In this case, the response that the 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 the application. In this case, the application must pass the response back to the user. The following is an example of a natural language response:
It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies.Function calling with thoughts
When calling functions with thinking enabled, you'll need to get the 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:
# 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)
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:
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)
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.
Parallel function callingFor prompts such as "Get weather details in Boston and San Francisco?", the model may propose several parallel function calls. For a list of models that support parallel function calling, see Supported models.
To learn about parallel function calling with an end-to-end Jupyter notebook tutorial, see Working with Parallel Function Calls and Multiple Function Responses in Gemini RESTThis example demonstrates a scenario with one 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.
To learn more about the request parameters, see Gemini API.
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "Boston"
}
}
},
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "San Francisco"
}
}
}
]
},
...
}
],
...
}
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.
Model requestPROJECT_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"
]
}
}
]
}
]
}'
The natural language response created by the model is similar to the following:
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
This example demonstrates a scenario with one get_current_weather function. The user prompt is "What is the weather like in Boston and San Francisco?".
Replace my-project with the name of your Google Cloud project.
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],
)
]
)
The following command demonstrates how you can provide the function output to the model.
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)
Instead of allowing the model to choose between a natural language response and a function call, you can force it to only predict function calls. This is known as forced function calling. You can also choose to provide the model with a full set of function declarations, but restrict its responses to a subset of these functions.
Mode DescriptionAUTO The default model behavior. The model decides whether to predict function calls or a natural language response. ANY The 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. NONE The model must not predict function calls. This behaviour is equivalent to a model request without any associated function declarations.
The following example is forced to predict only get_weather function calls.
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 declarations are compatible with the OpenAPI schema. We support the following attributes: type, nullable, required, format, description, properties, items, enum, anyOf, $ref, and $defs. Remaining attributes are not supported.
The following example uses a Python dictionary to declare a function that takes both 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
The following example uses a Python dictionary to declare a function that takes an integer 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
The following JSON function declaration uses the 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" }
}
}
}
]
}
]
}
Usage notes:
ref and defs without the $ symbol.ref must refer to direct child of defs; no external references.defs (self-reference) is limited to two.from_func with array parameter
The following code sample declares a function that multiplies an array of numbers and uses from_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 Write clear and detailed function names, parameter descriptions, and instructions
Function names should start with a letter or an underscore and contain only characters a-z, A-Z, 0-9, underscores, dots or dashes with a maximum length of 64.
Function descriptions should be clear and verbose. For example, a 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
If the parameter values are from a finite set, add an 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.
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.
Update user promptFor best results, prepend the user prompt with the following details:
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.For the temperature parameter, use 0 or another low value. This instructs the model to generate more confident results and reduces hallucinations.
If the model proposes the invocation of a function that would send an order, update a database, or otherwise have significant consequences, validate the function call with the user before executing it.
Use thought signaturesThought signatures should always be used with function calling for best results.
PricingThe pricing for function calling is based on the number of characters within the text inputs and outputs. To learn more, see Vertex AI pricing.
Here, 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.
Use cases of function callingYou can use function calling for the following tasks:
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 tutorialHere are some more use cases:
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 ask 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 ask 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. Ask 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. Enable 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.
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-15 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-15 UTC."],[],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4