Interactions API

‫Interactions API הוא הדרך הכי טובה לבנות באמצעות מודלים וסוכנים של Gemini. החל מיוני 2026, הוא זמין לכלל המשתמשים ומומלץ לכל הפרויקטים החדשים. ממשק ה-API המקורי של generateContent עדיין נתמך באופן מלא, אבל הוא נחשב עכשיו לגרסה מדור קודם.

למה כדאי להשתמש ב-Interactions API?

  • ממשק אוניברסלי לכל האפליקציות: הממשק הזה נועד להיות הממשק הסטנדרטי לכל תרחישי השימוש, כולל יצירת טקסט בשיחה אחת, הבנה מולטי-מודאלית, פלט מובנה, תיאום כלים ותהליכי עבודה מבוססי-סוכן.
  • ממשק API יחיד למודלים ולסוכנים: נקודת קצה (Endpoint) ותבנית מאוחדות לקריאה למודלים רגילים של Gemini וגם לסוכנים מיוחדים ישירות (כמו Deep Research וסוכנים מנוהלים בהתאמה אישית).
  • יכולות חדשות שזמינות לשימוש מיידי: תכונות כמו מצב שיחה אופציונלי בצד השרת באמצעות previous_interaction_id, שלבי ביצוע שניתנים לצפייה לצורך ניפוי באגים ועיבוד ממשק משתמש, וביצוע ברקע של משימות ארוכות טווח באמצעות background=true.
  • עלות נמוכה יותר עם שיעורי פגיעה גבוהים יותר במטמון: כשמשתמשים בשיחות מרובות תורות, ניהול מצב אופציונלי בצד השרת מאפשר שמירה יעילה יותר של הקשר במטמון בין התורות, וכך מקטין את עלויות האסימונים.
  • איפה יושקו התכונות החדשות: מעכשיו, כל המודלים החדשים, היכולות המולטימודאליות, הכלים והתכונות של הסוכנים יושקו ב-Interactions API.

כברירת מחדל, ה-Interactions API שומר בקשות כדי שתוכלו להשתמש בתכונות של ניהול מצב בצד השרת באמצעות previous_interaction_id. כדי להפעיל התנהגות חסרת מצב, צריך להגדיר את store=false. פרטים נוספים זמינים בקטע שמירת נתונים.

שנתחיל?

  • הגדרת סוכן התכנות: מתחברים ל-Gemini Docs MCP ומתקינים את מיומנות gemini-interactions-api כדי לתת לעוזר הדיגיטלי גישה ישירה למסמכי העזרה למפתחים ולשיטות המומלצות העדכניים ביותר. הוראות מפורטות מופיעות במאמר בנושא הגדרת סוכן קידוד.
  • מעבר מ-generateContent: אם יש לכם שילוב קיים, כדאי לעיין במדריך למעבר כדי לעבור ל-Interactions API.
  • איך מתחילים: פועלים לפי השלבים במדריך איך מתחילים להשתמש ב-Interactions API.

מדריכים לתכונות

במדריכים האלה מוסבר על היכולות הספציפיות של Interactions API. אפשר להשתמש במתג בדפים האלה כדי לעבור בין generateContent לבין Interactions API:

איך Interactions API פועל

ה-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 וכו')

כלומר, אם רוצים שהפרמטרים האלה יחולו, צריך לציין אותם מחדש בכל אינטראקציה חדשה. ניהול המצב בצד השרת הוא אופציונלי. אפשר גם לפעול במצב חסר מצב (stateless) על ידי שליחת היסטוריית השיחות המלאה בכל בקשה.

אחסון ושמירה של נתונים

כברירת מחדל, ה-API שומר את כל אובייקטי האינטראקציה (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

ממשק ה-API שומר בקשות של Interactions API שמופעלות באמצעות store=true עבור פרויקטים ברמה בתשלום. אפשר לראות אותם ישירות בדף היומנים ב-Google AI Studio. מידע נוסף זמין במדריך ליומנים.

שיטות מומלצות

  • שיעור מציאות במטמון: שמירה במטמון באופן מרומז נתמכת במצב עם שמירת מצב ובמצב בלי שמירת מצב (ראו מדריך למתחילים). השימוש ב-previous_interaction_id (עם שמירת מצב) כדי להמשיך שיחות מאפשר למערכת להשתמש בקלות רבה יותר בשמירת מטמון מרומזת של היסטוריית השיחות, וכך לשפר את הביצועים ולהפחית את העלויות.
  • שילוב אינטראקציות: אתם יכולים לשלב בין אינטראקציות עם נציג ועם מודל במהלך שיחה. לדוגמה, אפשר להשתמש בסוכן מיוחד, כמו סוכן Deep Research, לאיסוף נתונים ראשוני, ואז להשתמש במודל Gemini רגיל למשימות המשך כמו סיכום או עיצוב מחדש, ולקשר בין השלבים האלה באמצעות previous_interaction_id.

מודלים וסוכנים נתמכים

שם דגם סוג מזהה דגם
Gemini 3.5 Flash מודל gemini-3.5-flash
‫Gemini 3.1 Pro Preview מודל gemini-3.1-pro-preview
Gemini 3.1 Flash-Lite מודל gemini-3.1-flash-lite
‫Gemini 3 Flash Preview מודל 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 Image מודל gemini-3-pro-image
תמונה של Gemini 3.1 Flash מודל gemini-3.1-flash-image
‫Gemini 3.1 Flash TTS Preview מודל 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
גרסת טרום-השקה (Preview) של Lyria 3 Pro מודל lyria-3-pro-preview
גרסת טרום-השקה (Preview) של Deep Research סוכן deep-research-preview-04-2026
גרסת טרום-השקה (Preview) של Deep Research סוכן deep-research-max-preview-04-2026
תצוגה מקדימה של Antigravity סוכן antigravity-preview-05-2026

ערכות SDK

אתם יכולים להשתמש בגרסה העדכנית של Google GenAI SDK כדי לגשת ל-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 AI.

המאמרים הבאים