במשימות ארוכות כמו Deep Research, הסקת מסקנות מורכבת או הפעלת סוכנים בכמה שלבים, זמן קצוב לתפוגה של החיבור עלול להפריע לבקשות HTTP רגילות (שבדרך כלל נסגרות אחרי 60 שניות). Interactions API מספק הרצה ברקע כדי להריץ את המשימות האלה באופן אסינכרוני.
כדי לאפשר לאינטראקציה לפעול עד שהיא משלימה את המשימה בשרת, מגדירים את "background": true כשיוצרים את האינטראקציה. ה-API מחזיר מיד מזהה אינטראקציה, שאפליקציות לקוח יכולות להשתמש בו כדי לבדוק את הסטטוס, לעקוב אחרי ההתקדמות של השידור החי או להתחבר מחדש לשידור חי שהתנתק.
אפשר להפעיל ברקע מודלים רגילים של Gemini (כמו gemini-4-argon ו-gemini-3.8-flash) וסוכנים מנוהלים (כמו antigravity-preview-09-2026).
יצירת אינטראקציה ברקע
כדי להתחיל אינטראקציה ברקע, מגדירים את הפרמטר background לערך true כשיוצרים את המשאב.
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="Write a guide on space exploration.",
background=True,
)
print(f"Created background interaction ID: {interaction.id}")
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3.8-flash",
input: "Write a guide on space exploration.",
background: true,
});
console.log(`Created background interaction ID: ${interaction.id}`);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model("gemini-3.8-flash")
.input(InteractionsInput.of("Write a guide on space exploration."))
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Created background interaction ID: " + interaction.id().orElse(""));
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
Input: interactions.NewInteractionsInput("Write a guide on space exploration."),
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.ID != nil {
fmt.Printf("Created background interaction ID: %s\n", *res.Interaction.ID)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-3.8-flash",
"input": "Write a guide on space exploration.",
"background": true
}'
איך פועלת הרצה ברקע
כשיוצרים אינטראקציה ברקע, המשימה פועלת באופן אסינכרוני בשרת. האינטראקציה עוברת בין מצבי ביצוע שונים:
-
in_progress: השרת מבצע את האינטראקציה (למשל, מריץ קוד או מבצע מחקר). requires_action: האינטראקציה הושהתה וממתינה לקלט מהלקוח (למשל, אישור הפעלה של כלי או מענה על שאלה).-
completed: האינטראקציה הסתיימה בהצלחה והפלט זמין. -
failed: אירעה שגיאה במהלך הביצוע (למשל, כשל בכלי או הגבלת קצב של יצירת בקשות). -
cancelled: בקשת לקוח עצרה את ההרצה.
תרחישים לדוגמה
שימוש בהרצה ברקע בשביל:
הרצות של סוכנים: משימות שדורשות הרצת קוד, גלישה באינטרנט או תזמור של סוכני משנה (כמו
antigravity-preview-09-2026).Deep Research: הפעלות באמצעות
deep-research-preview-04-2026אוdeep-research-max-preview-04-2026שנמשכות כמה דקות.תהליך חשיבה ארוך: משימות שבהן שלבי החשיבה המורחבים של המודל חורגים ממגבלות החיבור הרגילות של HTTP.
פענוח ארוך (Gemini 4): משימות שיוצרות השלמות מורחבות מעבר ל-
65,536טוקנים. ב-gemini-4-argon, אפשר להגדירmax_output_tokensעד1,048,576אסימונים באמצעות פענוח ארוך.
שמירת נתונים להרצה ברקע
כדי להפעיל ברקע (background=True) צריך להשתמש ב-store=True (ברירת המחדל), כדי שהשרת יוכל לאחסן את האינטראקציה בזמן שאתם דוגמים או מזרימים תוצאות. העברת background=True עם store=False מחזירה שגיאת 400.
האינטראקציות ברקע שנשמרות פועלות בהתאם למדיניות הרגילה של אחסון ושמירת נתונים ב-Interactions API:
- גרסה בתשלום: נשמרים למשך 55 ימים (אפשר להגדיר ל-7, 14, 28 או 55 ימים ב-Google AI Studio).
- תוכנית בחינם: נשמרים למשך יום אחד.
כדי להסיר אינטראקציה ברקע לפני כן, מוחקים את האינטראקציה אחרי שמקבלים את התוצאה.
אחזור תוצאות
מקבלים את התוצאות של האינטראקציה ברקע באמצעות סקרים או סטרימינג.
דפוס דגימה (לא חוסם)
בשיטת הסקר, המערכת בודקת את סטטוס האינטראקציה מדי פעם באמצעות בקשות GET שלא חוסמות את הפעולה, עד שהיא מגיעה למצב סופי.
Python
import time
from google import genai
client = genai.Client()
interaction = client.interactions.get(id="YOUR_INTERACTION_ID")
while interaction.status == "in_progress":
time.sleep(5)
interaction = client.interactions.get(id=interaction.id)
if interaction.status == "completed":
print(interaction.output_text)
else:
print(f"Finished with status: {interaction.status}")
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
let interaction = await client.interactions.get("YOUR_INTERACTION_ID");
while (interaction.status === "in_progress") {
await new Promise(resolve => setTimeout(resolve, 5000));
interaction = await client.interactions.get(interaction.id);
}
if (interaction.status === "completed") {
console.log(interaction.output_text);
} else {
console.log(`Finished with status: ${interaction.status}`);
}
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
Client client = new Client();
Interaction interaction =
client.interactions
.get(GetInteractionByIdRequest.builder().id("YOUR_INTERACTION_ID").build())
.interaction()
.get();
while (InteractionStatus.IN_PROGRESS.equals(interaction.status().orElse(null))) {
Thread.sleep(5000);
interaction =
client.interactions
.get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())
.interaction()
.get();
}
if (InteractionStatus.COMPLETED.equals(interaction.status().orElse(null))) {
System.out.println(interaction.outputText().orElse(""));
} else {
System.out.println(
"Finished with status: " + interaction.status().map(InteractionStatus::value).orElse(""));
}
Go
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: "YOUR_INTERACTION_ID",
})
if err != nil {
log.Fatal(err)
}
interaction := res.Interaction
for interaction.Status == interactions.InteractionStatusInProgress {
time.Sleep(5 * time.Second)
res, err = client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: *interaction.ID,
})
if err != nil {
log.Fatal(err)
}
interaction = res.Interaction
}
if interaction.Status == interactions.InteractionStatusCompleted {
if interaction.OutputText != nil {
fmt.Println(*interaction.OutputText)
}
} else {
fmt.Printf("Finished with status: %s\n", interaction.Status)
}
}
REST
curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20"
תבנית סטרימינג
אם השידור מתנתק בגלל הפרעה ברשת, אפשר להמשיך את השידור מהאירוע האחרון שהתקבל. כל דלתא מכילה event_id ייחודי במטען הייעודי (payload) שלה. העברת המזהה הזה בתור last_event_id מחדשת את הסטרימינג מהאירוע הזה.
Python
import time
from google import genai
client = genai.Client()
interaction_id = "YOUR_INTERACTION_ID"
def stream_with_reconnect(interaction_id: str):
last_event_id = None
while True:
try:
# Retrieve the stream. If resuming, pass last_event_id
stream = client.interactions.get(
id=interaction_id,
stream=True,
last_event_id=last_event_id
)
for event in stream:
# Log event updates and capture event_id if present
if event.event_id:
last_event_id = event.event_id
if event.event_type == "step.delta" and event.delta.type == "text":
print(event.delta.text, end="", flush=True)
if event.event_type == "interaction.completed":
return
except Exception as e:
print(f"\n[Connection lost: {e}. Reconnecting in 3s...]")
time.sleep(3)
stream_with_reconnect(interaction_id)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interactionId = "YOUR_INTERACTION_ID";
async function streamWithReconnect(id) {
let lastEventId = undefined;
while (true) {
try {
// Retrieve the stream. If resuming, pass last_event_id in options
const stream = await client.interactions.get(id, {
stream: true,
last_event_id: lastEventId
});
for await (const event of stream) {
// Capture event_id if present
const idVal = event.event_id || event.id;
if (idVal) {
lastEventId = idVal;
}
if (event.event_type === "step.delta" && event.delta?.type === "text") {
process.stdout.write(event.delta.text);
}
if (event.event_type === "interaction.completed") {
return;
}
}
} catch (error) {
console.log(`\n[Connection lost: ${error.message}. Reconnecting in 3s...]`);
await new Promise(resolve => setTimeout(resolve, 3000));
}
}
}
await streamWithReconnect(interactionId);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.InteractionCompletedEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import com.google.genai.gaos.utils.EventStream;
Client client = new Client();
String interactionId = "YOUR_INTERACTION_ID";
String lastEventId = null;
boolean completed = false;
while (!completed) {
try (EventStream<InteractionSSEStreamEvent> stream =
client.interactions
.get(
GetInteractionByIdRequest.builder()
.id(interactionId)
.stream(true)
.lastEventId(lastEventId)
.build())
.events()) {
for (InteractionSSEStreamEvent streamEvent : stream) {
InteractionSSEEvent event = streamEvent.data().orElse(null);
if (event instanceof StepDelta) {
StepDelta stepDelta = (StepDelta) event;
if (stepDelta.eventId().isPresent()) {
lastEventId = stepDelta.eventId().get();
}
if (stepDelta.delta().isPresent() && stepDelta.delta().get() instanceof TextDelta) {
System.out.print(((TextDelta) stepDelta.delta().get()).text().orElse(""));
System.out.flush();
}
} else if (event instanceof InteractionCompletedEvent) {
completed = true;
break;
}
}
} catch (Exception e) {
System.out.println("\n[Connection lost: " + e.getMessage() + ". Reconnecting in 3s...]");
Thread.sleep(3000);
}
}
Go
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
interactionID := "YOUR_INTERACTION_ID"
var lastEventID *string
completed := false
for !completed {
res, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: interactionID,
Stream: genai.Ptr(true),
LastEventID: lastEventID,
})
if err != nil {
fmt.Printf("\n[Connection lost: %v. Reconnecting in 3s...]\n", err)
time.Sleep(3 * time.Second)
continue
}
stream := res.InteractionSSEStreamEvent
for stream.Next() {
event := stream.Value()
if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
if stepDelta.EventID != nil {
lastEventID = stepDelta.EventID
}
if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
fmt.Print(textDelta.GetText())
}
} else if event.GetDataInteractionCompleted() != nil {
completed = true
break
}
}
if err := stream.Err(); err != nil {
fmt.Printf("\n[Stream error: %v. Reconnecting in 3s...]\n", err)
_ = stream.Close()
time.Sleep(3 * time.Second)
continue
}
_ = stream.Close()
}
}
REST
curl -N -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID?stream=true&last_event_id=YOUR_LAST_EVENT_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20"
שיחות עם זיכרון
אינטראקציות נוספות יכולות להמשיך שיחה ברקע באמצעות previous_interaction_id, בכפוף למגבלות הבאות:
- הפעלות פעילות חסומות: שרשור של אינטראקציה עוקבת לאינטראקציה עם סטטוס
in_progressמחזיר שגיאה מסוג400 Bad Request. צריך לחכות שהאינטראקציה תגיע למצבcompletedלפני שמתחילים את האינטראקציה הבאה. - פרמטר סביבה לנציגים מנוהלים: כשמשרשרים אינטראקציות לנציגים מנוהלים (כמו
antigravity-preview-09-2026), הבקשות חייבות לכלול גם אתprevious_interaction_idוגם אתenvironment.
הדוגמאות הבאות מראות איך לשרשר אינטראקציות:
Python
import time
from google import genai
client = genai.Client()
agent_model = "antigravity-preview-09-2026"
# First interaction: Provision sandbox environment and execute first instruction
interaction1 = client.interactions.create(
agent=agent_model,
input="Create a folder named project/ and write hello.py inside.",
environment="remote",
background=True
)
# Wait for completion
while True:
check = client.interactions.get(id=interaction1.id)
if check.status != "in_progress":
break
time.sleep(2)
# Second interaction: Chain using previous_interaction_id and environment
interaction2 = client.interactions.create(
agent=agent_model,
input="List all files in the project/ directory.",
previous_interaction_id=interaction1.id,
environment="remote",
background=True
)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const agentModel = "antigravity-preview-09-2026";
// First interaction: Provision sandbox environment and execute first instruction
const interaction1 = await client.interactions.create({
agent: agentModel,
input: "Create a folder named project/ and write hello.py inside.",
environment: "remote",
background: true
});
// Wait for completion
while (true) {
const check = await client.interactions.get(interaction1.id);
if (check.status !== "in_progress") {
break;
}
await new Promise(resolve => setTimeout(resolve, 2000));
}
// Second interaction: Chain using previous_interaction_id and environment
const interaction2 = await client.interactions.create({
agent: agentModel,
input: "List all files in the project/ directory.",
previous_interaction_id: interaction1.id,
environment: "remote",
background: true
});
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
Client client = new Client();
String agentModel = "antigravity-preview-09-2026";
// First interaction: Provision sandbox environment and execute first instruction
CreateModelInteraction params1 =
CreateModelInteraction.builder()
.model(agentModel)
.input(InteractionsInput.of("Create a folder named project/ and write hello.py inside."))
.environment(CreateModelInteractionEnvironment.of("remote"))
.background(true)
.build();
Interaction interaction1 =
client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();
// Wait for completion
while (true) {
Interaction check =
client.interactions
.get(GetInteractionByIdRequest.builder().id(interaction1.id().get()).build())
.interaction()
.get();
if (!InteractionStatus.IN_PROGRESS.equals(check.status().orElse(null))) {
break;
}
Thread.sleep(2000);
}
// Second interaction: Chain using previousInteractionId and environment
CreateModelInteraction params2 =
CreateModelInteraction.builder()
.model(agentModel)
.input(InteractionsInput.of("List all files in the project/ directory."))
.previousInteractionId(interaction1.id().get())
.environment(CreateModelInteractionEnvironment.of("remote"))
.background(true)
.build();
Interaction interaction2 =
client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();
Go
package main
import (
"context"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
agentModel := interactions.Model("antigravity-preview-09-2026")
remoteEnv := interactions.NewCreateModelInteractionEnvironment("remote")
// First interaction: Provision sandbox environment and execute first instruction
res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: agentModel,
Input: interactions.NewInteractionsInput("Create a folder named project/ and write hello.py inside."),
Environment: &remoteEnv,
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
// Wait for completion
for {
check, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: *res1.Interaction.ID,
})
if err != nil {
log.Fatal(err)
}
if check.Interaction.Status != interactions.InteractionStatusInProgress {
break
}
time.Sleep(2 * time.Second)
}
// Second interaction: Chain using PreviousInteractionID and Environment
_, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: agentModel,
Input: interactions.NewInteractionsInput("List all files in the project/ directory."),
PreviousInteractionID: res1.Interaction.ID,
Environment: &remoteEnv,
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
}
REST
# Chain second interaction (Make sure FIRST_INTERACTION_ID has status 'completed')
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-H "Api-Revision: 2026-05-20" \
-d '{
"agent": "antigravity-preview-09-2026",
"input": "List all files in the project/ directory.",
"previous_interaction_id": "FIRST_INTERACTION_ID",
"environment": "remote",
"background": true
}'
ביטול ומחיקה
אתם יכולים לשלוט בהפעלות שרצות ולנהל את האחסון באמצעות בקשות ביטול ומחיקה:
- ביטול (
POST /interactions/{id}/cancel): הפסקת המשימה שפועלת. הסטטוס משתנה ל-cancelled. פעולות ניקוי בשרת יכולות לגרום לעיכוב קל לפני שהסטטוס מתעדכן בבקשות GET. מחיקה (
DELETE /interactions/{id}): הסרת רשומות האינטראקציה מהשרת. בקשות GET הבאות מחזירות שגיאת404 Not Found.
Python
from google import genai
client = genai.Client()
# Cancel a running interaction
client.interactions.cancel(id="YOUR_INTERACTION_ID")
# Delete the interaction record entirely
client.interactions.delete(id="YOUR_INTERACTION_ID")
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
// Cancel a running interaction
await client.interactions.cancel("YOUR_INTERACTION_ID");
// Delete the interaction record entirely
await client.interactions.delete("YOUR_INTERACTION_ID");
Java
import com.google.genai.Client;
Client client = new Client();
// Cancel a running interaction
client.interactions.cancel("YOUR_INTERACTION_ID");
// Delete the interaction record entirely
client.interactions.delete("YOUR_INTERACTION_ID");
Go
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
// Cancel a running interaction
_, err = client.Interactions.Cancel(ctx, operations.CancelInteractionByIDRequest{
ID: "YOUR_INTERACTION_ID",
})
if err != nil {
log.Fatal(err)
}
// Delete the interaction record entirely
_, err = client.Interactions.Delete(ctx, operations.DeleteInteractionRequest{
ID: "YOUR_INTERACTION_ID",
})
if err != nil {
log.Fatal(err)
}
}
REST
# Cancel the interaction
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID/cancel" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20"
# Delete the interaction
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20"
השלבים הבאים
- כדי להבין איך מנהלים סשנים ומצבים, קראו את הסקירה הכללית על Interactions API.
- במדריך אינטראקציות בסטרימינג מוסבר איך לעדכן אירועים בזמן אמת.
- במדריך למתחילים בנושא סוכנים מנוהלים מוסבר איך ליצור סוכנים עם מצב (stateful) לשיחות מרובות-שלבים.