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

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

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

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

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

איך 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 מעבדת את הקלט, מפעילה את הכלים בצד השרת או את לולאות הסוכן שהוגדרו, ומחזירה את המשאב Interaction שנוצר. במדריך למפתחים של Interactions API יש דוגמאות קוד ב-Python, ב-TypeScript או ב-JavaScript וב-REST.

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

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

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

בנוסף למודלים של Gemini ברשימה שלמעלה, Interactions API תומך במודלים הבאים של מוזיקה גנרטיבית: * ‫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 שמיועד למחקר ולסיכום מידע מהאינטרנט באופן אוטונומי ובכמה שלבים.
  • סוכנים מנוהלים בהתאמה אישית שנפרסו ב-Agent Platform.

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

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

ניהול מצבים

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

מגבלות על בקשות ועל מולטי-מודאליות

‫Interactions API אוכף את המגבלות הבאות על המטען הייעודי (payload) של הבקשה ועל הקלט המולטימודלי:

  • מגבלות המטען הייעודי (payload) של הבקשה: המטען הייעודי הדחוס של בקשת ה-HTTP לא יכול להיות גדול מ-256MiB לבקשות interactions.create סינכרוניות ובסטרימינג. כשהערך של service_tier מוגדר כ-deferred (מה שמחייב שגם background וגם store יהיו true), הבקשה הלא דחוסה לא יכולה להיות גדולה מ-9.75MiB.
  • מגבלת ה-URI לקובצי Cloud Storage: בקשות אינטראקציה רגילות עם מודל Gemini תומכות בעד 100 מזהי URI נפרדים של Cloud Storage (gs://) לכל בקשה, כולל מזהי URI שהועברו מסבבי שיחה קודמים דרך previous_interaction_id. המגבלה של 100 מזהי URI לא חלה על אינטראקציות עם סוכנים מנוהלים, מודלים של Gemini Omni ומודלים של Lyria 3. במאמר גישה לקבצים שהועלו ל-Cloud Storage מוסבר איך לטפל בהרשאות ובמזהי URI בשיחות עם כמה פניות.
  • מגבלות על פריטים וטוקנים במודלים מרובי-מצבים: מודלי Gemini סטנדרטיים מקבלים את אותן כמויות פריטים לכל מצב כמו generateContent (עד 3,000 תמונות וקובצי PDF ביחד, 1,000 קובצי אודיו, 10 סרטונים ועד 6,500 קבצים מרובי-מצבים ביחד, כולל קובצי טקסט פשוט), בכפוף לחלון ההקשר של המודל, שכולל 1,048,576 טוקנים. הגודל של קובצי Cloud Storage לא יכול להיות יותר מ-2GiB פחות 500KiB, והגודל של כתובות URL ציבוריות מסוג HTTP או כתובות URL מסוג HTTPS לא יכול להיות יותר מ-15MiB. כדי לשלוח יותר מ-100 קבצים בבקשה אחת, צריך להעביר קבצים מצורפים נוספים בתוך השורה במגבלת המטען הייעודי (payload) של הבקשה או להפעיל את generateContent.

כלים נתמכים ועיגון (grounding)

במודלים של 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.
  • ‫Exa Web Search: מבסס את התשובות של המודל על תוצאות חיפוש באינטרנט מ-Exa Search API.
  • Parallel Web Search: מעגן את התשובות של המודל בנתונים בזמן אמת מהאינטרנט הציבורי, שמסופקים על ידי ה-API של Parallel Web Systems לחיפוש באינטרנט.
  • הקשר של כתובת URL: מאחזר ומנתח תוכן מכתובות URL ציבוריות שכלולות בהנחיה.
  • הפעלת קוד: מאפשרת למודל ליצור ולהפעיל קוד Python בסביבה מאובטחת של ארגז חול (sandbox).
  • שימוש במחשב: מאפשר תהליכי עבודה אוטומטיים בדפדפן ובממשק המשתמש.
  • קריאה להפעלת פונקציות: מאפשרת למודלים להתחבר לכלים, לממשקי API ולמסדי נתונים חיצוניים על ידי החזרת ארגומנטים מובְנים של פונקציות.

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

חיוב

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

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

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

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

‫Interactions API תומך באמצעי בקרת האבטחה, אישורי התאימות והגדרות נקודות הקצה הבאים:

  • נקודות קצה (endpoints): ב-Interactions API יש תמיכה בנקודת הקצה הגלובלית (locations/global ב-aiplatform.googleapis.com) ובנקודות הקצה במספר אזורים us ו-eu (locations/us ב-aiplatform.us.rep.googleapis.com ו-locations/eu ב-aiplatform.eu.rep.googleapis.com). אין תמיכה בנקודות קצה באזור יחיד (כמו us-central1 או europe-west1).
  • מיקום אחסון הנתונים: כשמשתמשים בנקודות הקצה (endpoints) במספר אזורים us ו-eu (locations/us ו-locations/eu), ב-Interactions API יש תמיכה במיקום אחסון הנתונים גם לעיבוד נתוני למידת מכונה (בשימוש) וגם לנתוני אינטראקציות באחסון (store=true). בקשות שנשלחות לנקודת הקצה global לא מספקות הבטחות לגבי מיקום אחסון הנתונים.
  • מפתחות הצפנה בניהול הלקוח (CMEK): ב-Interactions API יש תמיכה ב-CMEK לנתוני אינטראקציות שמאוחסנים באמצעות פרופילים להצגת מודעות (כאשר scope מוגדר ל-INTERACTIONS_API) באזורים מרובי אזורים us ו-eu. נקודת הקצה (endpoint) global לא נתמכת ב-CMEK.
  • ‫VPC Service Controls ‏(VPC-SC): Interactions API תומך ב-VPC-SC כדי לאבטח את היקף ה-API ולצמצם את הסיכונים לזליגת נתונים.
  • ‫Access Transparency ‏(AXT): Interactions API תומך ביומני AXT כדי לספק נראות כמעט בזמן אמת כשאנשי Google ניגשים לתוכן אינטראקציה ששמור.
  • אישורי אבטחה ותאימות: Interactions API עומד בדרישות של FedRAMP High במסגרת גבולות ההרשאה של Google Cloud FedRAMP High. ‫Interactions API לא עומד בדרישות של משרד ההגנה של ארה"ב (DoD) לרמת השפעה 5 (IL5) או בדרישות של התקנות הבינלאומיות לסחר בנשק (ITAR).

ערכות 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.

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