الجمع بين الأدوات المضمّنة واستدعاء الدوال

يتيح 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 مع الأدوات المضمّنة التي تريد استخدامها لتفعيل السلوك المجمّع.

الخطوات التي تعرضها واجهة برمجة التطبيقات

في ردّ التفاعل، تعرض واجهة برمجة التطبيقات خطوات منفصلة لطلبات البيانات من الأدوات المضمّنة وطلبات البيانات من الدوال (الأدوات المخصّصة):

• خطوات الأداة المضمّنة: تدير واجهة برمجة التطبيقات هذه الخطوات تلقائيًا، مع الحفاظ على السياق في كل خطوة.
• خطوات استدعاء الدوال: تعرض واجهة برمجة التطبيقات function_call خطوة لدوالك المخصّصة. يمكنك تنفيذ الدالة وتقديم النتيجة مرة أخرى.

الحقول المهمة في الخطوات التي تم إرجاعها

تُعدّ بعض الحقول في الخطوات التي يتم إرجاعها ضرورية للحفاظ على سياق الأداة وإتاحة استخدام مجموعات من الأدوات:

• id: تظهر في الخطوتَين function_call وfunction_response. معرّف فريد يربط طلبًا بردّه.
• signature: تظهر في خطوات thought، بالإضافة إلى جميع خطوات طلب الأداة (مثل function_call) ونتيجتها (مثل function_response) لنماذج Gemini 3 والإصدارات الأحدث. يتيح هذا السياق المشفّر تداول سياق الأداة في جميع التفاعلات.

إدارة هذه الحقول:

• الوضع ذو الحالة (مُقترَح): عند استخدام previous_interaction_id، يعالج الخادم تلقائيًا الحقلَين id وsignature.
• وضع عدم الاحتفاظ بالحالة: عند إدارة سجلّ المحادثات يدويًا، يجب التأكّد من إعادة تمرير الحقلَين id وsignature إلى النموذج في الطلبات اللاحقة للتحقّق من صحة البيانات والحفاظ على السياق. تتعامل حِزم SDK الرسمية مع ذلك تلقائيًا إذا أرسلت عنصر الردّ الكامل إلى السجلّ.

البيانات الخاصة بالأداة

تعرض بعض الأدوات المضمّنة وسيطات بيانات مرئية للمستخدم خاصة بنوع الأداة.

الرموز المميزة والأسعار

يُرجى العِلم أنّ أجزاء طلبات استدعاء الأدوات المضمّنة يتم احتسابها ضمن prompt_token_count. بما أنّ خطوات الأدوات الوسيطة هذه أصبحت مرئية ويتم إرجاعها إليك، فهي تشكّل جزءًا من سجلّ المحادثات. ينطبق ذلك على الطلبات فقط، وليس على الردود.

تُستثنى أداة "بحث Google" من هذه القاعدة. يستخدم محرّك بحث Google نموذج التسعير الخاص به على مستوى طلب البحث، لذا لن يتم تحصيل رسوم مضاعفة مقابل الرموز المميزة (راجِع صفحة الأسعار).

يمكنك الاطّلاع على صفحة الرموز المميزة للحصول على مزيد من المعلومات.

القيود

• يتم ضبط الوضع التلقائي على validated (الوضع auto غير متاح) عند تفعيل ميزة "تداول سياق الأداة".
• تعتمد الأدوات المضمّنة، مثل google_search، على معلومات الموقع الجغرافي والوقت الحالي، لذا إذا كان system_instruction أو function_declaration.description يتضمّن معلومات متضاربة حول الموقع الجغرافي والوقت، قد لا تعمل ميزة دمج الأدوات بشكل جيد.

الأدوات المتوافقة

يتم تطبيق تداول سياق الأداة العادي على الأدوات من جهة الخادم (المضمّنة). "تنفيذ التعليمات البرمجية" هي أيضًا أداة من جهة الخادم، ولكنّها تتضمّن حلاً مدمجًا خاصًا بها لتداول السياق. إنّ استخدام الكمبيوتر واستدعاء الدوال هما أداتان من جهة العميل، وتتضمّنان أيضًا حلولاً مدمجة لتداول السياق.

الخطوات التالية

• مزيد من المعلومات حول ميزة "استدعاء الدوال" في Gemini API
• استكشاف الأدوات المتوافقة:
  • بحث Google
  • خرائط Google
  • سياق عنوان URL
  • البحث عن الملفات