Advanced Features

Function Calling and Tool Use

Define tools for Gemini to call, handle tool responses, and build reliable agentic workflows with function calling.

Function Calling in Gemini

Function calling (tool use) allows Gemini to interact with your code, APIs, and databases by invoking developer-defined functions. The model decides when and with what arguments to call a function based on the user's request.

How It Works

  1. You define tools with a name, description, and parameter schema
  2. Gemini returns a functionCall part when it wants to invoke a tool
  3. You execute the function and return the result
  4. Gemini generates a final response using the tool result

Defining Tools

Tools use JSON Schema to describe their parameters. Good descriptions are critical — Gemini reads them to decide when to call each tool.

Tool Config Options

ModeBehavior
AUTOGemini decides whether to call a function (default)
ANYForce function use (pick from the list)
NONEDisable function calling entirely

Parallel Function Calls

Gemini can request multiple function calls in a single turn, executing them in parallel. This significantly speeds up agentic workflows where multiple independent data sources must be queried.

Structured Output vs Function Calling

Use JSON mode (response_mime_type) when you want structured data output. Use function calling when you want the model to actually trigger actions or fetch external data.

Example

typescript
import { GoogleGenerativeAI, FunctionDeclarationSchemaType } from "@google/generative-ai";

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

// Define tools
const tools = [{
  functionDeclarations: [
    {
      name: "get_weather",
      description: "Get the current weather for a city. Use when the user asks about weather.",
      parameters: {
        type: FunctionDeclarationSchemaType.OBJECT,
        properties: {
          city: { type: FunctionDeclarationSchemaType.STRING, description: "The city name" },
          units: {
            type: FunctionDeclarationSchemaType.STRING,
            enum: ["celsius", "fahrenheit"],
            description: "Temperature units",
          },
        },
        required: ["city"],
      },
    },
    {
      name: "search_docs",
      description: "Search the product documentation for a given query.",
      parameters: {
        type: FunctionDeclarationSchemaType.OBJECT,
        properties: {
          query: { type: FunctionDeclarationSchemaType.STRING, description: "Search query" },
        },
        required: ["query"],
      },
    },
  ],
}];

const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro", tools });

// Agent loop
async function runAgent(userMessage: string) {
  const chat = model.startChat();
  let response = await chat.sendMessage(userMessage);

  while (response.response.candidates?.[0]?.content?.parts?.some(p => p.functionCall)) {
    const calls = response.response.candidates[0].content.parts
      .filter(p => p.functionCall)
      .map(p => p.functionCall!);

    // Execute all tool calls (can be parallel)
    const results = await Promise.all(calls.map(async call => ({
      functionResponse: {
        name: call.name,
        response: call.name === "get_weather"
          ? { temperature: 22, condition: "Sunny", city: call.args.city }
          : { results: ["Gemini supports function calling since May 2024"] },
      },
    })));

    response = await chat.sendMessage(results);
  }

  return response.response.text();
}

const answer = await runAgent("What's the weather in Tokyo and find docs on function calling?");
console.log(answer);
Try it yourself — TYPESCRIPT