Combinare strumenti integrati e chiamate di funzione

Gemini consente di combinare strumenti integrati, come google_search, e chiamate di funzione (note anche come strumenti personalizzati) in una singola interazione, mantenendo ed esponendo la cronologia del contesto delle chiamate allo strumento. Le combinazioni di strumenti integrati e personalizzati consentono flussi di lavoro complessi e agentivi in cui, ad esempio, il modello può basarsi su dati web in tempo reale prima di chiamare la logica di business specifica.

Ecco un esempio che consente combinazioni di strumenti integrati e personalizzati con google_search e una funzione personalizzata 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-flash-preview",
    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-flash-preview",
    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" \
-H "Api-Revision: 2026-05-20" \
-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 dello strumento per consentire combinazioni di strumenti integrati e personalizzati. La circolazione del contesto dello strumento consente di mantenere ed esporre il contesto degli strumenti integrati e di condividerlo con gli strumenti personalizzati nella stessa interazione.

Attivare la combinazione di strumenti

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

Passaggi restituiti dall'API

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

• Passaggi dello strumento integrato: l'API li gestisce automaticamente, mantenendo il contesto tra i turni.
• Passaggi della chiamata di funzione: l'API restituisce i passaggi function_call per le 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 mappa una chiamata alla relativa risposta.
• signature: si trova nei passaggi thought, nonché in tutti i passaggi di chiamata allo strumento (ad es. function_call) e di risultato (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à senza stato: quando gestisci manualmente la cronologia delle conversazioni, devi assicurarti di restituire 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 automaticamente questa operazione se restituisci l'oggetto di risposta completo alla cronologia.

Dati specifici dello strumento

Alcuni strumenti integrati restituiscono argomenti di dati visibili all'utente specifici per il tipo di strumento.

Token e prezzi

Tieni presente che le parti della chiamata allo strumento integrato nelle richieste vengono conteggiate in prompt_token_count. Poiché questi passaggi intermedi dello strumento sono ora visibili e ti vengono restituiti, fanno parte della cronologia delle conversazioni. Questo vale solo per il caso per richieste, non per risposte.

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

Per ulteriori informazioni, consulta la pagina Token.

Limitazioni

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

Strumenti supportati

La circolazione del contesto dello strumento standard si applica agli strumenti lato server (integrati). Anche Esecuzione di codice è uno strumento lato server, ma ha una propria soluzione integrata per la circolazione del contesto. Utilizzo del computer e chiamate di funzione sono strumenti lato client e hanno anche soluzioni integrate per la circolazione del contesto.

Passaggi successivi

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