واجهة برمجة التطبيقات Interactions API

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

أسباب استخدام Interactions API

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

تخزّن Interactions API الطلبات تلقائيًا حتى تتمكّن من الاستفادة من ميزات إدارة الحالة من جهة الخادم باستخدام previous_interaction_id. يمكنك تفعيل السلوك غير المرتبط بحالة معيّنة من خلال ضبط store=false. راجِع قسم الاحتفاظ بالبيانات لمعرفة التفاصيل.

البدء

  • إعداد وكيل الترميز: اربط وكيل الترميز ببروتوكول 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 غير متوافق مع التنفيذ في الخلفية ويمنع استخدام previous_interaction_id في الأدوار اللاحقة.

بالنسبة إلى مشاريع "المستوى المدفوع"، يمكنك ضبط فترة الاحتفاظ بالبيانات في AI Studio لوضع علامة تلقائيًا على السجلات ليتم حذفها من مساحة تخزين المشروع بعد 7 أو 14 أو 28 أو 55 يومًا. قد يؤثّر تقليل مدة الاحتفاظ بالبيانات في استرجاع المحادثات السابقة.

يمكنك حذف التفاعلات المخزّنة في أي وقت باستخدام طريقة delete آليًا، والتي تتطلّب معرّف التفاعل. يمكنك أيضًا عرض سجلّات التفاعلات المخزّنة وإدارتها، بما في ذلك حذفها من مساحة تخزين المشروع، في AI Studio.

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

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

عرض التفاعلات في AI Studio

تخزّن واجهة برمجة التطبيقات طلبات Interactions API التي تم تنفيذها باستخدام store=true للمشاريع في "الفئة المدفوعة". يمكنك الاطّلاع عليها مباشرةً من صفحة "السجلات" في Google AI Studio. اطّلِع على دليل السجلات لمزيد من المعلومات.

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

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

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

اسم النموذج النوع رقم تعريف الطراز
Gemini 3.5 Flash الطراز gemini-3.5-flash
معاينة Gemini 3.1 Pro الطراز gemini-3.1-pro-preview
Gemini 3.1 Flash-Lite الطراز gemini-3.1-flash-lite
معاينة 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
صورة Gemini 3 Pro الطراز gemini-3-pro-image
صورة Gemini 3.1 Flash الطراز gemini-3.1-flash-image
معاينة ميزة "تحويل النص إلى كلام" في Gemini 3.1 Flash الطراز gemini-3.1-flash-tts-preview
Gemma 4 31B IT الطراز gemma-4-31b-it
Gemma 4 26B MoE IT الطراز gemma-4-26b-a4b-it
معاينة مقطع Lyria 3 الطراز lyria-3-clip-preview
معاينة Lyria 3 Pro الطراز lyria-3-pro-preview
معاينة Deep Research الوكيل deep-research-preview-04-2026
معاينة Deep Research الوكيل deep-research-max-preview-04-2026
معاينة Antigravity الوكيل antigravity-preview-05-2026

حزم SDK

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

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

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

القيود

  • بروتوكول سياق النموذج (MCP) عن بُعد: لا يتوافق Gemini 3 مع بروتوكول سياق النموذج (MCP) عن بُعد، وسيتوفّر قريبًا.
  • توافق النماذج المتعددة الأدوار: عند استخدام نماذج مختلفة في محادثة (سواء كانت تتضمّن حالة أو لا تتضمّن حالة)، يجب أن تتوافق النماذج اللاحقة مع أساليب الإخراج الخاصة بالنماذج السابقة كمدخلات. على سبيل المثال، إذا أنشأت صورة باستخدام gemini-3.1-flash-image، لا يمكنك مواصلة المحادثة مع نموذج لا يقبل إدخالات الصور (مثل نموذج نصي فقط أو نموذج لإنشاء الموسيقى مثل Lyria).

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

الملاحظات

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

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