รวมเครื่องมือในตัวและการเรียกใช้ฟังก์ชัน

Gemini ช่วยให้คุณใช้เครื่องมือในตัว เช่น google_search และการเรียกใช้ฟังก์ชัน (หรือที่เรียกว่าเครื่องมือที่กำหนดเอง) ร่วมกันได้ในการโต้ตอบครั้งเดียวโดยการเก็บรักษาและแสดงประวัติบริบทของการเรียกใช้เครื่องมือ การผสมผสานเครื่องมือในตัวและเครื่องมือที่กำหนดเองช่วยให้ เวิร์กโฟลว์ที่ซับซ้อนและมีเอเจนต์ทำงานได้ เช่น โมเดลสามารถอ้างอิง ข้อมูลเว็บแบบเรียลไทม์ก่อนที่จะเรียกตรรกะทางธุรกิจที่เฉพาะเจาะจงของคุณ

ตัวอย่างที่เปิดใช้ชุดค่าผสมของเครื่องมือในตัวและเครื่องมือที่กำหนดเองด้วย google_search และฟังก์ชันที่กำหนดเอง 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"]
      }
    }
  ]
}'

วิธีการทำงาน

โมเดล Gemini 3 ใช้การหมุนเวียนบริบทของเครื่องมือเพื่อเปิดใช้ชุดค่าผสมของเครื่องมือในตัวและเครื่องมือที่กำหนดเอง การหมุนเวียนบริบทของเครื่องมือช่วยให้สามารถรักษาและ แสดงบริบทของเครื่องมือในตัว รวมถึงแชร์กับเครื่องมือที่กำหนดเองในการโต้ตอบเดียวกันได้

เปิดใช้การรวมเครื่องมือ

• ใส่ function_declarations พร้อมกับเครื่องมือในตัวที่คุณต้องการใช้เพื่อเรียกใช้ลักษณะการทำงานร่วมกัน

ขั้นตอนการคืนสินค้าผ่าน API

ในการตอบกลับการโต้ตอบ API จะแสดงขั้นตอนแยกต่างหากสำหรับการเรียกเครื่องมือในตัว และการเรียกฟังก์ชัน (เครื่องมือที่กำหนดเอง)

• ขั้นตอนเครื่องมือในตัว: API จะจัดการสิ่งเหล่านี้โดยอัตโนมัติเพื่อรักษาบริบทในแต่ละรอบ
• ขั้นตอนการเรียกฟังก์ชัน: API จะแสดงผลขั้นตอน function_call สำหรับฟังก์ชันที่กำหนดเอง คุณเรียกใช้ฟังก์ชันและส่งผลลัพธ์กลับมา

ฟิลด์ที่สำคัญในขั้นตอนที่แสดงผล

ฟิลด์บางรายการในขั้นตอนที่ส่งคืนมีความสำคัญต่อการรักษาบริบทของเครื่องมือและการเปิดใช้การรวมเครื่องมือ

• id: ดูได้ในขั้นตอนที่ function_call และ function_response ตัวระบุที่ไม่ซ้ำกันซึ่งแมปการเรียกไปยังการตอบกลับ
• signature: พบในขั้นตอน thought รวมถึงขั้นตอนการเรียกใช้เครื่องมือทั้งหมด (เช่น function_call) และขั้นตอนผลลัพธ์ (เช่น function_response) สำหรับโมเดล Gemini 3+ บริบทที่เข้ารหัสนี้ช่วยให้การหมุนเวียนบริบทของเครื่องมือในการโต้ตอบต่างๆ

การจัดการช่องเหล่านี้

• โหมด Stateful (แนะนำ): เมื่อใช้ previous_interaction_id เซิร์ฟเวอร์จะจัดการทั้งฟิลด์ id และ signature โดยอัตโนมัติ
• โหมดไม่เก็บสถานะ: เมื่อจัดการประวัติการสนทนาด้วยตนเอง คุณต้องตรวจสอบว่าได้ส่งทั้งฟิลด์ id และ signature กลับไปยังโมเดลในคำขอที่ตามมาเพื่อตรวจสอบความถูกต้องและรักษาบริบท SDK อย่างเป็นทางการจะจัดการเรื่องนี้โดยอัตโนมัติหากคุณส่งออบเจ็กต์การตอบกลับแบบเต็มกลับไปยังประวัติ

ข้อมูลเฉพาะเครื่องมือ

เครื่องมือในตัวบางอย่างจะแสดงอาร์กิวเมนต์ข้อมูลที่ผู้ใช้มองเห็นได้ซึ่งเจาะจงสำหรับประเภทเครื่องมือ

โทเค็นและการกำหนดราคา

โปรดทราบว่าระบบจะนับรวมชิ้นส่วนการเรียกใช้เครื่องมือในตัวในคำขอไว้ใน prompt_token_count เนื่องจากตอนนี้คุณสามารถเห็นขั้นตอนเครื่องมือระดับกลางเหล่านี้และระบบจะส่งคืนให้คุณ ขั้นตอนเหล่านี้จึงเป็นส่วนหนึ่งของประวัติการสนทนา ซึ่งจะเกิดขึ้นกับคำขอเท่านั้น ไม่ใช่การตอบกลับ

เครื่องมือ Google Search เป็นข้อยกเว้นของกฎนี้ Google Search ใช้โมเดลราคาของตัวเองที่ระดับคำค้นหาอยู่แล้ว จึงไม่มีการเรียกเก็บค่าโทเค็นซ้ำ (ดูหน้าราคา)

อ่านข้อมูลเพิ่มเติมได้ที่หน้าโทเค็น

ข้อจำกัด

• ค่าเริ่มต้นคือโหมด validated (ไม่รองรับโหมด auto) เมื่อเปิดใช้การหมุนเวียนบริบทของเครื่องมือ
• เครื่องมือในตัว เช่น google_search อาศัยข้อมูลตำแหน่งและเวลาปัจจุบัน ดังนั้นหาก system_instruction หรือ function_declaration.description มีข้อมูลตำแหน่งและเวลา ที่ขัดแย้งกัน ฟีเจอร์การรวมเครื่องมืออาจทำงานได้ไม่ดี

เครื่องมือที่รองรับ

การหมุนเวียนบริบทของเครื่องมือมาตรฐานจะใช้กับเครื่องมือฝั่งเซิร์ฟเวอร์ (ในตัว) การดำเนินการโค้ดเป็นเครื่องมือฝั่งเซิร์ฟเวอร์เช่นกัน แต่มีโซลูชันในตัวของตัวเองสำหรับ การหมุนเวียนบริบท การใช้คอมพิวเตอร์และการเรียกใช้ฟังก์ชันเป็นเครื่องมือฝั่งไคลเอ็นต์ และยังมีโซลูชันในตัวสำหรับการหมุนเวียนบริบทด้วย

ขั้นตอนถัดไป

• ดูข้อมูลเพิ่มเติมเกี่ยวกับการเรียกฟังก์ชันใน Gemini API
• สำรวจเครื่องมือที่รองรับ
  • Google Search
  • Google Maps
  • บริบทของ URL
  • ค้นหาไฟล์