Menggabungkan alat bawaan dan panggilan fungsi

Gemini memungkinkan kombinasi alat bawaan, seperti google_search, dan panggilan fungsi (juga dikenal sebagai alat kustom) dalam satu interaksi dengan mempertahankan dan mengekspos histori konteks panggilan alat. Kombinasi alat bawaan dan kustom memungkinkan alur kerja yang kompleks dan seperti agen, misalnya, model dapat mendasarkan dirinya pada data web real-time sebelum memanggil logika bisnis spesifik Anda.

Berikut adalah contoh yang memungkinkan kombinasi alat bawaan dan kustom dengan google_search dan fungsi kustom 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"]
      }
    }
  ]
}'

Cara kerjanya

Model Gemini 3 menggunakan sirkulasi konteks alat untuk mengaktifkan kombinasi alat bawaan dan kustom. Sirkulasi konteks alat memungkinkan konteks alat bawaan dipertahankan dan diekspos, serta dibagikan dengan alat kustom dalam interaksi yang sama.

Mengaktifkan kombinasi alat

• Sertakan function_declarations, beserta alat bawaan yang ingin Anda gunakan, untuk memicu perilaku kombinasi.

Langkah-langkah pengembalian API

Dalam respons interaksi, API menampilkan langkah-langkah terpisah untuk panggilan alat bawaan dan panggilan fungsi (alat kustom):

• Langkah-langkah alat bawaan: API mengelola langkah-langkah ini secara otomatis, dengan mempertahankan konteks di seluruh giliran.
• Langkah-langkah panggilan fungsi: API menampilkan function_call langkah untuk fungsi kustom Anda. Anda menjalankan fungsi dan memberikan hasilnya kembali.

Kolom penting dalam langkah yang ditampilkan

Kolom tertentu dalam langkah yang ditampilkan sangat penting untuk mempertahankan konteks alat dan memungkinkan kombinasi alat:

• id: Ditemukan di langkah function_call dan function_response. ID unik yang memetakan panggilan ke responsnya.
• signature: Ditemukan di langkah thought, serta semua langkah panggilan alat (misalnya, function_call) dan hasil (misalnya, function_response) untuk model Gemini 3+. Konteks terenkripsi ini memungkinkan sirkulasi konteks alat di seluruh interaksi.

Mengelola kolom ini:

• Mode Stateful (Direkomendasikan): Saat Anda menggunakan previous_interaction_id, server akan otomatis menangani kolom id dan signature.
• Mode Tanpa Status: Saat mengelola histori percakapan secara manual, Anda harus memastikan bahwa Anda meneruskan kembali kolom id dan signature ke model dalam permintaan berikutnya untuk memvalidasi keaslian dan mempertahankan konteks. SDK resmi menanganinya secara otomatis jika Anda meneruskan kembali objek respons lengkap ke histori.

Data khusus alat

Beberapa alat bawaan menampilkan argumen data yang terlihat oleh pengguna yang khusus untuk jenis alat.

Token dan harga

Perhatikan bahwa bagian panggilan alat bawaan dalam permintaan dihitung dalam prompt_token_count. Karena langkah-langkah alat perantara ini kini terlihat dan dikembalikan kepada Anda, langkah-langkah tersebut menjadi bagian dari histori percakapan. Hal ini hanya berlaku untuk permintaan, bukan respons.

Alat Google Penelusuran dikecualikan dari aturan ini. Google Penelusuran sudah menerapkan model harganya sendiri di tingkat kueri, sehingga token tidak ditagih dua kali (lihat halaman Harga).

Baca halaman Token untuk mengetahui informasi selengkapnya.

Batasan

• Secara default menggunakan mode validated (mode auto tidak didukung) jika sirkulasi konteks alat diaktifkan.
• Alat bawaan seperti google_search mengandalkan informasi lokasi dan waktu saat ini, jadi jika system_instruction atau function_declaration.description Anda memiliki informasi lokasi dan waktu yang bertentangan, fitur kombinasi alat mungkin tidak berfungsi dengan baik.

Alat yang didukung

Sirkulasi konteks alat standar berlaku untuk alat sisi server (bawaan). Eksekusi Kode juga merupakan alat sisi server, tetapi memiliki solusi bawaan sendiri untuk sirkulasi konteks. Penggunaan Komputer dan panggilan fungsi adalah alat sisi klien, dan juga memiliki solusi bawaan untuk sirkulasi konteks.

Langkah berikutnya

• Pelajari lebih lanjut Panggilan fungsi di Gemini API.
• Jelajahi alat yang didukung:
  • Google Penelusuran
  • Google Maps
  • Konteks URL
  • Penelusuran File