برای تکالیف طولانیمدت مثل پژوهش عمیق، استدلال پیچیده، یا اجرای چندمرحلهای عامل، مهلتهای زمانی اتصال میتواند درخواستهای استاندارد HTTP را (که معمولاً پساز ۶۰ ثانیه بسته میشوند) قطع کند. میانای برنامهسازی کاربردی تعاملات اجرای پسزمینهای را برای اجرای ناهمزمان این کارها ارائه میدهد.
برای اینکه تعامل تا زمانی که تکلیف را در سرور تکمیل کند اجرا شود، "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}`);
جاوا
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(""));
رفتن
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-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، مدت زمان ذخیره شدن تعامل را پیکربندی کنید:
store=True(پیشفرض): بهمدت ۷ روز در فضای ذخیرهسازی بادوام برای پروژه شما ذخیره میشود.store=False: برای پروژه شما بهمدت ۲۴ ساعت (TTL) ذخیره میشود تا امکان بازیابی نتیجه بااستفاده از درخواستهایGETفراهم شود.
بازیابی نتایج
نتایج تعامل پسزمینهای را بااستفاده از رأیگیری یا جاریسازی دریافت کنید.
الگوی نظرسنجی (غیرمسدودکننده)
نظرسنجی وضعیت تعامل را بهطور دورهای بااستفاده از درخواستهای 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}`);
}
جاوا
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(""));
}
رفتن
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 منحصربهفرد در بار خود است. با ارسال این شناسه بهعنوان 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);
جاوا
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);
}
}
رفتن
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
});
جاوا
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();
رفتن
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)
}
}
استراحت
# 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");
جاوا
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");
رفتن
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 را بخوانید.
- برای جزئیات مربوط به بهروزرسانیهای رویداد همزمان، راهنمای تعاملهای جاریسازی را ببینید.
- برای ساختن عاملهای چندنوبتی با حفظ وضعیت، شروع سریع عاملهای مدیریتشده را کاوش کنید.