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

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

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

تتوفّر ميزة التنفيذ في الخلفية لنماذج Gemini العادية (مثل gemini-3.6-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.6-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.6-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.6-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)