API تعاملات

API تعاملات، استاندارد اولیه جدید برای ساخت با Gemini است که برای همه پروژه‌های جدید توصیه می‌شود. این API برای گردش‌های کاری عامل‌محور، مدیریت وضعیت سمت سرور و مکالمات پیچیده چندوجهی و چند نوبتی بهینه شده است. API generateContent اصلی همچنان به طور کامل پشتیبانی می‌شود.

چرا از API تعاملات استفاده کنیم؟

  • مدیریت تاریخچه سمت سرور : جریان‌های چند نوبتی ساده‌شده از طریق previous_interaction_id . سرور به طور پیش‌فرض وضعیت ( store=true ) را فعال می‌کند، اما می‌توانید با تنظیم store=false ، رفتار بدون وضعیت (stateless) را انتخاب کنید.
  • مراحل اجرای قابل مشاهده : مراحل تایپ شده، اشکال‌زدایی جریان‌های پیچیده و رندر رابط کاربری برای رویدادهای میانی (مانند افکار یا ابزارک‌های جستجو) را آسان می‌کنند.
  • ساخته شده برای گردش‌های کاری عامل‌محور : پشتیبانی بومی برای استفاده از ابزار چند مرحله‌ای، هماهنگ‌سازی و استدلال پیچیده از طریق مراحل اجرایی تایپ‌شده جریان می‌یابد.
  • وظایف طولانی مدت و پس‌زمینه : از تخلیه بار عملیات زمان‌بر مانند Deep Think و Deep Research به فرآیندهای پس‌زمینه با استفاده از background=true پشتیبانی می‌کند.
  • دسترسی به مدل‌ها و قابلیت‌های جدید : در ادامه، مدل‌های جدید فراتر از خانواده اصلی، همراه با قابلیت‌ها و ابزارهای جدید عامل، منحصراً در API تعاملات راه‌اندازی خواهند شد.

اگر در حال شروع یک پروژه جدید، ساخت برنامه‌های agentic یا نیاز به مدیریت مکالمه سمت سرور هستید، از Interactions API استفاده کنید . اگر از قبل یکپارچه‌سازی‌ای دارید که برای نیازهای شما کار می‌کند، یا اگر به ویژگی‌ای نیاز دارید که هنوز در Interactions API موجود نیست ، مانند Batch API یا caching صریح، generateContent استفاده کنید .

شروع کنید

  • عامل کدنویسی خود را تنظیم کنید : به MCP اسناد Gemini متصل شوید و مهارت gemini-interactions-api را نصب کنید تا دستیار شما مستقیماً به جدیدترین اسناد توسعه‌دهنده و بهترین شیوه‌ها دسترسی داشته باشد. عامل کدنویسی خود را تنظیم کنید →
  • مهاجرت از generateContent : اگر از قبل یکپارچه‌سازی دارید، برای انتقال به Interactions API، راهنمای مهاجرت را دنبال کنید.
  • شروع سریع را امتحان کنید : با یک مثال کاربردی مینیمال در شروع سریع Interactions API شروع کنید.

راهنماهای ویژگی

قابلیت‌های خاص Interactions API را از طریق این راهنماها بررسی کنید. می‌توانید از دکمه‌ی موجود در این صفحات برای جابجایی بین generateContent و Interactions API استفاده کنید:

نحوه عملکرد API تعاملات

رابط برنامه‌نویسی کاربردی Interactions حول یک منبع اصلی متمرکز است: 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 و غیره)

این بدان معناست که اگر می‌خواهید این پارامترها اعمال شوند، باید آنها را در هر تعامل جدید دوباره مشخص کنید. این مدیریت وضعیت سمت سرور اختیاری است؛ همچنین می‌توانید با ارسال تاریخچه کامل مکالمه در هر درخواست، در حالت بدون وضعیت (stateless) عمل کنید.

ذخیره‌سازی و نگهداری داده‌ها

به طور پیش‌فرض، API تمام اشیاء Interaction ( store=true ) را ذخیره می‌کند تا استفاده از ویژگی‌های مدیریت وضعیت سمت سرور (با previous_interaction_id )، اجرای پس‌زمینه (با استفاده از background=true ) و اهداف مشاهده‌پذیری را ساده کند.

  • سطح پولی : سیستم تعاملات را به مدت ۵۵ روز ذخیره می‌کند.
  • ردیف رایگان : سیستم تعاملات را به مدت ۱ روز نگه می‌دارد.

اگر این را نمی‌خواهید، می‌توانید در درخواست خود store=false را تنظیم کنید. این کنترل جدا از مدیریت وضعیت است؛ می‌توانید از ذخیره‌سازی برای هر تعاملی انصراف دهید. با این حال، توجه داشته باشید که store=false با background=true سازگار نیست و از استفاده previous_interaction_id برای نوبت‌های بعدی جلوگیری می‌کند.

شما می‌توانید تعاملات ذخیره شده را در هر زمانی با استفاده از متد delete که در مرجع API موجود است، حذف کنید. شما فقط در صورتی می‌توانید تعاملات را حذف کنید که شناسه تعامل را بدانید.

پس از پایان دوره نگهداری، اطلاعات شما به طور خودکار حذف خواهد شد.

سیستم اشیاء تعامل را طبق شرایط پردازش می‌کند.

بهترین شیوه‌ها

  • نرخ موفقیت در حافظه پنهان (Cache hit rate ): استفاده از previous_interaction_id برای ادامه مکالمات به سیستم اجازه می‌دهد تا راحت‌تر از حافظه پنهان ضمنی (implicit caching) برای تاریخچه مکالمات استفاده کند، که این امر باعث بهبود عملکرد و کاهش هزینه‌ها می‌شود.
  • ترکیب تعاملات : شما انعطاف‌پذیری لازم برای ترکیب و تطبیق تعاملات عامل و مدل را در یک مکالمه دارید. به عنوان مثال، می‌توانید از یک عامل تخصصی مانند عامل Deep Research برای جمع‌آوری داده‌های اولیه استفاده کنید و سپس از یک مدل استاندارد Gemini برای کارهای بعدی مانند خلاصه‌سازی یا قالب‌بندی مجدد استفاده کنید و این مراحل را با previous_interaction_id مرتبط کنید.

مدل‌ها و عامل‌های پشتیبانی‌شده

نام مدل نوع شناسه مدل
جمینی ۳.۱ فلش-لایت مدل 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-preview
جمینی ۲.۵ پرو مدل gemini-2.5-pro
فلش جمینی ۲.۵ مدل gemini-2.5-flash
جمینی ۲.۵ فلش لایت مدل gemini-2.5-flash-lite
پیش‌نمایش کلیپ لیریا ۳ مدل lyria-3-clip-preview
پیش‌نمایش Lyria 3 Pro مدل lyria-3-pro-preview
پیش‌نمایش تحقیقات عمیق عامل deep-research-pro-preview-12-2025
پیش‌نمایش تحقیقات عمیق عامل deep-research-preview-04-2026
پیش‌نمایش تحقیقات عمیق عامل deep-research-max-preview-04-2026

SDK ها

برای دسترسی به API تعاملات می‌توانید از آخرین نسخه Google GenAI SDKs استفاده کنید.

  • در پایتون، این بسته google-genai از نسخه 1.55.0 به بعد است.
  • در جاوا اسکریپت، این پکیج @google/genai از نسخه 1.33.0 به بعد است.

می‌توانید درباره نحوه نصب SDKها در صفحه کتابخانه‌ها بیشتر بیاموزید.

محدودیت‌ها

  • وضعیت بتا : رابط برنامه‌نویسی کاربردی تعاملات (Interactions API) در مرحله بتا/پیش‌نمایش است. ویژگی‌ها و طرحواره‌ها ممکن است تغییر کنند.
  • کنترل از راه دور MCP : جمینی ۳ از کنترل از راه دور MCP پشتیبانی نمی‌کند، این قابلیت به زودی اضافه خواهد شد.

ویژگی‌های زیر توسط generateContent API پشتیبانی می‌شوند اما هنوز در Interactions API در دسترس نیستند :

شکستن تغییرات

رابط برنامه‌نویسی کاربردی تعاملات (Interactions API) در حال حاضر در مرحله بتای اولیه است. ما به طور فعال در حال توسعه و اصلاح قابلیت‌های رابط برنامه‌نویسی کاربردی (API)، طرحواره‌های منابع (Resource Schemas) و رابط‌های SDK بر اساس کاربرد در دنیای واقعی و بازخورد توسعه‌دهندگان هستیم.

در نتیجه، ممکن است تغییرات مهمی رخ دهد . به‌روزرسانی‌ها ممکن است شامل تغییراتی در موارد زیر باشند:

  • طرحواره‌هایی برای ورودی و خروجی.
  • امضاهای متد SDK و ساختارهای شیء.
  • رفتارهای ویژگی خاص.

برای بارهای کاری عملیاتی، شما باید همچنان از API استاندارد generateContent استفاده کنید. این مسیر همچنان مسیر پیشنهادی برای استقرار پایدار است و ما به طور فعال به توسعه و نگهداری آن ادامه خواهیم داد.

بازخورد

بازخورد شما برای توسعه‌ی Interactions API بسیار مهم است. نظرات خود را به اشتراک بگذارید، اشکالات را گزارش دهید یا درخواست ویژگی‌ها را در انجمن توسعه‌دهندگان Google AI ما داشته باشید.

قدم بعدی چیست؟