التنفيذ في الخلفية

بالنسبة إلى المهام الطويلة، مثل البحث المعمّق أو الاستدلال المعقّد أو عمليات تنفيذ الوكيل المتعدّدة الخطوات، يمكن أن تؤدي مهلات الاتصال إلى مقاطعة طلبات HTTP العادية (التي يتم إغلاقها عادةً بعد 60 ثانية). توفر Interactions API ميزة التنفيذ في الخلفية لتشغيل هذه المهام بشكل غير متزامن.

للسماح بتشغيل التفاعل إلى أن يكمل المهمة على الخادم، اضبط "background": true عند إنشاء التفاعل. تعرض واجهة برمجة التطبيقات على الفور معرّف تفاعل، يمكن لتطبيقات العميل استخدامه للتحقّق من الحالة أو بثّ مستوى التقدّم أو إعادة الاتصال ببثّ تم قطع اتصاله.

تتوفّر ميزة "التنفيذ في الخلفية" لنماذج Gemini العادية (مثل gemini-3.5-flash وgemini-3.1-pro-preview) و"الوكلاء المُدارون" (مثل antigravity-preview-05-2026).

إنشاء تفاعل في الخلفية

لبدء تفاعل في الخلفية، اضبط المَعلمة background على true عند إنشاء المورد.

Python

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}")

JavaScript

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}`);

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.5-flash",
    "input": "Write a guide on space exploration.",
    "background": true
  }'

كيفية عمل ميزة "التنفيذ في الخلفية"

عند إنشاء تفاعل في الخلفية، يتم تشغيل المهمة بشكل غير متزامن على الخادم. ينتقل التفاعل بين حالات التنفيذ المختلفة:

  • in_progress: ينفّذ الخادم التفاعل بنشاط (مثل تشغيل الرمز أو إجراء بحث).
  • requires_action: تم إيقاف التفاعل مؤقتًا وينتظر إدخال بيانات من العميل (مثل تأكيد تنفيذ أداة أو الإجابة عن سؤال).
  • completed: اكتمل التفاعل بنجاح وأصبحت النتائج متاحة.
  • failed: حدث خطأ أثناء التنفيذ (مثل تعذُّر استخدام أداة أو تجاوز الحدود القصوى للطلبات).
  • cancelled: أوقف طلب من العميل عملية التنفيذ.

حالات الاستخدام

استخدِم ميزة "التنفيذ في الخلفية" في الحالات التالية:

  • عمليات تنفيذ الوكيل: المهام التي تتطلّب تطبيق الرموز البرمجية أو تصفّح الويب أو تنسيق الوكلاء الفرعيين (مثل antigravity-preview-05-2026).

  • البحث المعمّق: عمليات التنفيذ التي تستخدِم deep-research-preview-04-2026 أو deep-research-max-preview-04-2026 وتستغرق عدة دقائق

  • الاستدلال الطويل: المهام التي تتجاوز فيها خطوات تفكير النموذج الحدود القصوى لاتصال HTTP العادي

استرداد النتائج

يمكنك الحصول على نتائج التفاعل في الخلفية باستخدام التحقّق من الحالة أو البثّ.

نمط التحقّق من الحالة (لا يسبب الحظر)

يتحقّق نمط التحقّق من الحالة من حالة التفاعل بشكل دوري باستخدام طلبات 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}`);
}

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);

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، مع مراعاة القيود التالية:

  1. يتم حظر عمليات التنفيذ النشطة: يؤدي ربط تفاعل لاحق بتفاعل حالته in_progress إلى عرض الخطأ 400 Bad Request. انتظِر إلى أن يصل التفاعل إلى الحالة completed قبل بدء التفاعل التالي.
  2. مَعلمة البيئة للوكلاء المُدارين: عند ربط التفاعلات للوكلاء المُدارين (مثل antigravity-preview-05-2026)، يجب أن تتضمّن الطلبات كلاً من previous_interaction_id وenvironment.

توضّح الأمثلة التالية كيفية ربط التفاعلات:

Python

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
)

JavaScript

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
});

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 '{
    "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.

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");

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"

الخطوات التالية