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

Gemini umożliwia łączenie wbudowanych narzędzi, takich jak google_search, i wywoływanie funkcji (znanych też jako narzędzia niestandardowe) w ramach jednej interakcji przez zachowywanie i udostępnianie historii kontekstu wywołań narzędzi. Wbudowane i niestandardowe kombinacje narzędzi umożliwiają tworzenie złożonych przepływów pracy opartych na agentach, 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 korzystanie z wbudowanych i niestandardowych kombinacji narzędzi z użyciem google_search i funkcji niestandardowej 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"]
      }
    }
  ]
}'

Jak to działa

Modele Gemini 3 korzystają z obiegu kontekstu narzędzia, aby umożliwić wbudowane i niestandardowe kombinacje narzędzi. Przekazywanie kontekstu narzędzia umożliwia zachowanie i udostępnianie kontekstu wbudowanych narzędzi oraz dzielenie się nim z narzędziami niestandardowymi w ramach tej samej interakcji.

Włączanie kombinacji narzędzi

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

Instrukcje dotyczące zwrotów w przypadku interfejsu API

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

• Wbudowane narzędzie: interfejs API zarządza tymi elementami automatycznie, zachowując kontekst w kolejnych turach.
• Kroki wywołania funkcji: interfejs API zwraca function_call kroków dla Twoich funkcji niestandardowych. Wykonujesz funkcję i zwracasz wynik.

Krytyczne pola w zwracanych krokach

Niektóre pola w zwróconych krokach mają kluczowe znaczenie dla zachowania kontekstu narzędzia i umożliwienia kombinacji narzędzi:

• id: Znajduje się w krokach function_call i function_response. Unikalny identyfikator, który mapuje wywołanie na odpowiedź.
• signature: występuje w krokach thought, a także we wszystkich krokach wywołania narzędzia (np. function_call) i wyniku (np. function_response) w przypadku modeli Gemini 3+. Ten zaszyfrowany kontekst umożliwia przekazywanie kontekstu narzędzia między interakcjami.

Zarządzanie tymi polami:

• Tryb stanowy (zalecany): gdy używasz previous_interaction_id, serwer automatycznie obsługuje pola id i signature.
• Tryb bezstanowy: gdy ręcznie zarządzasz historią rozmów, musisz w kolejnych żądaniach przekazywać do modelu pola id i signature, aby potwierdzić autentyczność i zachować kontekst. Oficjalne pakiety SDK obsługują to automatycznie, jeśli przekażesz pełny obiekt odpowiedzi z powrotem do historii.

Dane dotyczące narzędzia

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

Tokeny i ceny

Pamiętaj, że wbudowane części wywołań narzędzi w żądaniach są wliczane do limitu prompt_token_count. Ponieważ te pośrednie kroki narzędzia są teraz widoczne i zwracane do Ciebie, stanowią część historii rozmowy. Dotyczy to tylko żą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

• Domyślnie tryb validated (tryb auto nie jest obsługiwany), gdy włączone jest przekazywanie kontekstu narzędzia.
• Wbudowane narzędzia, takie jak google_search, korzystają z informacji o lokalizacji i bieżącym czasie, więc jeśli system_instruction lub function_declaration.description mają sprzeczne informacje o lokalizacji i czasie, funkcja łączenia narzędzi może nie działać prawidłowo.

Obsługiwane narzędzia

W przypadku narzędzi po stronie serwera (wbudowanych) obowiązuje standardowe przekazywanie kontekstu narzędzia. Wykonywanie kodu to również narzędzie po stronie serwera, ale ma własne wbudowane rozwiązanie do przekazywania kontekstu. Korzystanie z komputera i wywoływanie funkcji to narzędzia po stronie klienta, które mają też wbudowane rozwiązania do przekazywania kontekstu.

Co dalej?

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