ابزارهای داخلی و فراخوانی توابع را ترکیب کنید

Gemini با حفظ و افشای تاریخچه‌ی زمینه‌ی فراخوانی‌های ابزار، امکان ترکیب ابزارهای داخلی مانند google_search و فراخوانی تابع (که به عنوان ابزارهای سفارشی نیز شناخته می‌شوند) را در یک تعامل واحد فراهم می‌کند. ترکیب ابزارهای داخلی و سفارشی، گردش‌های کاری پیچیده و عامل‌محور را امکان‌پذیر می‌سازد، به عنوان مثال، مدل می‌تواند قبل از فراخوانی منطق تجاری خاص شما، خود را در داده‌های وب در لحظه مستقر کند.

در اینجا مثالی آورده شده است که ترکیب ابزارهای داخلی و سفارشی را با google_search و یک تابع سفارشی 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"]
      }
    }
  ]
}'

چگونه کار می‌کند؟

مدل‌های 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 شمارش می‌شوند. از آنجایی که این مراحل میانی ابزار اکنون قابل مشاهده و به شما بازگردانده می‌شوند، بخشی از تاریخچه مکالمه هستند. این فقط در مورد درخواست‌ها صدق می‌کند، نه پاسخ‌ها .

ابزار جستجوی گوگل از این قاعده مستثنی است. جستجوی گوگل از قبل مدل قیمت‌گذاری خود را در سطح پرس‌وجو اعمال می‌کند، بنابراین توکن‌ها دو برابر هزینه نمی‌شوند (به صفحه قیمت‌گذاری مراجعه کنید).

برای اطلاعات بیشتر صفحه توکن‌ها را مطالعه کنید.

محدودیت‌ها

• وقتی گردش متن ابزار فعال باشد، پیش‌فرض روی حالت validated (حالت auto پشتیبانی نمی‌شود) قرار می‌گیرد.
• ابزارهای داخلی مانند google_search به اطلاعات مکان و زمان فعلی متکی هستند، بنابراین اگر system_instruction یا function_declaration.description شما اطلاعات مکان و زمان متناقضی داشته باشند، ممکن است ویژگی ترکیب ابزار به خوبی کار نکند.

ابزارهای پشتیبانی شده

ابزار استاندارد گردش متن برای ابزارهای سمت سرور (توکار) اعمال می‌شود. اجرای کد نیز یک ابزار سمت سرور است، اما راه‌حل توکار خود را برای گردش متن دارد. استفاده از کامپیوتر و فراخوانی تابع، ابزارهای سمت کلاینت هستند و همچنین راه‌حل‌های توکار برای گردش متن دارند.

قدم بعدی چیست؟

• درباره فراخوانی تابع در API مربوط به Gemini بیشتر بدانید.
• ابزارهای پشتیبانی شده را بررسی کنید:
  • جستجوی گوگل
  • نقشه‌های گوگل
  • متن URL
  • جستجوی فایل