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 préservant 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 autonomes où, par exemple, le modèle peut s'appuyer sur des données Web en temps réel avant d'appeler votre logique métier spécifique.

Voici un exemple qui active les combinaisons d'outils intégrés et personnalisés avec google_search et une fonction personnalisée getWeather :

# This will only work for SDK newer than 2.0.0
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.5-flash",
    input="What is the northernmost city in the United States? What's the weather like there today?",
    tools=[
        {"type": "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.

// This will only work for SDK newer than 2.0.0
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.5-flash",
    input: "What is the northernmost city in the United States? What's the weather like there today?",
    tools: [
        { type: "google_search" },
        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.
    }
}

# Specifies the API revision to avoid breaking changes when they become default
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.5-flash",
  "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 d'outil pour activer les combinaisons d'outils intégrés et personnalisés. La circulation du contexte d'outil permet de préserver et d'exposer le contexte des outils intégrés, et de le partager avec des outils personnalisés dans la même interaction.

Activer la combinaison d'outils

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

Étapes renvoyées par 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 fonction (outil personnalisé) :

• Étapes d'outil intégré : l'API les gère automatiquement, en préservant le contexte entre les tours.
• Étapes d'appel de fonction : l'API renvoie des étapes function_call pour vos fonctions personnalisées. Vous exécutez la fonction et fournissez 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 activer les combinaisons d'outils :

• id: se trouve dans les étapes function_call et function_response. Identifiant unique qui mappe un appel à sa réponse.
• signature: se trouve 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 d'outil entre les 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é dans les requêtes sont comptabilisées dans prompt_token_count. Étant donné que ces étapes d'outil intermédiaires sont désormais visibles et vous sont renvoyées, elles font partie de l'historique des conversations. Cela ne s'applique qu'aux cas de 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 de la requête. Les jetons ne sont donc pas facturés deux fois (consultez la page des tarifs).

Pour en savoir plus, consultez la page Jetons.

Limites

• Par défaut, le mode validated est activé (le mode auto n'est pas compatible) lorsque la circulation du contexte d'outil est activée.
• Les outils intégrés tels que google_search s'appuient sur des informations de localisation et d'heure actuelles. Par conséquent, si votre system_instruction ou function_declaration.description contient des informations de localisation et d'heure conflictuelles, 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 fonction sont des outils côté client, et 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