واجهة Interactions API

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

لماذا يجب استخدام Interactions API؟

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

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

البدء

  • إعداد وكيل الترميز: اربط وكيلك ببروتوكول MCP في "مستندات Gemini" وثبِّت مهارة 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 وما إلى ذلك)

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

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

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

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

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

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

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

يعالج النظام عناصر التفاعل وفقًا للبنود.

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

  • نسبة نتيجة ذاكرة التخزين المؤقت: يتيح استخدام previous_interaction_id لمواصلة المحادثات للنظام الاستفادة بسهولة أكبر من التخزين المؤقت الضمني لسجلّ المحادثات، ما يحسّن الأداء ويقلّل التكاليف.
  • مزج التفاعلات: يمكنك مزج التفاعلات بين الوكيل والنموذج ومطابقتها ضمن محادثة واحدة. على سبيل المثال، يمكنك استخدام وكيل متخصص، مثل وكيل "البحث المعمّق"، لجمع البيانات الأولية، ثم استخدام نموذج 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 الطراز 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 الوكيل deep-research-max-preview-04-2026

حزم SDK

يمكنك استخدام أحدث إصدار من حِزم تطوير البرامج (SDK) من Google GenAI للوصول إلى واجهة برمجة التطبيقات Interactions API.

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

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

القيود

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

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

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

تتوفّر واجهة Interactions API حاليًا في مرحلة تجريبية مبكرة. نعمل حاليًا على تطوير وتحسين إمكانات واجهة برمجة التطبيقات ومخططات الموارد وواجهات حزمة تطوير البرامج (SDK) استنادًا إلى الاستخدام الفعلي وملاحظات المطوّرين.

نتيجةً لذلك، قد تحدث تغييرات غير متوافقة مع الإصدارات السابقة. قد تشمل التعديلات تغييرات على ما يلي:

  • مخططات الإدخال والإخراج
  • توقيعات طرق حزمة SDK وبُنى العناصر
  • سلوكيات الميزات المحدّدة

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

الملاحظات

تُعدّ ملاحظاتك مهمة جدًا لتطوير Interactions API. يمكنك مشاركة أفكارك أو الإبلاغ عن أخطاء أو طلب ميزات في منتدى مطوّري الذكاء الاصطناعي من Google.

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