Combina herramientas integradas y llamadas a funciones

Gemini permite la combinación de herramientas integradas, como google_search, y llamadas a funciones (también conocidas como herramientas personalizadas) en una sola interacción mediante la preservación y la exposición del historial de contexto de las llamadas a herramientas. Las combinaciones de herramientas integradas y personalizadas permiten flujos de trabajo complejos y de agentes en los que, por ejemplo, el modelo puede basarse en datos web en tiempo real antes de llamar a tu lógica empresarial específica.

Este es un ejemplo que habilita las combinaciones de herramientas integradas y personalizadas con google_search y una función personalizada getWeather:

from google import genai

client = genai.Client()

getWeather = {
    "type": "function",
    "name": "getWeather",
    "description": "Gets the weather for a requested city.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "The city and state, e.g. Utqiaġvik, Alaska",
            },
        },
        "required": ["city"],
    },
}

# The Interactions API manages context automatically across tool calls.
# The model will first use Google Search, then call getWeather.
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the northernmost city in the United States? What's the weather like there today?",
    tools=[
        {"google_search": {}},
        getWeather,
    ],
)

# Process steps: the interaction contains search results and a function call
for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function call: {step.name} with args: {step.arguments}")
        # In a real application, you would execute the function here
        # and provide the result back to the model.

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const getWeather = {
    type: "function",
    name: "getWeather",
    description: "Get the weather in a given location",
    parameters: {
        type: "object",
        properties: {
            location: {
                type: "string",
                description: "The city and state, e.g. San Francisco, CA"
            }
        },
        required: ["location"]
    }
};

// The Interactions API manages context automatically across tool calls.
// The model will first use Google Search, then call getWeather.
const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is the northernmost city in the United States? What's the weather like there today?",
    tools: [
        { googleSearch: {} },
        getWeather,
    ],
});

// Process steps: the interaction contains search results and a function call
for (const step of interaction.steps) {
    if (step.type === "function_call") {
        console.log(`Function call: ${step.name} with args: ${JSON.stringify(step.arguments)}`);
        // In a real application, you would execute the function here
        // and provide the result back to the model.
    }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
  "model": "gemini-3-flash-preview",
  "input": "What is the northernmost city in the United States? What'\''s the weather like there today?",
  "tools": [
    { "type": "google_search" },
    {
      "type": "function",
      "name": "getWeather",
      "description": "Get the weather in a given location",
      "parameters": {
          "type": "object",
          "properties": {
              "location": {
                  "type": "string",
                  "description": "The city and state, e.g. San Francisco, CA"
              }
          },
          "required": ["location"]
      }
    }
  ]
}'

Cómo funciona

Los modelos de Gemini 3 usan la circulación de contexto de herramientas para habilitar combinaciones de herramientas integradas y personalizadas. La circulación de contexto de herramientas permite preservar y exponer el contexto de las herramientas integradas y compartirlo con herramientas personalizadas en la misma interacción.

Habilita la combinación de herramientas

• Incluye function_declarations, junto con las herramientas integradas que deseas usar, para activar el comportamiento de combinación.

Pasos que muestra la API

En una respuesta de interacción, la API muestra pasos separados para las llamadas a herramientas integradas y las llamadas a funciones (herramientas personalizadas):

• Pasos de herramientas integradas: La API los administra automáticamente y preserva el contexto en los turnos.
• Pasos de llamadas a funciones: La API muestra pasos function_call para tus funciones personalizadas. Ejecutas la función y proporcionas el resultado.

Campos críticos en los pasos mostrados

Ciertos campos en los pasos mostrados son fundamentales para mantener el contexto de las herramientas y habilitar las combinaciones de herramientas:

• id: Se encuentra en los pasos function_call y function_response. Es un identificador único que asigna una llamada a su respuesta.
• signature: Se encuentra en los pasos thought, así como en todos los pasos de llamada a herramientas (p.ej., function_call) y de resultado (p.ej., function_response) para los modelos de Gemini 3 y versiones posteriores. Este contexto encriptado permite la circulación de contexto de herramientas en las interacciones.

Administración de estos campos:

• Modo con estado (recomendado): Cuando usas previous_interaction_id, el servidor controla automáticamente los campos id y signature.
• Modo sin estado: Cuando administras el historial de conversaciones de forma manual, debes asegurarte de pasar los campos id y signature al modelo en las solicitudes posteriores para validar la autenticidad y mantener el contexto. Los SDK oficiales controlan esto automáticamente si pasas el objeto de respuesta completo al historial.

Datos específicos de la herramienta

Algunas herramientas integradas muestran argumentos de datos visibles para el usuario que son específicos del tipo de herramienta.

Tokens y precios

Ten en cuenta que las partes de llamadas a herramientas integradas en las solicitudes se cuentan para prompt_token_count. Dado que estos pasos de herramientas intermedias ahora son visibles y se te muestran, forman parte del historial de conversaciones. Este es solo el caso de las solicitudes, no de las respuestas.

La herramienta Búsqueda de Google es una excepción a esta regla. La Búsqueda de Google ya aplica su propio modelo de precios a nivel de la consulta, por lo que los tokens no se cobran dos veces (consulta la página de precios).

Lee la página Tokens para obtener más información.

Limitaciones

• Se establece el modo validated de forma predeterminada (no admitido el modo auto) cuando se habilita la circulación de contexto de herramientas.
• Las herramientas integradas, como google_search, dependen de la información de ubicación y hora actual, por lo que, si tu system_instruction o function_declaration.description tienen información de ubicación y hora en conflicto, es posible que la función de combinación de herramientas no funcione bien.

Herramientas compatibles

La circulación de contexto de herramientas estándar se aplica a las herramientas del lado del servidor (integradas). La ejecución de código también es una herramienta del lado del servidor, pero tiene su propia solución integrada para la circulación de contexto. El uso de la computadora y las llamadas a funciones son herramientas del lado del cliente y también tienen soluciones integradas para la circulación de contexto.

¿Qué sigue?

• Obtén más información sobre las llamadas a funciones en la API de Gemini.
• Explora las herramientas compatibles:
  • Búsqueda de Google
  • Google Maps
  • Contexto de URL
  • Búsqueda de archivos