Interactions API

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

למרות שה-API המקורי של generateContent נחשב עכשיו לגרסה מדור קודם, הוא עדיין נתמך באופן מלא.

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

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

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

שנתחיל?

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

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

במדריכים האלה מוסבר על היכולות הספציפיות של 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 לא תואם ל-background=true ומונע שימוש ב-previous_interaction_id בפניות הבאות.

אתם יכולים למחוק את האינטראקציות השמורות מתי שתרצו באמצעות שיטת המחיקה שמופיעה במדריך העזר ל-API. אפשר למחוק אינטראקציות רק אם יודעים את מזהה האינטראקציה.

אחרי שתקופת השמירה תסתיים, הנתונים יימחקו באופן אוטומטי.

המערכת מעבדת אובייקטים של אינטראקציות בהתאם לתנאים.

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

  • שיעור הפגיעות במטמון: השימוש ב-previous_interaction_id כדי להמשיך שיחות מאפשר למערכת לנצל בקלות רבה יותר את השמירה במטמון של היסטוריית השיחות, וכך לשפר את הביצועים ולהפחית את העלויות.
  • שילוב אינטראקציות: אתם יכולים לשלב בין אינטראקציות עם נציג ועם מודל במהלך שיחה. לדוגמה, אפשר להשתמש בסוכן מיוחד, כמו סוכן Deep Research, לאיסוף נתונים ראשוני, ואז להשתמש במודל 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 Preview מודל gemini-3.1-pro-preview
‫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
תצוגה מקדימה של קליפ ב-Lyria 3 מודל lyria-3-clip-preview
גרסת טרום-השקה (Preview) של Lyria 3 Pro מודל lyria-3-pro-preview
Deep Research Preview סוכן deep-research-pro-preview-12-2025
Deep Research Preview סוכן deep-research-preview-04-2026
Deep Research Preview סוכן deep-research-max-preview-04-2026
תצוגה מקדימה של Antigravity סוכן antigravity-preview-05-2026

ערכות SDK

אתם יכולים להשתמש בגרסה העדכנית של Google GenAI SDK כדי לגשת ל-Interactions API.

  • ב-Python, זו חבילת google-genai החל מגרסה 1.55.0.
  • ב-JavaScript, החל מגרסה 1.33.0 של חבילת @google/genai.

מידע נוסף על התקנת ערכות ה-SDK זמין בדף ספריות.

מגבלות

  • MCP מרוחק: Gemini 3 לא תומך ב-MCP מרוחק, אבל התמיכה הזו תגיע בקרוב.

התכונות הבאות נתמכות על ידי generateContent API, אבל עדיין לא זמינות ב-Interactions API:

משוב

המשוב שלכם חשוב מאוד לפיתוח של Interactions API. אתם יכולים לשתף את המחשבות שלכם, לדווח על באגים או לבקש תכונות בפורום הקהילה של מפתחי Google AI.

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