‫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 جديدًا.

الوصول إلى النتائج باستخدام خصائص حزمة تطوير البرامج (SDK) المريحة

على الرغم من أنّ Interactions API يعرض جدولاً زمنيًا منظَّمًا لخطوات التنفيذ (مثل الأفكار وطلبات البحث واستدعاءات الوظائف)، ليس عليكم الانتقال يدويًا بين الخطوات للحصول على استجابة النموذج النهائية.

توفر حِزم SDK للذكاء الاصطناعي التوليدي من Google خصائص مريحة مباشرةً في عنصر Interaction الذي يتم عرضه للوصول إلى النتائج لمختلف الوسائط:

خاصية حزمة تطوير البرامج (SDK) المريحة نوع القيمة التي يتم عرضها الوصف
interaction.output_text سلسلة تعرض آخر كتل نصية في استجابة النموذج. إذا تم تقسيم الاستجابة على عدة كتل متتالية من TextContent، يتم دمجها تلقائيًا. لا تتضمّن هذه الخاصية كتل النصوص السابقة التي تفصلها محتوى غير نصي (مثل الأفكار أو الصور أو المحتوى الصوتي أو استدعاءات الأدوات). بالنسبة إلى الاستجابات المعقّدة أو المتداخلة المتعددة الوسائط، يجب تكرار steps يدويًا بدلاً من ذلك.
interaction.output_image ‫ImageContent أو None تعرض آخر كتلة صور أنشأها النموذج في الطلب الحالي.
interaction.output_audio ‫AudioContent أو None تعرض آخر كتلة صوتية أنشأها النموذج في الطلب الحالي.

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

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

يمكنكم استخدام 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.5 Flash الطراز gemini-3.5-flash
‫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

يمكنكم استخدام أحدث إصدار من حِزم SDK للذكاء الاصطناعي التوليدي من Google للوصول إلى 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) استنادًا إلى الاستخدام الفعلي وملاحظات المطوّرين. نتيجةً لذلك، قد تحدث تغييرات قد تؤدي إلى أعطال.

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

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

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

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

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

الملاحظات

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

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