برای وظایف طولانی مدت مانند تحقیقات عمیق، استدلال پیچیده یا اجرای چند مرحلهای عامل، وقفههای اتصال میتوانند درخواستهای استاندارد HTTP (که معمولاً پس از 60 ثانیه بسته میشوند) را قطع کنند. API تعاملات، اجرای پسزمینه را برای اجرای این وظایف به صورت غیرهمزمان فراهم میکند.
برای اینکه تعامل تا زمان تکمیل وظیفه در سرور اجرا شود، هنگام ایجاد تعامل، "background": true را تنظیم کنید. API بلافاصله یک شناسه تعامل را برمیگرداند که برنامههای کلاینت میتوانند از آن برای نظرسنجی در مورد وضعیت، پیشرفت جریان یا اتصال مجدد به یک جریان قطع شده استفاده کنند.
اجرای پسزمینه برای مدلهای استاندارد Gemini (مانند gemini-3.5-flash و gemini-3.1-pro-preview ) و Managed Agents (مانند antigravity-preview-05-2026 ) پشتیبانی میشود.
ایجاد یک تعامل پسزمینه
برای شروع یک تعامل پسزمینه، هنگام ایجاد منبع، پارامتر background را روی true تنظیم کنید.
پایتون
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.5-flash",
input="Write a guide on space exploration.",
background=True,
)
print(f"Created background interaction ID: {interaction.id}")
جاوا اسکریپت
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3.5-flash",
input: "Write a guide on space exploration.",
background: true,
});
console.log(`Created background interaction ID: ${interaction.id}`);
استراحت
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.5-flash",
"input": "Write a guide on space exploration.",
"background": true
}'
نحوه اجرای پس زمینه
وقتی یک تعامل پسزمینه ایجاد میکنید، وظیفه (task) به صورت ناهمگام (asynchronous) روی سرور اجرا میشود. این تعامل از حالتهای اجرایی مختلفی عبور میکند:
-
in_progress: سرور به طور فعال در حال اجرای تعامل (مانند اجرای کد یا تحقیق) است. -
requires_action: تعامل متوقف شده و منتظر ورودی کلاینت است (مانند تأیید اجرای یک ابزار یا پاسخ به یک سوال). -
completed: تعامل با موفقیت پایان یافت و خروجی در دسترس است. -
failed: خطایی در حین اجرا رخ داده است (مانند خرابی ابزار یا محدودیتهای سرعت). -
cancelled: درخواست کلاینت، اجرا را متوقف کرد.
موارد استفاده
استفاده از اجرای پسزمینه برای:
اجراهای عامل: وظایفی که نیاز به اجرای کد، مرور وب یا هماهنگی زیرعامل دارند (مانند
antigravity-preview-05-2026).تحقیقات عمیق: با استفاده از
deep-research-preview-04-2026یاdeep-research-max-preview-04-2026اجرا میشود که چند دقیقه طول میکشد.استدلال طولانی: وظایفی که در آنها مراحل تفکر مدل از محدودیتهای اتصال استاندارد HTTP فراتر میرود.
بازیابی نتایج
نتایج تعامل پسزمینه را با استفاده از نظرسنجی یا جریانسازی به دست آورید.
الگوی نظرسنجی (غیر مسدودکننده)
نظرسنجی وضعیت تعامل را به صورت دورهای با استفاده از درخواستهای GET بدون انسداد بررسی میکند تا زمانی که به حالت ترمینال برسد.
پایتون
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}")
جاوا اسکریپت
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}`);
}
استراحت
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 پخش جریانی را از آن رویداد از سر میگیرد.
پایتون
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)
جاوا اسکریپت
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);
استراحت
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-05-2026)، درخواستها باید شاملprevious_interaction_idوenvironmentباشند.
مثالهای زیر نحوهی زنجیرهسازی تعاملات را نشان میدهند:
پایتون
import time
from google import genai
client = genai.Client()
agent_model = "antigravity-preview-05-2026"
# First interaction: Provision sandbox environment and execute first instruction
interaction1 = client.interactions.create(
model=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(
model=agent_model,
input="List all files in the project/ directory.",
previous_interaction_id=interaction1.id,
environment="remote",
background=True
)
جاوا اسکریپت
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const agentModel = "antigravity-preview-05-2026";
// First interaction: Provision sandbox environment and execute first instruction
const interaction1 = await client.interactions.create({
model: 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({
model: agentModel,
input: "List all files in the project/ directory.",
previous_interaction_id: interaction1.id,
environment: "remote",
background: true
});
استراحت
# 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 '{
"model": "antigravity-preview-05-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را برمیگردانند.
پایتون
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")
جاوا اسکریپت
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");
استراحت
# 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"
مراحل بعدی
- برای درک مدیریت جلسه و وضعیت، مرور کلی API تعاملات را مطالعه کنید.
- برای جزئیات بیشتر در مورد بهروزرسانیهای رویداد در لحظه، به راهنمای تعاملات پخش زنده مراجعه کنید.
- برای ساخت عاملهای چند نوبتیِ دارای وضعیت ، راهنمای سریع عاملهای مدیریتشده را بررسی کنید.