‫Interactions API

‫Interactions API هي الوحدة الأساسية الجديدة التي ننصح بها لجميع المشاريع الجديدة التي يتم إنشاؤها باستخدام Gemini. وهي محسّنة لسير العمل بالذكاء الاصطناعي الوكيل وإدارة الحالة من جهة الخادم والمحادثات المعقّدة المتعددة الوسائط والمتعددة الأدوار. تظلّ generateContent API الأصلية متوافقة تمامًا.

أهمية استخدام Interactions API

  • إدارة السجلّ من جهة الخادم: تبسيط التدفقات المتعددة الأدوار من خلال previous_interaction_id يُفعِّل الخادم الحالة تلقائيًا (store=true)، ولكن يمكنك تفعيل السلوك بدون حالة من خلال ضبط store=false.
  • خطوات التنفيذ القابلة للمراقبة: تسهّل الخطوات المصنّفة تصنيفًا واضحًا تصحيح الأخطاء في التدفقات المعقّدة وعرض واجهة المستخدم للأحداث الوسيطة (مثل الأفكار أو مربّعات البحث).
  • مصمّمة لسير العمل بالذكاء الاصطناعي الوكيل: توفّر دعمًا أصليًا لاستخدام الأدوات المتعددة الخطوات والتنسيق وتدفقات الاستنتاج المعقّدة من خلال خطوات التنفيذ المصنّفة تصنيفًا واضحًا.
  • المهام الطويلة والمهام في الخلفية: تتيح نقل العمليات التي تستغرق وقتًا طويلاً، مثل Deep Think وDeep Research، إلى عمليات الخلفية باستخدام background=true.
  • الوصول إلى النماذج والإمكانات الجديدة: من الآن فصاعدًا، سيتم إطلاق النماذج الجديدة التي تتجاوز عائلة النماذج الأساسية، بالإضافة إلى الإمكانات والأدوات الجديدة بالذكاء الاصطناعي الوكيل، حصريًا على Interactions API.

استخدِم Interactions API إذا كنت تبدأ مشروعًا جديدًا أو تنشئ تطبيقات تستند إلى الذكاء الاصطناعي الوكيل أو تحتاج إلى إدارة المحادثات من جهة الخادم. استخدِم generateContent إذا كان لديك عملية دمج حالية تناسب احتياجاتك أو إذا كنت بحاجة إلى ميزة غير متاحة بعد في Interactions API، مثل Batch API أو التخزين المؤقت الصريح.

البدء

  • إعداد وكيل الترميز: يمكنك الاتصال بـ Gemini Docs MCP وتثبيت مهارة gemini-interactions-api لمنح مساعدك إمكانية الوصول المباشر إلى أحدث مستندات المطوّرين وأفضل الممارسات. إعداد وكيل الترميز ←
  • نقل البيانات من generateContent: إذا كان لديك عملية دمج حالية، اتّبِع دليل نقل البيانات للانتقال إلى Interactions API.
  • تجربة التشغيل السريع: ابدأ باستخدام مثال بسيط وعملي في التشغيل السريع لـ Interactions API.

أدلة الميزات

يمكنك استكشاف الإمكانات المحدّدة لـ Interactions API من خلال هذه الأدلة. يمكنك استخدام الزرّ في هذه الصفحات للتبديل بين generateContent وInteractions API:

طريقة عمل Interactions API

تتمحور Interactions API حول مورد أساسي: الـ Interaction. يمثّل Interaction دورًا كاملاً في محادثة أو مهمة. ويعمل كسجلّ جلسة، يحتوي على السجلّ الكامل لتفاعل ما كسلسلة زمنية من خطوات التنفيذ. تتضمّن هذه الخطوات أفكار النموذج واستدعاءات الأدوات ونتائجها من جهة الخادم أو من جهة العميل (مثل function_call وfunction_result) وmodel_output النهائي. يتضمّن المورد المخزَّن (الذي يتم استرداده من خلال interactions.get) أيضًا خطوات user_input للحصول على السياق الكامل، على الرغم من أنّ استجابة interactions.create لا تعرض سوى الخطوات التي تم إنشاؤها بواسطة النموذج.

عند إجراء طلب إلى interactions.create، أنت تنشئ موردًا جديدًا Interaction.

إدارة الحالة من جهة الخادم

يمكنك استخدام id لتفاعل مكتمل في طلب لاحق باستخدام previous_interaction_id لمواصلة المحادثة. يستخدم الخادم هذا المعرّف لاسترداد سجلّ المحادثات، ما يوفّر عليك إعادة إرسال سجلّ المحادثات بالكامل.

تحتفظ المَعلمة previous_interaction_id بسجلّ المحادثات فقط (المدخلات والمخرجات) باستخدام previous_interaction_id. أما المَعلمات الأخرى، فهي ضمن نطاق التفاعل ولا تنطبق إلا على التفاعل المحدّد الذي تنشئه حاليًا:

  • tools
  • system_instruction
  • generation_config (بما في ذلك thinking_level وtemperature وما إلى ذلك)

يعني ذلك أنّه عليك إعادة تحديد هذه المَعلمات في كل تفاعل جديد إذا كنت تريد تطبيقها. إنّ إدارة الحالة من جانب الخادم اختيارية، ويمكنك أيضًا العمل في وضع بدون حالة من خلال إرسال سجلّ المحادثات الكامل في كل طلب.

تخزين البيانات والاحتفاظ بها

تخزِّن واجهة برمجة التطبيقات تلقائيًا جميع عناصر التفاعل (store=true) لتسهيل استخدام ميزات إدارة الحالة من جهة الخادم (باستخدام previous_interaction_id) والتنفيذ في الخلفية (باستخدام background=true) ولأغراض إمكانية تتبّع البيانات.

  • الخطة المدفوعة: يحتفظ النظام بالتفاعلات لمدة 55 يومًا.
  • الخطة المجانية: يحتفظ النظام بالتفاعلات لمدة يوم واحد.

إذا كنت لا تريد ذلك، يمكنك ضبط store=false في طلبك. يختلف عنصر التحكّم هذا عن إدارة الحالة، ويمكنك إيقاف التخزين لأي تفاعل. ومع ذلك، يُرجى العِلم أنّ store=false غير متوافق مع background=true ويمنع استخدام previous_interaction_id للأدوار اللاحقة.

يمكنك حذف التفاعلات المخزَّنة في أي وقت باستخدام طريقة الحذف الواردة في مرجع واجهة برمجة التطبيقات. لا يمكنك حذف التفاعلات إلا إذا كنت تعرف معرّف التفاعل.

وبعد انتهاء فترة التخزين، سيتم حذف بياناتك تلقائيًا.

يعالج النظام عناصر التفاعل وفقًا للأحكام .

أفضل الممارسات

  • معدّل نتائج ذاكرة التخزين المؤقت: يتيح استخدام previous_interaction_id لمواصلة المحادثات للنظام استخدام التخزين المؤقت الضمني لـ سجلّ المحادثات بسهولة أكبر، ما يحسّن الأداء ويقلّل التكاليف.
  • خلط التفاعلات: يمكنك خلط تفاعلات الوكيل و النموذج ومطابقتها ضمن محادثة. على سبيل المثال، يمكنك استخدام وكيل متخصّص، مثل وكيل Deep Research، لجمع البيانات الأولية، ثم استخدام نموذج Gemini عادي للمهام اللاحقة، مثل التلخيص أو إعادة التنسيق، وربط هذه الخطوات باستخدام previous_interaction_id.

النماذج والوكلاء المتوافقون

اسم النموذج النوع رقم تعريف الطراز
‫Gemini 3.1 Flash-Lite الطراز gemini-3.1-flash-lite
‫Gemini 3.1 Flash-Lite (معاينة) الطراز gemini-3.1-flash-lite-preview
‫Gemini 3.1 Pro (معاينة) الطراز gemini-3.1-pro-preview
‫Gemini 3 Flash (معاينة) الطراز gemini-3-flash-preview
Gemini 2.5 Pro الطراز gemini-2.5-pro
Gemini 2.5 Flash الطراز gemini-2.5-flash
‫Gemini 2.5 Flash-lite الطراز gemini-2.5-flash-lite
‫Lyria 3 Clip (معاينة) الطراز lyria-3-clip-preview
‫Lyria 3 Pro (معاينة) الطراز lyria-3-pro-preview
‫Deep Research (معاينة) الوكيل deep-research-pro-preview-12-2025
‫Deep Research (معاينة) الوكيل deep-research-preview-04-2026
‫Deep Research Max (معاينة) الوكيل deep-research-max-preview-04-2026

حزم SDK

يمكنك استخدام أحدث إصدار من حزم Google GenAI SDK للوصول إلى Interactions API.

  • في Python، هذه هي حزمة google-genai من الإصدار 1.55.0 والإصدارات الأحدث.
  • في JavaScript، هذه هي حزمة @google/genai من الإصدار 1.33.0 والإصدارات الأحدث.

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

القيود

  • الحالة التجريبية: ‫Interactions API في الإصدار التجريبي أو المعاينة. قد تتغيّر الميزات والمخططات.
  • ‫MCP عن بُعد: لا يتوافق Gemini 3 مع MCP عن بُعد، وسيتم توفير هذه الميزة قريبًا.

تتوافق API مع الميزات التالية، ولكن لا تتوفّر بعد في Interactions API:generateContent

تغييرات قد تؤدي إلى أعطال

‫Interactions API في مرحلة تجريبية مبكرة حاليًا. نعمل بنشاط على تطوير وتحسين إمكانات واجهة برمجة التطبيقات ومخططات الموارد وواجهات حزمة SDK استنادًا إلى الاستخدام الفعلي وملاحظات المطوّرين. نتيجةً لذلك، قد تحدث تغييرات قد تؤدي إلى أعطال.

التغييرات الحالية التي قد تؤدي إلى أعطال:

  • مخطط الخطوات: تحلّ مصفوفة خطوات جديدة محلّ مصفوفة المخرجات، ما يوفّر جدولاً زمنيًا منظَّمًا لكل دور من أدوار التفاعل.

للتعرّف على أحدث تغيير قد يؤدي إلى عطل وفهم كيفية نقل البيانات، يُرجى الاطّلاع على دليل نقل البيانات للتغييرات التي قد تؤدي إلى أعطال (مايو 2026).

قد تشمل التحديثات المحتمَلة الأخرى تغييرات في مخططات الإدخال والإخراج وتوقيعات طرق حزمة SDK وبُنى العناصر وسلوكيات ميزات محدّدة.

بالنسبة إلى أحمال العمل في مرحلة الإنتاج، يجب مواصلة استخدام generateContent API العادية. تظلّ هذه الواجهة هي المسار المقترَح للعمليات المستقرة، وسنواصل تطويرها وصيانتها بنشاط.

الملاحظات

ملاحظاتك ضرورية لتطوير Interactions API. يمكنك مشاركة أفكارك أو الإبلاغ عن الأخطاء أو طلب ميزات في منتدى Google AI Developer Community.

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