סקירה כללית על Interactions API

‫Interactions API מספק ממשק מאוחד עם שמירת מצב (stateful) לפיתוח אפליקציות מבוססות-AI גנרטיבי ותהליכי עבודה Agentic Workflows באמצעות מודלים של Gemini וסוכנים שמתארחים ב-Gemini Enterprise Agent Platform. למרות שיש חפיפה בין התכונות של generateContent API לבין אלה של generateContent API, אנחנו ממשיכים לתמוך באופן מלא ב-API.

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

ל-Interactions API יש כמה יתרונות מרכזיים בפיתוח אפליקציות מבוססות-AI גנרטיבי ותהליכי עבודה מבוססי-סוכנים:

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

איך Interactions API פועל

המשאב Interaction הוא המרכז של Interactions API. ‫Interaction מייצג תור מלא בשיחה או במשימה ומשמש כרשומה של סשן שמכילה רצף כרונולוגי של ביצוע steps:

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

כששולחים קריאה ל-interactions.create, פלטפורמת Agent Platform מעבדת את הקלט, מפעילה את הכלים בצד השרת או את לולאות הסוכן שהוגדרו, ומחזירה את המשאב Interaction שנוצר. במדריך למפתחים של Interactions API יש דוגמאות קוד ב-Python, ב-TypeScript או ב-JavaScript וב-REST.

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

מודלי Gemini הבאים תומכים ב-Interactions API:

כדי להרחיב את רשימת המודלים הנתמכים, לוחצים כאן

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

  • ‫gemini-omni-flash-preview: מודל מולטי-מודאלי עם ביצועים גבוהים ליצירת סרטונים, עריכה ושליטה קולנועית באמצעות שיחה.
  • ‫lyria-3-clip-preview ו-lyria-3-pro-preview: מודלים ליצירת מוזיקה גנרטיבית לקליפים של אודיו באיכות גבוהה וליצירת שירים מלאים (נתמך רק באינטראקציות ללא שמירת מצב עם store=false).

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

כדי להפעיל את הסוכנים הבאים באמצעות Interactions API, צריך לציין את הפרמטר agent במקום model:

  • ‫antigravity-preview-05-2026: סוכן אוטונומי למטרות כלליות שמיועד לחשיבה רציונלית לאורך כמה שלבים, כתיבת קוד, פעולות בקבצים ושימוש בכלים.
  • ‫deep-research-preview-04-2026: Gemini Deep Research Agent שמיועד למחקר ולסיכום מידע מהאינטרנט באופן אוטונומי ובכמה שלבים.
  • סוכנים מנוהלים בהתאמה אישית שנפרסו בפלטפורמת הסוכנים.

תכונות ומפרטים

בקטעים הבאים מתוארות היכולות העיקריות, המפרטים הטכניים והשיקולים התפעוליים של Interactions API.

ניהול מצבים

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

כלים נתמכים והארקה

במודלים של Gemini 3 ב-Interactions API יש תמיכה בכלים המובנים, בספקי ה-grounding וביכולות החיפוש הבאים:

  • ‫עיגון באמצעות חיפוש Google ו-Web Grounding for Enterprise: מעגן את התשובות של המודל למידע בזמן אמת מהאינטרנט מחיפוש Google או מ-Web Grounding for Enterprise.
  • ‫Agent Search ו-RAG Engine ב-Gemini Enterprise Agent Platform: עיגון של תשובות המודל למאגרי נתונים פרטיים של הארגון ולמאגרי מסמכים באמצעות Agent Search ו-RAG Engine.
  • ‫xAI Search: מחבר מודלים לחיפוש בזמן אמת ברשתות חברתיות ול-grounding של ידע.
  • ‫Parallel Search: מבסס את התשובות של המודל על נתונים בזמן אמת שזמינים לכולם באינטרנט, באמצעות ה-API לחיפוש של Parallel Web Systems.
  • הרצת קוד: המודל יכול ליצור ולהריץ קוד Python בסביבה מאובטחת של ארגז חול (sandbox).
  • קריאה להפעלת פונקציות: מאפשרת למודלים להתחבר לכלים חיצוניים, לממשקי API ולמסדי נתונים על ידי החזרת ארגומנטים מובְנים של פונקציות.

‫Interactions API תומך ב-Web Grounding for Enterprise וב-עיגון באמצעות חיפוש Google. השימוש בתכונות האלה כפוף גם לתנאים הספציפיים לשירות.

חיוב

החיוב על השימוש ב-Interactions API מבוסס על צריכת טוקנים.

החיוב על בקשות שנקטעו או שלא הושלמו מתבצע באופן הבא:

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

אבטחה ותאימות

במהלך תקופת התצוגה המקדימה, יש לקחת בחשבון את השיקולים הבאים לגבי אבטחה, תאימות ומיקום אחסון הנתונים של Interactions API:

  • אישורים בנושא אבטחה ותאימות: גרסת הטרום-השקה של Interactions API לא תומכת ב-FedRAMP, והיא לא עומדת בדרישות של רמה 5 (IL5) של משרד ההגנה (DoD) או בדרישות של International Traffic in Arms Regulations (ITAR).
  • מפתחות הצפנה בניהול הלקוח (CMEK): ב-Interactions API יש תמיכה ב-CMEK לנתוני אינטראקציות שמאוחסנים באמצעות פרופילים להצגת מודעות (כאשר scope מוגדר ל-INTERACTIONS_API) באזורים us ו-eu.
  • ‫VPC Service Controls: גרסת הטרום-השקה של Interactions API תומכת ב-VPC Service Controls (VPC-SC) כדי לאבטח את היקף ה-API.
  • מיקום אחסון הנתונים: גרסת הטרום-השקה של Interactions API לא תומכת במיקום אחסון הנתונים ולא מתחייבת לשום דבר לגבי אחסון סשנים.
  • נקודות קצה: גרסת הטרום-השקה של Interactions API תומכת בנקודת הקצה הגלובלית (locations/global), ובנקודות הקצה מרובות האזורים us ו-eu (locations/us ו-locations/eu) כשמשתמשים ב-CMEK.

ערכות SDK נתמכות

אתם יכולים לגשת ל-Interactions API באמצעות Google Gen AI SDK המאוחד או באמצעות קריאות REST ישירות:

  • ‫Python: גרסה google-genai של 2.3.0 ואילך
  • ‫TypeScript / JavaScript: גרסה @google/genai של 2.3.0 ואילך
  • Go: google.golang.org/genai
  • Java: com.google.genai:google-genai

ערכות SDK מדור קודם (google-cloud-aiplatform,‏ @google-cloud/vertexai ו-google-generativeai) לא תומכות ב-Interactions API.

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