Integrierte Tools und Funktionsaufrufe kombinieren

Mit Gemini können integrierte Tools wie google_search und Funktionsaufrufe (auch benutzerdefinierte Tools genannt) in einer einzigen Interaktion kombiniert werden, indem der Kontextverlauf von Tool-Aufrufen beibehalten und verfügbar gemacht wird. Mit integrierten und benutzerdefinierten Tool-Kombinationen lassen sich komplexe, agentenbasierte Workflows erstellen. Das Modell kann sich beispielsweise auf Webdaten in Echtzeit stützen, bevor es Ihre spezifische Geschäftslogik aufruft.

Hier ist ein Beispiel, in dem integrierte und benutzerdefinierte Toolkombinationen mit google_search und einer benutzerdefinierten Funktion getWeather aktiviert werden:

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"]
      }
    }
  ]
}'

Funktionsweise

Gemini 3-Modelle verwenden Tool-Kontextzirkulation, um integrierte und benutzerdefinierte Tool-Kombinationen zu ermöglichen. Durch die Weitergabe des Tool-Kontexts kann der Kontext integrierter Tools beibehalten und verfügbar gemacht werden und mit benutzerdefinierten Tools in derselben Interaktion geteilt werden.

Tool-Kombination aktivieren

• Fügen Sie die function_declarations zusammen mit den integrierten Tools, die Sie verwenden möchten, hinzu, um das Kombinationsverhalten auszulösen.

Schritte für die API-Rückgabe

In einer Interaktionsantwort gibt die API separate Schritte für integrierte Tool-Aufrufe und Funktionsaufrufe (benutzerdefinierte Tools) zurück:

• Integrierte Tool-Schritte: Diese werden von der API automatisch verwaltet und der Kontext bleibt über mehrere Turns hinweg erhalten.
• Schritte für Funktionsaufrufe: Die API gibt function_call-Schritte für Ihre benutzerdefinierten Funktionen zurück. Sie führen die Funktion aus und geben das Ergebnis zurück.

Kritische Felder in zurückgegebenen Schritten

Bestimmte Felder in den zurückgegebenen Schritten sind entscheidend, um den Tool-Kontext beizubehalten und Tool-Kombinationen zu ermöglichen:

• id: In den Schritten function_call und function_response gefunden. Eine eindeutige Kennung, die einen Aufruf seiner Antwort zuordnet.
• signature: In thought-Schritten sowie in allen Tool-Aufruf- (z.B. function_call) und Ergebnisschritten (z.B. function_response) für Gemini 3+-Modelle. Dieser verschlüsselte Kontext ermöglicht die Weitergabe des Tool-Kontexts über Interaktionen hinweg.

Felder verwalten:

• Zustandsorientierter Modus (empfohlen): Wenn Sie previous_interaction_id verwenden, verarbeitet der Server automatisch die Felder id und signature.
• Zustandsloser Modus: Wenn Sie den Unterhaltungsverlauf manuell verwalten, müssen Sie dafür sorgen, dass Sie sowohl das Feld id als auch das Feld signature in nachfolgenden Anfragen an das Modell zurückgeben, um die Authentizität zu bestätigen und den Kontext beizubehalten. Die offiziellen SDKs verarbeiten dies automatisch, wenn Sie das vollständige Antwortobjekt an den Verlauf zurückgeben.

Tool-spezifische Daten

Einige integrierte Tools geben nutzersichtbare Datenargumente zurück, die für den jeweiligen Tooltyp spezifisch sind.

Tokens und Preise

Beachten Sie, dass integrierte Tool-Aufruf-Teile in Anfragen auf prompt_token_count angerechnet werden. Da diese Zwischenschritte des Tools jetzt sichtbar sind und an Sie zurückgegeben werden, sind sie Teil des Unterhaltungsverlaufs. Dies ist nur bei Anfragen der Fall, nicht bei Antworten.

Das Tool für die Google Suche ist eine Ausnahme von dieser Regel. Die Google Suche wendet bereits ein eigenes Preismodell auf Abfrageebene an. Daher werden Tokens nicht doppelt berechnet (siehe Seite „Preise“).

Weitere Informationen finden Sie auf der Seite Tokens.

Beschränkungen

• Standardmäßig wird der Modus validated verwendet (der Modus auto wird nicht unterstützt), wenn die Toolkontext-Zirkulation aktiviert ist.
• Integrierte Tools wie google_search basieren auf Standort- und Uhrzeitinformationen. Wenn Ihr system_instruction oder function_declaration.description widersprüchliche Standort- und Uhrzeitinformationen enthält, funktioniert die Funktion für die Kombination von Tools möglicherweise nicht richtig.

Unterstützte Tools

Die standardmäßige Weitergabe des Toolkontexts gilt für serverseitige (integrierte) Tools. Die Codeausführung ist ebenfalls ein serverseitiges Tool, hat aber eine eigene integrierte Lösung für die Kontextweitergabe. Die Tool-Nutzung und Funktionsaufrufe sind clientseitige Tools und bieten auch integrierte Lösungen für die Kontextweitergabe.

Nächste Schritte

• Weitere Informationen zu Funktionsaufrufen in der Gemini API
• Unterstützte Tools:
  • Google Suche
  • Google Maps
  • URL-Kontext
  • Dateisuche