Combiner les outils intégrés et l'appel de fonction

Gemini permet de combiner des outils intégrés, tels que google_search, et l'appel de fonction (également appelé outils personnalisés) dans une seule interaction en conservant et en exposant l'historique du contexte des appels d'outils. Les combinaisons d'outils intégrés et personnalisés permettent de créer des workflows complexes et agentiques où, par exemple, le modèle peut s'ancrer dans des données Web en temps réel avant d'appeler votre logique métier spécifique.

Voici un exemple qui permet des combinaisons d'outils intégrés et personnalisés avec google_search et une fonction personnalisée 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"]
      }
    }
  ]
}'

Fonctionnement

Les modèles Gemini 3 utilisent la circulation du contexte des outils pour permettre les combinaisons d'outils intégrés et personnalisés. La circulation du contexte des outils permet de préserver et d'exposer le contexte des outils intégrés, et de le partager avec les outils personnalisés lors de la même interaction.

Activer la combinaison d'outils

• Incluez function_declarations, ainsi que les outils intégrés que vous souhaitez utiliser, pour déclencher le comportement de combinaison.

Étapes de retour de l'API

Dans une réponse d'interaction, l'API renvoie des étapes distinctes pour les appels d'outils intégrés et les appels de fonctions (outils personnalisés) :

• Étapes de l'outil intégré : l'API les gère automatiquement, en préservant le contexte à chaque tour.
• Étapes d'appel de fonction : l'API renvoie des étapes function_call pour vos fonctions personnalisées. Vous exécutez la fonction et renvoyez le résultat.

Champs essentiels dans les étapes renvoyées

Certains champs des étapes renvoyées sont essentiels pour maintenir le contexte de l'outil et permettre les combinaisons d'outils :

• id : se trouve dans les étapes function_call et function_response. Identifiant unique qui associe un appel à sa réponse.
• signature : disponible dans les étapes thought, ainsi que dans toutes les étapes d'appel d'outil (par exemple, function_call) et de résultat (par exemple, function_response) pour les modèles Gemini 3 et versions ultérieures. Ce contexte chiffré permet la circulation du contexte de l'outil lors des interactions.

Gérer ces champs :

• Mode avec état (recommandé) : lorsque vous utilisez previous_interaction_id, le serveur gère automatiquement les champs id et signature.
• Mode sans état : lorsque vous gérez manuellement l'historique des conversations, vous devez vous assurer de renvoyer les champs id et signature au modèle dans les requêtes suivantes pour valider l'authenticité et maintenir le contexte. Les SDK officiels gèrent cela automatiquement si vous renvoyez l'objet de réponse complet à l'historique.

Données spécifiques à l'outil

Certains outils intégrés renvoient des arguments de données visibles par l'utilisateur, spécifiques au type d'outil.

Jetons et tarifs

Notez que les parties d'appel d'outil intégrées dans les requêtes sont comptabilisées dans prompt_token_count. Étant donné que ces étapes intermédiaires de l'outil sont désormais visibles et vous sont renvoyées, elles font partie de l'historique des conversations. Cela ne s'applique qu'aux requêtes, et non aux réponses.

L'outil Recherche Google est une exception à cette règle. La recherche Google applique déjà son propre modèle de tarification au niveau des requêtes. Les jetons ne sont donc pas facturés deux fois (consultez la page Tarifs).

Pour en savoir plus, consultez la page Jetons.

Limites

• Par défaut, le mode validated (le mode auto n'est pas pris en charge) est utilisé lorsque la circulation du contexte de l'outil est activée.
• Les outils intégrés tels que google_search s'appuient sur des informations de localisation et d'heure actuelle. Par conséquent, si votre system_instruction ou votre function_declaration.description comporte des informations de localisation et d'heure incohérentes, la fonctionnalité de combinaison d'outils risque de ne pas fonctionner correctement.

Outils compatibles

La circulation standard du contexte d'outil s'applique aux outils côté serveur (intégrés). L'exécution de code est également un outil côté serveur, mais elle dispose de sa propre solution intégrée pour la circulation du contexte. L'utilisation de l'ordinateur et l'appel de fonctions sont des outils côté client qui disposent également de solutions intégrées pour la circulation du contexte.

Étape suivante

• En savoir plus sur l'appel de fonction dans l'API Gemini
• Découvrez les outils compatibles :
  • La recherche Google
  • Google Maps
  • Contexte de l'URL
  • Recherche de fichiers