Combinare strumenti integrati e chiamata di funzione

Gemini consente la combinazione di strumenti integrati, come google_search, e chiamata di funzioni (nota anche come strumenti personalizzati) in una singola interazione conservando ed esponendo la cronologia del contesto delle chiamate agli strumenti. Le combinazioni di strumenti integrati e personalizzati consentono workflow complessi e basati su agenti in cui, ad esempio, il modello può basarsi su dati web in tempo reale prima di richiamare la logica di business specifica.

Ecco un esempio che consente combinazioni di strumenti integrati e personalizzati con google_search e una funzione personalizzata 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"]
      }
    }
  ]
}'

Come funziona

I modelli Gemini 3 utilizzano la circolazione del contesto degli strumenti per consentire combinazioni di strumenti integrati e personalizzati. La circolazione del contesto degli strumenti consente di preservare ed esporre il contesto degli strumenti integrati e condividerlo con gli strumenti personalizzati nella stessa interazione.

Abilitare la combinazione di strumenti

• Includi function_declarations, insieme agli strumenti integrati che vuoi utilizzare, per attivare il comportamento della combinazione.

Passaggi per i resi API

In una risposta all'interazione, l'API restituisce passaggi separati per le chiamate allo strumento integrato e alla funzione (strumento personalizzato):

• Passaggi dello strumento integrato: l'API li gestisce automaticamente, preservando il contesto tra i turni.
• Passaggi della chiamata di funzione: l'API restituisce function_call passaggi per le tue funzioni personalizzate. Esegui la funzione e fornisci il risultato.

Campi critici nei passaggi restituiti

Alcuni campi nei passaggi restituiti sono fondamentali per mantenere il contesto dello strumento e consentire le combinazioni di strumenti:

• id: si trova nei passaggi function_call e function_response. Un identificatore univoco che associa una chiamata alla relativa risposta.
• signature: presente nei passaggi thought, nonché in tutti i passaggi di chiamata dello strumento (ad es. function_call) e dei risultati (ad es. function_response) per i modelli Gemini 3+. Questo contesto criptato consente la circolazione del contesto dello strumento tra le interazioni.

Gestione di questi campi:

• Modalità con stato (consigliata): quando utilizzi previous_interaction_id, il server gestisce automaticamente i campi id e signature.
• Modalità stateless: quando gestisci manualmente la cronologia delle conversazioni, devi assicurarti di trasmettere al modello sia il campo id sia il campo signature nelle richieste successive per convalidare l'autenticità e mantenere il contesto. Gli SDK ufficiali gestiscono questa operazione automaticamente se passi l'oggetto della risposta completo alla cronologia.

Dati specifici dello strumento

Alcuni strumenti integrati restituiscono argomenti di dati visibili agli utenti specifici per il tipo di strumento.

Token e prezzi

Tieni presente che le parti di chiamata dello strumento integrate nelle richieste vengono conteggiate ai fini di prompt_token_count. Poiché questi passaggi intermedi dello strumento sono ora visibili e ti vengono restituiti, fanno parte della cronologia della conversazione. Questo vale solo per le richieste, non per le risposte.

Lo strumento Ricerca Google è un'eccezione a questa regola. La Ricerca Google applica già il proprio modello di prezzi a livello di query, pertanto i token non vengono addebitati due volte (vedi la pagina Prezzi).

Per saperne di più, consulta la pagina Token.

Limitazioni

• Impostazione predefinita della modalità validated (la modalità auto non è supportata) quando è attivata la circolazione del contesto dello strumento.
• Gli strumenti integrati come google_search si basano su informazioni relative alla posizione e all'ora corrente, quindi se system_instruction o function_declaration.description hanno informazioni su posizione e ora in conflitto, la funzionalità di combinazione degli strumenti potrebbe non funzionare correttamente.

Strumenti supportati

La circolazione del contesto degli strumenti standard si applica agli strumenti lato server (integrati). Code Execution è anche uno strumento lato server, ma ha una propria soluzione integrata per la circolazione del contesto. L'utilizzo del computer e la chiamata di funzioni sono strumenti lato client e dispongono anche di soluzioni integrate per la circolazione del contesto.

Passaggi successivi

• Scopri di più sulla chiamata di funzione nell'API Gemini.
• Esplora gli strumenti supportati:
  • la Ricerca Google
  • Google Maps
  • Contesto URL
  • Ricerca file