Custom functions can be defined and provided to a generative AI model using function calling. The model does not directly invoke these functions, but instead generates structured data output that specifies the function name and suggested arguments. This output enables the calling of external APIs, and the resulting API output can then be incorporated back into the model, allowing for more comprehensive query responses. Function calling empowers LLMs to interact with real-time information and various services, such as databases, customer relationship management systems, and document repositories, enhancing their ability to provide relevant and contextual answers.
How function calling works
Functions are described using function declarations. After you pass a list of function declarations in a query to a language model, the model returns an object in an OpenAPI compatible schema format that includes the names of functions and their arguments and tries to answer the user query with one of the returned functions. The language model understands the purpose of a function by analyzing its function declaration. The model doesn't actually call the function. Instead, a developer uses the OpenAPI compatible schema object in the response to call the function that the model returns.
When you implement function calling, you create one or more function
declarations, then add the function declarations to a tools
object that's
passed to the model. Each function declaration contains information about one
function that includes the following:
- Function name
- Function parameters in an OpenAPI compatible schema format. A select subset is supported. When using curl, the schema is specified using JSON.
- Function description (optional). For the best results, we recommend that you include a description.
This document includes curl examples that make REST calls with the
GenerativeModel
class and its methods.
Supported models
The following models support function calling:
gemini-1.0-pro
gemini-1.0-pro-001
gemini-1.5-pro-latest
Function calling mode
You can use the function calling mode to define the execution behavior for function calling. There are three modes available:
AUTO
: The default model behavior. The model decides to predict either a function call or a natural language response.ANY
: The model is constrained to always predict a function call. Ifallowed_function_names
is not provided, the model picks from all of the available function declarations. Ifallowed_function_names
is provided, the model picks from the set of allowed functions.NONE
: The model won't predict a function call. In this case, the model behavior is the same as if you don't pass any function declarations.
You can also pass a set of allowed_function_names
that, when provided, limits
the functions that the model will call. You should only include
allowed_function_names
when the mode is ANY
. Function names should match
function declaration names. With the mode set to ANY
and the
allowed_function_names
set, the model will predict a function call from the
set of function names provided.
Here's part of an
example request that sets the
mode to ANY
and specifies a list of allowed functions:
"tool_config": {
"function_calling_config": {
"mode": "ANY",
"allowed_function_names": ["find_theaters", "get_showtimes"]
},
}
Function calling cURL samples
When you use cURL, the function and parameter information is included in the
tools
element. Each function declaration in the tools
element contains the
function name, its parameters specified using the
OpenAPI compatible schema, and
a function description. The following samples demonstrate how to use curl
commands with function calling:
Single-turn curl sample
Single-turn is when you call the language model one time. With function calling, a single-turn use case might be when you provide the model a natural language query and a list of functions. In this case, the model uses the function declaration, which includes the function name, parameters, and description, to predict which function to call and the arguments to call it with.
The following curl sample is an example of passing in a description of a
function that returns information about where a movie is playing. Several
function declarations are included in the request, such as find_movies
and
find_theaters
.
Single-turn function calling curl example request
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": { "role": "user", "parts": { "text": "Which theaters in Mountain View show Barbie movie?" } }, "tools": [ { "function_declarations": [ { "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "string", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": [ "description" ] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" } }, "required": [ "location" ] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" }, "theater": { "type": "string", "description": "Name of the theater" }, "date": { "type": "string", "description": "Date for requested showtime" } }, "required": [ "location", "movie", "theater", "date" ] } } ] } ] }'
The response to this curl example might be similar to the following.
Single-turn function calling curl example response
[{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_theaters", "args": { "movie": "Barbie", "location": "Mountain View, CA" } } } ] }, "finishReason": "STOP", "safetyRatings": [ { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } ], "usageMetadata": { "promptTokenCount": 9, "totalTokenCount": 9 } }]
Single-turn example using ANY mode
The following curl example is similar to the
single-turn example, but it sets
the mode to ANY
:
"tool_config": {
"function_calling_config": {
"mode": "ANY"
},
}
Single-turn function calling using ANY mode (request)
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": { "role": "user", "parts": { "text": "What movies are showing in North Seattle tonight?" } }, "tools": [ { "function_declarations": [ { "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "string", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": [ "description" ] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" } }, "required": [ "location" ] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" }, "theater": { "type": "string", "description": "Name of the theater" }, "date": { "type": "string", "description": "Date for requested showtime" } }, "required": [ "location", "movie", "theater", "date" ] } } ] } ], "tool_config": { "function_calling_config": { "mode": "ANY" }, } }'
The response might be similar to the following:
Single-turn function calling using ANY mode (response)
{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_movies", "args": { "description": "", "location": "North Seattle, WA" } } } ], "role": "model" }, "finishReason": "STOP", "index": 0, "safetyRatings": [ { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" } ] } ], "promptFeedback": { "safetyRatings": [ { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } }
Single-turn example using ANY mode and allowed functions
The following curl example is similar to the
single-turn example, but it sets
the mode to ANY
and includes a list of allowed
functions:
"tool_config": {
"function_calling_config": {
"mode": "ANY",
"allowed_function_names": ["find_theaters", "get_showtimes"]
},
}
Single-turn function calling using ANY mode and allowed functions (request)
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": { "role": "user", "parts": { "text": "What movies are showing in North Seattle tonight?" } }, "tools": [ { "function_declarations": [ { "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "string", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": [ "description" ] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" } }, "required": [ "location" ] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" }, "theater": { "type": "string", "description": "Name of the theater" }, "date": { "type": "string", "description": "Date for requested showtime" } }, "required": [ "location", "movie", "theater", "date" ] } } ] } ], "tool_config": { "function_calling_config": { "mode": "ANY", "allowed_function_names": ["find_theaters", "get_showtimes"] }, } }'
The model can't predict the find_movies
function, because it's not on the list
of allowed functions, so it predicts a different function instead. The response
might be similar to the following:
Single-turn function calling using ANY mode and allowed functions (response)
{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_theaters", "args": { "location": "North Seattle, WA", "movie": null } } } ], "role": "model" }, "finishReason": "STOP", "index": 0, "safetyRatings": [ { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } ], "promptFeedback": { "safetyRatings": [ { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } }
Multi-turn curl examples
You can implement a multi-turn function calling scenario by doing the following:
- Get a function call response by calling the language model. This is the first turn.
- Call the language model using the function call response from the first turn and the function response you get from calling that function. This is the second turn.
The response from the second turn either summarizes the results to answer your query in the first turn, or contains a second function call you can use to get more information for your query.
This topic includes two multi-turn curl examples:
- Curl example that uses a function response from a previous turn
- Curl example that calls a language model multiple times
Curl example that uses a response from a previous turn
The following curl sample calls the function and arguments returned by the previous single-turn example to get a response. The method and parameters returned by the single-turn example are in this JSON.
"functionCall": {
"name": "find_theaters",
"args": {
"movie": "Barbie",
"location": "Mountain View, CA"
}
}
Multi-turn function calling curl example request
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": [{ "role": "user", "parts": [{ "text": "Which theaters in Mountain View show Barbie movie?" }] }, { "role": "model", "parts": [{ "functionCall": { "name": "find_theaters", "args": { "location": "Mountain View, CA", "movie": "Barbie" } } }] }, { "role": "function", "parts": [{ "functionResponse": { "name": "find_theaters", "response": { "name": "find_theaters", "content": { "movie": "Barbie", "theaters": [{ "name": "AMC Mountain View 16", "address": "2000 W El Camino Real, Mountain View, CA 94040" }, { "name": "Regal Edwards 14", "address": "245 Castro St, Mountain View, CA 94040" }] } } } }] }], "tools": [{ "functionDeclarations": [{ "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "STRING", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": ["description"] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" } }, "required": ["location"] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" }, "theater": { "type": "STRING", "description": "Name of the theater" }, "date": { "type": "STRING", "description": "Date for requested showtime" } }, "required": ["location", "movie", "theater", "date"] } }] }] }'
The response to this curl example includes the result of calling the
find_theaters
method. The response might be similar to the following:
Multi-turn function calling curl example response
{ "candidates": [ { "content": { "parts": [ { "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14." } ] } } ], "usageMetadata": { "promptTokenCount": 9, "candidatesTokenCount": 27, "totalTokenCount": 36 } }
Curl example that calls a language model multiple times
The following curl example calls the language model multiple times to call a function. Each time the model calls the function, it can use a different function to answer a different user query in the request.
Multi-turn function calling curl example request
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": [{ "role": "user", "parts": [{ "text": "Which theaters in Mountain View show Barbie movie?" }] }, { "role": "model", "parts": [{ "functionCall": { "name": "find_theaters", "args": { "location": "Mountain View, CA", "movie": "Barbie" } } }] }, { "role": "function", "parts": [{ "functionResponse": { "name": "find_theaters", "response": { "name": "find_theaters", "content": { "movie": "Barbie", "theaters": [{ "name": "AMC Mountain View 16", "address": "2000 W El Camino Real, Mountain View, CA 94040" }, { "name": "Regal Edwards 14", "address": "245 Castro St, Mountain View, CA 94040" }] } } } }] }, { "role": "model", "parts": [{ "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14." }] },{ "role": "user", "parts": [{ "text": "Can we recommend some comedy movies on show in Mountain View?" }] }], "tools": [{ "functionDeclarations": [{ "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "STRING", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": ["description"] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" } }, "required": ["location"] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" }, "theater": { "type": "STRING", "description": "Name of the theater" }, "date": { "type": "STRING", "description": "Date for requested showtime" } }, "required": ["location", "movie", "theater", "date"] } }] }] }'
Multi-turn function calling curl example response
[{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_movies", "args": { "description": "comedy", "location": "Mountain View, CA" } } } ] }, "finishReason": "STOP", "safetyRatings": [ { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } ], "usageMetadata": { "promptTokenCount": 48, "totalTokenCount": 48 } } ]
Best practices
Follow these best practices to improve the accuracy and reliability of your function calls.
Function key fields
Accurately defining your functions is essential when integrating them into your
requests. Each function relies on specific parameters that guide its behavior
and interaction with the model. Here's a breakdown of the key parameters used
within the functions_declarations
array.
function_declarations
(array):
- Contains one or more objects, each representing a distinct function.
Within each function_declarations
object:
name
(string): The unique identifier for the function within the API call.- Best practice: Use clear, descriptive names without space, period (
.
), or dash (-
) characters. Instead, use underscore (_
) characters or camel case.
- Best practice: Use clear, descriptive names without space, period (
description
(string): A comprehensive explanation of the function's purpose and capabilities.- Best practice: Be detailed, clear, and specific in function descriptions, providing examples if necessary. For example, instead of
find theaters
, usefind theaters based on location and optionally movie title that is currently playing in theaters.
Avoid overly broad or ambiguous descriptions.
- Best practice: Be detailed, clear, and specific in function descriptions, providing examples if necessary. For example, instead of
parameters
(object): Defines the input data required by the function.type
(string): Specifies the overall data type (e.g.,object
).properties
(object):- Lists individual parameters, each with:
type
(string): The data type of the parameter (e.g.,string
,integer
,boolean
).- Best practice: Use strongly typed parameters to reduce model hallucinations. For example, if the parameter values are from a finite set, use an
enum
field instead of listing the values in the description (e.g.,"type": "enum", "values": ["now_playing", "upcoming"]
). If the parameter value is always an integer, set the type tointeger
rather thannumber
.
- Best practice: Use strongly typed parameters to reduce model hallucinations. For example, if the parameter values are from a finite set, use an
description
(string): A clear explanation of the parameter's purpose and expected format.- Best practice: Provide concrete examples and constraints. For example, instead of
the location to search
, useThe city and state, e.g. San Francisco, CA or a zip code e.g. 95616
.
- Best practice: Provide concrete examples and constraints. For example, instead of
- Lists individual parameters, each with:
required
(array):- An array of strings listing the parameter names that are mandatory for the function to operate.
User prompt
For best results, prepend the user query with the following details:
- Additional context for the model. For example,
You are a movie API assistant to help users find movies and showtimes based on their preferences.
- Details or instructions on how and when to use the functions. For example,
Don't make assumptions on showtimes. Always use a future date for showtimes.
- Instructions to ask clarifying questions if user queries are ambiguous. For example,
Ask clarifying questions if not enough information is available to complete the request.
Sampling parameters
For the temperature parameter, use 0
or another low value. This instructs
the model to generate more confident results and reduces hallucinations.
API invocation
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.