Interactions API

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

למה כדאי להשתמש ב-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 פועל

ממשק ה-API של האינטראקציות מתבסס על משאב ליבה: Interaction. משאב Interaction מייצג תור שלם בשיחה או במשימה. הוא משמש כרשומה של סשן, ומכיל את ההיסטוריה המלאה של אינטראקציה כרצף כרונולוגי של שלבי ביצוע. השלבים האלה כוללים מחשבות של המודל, קריאות לכלים ותוצאות בצד השרת או בצד הלקוח (כמו function_call ו-function_result), ואת model_output הסופי. המשאב המאוחסן (שמאוחזר באמצעות interactions.get) כולל גם שלבי user_input להקשר מלא, אבל בתגובת interactions.create מוחזרים רק שלבים שנוצרו על ידי המודל.

כשמתקשרים אל interactions.create, נוצר משאב חדש של Interaction.

גישה לפלט באמצעות מאפייני נוחות של SDK

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

ערכות ה-SDK של Google GenAI מספקות מאפייני נוחות ישירות באובייקט 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 וכו')

כלומר, אם רוצים שהפרמטרים האלה יחולו, צריך לציין אותם מחדש בכל אינטראקציה חדשה. ניהול המצב בצד השרת הוא אופציונלי. אפשר גם לפעול במצב חסר מצב (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.5 Flash מודל gemini-3.5-flash
Gemini 3.1 Flash-Lite מודל gemini-3.1-flash-lite
‫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
גרסת טרום-השקה (Preview) של Deep Research סוכן deep-research-pro-preview-12-2025
גרסת טרום-השקה (Preview) של Deep Research סוכן deep-research-preview-04-2026
גרסת טרום-השקה (Preview) של Deep Research סוכן deep-research-max-preview-04-2026

ערכות SDK

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

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

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

מגבלות

  • סטטוס בטא: ממשק ה-API של האינטראקציות נמצא בגרסת בטא או בתצוגה מקדימה. יכול להיות שיהיו שינויים בתכונות ובסכימות.
  • MCP מרחוק: Gemini 3 לא תומך ב-MCP מרחוק, אבל התמיכה הזו תגיע בקרוב.

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

שינויי תוכנה שעלולים לגרום לכשלים

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

שינויים קיימים שעלולים לגרום לכשל:

  • סכימת השלבים: מערך חדש של שלבים מחליף את מערך הפלט, ומספק ציר זמן מובנה של כל תור אינטראקציה.

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

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

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

משוב

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

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