استدعاء الدوال مع Gemini 3.8 Flash: معرف الاستدعاء، حلقات الأدوات التكرارية، وكيفية اختبارها

تم إطلاق Gemini 3.8 Flash في 2 سبتمبر 2026، وقد بنته جوجل لـ "استدعاء الأدوات بشكل متكرر": ففي المهمة الصعبة يقوم بإجراء مكالمة، والتحقق من النتيجة، ثم يقوم بمكالمة أخرى، بدلاً من تخمين كل شيء دفعة واحدة. هذه أخبار جيدة للوكلاء وصداع جديد لأي شخص تم ضبط حلقة أدواته على 3.7 Flash. هناك تفصيلان مهمان في واجهة برمجة التطبيقات أكثر من أي شيء آخر. يجب أن تحمل كل نتيجة دالة كلاً من call_id و name، وأصبحت Interactions API، وليس generateContent، هي الطريقة الأساسية لتشغيل الحلقة.

يشرح هذا الدليل التدفق الكامل ذي الدورتين على Interactions API، ويعرض شكل generateContent القديم الذي ربما لا تزال تستخدمه، ويوضح سبب قضاء النموذج الجديد المزيد من الدورات والتوكنات على الأدوات، وينتهي بإعداد اختبار يمكنك تشغيله يوميًا: محاكاة الواجهة الخلفية للأداة، وربط كلتا الدورتين، والتأكد من أن call_id يعود ذهابًا وإيابًا. إذا كنت بحاجة إلى نظرة عامة على النموذج أولاً، فابدأ بـ ما هو Gemini 3.8 Flash. أسماء الحقول أدناه تأتي من وثائق استدعاء الدالة من جوجل.

كل طلب هنا هو HTTP عادي مع JSON، لذا يمكنك بنائه وتصحيحه في Apidog قبل أن يدخل في كود التطبيق.

استدعاء الدالة على Gemini 3.8 Flash في لمحة

الخطوة 1: الإعلان عن الأداة

على Interactions API، الأداة هي كائن مسطح: `type` من `function`، و`name`، و`description` يقرأها النموذج ليقرر متى يستدعيها، ومخطط JSON تحت `parameters`. اجعل الوصف محددًا. "البحث عن حالة الشحن الحالية لطلب معين بواسطة معرفه" يتم استدعاؤه في اللحظة المناسبة؛ بينما "مساعد الطلبات" يتم استدعاؤه عشوائيًا.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Where is order A1029 right now?",
    "generation_config": {"thinking_level": "low"},
    "tools": [{
      "type": "function",
      "name": "get_order_status",
      "description": "Look up the current shipping status of an order by its ID.",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    }]
  }'

هناك خياران في هذا الطلب مقصودان. `thinking_level` هو `low` لأن عملية بحث واحدة لا تحتاج إلى `medium` الافتراضي؛ يغطي دليل مستويات التفكير متى يجب رفعه. ولا يوجد `temperature`. إرشادات Gemini 3 من جوجل هي تركه عند القيمة الافتراضية 1.0، لأن خفضه قد يتسبب في حدوث حلقات، وهو آخر شيء تريده داخل حلقة أداة.

الخطوة 2: قراءة خطوة function_call

لا تستجيب Interactions API برسالة واحدة. بل تُرجع `id` الخاص بالتفاعل بالإضافة إلى قائمة بخطوات التنفيذ: أفكار النموذج، واستدعاءات الأداة، وأخيرًا خطوة `model_output` بمجرد حصول النموذج على إجابة. عندما يقرر النموذج أنه يحتاج إلى أداتك، تحتوي القائمة على خطوة `function_call` بدلاً من `model_output`:

{
  "type": "function_call",
  "id": "call_8f2d...",
  "name": "get_order_status",
  "arguments": {"order_id": "A1029"}
}

ثلاثة حقول، وتحتاج إليها جميعًا. `id` هو المعرف الذي ترسله مرة أخرى كـ `call_id`. `name` يخبرك بالوظيفة التي يجب تشغيلها ويجب إعادتها أيضًا. `arguments` هو JSON محلل بالفعل، لذا قم بالتحقق من صحته وفقًا لقواعدك الخاصة قبل تنفيذ أي شيء؛ يملأ النموذج الشكل الذي أعلنته، لكنه لا يعرف أن معرفات طلباتك تتكون من خمسة أحرف.

قم بتخزين `id` التفاعل من أعلى الاستجابة في نفس الوقت. يصبح `previous_interaction_id` في الدورة التالية.

الخطوة 3: إرجاع النتيجة باستخدام call_id و name

قم بتشغيل دالتك، ثم أرسل طلبًا ثانيًا يكون `input` فيه عبارة عن `function_result`. يتطلب Gemini 3.8 Flash كلاً من `call_id` و `name`. إذا أسقطت أحدهما، يفشل الاستدعاء، وهذا هو الخلل الأكثر شيوعًا عند نقل الفرق للحلقات المكتوبة لنماذج أقدم.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "previous_interaction_id": "<interaction id from step 2>",
    "input": [{
      "type": "function_result",
      "name": "get_order_status",
      "call_id": "call_8f2d...",
      "result": [{"type": "text", "text": "{\"status\":\"in_transit\",\"eta\":\"2026-09-05\"}"}]
    }]
  }'

`result` هي قائمة من أجزاء المحتوى، ويحمل الجزء النصي JSON الخاص بك كسلسلة. بما أن `previous_interaction_id` يشير إلى الدورة السابقة، فإن الخادم يحتفظ بالفعل بالمطالبة الأصلية، وإعلان الأداة، ومنطق النموذج؛ لست بحاجة لإعادة إرسال أي منها. الاستجابة هي قائمة خطوات أخرى. إذا انتهت بـ `model_output`، فقد انتهيت، وتعرض SDK النص كـ `interaction.output_text`. إذا كانت تحتوي على `function_call` أخرى، فارجع إلى الخطوة 2. هذه الحلقة هي النمط بأكمله.

في بايثون، يكون التدفق هو `client.interactions.create(model="gemini-3.8-flash", input=..., ...)` بنفس حقول JSON كمعاملات للكلمات المفتاحية، ثم استدعاء `create` ثاني مع `previous_interaction_id` وقائمة `function_result` كـ `input`. يغطي دليل كيفية استخدام Gemini 3.8 Flash API المفاتيح، والبث، وقراءة استخدام التوكنات إذا كانت نقطة النهاية جديدة بالنسبة لك.

المكافئ القديم لـ generateContent

لا يزال معظم كود Gemini الحالي يستدعي `models/gemini-3.8-flash:generateContent`، وتقول جوجل إنه "مدعوم بالكامل" بدون تاريخ إيقاف. المفردات مختلفة؛ القاعدة هي نفسها. يتم الإعلان عن الأدوات تحت `functionDeclarations`، ويرد النموذج بجزء `functionCall`، وتجيب أنت بجزء `functionResponse`. في الشكل القديم، يحمل جزء `functionCall` الخاص بالنموذج `id`، ويجب أن يعكس جزء `functionResponse` الخاص بك نفس القيمة في حقل `id` الخاص به جنبًا إلى جنب مع `name` و `response`. إنه نفس العقد مثل `call_id` على Interactions API تحت اسم حقل مختلف، وإرشادات Gemini 3 من جوجل واضحة على أن كل من الـ id والـ name مطلوبان.

هناك اختلافان عمليان. أولاً، `generateContent` بلا حالة، لذا عليك حمل المحادثة بنفسك: يعود سجل `contents` الكامل في كل دورة، بما في ذلك جزء `functionCall` الخاص بالنموذج وأي توقيعات تفكير أعادها. ثانيًا، يتم تكوين التفكير تحت `generationConfig.thinkingConfig.thinkingLevel` بدلاً من `generation_config.thinking_level`:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

تظهر رموز التفكير كـ `usageMetadata.thoughtsTokenCount` في الاستجابة وتتم فوترتها كإخراج. إذا كنت تختار بين واجهتي برمجة التطبيقات لمشروع جديد، فاختر Interactions: حيث تزيل الحالة من جانب الخادم فئة الأخطاء التي يفقد فيها سجل معاد توقيعًا أو `call_id`.

لماذا يستدعي 3.8 Flash الأدوات بشكل متكرر، وكيفية تحديد سقف للحلقة

يقول منشور إطلاق جوجل أن النموذج "يعمل بجهد أكبر": في المهام المعقدة "ينفذ خطوات استدلال إضافية، ويستدعي الأدوات بشكل متكرر"، ويأخذ "خطوات استدلال أصغر" ويتحقق من عمله على طول الطريق. وتقول جوجل أيضًا أنه "يمكنه استخدام المزيد من التوكنات في المهام الأطول والأكثر تعقيدًا، حسب التصميم". قامت شركة Artificial Analysis بقياس التأثير: حوالي 48 ألف توكن إخراج لكل مهمة في مؤشرهم، بزيادة 30% عن 3.7 Flash، وتكلفة قدرها 0.58 دولارًا لكل مهمة عند مستوى `high` مقابل 0.40 دولارًا لـ 3.7 Flash بنفس أسعار التوكن الواحد. وجاء المستوى المتوسط عند 0.41 دولارًا والمنخفض عند 0.24 دولارًا.

بالنسبة لحلقة الأداة، هذا يعني المزيد من خطوات `function_call` لكل مهمة. الجانب الإيجابي حقيقي: ارتفعت نتيجة Tau3-Banking، وهي تقييم AA لاستخدام الأداة، بمقدار 12 نقطة لتصل إلى 45%. أما الجانب السلبي فهو أن الحلقة التي لا يوجد لها سقف الآن تستغرق وقتًا أطول مما كانت عليه في أغسطس. أربع ضوابط، بترتيب تطبيقها:

• الحد الأقصى للدورات في نظامك. احسب خطوات `function_call` لكل مهمة وتوقف عند حد تختاره؛ من 6 إلى 10 هو نطاق بدء معقول لعمليات البحث، وأعلى للبرمجة الذاتية (agentic coding). عندما يصل الحد، أرسل دورة أخيرة بدون أدوات، أو أرجع خطأ للمستخدم. النموذج لن يحدد لنفسه سقفًا.
• `thinking_level` لكل مسار. `low` لعمليات البحث والأدوات ذات الخطوة الواحدة، `medium` (الافتراضي) للعمل متعدد الخطوات، `high` فقط عندما يكون التحقق الإضافي مجديًا. لا ترسل `minimal`؛ يُرجع 3.8 Flash خطأ في التحقق.
• مهلات على كلا الجانبين. مهلة لكل طلب على استدعاء Gemini وساعة توقيت جدارية لكل مهمة على الحلقة. استغرقت عمليات التشغيل ذات التفكير العالي لـ AA متوسط 2.5 دقيقة لكل مهمة، و0.8 دقيقة عند المستوى المنخفض.
• أدوات متطابقة. يعيد النموذج التكراري المحاولة. اجعل `get_order_status` آمنًا للاستدعاء مرتين، واجعل أي شيء له آثار جانبية (مثل عمليات الاسترداد والإرسال) يتطلب خطوة تأكيد.

إذا كانت ميزانيتك لا تستطيع استيعاب الدورات الإضافية، فإن دليل الترحيل من 3.7 إلى 3.8 Flash يغطي كيفية الاحتفاظ بـ 3.7 Flash، والذي لا يزال مدعومًا بالكامل، خلف علامة تكوين.

توقيعات الأفكار، المكالمات المتوازية، والمخرجات المنظمة

توقيعات الأفكار. نماذج Gemini 3 تُرفق توقيعات بمنطقها. مع تدفق Interactions المخزن الافتراضي، يتعامل `previous_interaction_id` معها نيابةً عنك. إذا قمت بتعيين `store: false` لإعداد بلا حالة، أو إذا كنت تستخدم `generateContent`، يجب عليك إرسال كتل الأفكار والتوقيعات تمامًا كما تم استلامها، على كل نوع جزء. لا تقم بالتقطيع أو إعادة الترتيب أو إعادة التسلسل؛ التوقيع غير شفاف وأي تعديل يبطله. تغطي وثائق Interactions API من جوجل المفاضلة بين الحالة المخزنة وعديمة الحالة.

المكالمات المتوازية. الاستجابة عبارة عن قائمة، لذا يمكن أن تحتوي على أكثر من خطوة `function_call` عندما يريد النموذج عدة عمليات بحث مستقلة في وقت واحد. تؤكد وثائق استدعاء الدالة من جوجل أن نماذج Gemini 3 تُرجع معرفًا فريدًا مع كل استدعاء بالضبط حتى يمكن أن تعود النتائج بأي ترتيب. تعامل مع ذلك عن طريق إرجاع `function_result` واحد لكل استدعاء في نفس مصفوفة `input`، كل منها مطابق لـ `call_id` الخاص به. المطابقة بواسطة `name` وحده لا يكفي؛ يحتاج استدعاءان لنفس الدالة إلى قيمتين مختلفتين لـ `call_id`.

المخرجات المنظمة. يدعم 3.8 Flash المخرجات المنظمة واستدعاء الدالة على نفس النموذج. النمط النظيف هو استخدام الأدوات للحلقة ومخطط JSON للإجابة النهائية، بحيث يكون `model_output` الذي يغلق الحلقة قابلاً للقراءة آليًا بدلاً من كونه نصًا نثريًا. توثق صفحات استدعاء الدالة والمخرجات المنظمة من جوجل التكوين. لا تزيف ذلك عن طريق الإعلان عن أداة وهمية وقراءة `arguments` الخاصة بها؛ فهذا يتعطل لحظة أن يقرر النموذج أنه لا يوجد لديه شيء لاستدعائه.

يفترض كل ما سبق أن النموذج يصل إلى نظامك عبر الدوال المعلنة. تُدرج جوجل أيضًا استخدام الكمبيوتر (معاينة) لـ 3.8 Flash؛ لمعرفة متى تتفوق واجهة برمجة التطبيقات المنظمة على قيادة الشاشة لوكيل، راجع استخدام الكمبيوتر مقابل واجهات برمجة التطبيقات المنظمة.

اختبار حلقة الأداة في Apidog

تحتوي حلقة الأداة على ثلاثة نقاط يمكن أن تتعطل فيها: الإعلان، رحلة ذهاب وعودة المعرّف (ID)، والإجابة النهائية. يمكنك تغطية الثلاثة جميعًا في Apidog دون لمس واجهتك الخلفية الحقيقية.

1. محاكاة الواجهة الخلفية للأداة. عرّف `GET /orders/{order_id}` كنقطة نهاية وشغّل خادم المحاكاة الخاص بها. أعطها نص استجابة ثابتًا، `{"status": "in_transit", "eta": "2026-09-05"}`، بحيث تحصل كل عملية تشغيل على نفس الإدخال، وأي تغيير في الإجابة النهائية للنموذج يكون من فعل النموذج، وليس قاعدة بياناتك. يشير نظامك إلى عنوان URL للمحاكاة في بيئة الاختبار وإلى الخدمة الحقيقية في الإنتاج.

2. ربط الدورتين في سيناريو اختبار. قم بتخزين `GEMINI_API_KEY` كمتغير بيئة وارجع إليه كـ `{{GEMINI_API_KEY}}` في رأس `x-goog-api-key`. ثم قم ببناء سيناريو بثلاث خطوات:

• الخطوة أ: إرسال POST إلى `/v1beta/interactions` مع المطالبة وإعلان `get_order_status`. استخرج `id` التفاعل و`id` خطوة `function_call` و`name` و`arguments.order_id` إلى متغيرات.
• الخطوة ب: إجراء GET على نقطة نهاية المحاكاة باستخدام `{{order_id}}`. هذه هي خطوة "تشغيل الدالة" الخاصة بك.
• الخطوة ج: إرسال POST لـ `function_result` مع تعيين `call_id` إلى `{{call_id}}`، و`name` إلى `{{tool_name}}`، و`previous_interaction_id` إلى `{{interaction_id}}`، ونص الخطوة ب كجزء نصي.

3. تأكيد ما يهم.

• الخطوة أ تُرجع 200 وتحتوي على خطوة يكون `type` الخاص بها `function_call` و`name` يساوي `get_order_status`.
• `arguments.order_id` المستخرج يساوي `A1029`، مما يثبت أن النموذج حلل المطالبة واحترم المخطط.
• الخطوة ج تُرجع 200 وتنتهي بخطوة يكون `type` الخاص بها `model_output` بدون `function_call` ثانٍ، مما يثبت أن `call_id` و`name` اللذين أرسلتهما قد تم قبولهما وأن الحلقة أغلقت في جولة واحدة.
• يحتوي النص النهائي على `in_transit`، مما يثبت أن النموذج استخدم نتيجة الأداة بدلاً من تخمينه الخاص.
• إذا قمت بتشغيل نفس السيناريو مقابل `generateContent`، أضف سقفًا على `usageMetadata.thoughtsTokenCount` لكل `thinking_level`. وهذا يلتقط زحف التكلفة "العمل بجدية أكبر" قبل أن يصل إلى فاتورتك.

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

الأسئلة الشائعة

هل `call_id` مطلوب في Gemini 3.8 Flash؟ نعم. في Interactions API، تحتاج كل `function_result` إلى `call_id` و `name`؛ وفي `generateContent`، تحتاج كل `functionResponse` إلى `id` و `name` الخاصة بالاستدعاء. الكود القديم الذي أرسل الاسم فقط يفشل في نماذج Gemini 3.

لماذا تستغرق حلقة أدواتي دورات أكثر في 3.8 Flash مقارنة بـ 3.7؟ هذا تصميم مقصود. تقول جوجل إن النموذج "يستدعي الأدوات بشكل متكرر" و"يمكنه استخدام المزيد من التوكنات في المهام الأطول والأكثر تعقيدًا". قم بتحديد سقف للدورات في نظامك وخفّض `thinking_level`؛ يحتوي دليل مستويات التفكير على التكلفة المقاسة لكل مستوى.

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

هل يعمل `thinking_level` "minimal" مع الأدوات؟ لا. يُرجع خطأ في التحقق على 3.8 Flash. استخدم `low`.

كم تكلف مهمة تعتمد على الأدوات بشكل كبير؟ تسعيرة التوكن هي 0.75 دولار للتوكن الداخل و 3.75 دولار للتوكن الخارج لكل مليون توكن حتى 31 ديسمبر 2026، مع فوترة التفكير كإخراج. قامت Artificial Analysis بقياس 0.58 دولار لكل مهمة عند مستوى `high`، و 0.41 دولار عند مستوى `medium`، و 0.24 دولار عند مستوى `low` في مؤشرهم. ستختلف مهامك، لذا تحقق من عدد التوكنات وقم بالقياس.

نشر الحلقة بسقف محدد

أعلن عن الأداة، اقرأ خطوة `function_call`، وأرجع `function_result` مع كل من `call_id` و `name` تحت `previous_interaction_id`. هذا هو العقد بأكمله. ما تغير مع Gemini 3.8 Flash هو استعداد النموذج للتكرار، لذلك يحتاج النظام إلى حد أقصى للدورات، و`thinking_level` لكل مسار، ومهلة قبل أن يدخل مرحلة الإنتاج. قم بمحاكاة الواجهة الخلفية، اربط الدورتين، تأكد من عودة المعرف (ID) ذهابًا وإيابًا، وجدول التشغيل. تحتوي صفحة "ما الجديد في Gemini 3.8 Flash" من جوجل على ملاحظات الترحيل؛ ويحتوي الدليل الرئيسي على كل شيء آخر حول النموذج.