Function calling using the Gemini API

Generative models are powerful at solving many types of problems. However, they are constrained by limitations like:

  • They are frozen after training, leading to stale knowledge.
  • They can't query or modify external data.

Function calling can help you overcome some of these limitations. Function calling is sometimes referred to as tool use because it allows a model to use external tools such as APIs and functions to generate its final response.


This guide shows you how you might implement a function call setup similar to the scenario described in the next major section of this page. At a high-level, here are the steps to set up function calling in your app:

  • Step 1: Write a function that can provide the model with information that it needs to generate its final response (for example, the function can call an external API).

  • Step 2: Create a function declaration that describes the function and its parameters.

  • Step 3: Provide the function declaration during model initialization so that the model knows how it can use the function, if needed.

  • Step 4: Set up your app so that the model can send along the required information for your app to call the function.

  • Step 5: Pass the function's response back to the model so that the model can generate its final response.

Jump to code implementation

Overview of a function calling example

When you send a request to the model, you can also provide the model with a set of "tools" (like functions) that it can use to generate its final response. In order to utilize these functions and call them ("function calling"), the model and your app need to pass information back-and-forth to each other, so the recommended way to use function calling is through the multi-turn chat interface.

Imagine that you have an app where a user could enter a prompt like: What was the weather in Boston on October 17, 2024?.

The Gemini models may not know this weather information; however, imagine that you know of an external weather service API that can provide it. You can use function calling to give the Gemini model a pathway to that API and its weather information.

First, you write a function fetchWeather in your app that interacts with this hypothetical external API, which has this input and output:

Parameter Type Required Description
Input
location Object Yes The name of the city and its state for which to get the weather.
Only cities in the USA are supported. Must always be a nested object of city and state.
date String Yes Date for which to fetch the weather (must always be in YYYY-MM-DD format).
Output
temperature Integer Yes Temperature (in Fahrenheit)
chancePrecipitation String Yes Chance of precipitation (expressed as a percentage)
cloudConditions String Yes Cloud conditions (one of clear, partlyCloudy, mostlyCloudy, cloudy)

When initializing the model, you tell the model that this fetchWeather function exists and how it can be used to process incoming requests, if needed. This is called a "function declaration". The model does not call the function directly. Instead, as the model is processing the incoming request, it decides if the fetchWeather function can help it respond to the request. If the model decides that the function can indeed be useful, the model generates structured data that will help your app call the function.

Look again at the incoming request: What was the weather in Boston on October 17, 2024?. The model would likely decide that the fetchWeather function can help it generate a response. The model would look at what input parameters are needed for fetchWeather and then generate structured input data for the function that looks roughly like this:

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

The model passes this structured input data to your app so that your app can call the fetchWeather function. When your app receives the weather conditions back from the API, it passes the information along to the model. This weather information allows the model to complete its final processing and generate its response to the initial request of What was the weather in Boston on October 17, 2024?

The model might provide a final natural-language response like: On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

Diagram showing how function calling involves the model interacting with a function in your app 

You can learn more about function calling in the Gemini Developer API documentation.

Implement function calling

The following steps in this guide show you how to implement a function call setup similar to the workflow described in Overview of a function calling example (see the top section of this page).

Supported models

  • gemini-3.1-pro-preview
  • gemini-3.7-flash (and the older gemini-3.6-flash and gemini-3.5-flash)
  • gemini-3.5-flash-lite (and the older gemini-3.1-flash-lite)

General-use Gemini 2.5 models support this capability, but they're all deprecated.

The Gemini Live API models also support this capability, but all the code samples in this guide are for the general-use Gemini models.

Before you begin

Click your Gemini API provider to view provider-specific content and code on this page.

If you haven't already, complete the getting started guide, which describes how to set up your Firebase project, connect your app to Firebase, add the SDK, initialize the backend service for your chosen Gemini API provider, and create a GenerativeModel instance.

For testing and iterating on your prompts, we recommend using Google AI Studio.

Step 1: Write the function

Imagine that you have an app where a user could enter a prompt like: What was the weather in Boston on October 17, 2024?. The Gemini models may not know this weather information; however, imagine that you know of an external weather service API that can provide it. The scenario in this guide relies on this hypothetical external API.

Write the function in your app that will interact with the hypothetical external API and provide the model with the information it needs to generate its final request. In this weather example, it will be a fetchWeather function that makes the call to this hypothetical external API.

Swift 

// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
func fetchWeather(city: String, state: String, date: String) -> JSONObject {

  // TODO(developer): Write a standard function that would call an external weather API.

  // For demo purposes, this hypothetical response is hardcoded here in the expected format.
  return [
    "temperature": .number(38),
    "chancePrecipitation": .string("56%"),
    "cloudConditions": .string("partlyCloudy"),
  ]
}

Kotlin 

// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
// `location` is an object of the form { city: string, state: string }
data class Location(val city: String, val state: String)

suspend fun fetchWeather(location: Location, date: String): JsonObject {

    // TODO(developer): Write a standard function that would call to an external weather API.

    // For demo purposes, this hypothetical response is hardcoded here in the expected format.
    return JsonObject(mapOf(
        "temperature" to JsonPrimitive(38),
        "chancePrecipitation" to JsonPrimitive("56%"),
        "cloudConditions" to JsonPrimitive("partlyCloudy")
    ))
}

Java 

// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
// `location` is an object of the form { city: string, state: string }
public JsonObject fetchWeather(Location location, String date) {

  // TODO(developer): Write a standard function that would call to an external weather API.

  // For demo purposes, this hypothetical response is hardcoded here in the expected format.
  return new JsonObject(Map.of(
        "temperature", JsonPrimitive(38),
        "chancePrecipitation", JsonPrimitive("56%"),
        "cloudConditions", JsonPrimitive("partlyCloudy")));
}

Web 

// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
// `location` is an object of the form { city: string, state: string }
async function fetchWeather({ location, date }) {

  // TODO(developer): Write a standard function that would call to an external weather API.

  // For demo purposes, this hypothetical response is hardcoded here in the expected format.
  return {
    temperature: 38,
    chancePrecipitation: "56%",
    cloudConditions: "partlyCloudy",
  };
}

Dart 

// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
// `location` is an object of the form { city: string, state: string }
Future<Map<String, Object?>> fetchWeather(
  Location location, String date
) async {

  // TODO(developer): Write a standard function that would call to an external weather API.

  // For demo purposes, this hypothetical response is hardcoded here in the expected format.
  final apiResponse = {
    'temperature': 38,
    'chancePrecipitation': '56%',
    'cloudConditions': 'partlyCloudy',
  };
  return apiResponse;
}

Unity 

// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
System.Collections.Generic.Dictionary<string, object> FetchWeather(
    string city, string state, string date) {

  // TODO(developer): Write a standard function that would call an external weather API.

  // For demo purposes, this hypothetical response is hardcoded here in the expected format.
  return new System.Collections.Generic.Dictionary<string, object>() {
    {"temperature", 38},
    {"chancePrecipitation", "56%"},
    {"cloudConditions", "partlyCloudy"},
  };
}

Step 2: Create a function declaration

Create the function declaration that you'll later provide to the model (next step of this guide).

In your declaration, include as much detail as possible in the descriptions for the function and its parameters.

The model uses the information in the function declaration to determine which function to select and how to provide parameter values for the actual call to the function. See Additional behaviors and options later on this page for how the model may choose among the functions, as well as how you can control that choice.

Note the following about the schema that you provide:

  • You must provide function declarations in a schema format that's compatible with the OpenAPI schema. Agent Platform offers limited support of the OpenAPI schema.

    • The following attributes are supported: type, nullable, required, format, description, properties, items, enum.

    • The following attributes are not supported: default, optional, maximum, oneOf.

  • By default, for Firebase AI Logic SDKs, all fields are considered required unless you specify them as optional in an optionalProperties array. For these optional fields, the model can populate the fields or skip them. Note that this is opposite from the default behavior of the two Gemini API providers if you use their server SDKs or their API directly.

For best practices related to the function declarations, including tips for names and descriptions, see Best practices in the Gemini Developer API documentation.

Here's how you can write a function declaration:

Swift 

let fetchWeatherTool = FunctionDeclaration(
  name: "fetchWeather",
  description: "Get the weather conditions for a specific city on a specific date.",
  parameters: [
    "location": .object(
      properties: [
        "city": .string(description: "The city of the location."),
        "state": .string(description: "The US state of the location."),
      ],
      description: """
      The name of the city and its state for which to get the weather. Only cities in the
      USA are supported.
      """
    ),
    "date": .string(
      description: &quot;""
      The date for which to get the weather. Date must be in the format: YYYY-MM-DD.
      """
    ),
  ]
)

Kotlin 

val fetchWeatherTool = FunctionDeclaration(
    "fetchWeather",
    "Get the weather conditions for a specific city on a specific date.",
    mapOf(
        "location" to Schema.obj(
            mapOf(
                "city" to Schema.string("The city of the location."),
                "state" to Schema.string("The US state of the location."),
            ),
            description = "The name of the city and its state for which " +
                "to get the weather. Only cities in the " +
                "USA are supported."
        ),
        "date" to Schema.string("The date for which to get the weather." +
                                " Date must be in the format: YYYY-MM-DD."
        ),
    ),
)

Java 

FunctionDeclaration fetchWeatherTool = new FunctionDeclaration(
        "fetchWeather",
        "Get the weather conditions for a specific city on a specific date.",
        Map.of("location",
                Schema.obj(Map.of(
                        "city", Schema.str("The city of the location."),
                        "state", Schema.str("The US state of the location."))),
                "date",
                Schema.str("The date for which to get the weather. " +
                              "Date must be in the format: YYYY-MM-DD.")),
        Collections.emptyList());

Web 

const fetchWeatherTool: FunctionDeclarationsTool = {
  functionDeclarations: [
   {
      name: "fetchWeather",
      description:
        "Get the weather conditions for a specific city on a specific date",
      parameters: Schema.object({
        properties: {
          location: Schema.object({
            description:
              "The name of the city and its state for which to get " +
              "the weather. Only cities in the USA are supported.",
            properties: {
              city: Schema.string({
                description: "The city of the location."
              }),
              state: Schema.string({
                description: "The US state of the location."
              }),
            },
          }),
          date: Schema.string({
            description:
              "The date for which to get the weather. Date must be in the" +
              &quot; format: YYYY-MM-DD.",
          }),
        },
      }),
    },
  ],
};

Dart 

final fetchWeatherTool = FunctionDeclaration(
    'fetchWeather',
    'Get the weather conditions for a specific city on a specific date.',
    parameters: {
      'location': Schema.object(
        description:
          'The name of the city and its state for which to get'
          'the weather. Only cities in the USA are supported.',
        properties: {
          'city': Schema.string(
             description: 'The city of the location.'
           ),
          'state': Schema.string(
             description: 'The US state of the location.'
          ),
        },
      ),
      'date': Schema.string(
        description:
          'The date for which to get the weather. Date must be in the format: YYYY-MM-DD.'
      ),
    },
  );

Unity 

var fetchWeatherTool = new Tool(new FunctionDeclaration(
  name: "fetchWeather",
  description: "Get the weather conditions for a specific city on a specific date.",
  parameters: new System.Collection<s.Generic.Dict>ionarystring, Schema() {
    { "location", Schema.Object(
      properties: new System.<Collections.Ge>neric.Dictionarystring, Schema() {
        { "city", Schema.String(description: "The city of the location.") },
        { "state", Schema.String(description: "The US state of the location.")}
      },
      description: "The name of the city and its state for which to get the weather. Only cities in the USA are supported."
    ) },
    { "date", Schema.String(
      description: "The date for which to get the weather. Date must be in the format: YYYY-MM-DD."
    )}
  }
));

Step 3: Provide the function declaration during model initialization

The maximum number of function declarations that you can provide with the request is 128. See Additional behaviors and options later on this page for how the model may choose among the functions, as well as how you can control that choice (using a toolConfig to set the function calling mode).

Swift 

Tool])]
)

import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports your use case.
let model = FirebaseAI.firebaseAI(backend: .googleAI()).generativeModel(
  modelName: "GEMINI_MODEL_NAME",
  // Provide the function declaration to the model.
  tools: [.functionDeclarations([fetchWeatherTool])]
)

Kotlin 

Tool)))
)

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports your use case.
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).generativeModel(
    mod<elN>ame = "varGE<MINI>_MODEL_NAME/var",
    // Provide the function declaration to the model.
    tools = listOf(Tool.functionDeclarations(listOf(fetchWeatherTool)))
)

Java 

ool)))));

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports your use case.
GenerativeModelFutures model = GenerativeModelFutures.from(
        FirebaseAI.getInstance(GenerativeBackend.googleAI())
                .generat<ive>Model("varGE<MINI>_MODEL_NAME/var",
                        null,
                        null,
                        // Provide the function declaration to the model.
                        List.of(Tool.functionDeclarations(List.of(fetchWeatherTool)))));

Web 

el.
  tools: fetchWeatherTool
});

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// TODO(developer): Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const