Łączenie wbudowanych narzędzi i wywoływania funkcji

Gemini umożliwia łączenie wbudowanych narzędzi, takich jak google_search, i wywoływania funkcji (znanych też jako narzędzia niestandardowe) w ramach jednej interakcji poprzez zachowanie i udostępnienie historii kontekstu wywołań narzędzi. Kombinacje narzędzi wbudowanych i niestandardowych umożliwiają złożone przepływy pracy, w których np. model może opierać się na danych internetowych w czasie rzeczywistym przed wywołaniem konkretnej logiki biznesowej.

Oto przykład, który umożliwia łączenie narzędzi wbudowanych i niestandardowych za pomocą google_search i funkcji niestandardowej 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"]
      }
    }
  ]
}'

Jak to działa

Modele Gemini 3 używają cyrkulacji kontekstu narzędzia, aby umożliwić łączenie narzędzi wbudowanych i niestandardowych. Cyrkulacja kontekstu narzędzia umożliwia zachowanie i udostępnienie kontekstu narzędzi wbudowanych oraz udostępnienie go narzędziom niestandardowym w ramach tej samej interakcji.

Włączanie łączenia narzędzi

• Aby wywołać zachowanie kombinacji, uwzględnij function_declarations wraz z narzędziami wbudowanymi, których chcesz użyć.

Kroki zwracane przez interfejs API

W odpowiedzi na interakcję interfejs API zwraca osobne kroki dla wywołań narzędzi wbudowanych i wywołań funkcji (narzędzi niestandardowych):

• Kroki narzędzi wbudowanych: interfejs API zarządza nimi automatycznie, zachowując kontekst w kolejnych turach.
• Kroki wywołań funkcji: interfejs API zwraca kro2/}ki dla Twoich funkcji niestandardowych.function_call Wykonujesz funkcję i podajesz wynik.

Krytyczne pola w zwracanych krokach

Niektóre pola w zwracanych krokach są niezbędne do zachowania kontekstu narzędzia i umożliwienia łączenia narzędzi:

• id: znajduje się w krokach function_call i function_response. Unikalny identyfikator, który mapuje wywołanie na jego odpowiedź.
• signature: znajduje się w krokach thought oraz we wszystkich krokach wywołań narzędzi (np. function_call) i wyników (np. function_response) w przypadku modeli Gemini 3 i nowszych. Ten zaszyfrowany kontekst umożliwia cyrkulację kontekstu narzędzia w ramach interakcji.

Zarządzanie tymi polami:

• Tryb stanowy (zalecany): gdy używasz previous_interaction_id, serwer automatycznie obsługuje pola id i signature.
• Tryb bezstanowy: podczas ręcznego zarządzania historią rozmów musisz się upewnić, że w kolejnych żądaniach przekazujesz do modelu zarówno pole id, jak i pole signature, aby zweryfikować autentyczność i zachować kontekst. Oficjalne pakiety SDK obsługują to automatycznie, jeśli przekazujesz pełny obiekt odpowiedzi do historii.

Dane specyficzne dla narzędzia

Niektóre narzędzia wbudowane zwracają argumenty danych widoczne dla użytkownika, które są specyficzne dla typu narzędzia.

Tokeny i ceny

Pamiętaj, że części wywołań narzędzi wbudowanych w żądaniach są wliczane do prompt_token_count. Ponieważ te pośrednie kroki narzędzi są teraz widoczne i zwracane, stanowią część historii rozmowy. Dotyczy to tylko przypadku żądań, a nie odpowiedzi.

Wyjątkiem od tej reguły jest narzędzie wyszukiwarki Google. Wyszukiwarka Google stosuje już własny model cenowy na poziomie zapytania, więc tokeny nie są naliczane podwójnie (patrz strona Ceny).

Więcej informacji znajdziesz na stronie Tokeny.

Ograniczenia

• Gdy włączona jest cyrkulacja kontekstu narzędzia, domyślnie używaj trybu validated (tryb auto nie jest obsługiwany).
• Narzędzia wbudowane, takie jak google_search, korzystają z informacji o lokalizacji i aktualnym czasie, więc jeśli system_instruction lub function_declaration.description zawierają sprzeczne informacje o lokalizacji i czasie, funkcja łączenia narzędzi może nie działać prawidłowo.

Obsługiwane narzędzia

Standardowa cyrkulacja kontekstu narzędzia dotyczy narzędzi po stronie serwera (wbudowanych). Wykonywanie kodu to też narzędzie po stronie serwera, ale ma własne wbudowane rozwiązanie do cyrkulacji kontekstu. Korzystanie z komputera i wywoływanie funkcji to narzędzia po stronie klienta, które też mają wbudowane rozwiązania do cyrkulacji kontekstu.

Co dalej?

• Dowiedz się więcej o wywoływaniu funkcji w interfejsie Gemini API.
• Poznaj obsługiwane narzędzia:
  • Wyszukiwarka Google
  • Mapy Google
  • Kontekst adresu URL
  • Wyszukiwanie plików