Function calling tutorial

Function calling makes it easier for you to get structured data outputs from generative models. You can then use these outputs to call other APIs and return the relevant response data to the model. In other words, function calling helps you connect generative models to external systems so that the generated content includes the most up-to-date and accurate information.

If you haven't already, check out the Introduction to function calling to learn more.

This tutorial shows you how to set up a Function Call for the Gemini API to interpret users lighting requests and map them to API settings to control a light's brightness and color temperature values.

Define an API function

Create a function that makes an API request. This function should be defined within the code of your application, but could call services or APIs outside of your application. The Gemini API does not call this function directly, so you can control how and when this function is executed through your application code. For demonstration purposes, this tutorial defines a mock API function that just returns the requested lighting values:

async function setLightValues(brightness, colorTemp) {
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

Create function declarations

Create the function declaration that you'll pass to the generative model. When you declare a function for use by the model, you should include as much detail as possible in the function and parameter descriptions. The generative model uses this information to determine which function to select and how to provide values for the parameters in the function call. The following code shows how to declare the lighting control function:

const controlLightFunctionDeclaration = {
  name: "controlLight",
  parameters: {
    type: "OBJECT",
    description: "Set the brightness and color temperature of a room light.",
    properties: {
      brightness: {
        type: "NUMBER",
        description: "Light level from 0 to 100. Zero is off and 100 is full brightness.",
      },
      colorTemperature: {
        type: "STRING",
        description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`.",
      },
    },
    required: ["brightness", "colorTemperature"],
  },
};

// Put functions in a "map" keyed by the function name so it is easier to call
const functions = {
  controlLight: ({ brightness, colorTemperature }) => {
    return setLightValues( brightness, colorTemperature)
  }
};

Declare functions during model initialization

When you want to use function calling with a model, you must provide your function declarations when you initialize the model object. You declare functions by setting the model's tools parameter:

const { GoogleGenerativeAI } = require("@google/generative-ai");

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

const generativeModel = genAI.getGenerativeModel({
  model: "gemini-2.0-flash",
  // Specify the function declaration.
  tools: {
    functionDeclarations: [controlLightFunctionDeclaration],
  },
});

Generate a function call

Once you have initialized the model with your function declarations, you can prompt the model with the defined function. You should use function calling using chat prompting (sendMessage()), since function calling generally benefits from having the context of previous prompts and responses.

const chat = generativeModel.startChat();
const prompt = "Dim the lights so the room feels cozy and warm.";

const result = await chat.sendMessage(prompt);
const call = result.response.functionCalls()[0];

if (call) {
  // Call the executable function
  const apiResponse = await functions[call.name](call.args);

  // Send the API response back to the model
  const result2 = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

  // Log the text response.
  console.log(result2.response.text());
}

Function calling mode

You can use the function calling mode parameter to modify the execution behavior of the feature. 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. 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 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.

You can specify the function calling mode by setting a toolConfig parameter when initializing the generative model.

const generativeModel2 = genAI.getGenerativeModel({
  // Setting a function calling mode is only available in Gemini 1.5 Pro.
  model: "gemini-1.5-pro-latest",
  tools: {
    functionDeclarations: [getExchangeRateFunctionDeclaration],
  },
  toolConfig: {
    functionCallingConfig: {
      // Possible values are: Mode.AUTO, Mode.ANY, Mode.NONE
      mode: FunctionCallingMode.ANY
    }
  }
});