Arka planda yürütme

Derin araştırma, karmaşık muhakeme veya çok adımlı aracı yürütme gibi uzun süren görevlerde bağlantı zaman aşımları, standart HTTP isteklerini (genellikle 60 saniye sonra kapanır) kesintiye uğratabilir. Etkileşimler API'si, bu görevleri eşzamansız olarak çalıştırmak için arka planda yürütme sağlar.

Etkileşimin sunucudaki görevi tamamlayana kadar çalışmasına izin vermek için etkileşimi oluştururken "background": true değerini ayarlayın. API, istemci uygulamalarının durumu yoklamak, akış ilerleme durumunu kontrol etmek veya bağlantısı kesilmiş bir akışa yeniden bağlanmak için kullanabileceği bir etkileşim kimliğini hemen döndürür.

Arka planda yürütme, standart Gemini modelleri (ör. gemini-3.5-flash ve gemini-3.1-pro-preview) ve yönetilen aracılar (ör. antigravity-preview-05-2026) için desteklenir.

Arka plan etkileşimi oluşturma

Arka plan etkileşimi başlatmak için kaynağı oluştururken background parametresini true olarak ayarlayın.

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
  }'

Arka planda yürütme nasıl çalışır?

Arka plan etkileşimi oluşturduğunuzda görev sunucuda eşzamansız olarak çalışır. Etkileşim, çeşitli yürütme durumlarından geçer:

  • in_progress: Sunucu, etkileşimi etkin bir şekilde yürütüyor (ör. kod çalıştırma veya araştırma).
  • requires_action: Etkileşim duraklatıldı ve istemci girişi (ör. bir araç yürütme işlemini onaylama veya bir soruyu yanıtlama) bekleniyor.
  • completed: Etkileşim başarıyla tamamlandı ve çıkış kullanılabilir.
  • failed: Yürütme sırasında bir hata oluştu (ör. araç arızası veya sıklık sınırları).
  • cancelled: Bir istemci isteği yürütmeyi durdurdu.

Kullanım alanları

Arka planda yürütmeyi şu amaçlarla kullanın:

  • Ajan yürütmeleri: Kod yürütme, web'de gezinme veya alt ajan düzenleme (ör. antigravity-preview-05-2026) gerektiren görevler.

  • Deep Research: Birkaç dakika süren deep-research-preview-04-2026 veya deep-research-max-preview-04-2026 kullanılarak çalıştırılır.

  • Uzun muhakeme: Model düşünme adımlarının standart HTTP bağlantı sınırlarını aştığı görevler.

Sonuçları alma

Yoklama veya akış kullanarak arka plan etkileşimi sonuçlarını alın.

Yoklama deseni (engellemeyen)

Yoklama, son duruma ulaşana kadar engellemeyen GET isteklerini kullanarak etkileşim durumunu düzenli olarak kontrol eder.

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"

Yayın deseni

Ağ kesintisi nedeniyle bağlantısı kesilen yayın, son alınan etkinlikten itibaren devam edebilir. Her delta, yükünde benzersiz bir event_id içerir. Bu kimliğin last_event_id olarak iletilmesi, akışı bu etkinlikten itibaren devam ettirir.

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"

Çok aşamalı etkileşimli görüşmeler

Sonraki etkileşimler, aşağıdaki kısıtlamalara tabi olarak previous_interaction_id kullanılarak arka plan görüşmesine bağlanabilir:

  1. Etkin yürütmeler engellenir: Bir sonraki etkileşimi in_progress durumundaki bir etkileşime bağlamak 400 Bad Request hatası döndürür. Bir sonraki etkileşimi başlatmadan önce etkileşimin completed durumuna ulaşmasını bekleyin.
  2. Yönetilen Aracılar için Ortam Parametresi: Yönetilen Aracılar için etkileşimler zincirlenirken (ör. antigravity-preview-05-2026), isteklere hem previous_interaction_id hem de environment dahil edilmelidir.

Aşağıdaki örneklerde etkileşimlerin nasıl zincirleneceği gösterilmektedir:

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
  }'

İptal ve silme

İptal etme ve silme isteklerini kullanarak çalışan yürütmeleri kontrol edin ve depolama alanını yönetin:

  • İptal (POST /interactions/{id}/cancel): Çalışan görevi durdurur. Durum cancelled olarak değişir. Sunucudaki temizleme işlemleri, GET isteklerindeki durum güncellemelerinde küçük bir gecikmeye neden olabilir.

  • Sil (DELETE /interactions/{id}): Etkileşim kayıtlarını sunucudan kaldırır. Sonraki GET istekleri 404 Not Found hatası döndürür.

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"

Sonraki adımlar