背景執行

對於長時間執行的工作 (例如深度研究、複雜推論或多步驟代理執行作業)，連線逾時可能會中斷標準 HTTP 要求 (通常會在 60 秒後關閉)。Interactions API 提供背景執行功能，可非同步執行這些工作。

如要讓互動持續執行，直到伺服器完成工作為止，請在建立互動時設定 "background": true。API 會立即傳回互動 ID，用戶端應用程式可使用此 ID 輪詢狀態、串流進度，或重新連線至已中斷的串流。

標準 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：使用 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