اجرای پس زمینه

برای وظایف طولانی مدت مانند تحقیقات عمیق، استدلال پیچیده یا اجرای چند مرحله‌ای عامل، وقفه‌های اتصال می‌توانند درخواست‌های استاندارد 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 به یک مکالمه پس‌زمینه متصل شوند، البته با رعایت این محدودیت‌ها:

  1. اجراهای فعال مسدود می‌شوند: زنجیره‌سازی یک تعامل بعدی به تعاملی با وضعیت in_progress ، خطای 400 Bad Request را برمی‌گرداند. قبل از شروع تعامل بعدی، منتظر بمانید تا تعامل به حالت completed برسد.
  2. پارامتر محیطی برای عوامل مدیریت‌شده: هنگام زنجیره‌سازی تعاملات برای عوامل مدیریت‌شده (مانند 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"

مراحل بعدی