Wykonywanie w tle

W przypadku długotrwałych działań, takich jak Deep Research, złożone rozumowanie czy wykonywanie działań przez agenta w kilku krokach, przekroczenie limitu czasu połączenia może przerwać standardowe żądania HTTP (które zwykle są zamykane po 60 sekundach). Interfejs Interactions API udostępnia wykonywanie w tle , aby uruchamiać te zadania asynchronicznie.

Aby interakcja trwała do momentu wykonania zadania na serwerze, podczas jej tworzenia ustaw parametr "background": true. Interfejs API natychmiast zwraca identyfikator interakcji, którego aplikacje klienckie mogą używać do sprawdzania stanu, postępu strumienia lub ponownego łączenia się z odłączonym strumieniem.

Wykonywanie w tle jest obsługiwane w przypadku standardowych modeli Gemini (takich jak gemini-3.6-flash i gemini-3.1-pro-preview) oraz zarządzanych agentów (takich jak antigravity-preview-05-2026).

Tworzenie interakcji w tle

Aby rozpocząć interakcję w tle, podczas tworzenia zasobu ustaw parametr background na 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
  }'

Jak działa wykonywanie w tle

Gdy tworzysz interakcję w tle, zadanie jest wykonywane asynchronicznie na serwerze. Interakcja przechodzi przez różne stany wykonywania:

  • in_progress: serwer aktywnie wykonuje interakcję (np. uruchamia kod lub prowadzi wyszukiwanie).
  • requires_action: interakcja została wstrzymana i czeka na dane wejściowe klienta (np. potwierdzenie wykonania narzędzia lub odpowiedź na pytanie).
  • completed: interakcja została zakończona pomyślnie i dane wyjściowe są dostępne.
  • failed: podczas wykonywania wystąpił błąd (np. awaria narzędzia lub przekroczenie limitów).
  • cancelled: wykonanie zostało przerwane przez żądanie klienta.

Przypadki użycia

Używaj wykonywania w tle w tych przypadkach:

  • Wykonywanie zadań przez agenta: zadania wymagające wykonania kodu, przeglądania internetu lub koordynacji działań sub-agenta (np. antigravity-preview-05-2026).

  • Szczegółowe wyszukiwanie: wyszukiwanie za pomocą deep-research-preview-04-2026 lub deep-research-max-preview-04-2026, które trwa kilka minut.

  • Długotrwałe rozumowanie: zadania, w których kroki rozumowania modelu przekraczają standardowe limity połączeń HTTP.

Pobieranie wyników

Wyniki interakcji w tle możesz uzyskać za pomocą odpytywania lub strumieniowania.

Wzorzec sondowania (nieblokujący)

Odpytywanie okresowo sprawdza stan interakcji za pomocą nieblokujących żądań GET, aż osiągnie ona stan końcowy.

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"

Wzorzec strumieniowania

Jeśli przerwa w sieci spowoduje odłączenie strumienia, strumieniowanie można wznowić od ostatniego odebranego zdarzenia. Każda delta zawiera w ładunku unikalny event_id. Przekazanie tego identyfikatora jako last_event_id spowoduje wznowienie strumienia od tego zdarzenia.

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"

Rozmowy wieloetapowe

Kolejne interakcje można łączyć z rozmową w tle za pomocą parametru previous_interaction_id, z zastrzeżeniem tych ograniczeń:

  1. Aktywne wykonywanie jest blokowane: połączenie kolejnej interakcji z interakcją o stanie in_progress spowoduje zwrócenie błędu 400 Bad Request. Zanim rozpoczniesz kolejną interakcję, poczekaj, aż poprzednia osiągnie stan completed.
  2. Parametr środowiska dla zarządzanych agentów: podczas łączenia interakcji dla zarządzanych agentów (np. antigravity-preview-05-2026) żądania muszą zawierać zarówno previous_interaction_id, jak i environment.

Poniższe przykłady pokazują, jak łączyć interakcje:

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

Anulowanie i usuwanie

Kontroluj wykonywanie i zarządzaj miejscem na dane za pomocą żądań anulowania i usuwania:

  • Anuluj (POST /interactions/{id}/cancel): zatrzymuje wykonywane zadanie. Stan zmienia się na cancelled. Działania czyszczące na serwerze mogą spowodować niewielkie opóźnienie, zanim stan zostanie zaktualizowany w żądaniach GET.

  • Usuń (DELETE /interactions/{id}): usuwa rekordy interakcji z serwera. Kolejne żądania GET zwracają błąd 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"

Dalsze kroki