Esecuzione in background

Per le attività a lunga esecuzione come la ricerca approfondita, il ragionamento complesso o le esecuzioni di agenti in più passaggi, i timeout di connessione possono interrompere le richieste HTTP standard (che in genere si chiudono dopo 60 secondi). L'API Interactions fornisce l'esecuzione in background per eseguire queste attività in modo asincrono.

Per consentire all'interazione di essere eseguita fino al completamento dell'attività sul server, imposta "background": true quando crei l'interazione. L'API restituisce immediatamente un ID di interazione, che le applicazioni client possono utilizzare per eseguire il polling dello stato, lo streaming dei progressi o la riconnessione a uno stream disconnesso.

L'esecuzione in background è supportata per i modelli Gemini standard (ad esempio gemini-3.6-flash e gemini-3.1-pro-preview) e gli agenti gestiti (ad esempio antigravity-preview-05-2026).

Creare un'interazione in background

Per avviare un'interazione in background, imposta il parametro background su true quando crei la risorsa.

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

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

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

Come funziona l'esecuzione in background

Quando crei un'interazione in background, l'attività viene eseguita in modo asincrono sul server. L'interazione passa attraverso vari stati di esecuzione:

• in_progress: il server sta eseguendo attivamente l'interazione (ad esempio, eseguendo codice o effettuando ricerche).
• requires_action: l'interazione è stata messa in pausa ed è in attesa dell'input del client (ad esempio, la conferma dell'esecuzione di uno strumento o la risposta a una domanda).
• completed: l'interazione è stata completata correttamente e l'output è disponibile.
• failed: si è verificato un errore durante l'esecuzione (ad esempio, un errore dello strumento o limiti di frequenza).
• cancelled: una richiesta del client ha interrotto l'esecuzione.

Casi d'uso

Utilizza l'esecuzione in background per: