Gemini 中文指南
获取 API 密钥 ↗

后台执行

↓ 下载 MarkdownInteractions API

对于深入研究、复杂推理或多步智能体执行等长时间运行的任务,连接超时可能会中断标准 HTTP 请求(通常在 60 秒后关闭)。的 Interactions API 提供 后台执行 异步运行这些任务。

要让交互运行直到完成服务器上的任务,请设置 "background": true 创建交互时。 API 立即返回一个交互 ID,客户端应用程序可以使用该 ID 轮询状态、流进度或重新连接到断开连接的流。

标准 Gemini 型号支持后台执行(例如 gemini-4-carbon, gemini-4-argon, gemini-4-hydrogen, 和 gemini-3.8-flash)和托管智能体(例如 antigravity-preview-09-2026).

创建后台交互 #

要启动后台交互,请设置 background 参数为 true 创建资源时。

python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Write a guide on space exploration.",
    background=True,
)
print(f"Created background interaction ID: {interaction.id}")

后台执行的工作原理 #

创建后台交互时,任务在服务器上异步运行。交互通过各种执行状态进行转换:

  • in_progress:服务器正在主动执行交互(例如运行代码或研究)。
  • requires_action:交互已暂停,正在等待客户端输入(例如确认工具执行或回答问题)。
  • completed:交互成功完成,有输出。
  • failed:执行期间发生错误(例如工具故障或速率限制)。
  • cancelled:客户端请求停止执行。

使用案例 #

使用后台执行:

  • 智能体执行: 需要代码执行、网页浏览或子智能体编排的任务(例如 antigravity-preview-09-2026).
  • 深入研究: 运行使用 deep-research-preview-04-2026 或 deep-research-max-preview-04-2026 这需要几分钟的时间。
  • 长推理: 扩展模型思考步骤超出标准 HTTP 连接限制的任务。
  • 长解码(Gemini 4): 产生超出范围的扩展完成的任务 65,536 token。开 gemini-4-carbon, gemini-4-argon, 和 gemini-4-hydrogen,你可以设置 max_output_tokens 最多 1,048,576 token 使用 长解码.

后台执行的数据保留 #

后台执行(background=True) 要求 store=True (默认),以便服务器可以在您轮询或流式传输结果时存储交互。路过 background=True 使用 store=False 返回一个 400 错误。

存储的后台交互遵循标准 Interactions API数据存储和保留 政策:

  • 付费等级: 保留用于 55天 (可配置为 7, 14, 28, 或 55 天) Google AI Studio).
  • 免费等级: 保留用于 1日.

要提前删除后台交互, 删除互动 检索结果后。

检索结果 #

使用以下任一方法获取后台交互结果 投票 或 流媒体.

轮询模式(非阻塞) #

轮询使用非阻塞 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}")

流式传输模式 #

如果网络中断导致流断开连接,则流可以从上次接收到的事件恢复。每个三角洲都包含一个独特的 event_id 在其有效负载中。将此 ID 传递为 last_event_id 从该事件恢复流。

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)

多轮对话 #

随后的交互可以使用链接到后台对话 previous_interaction_id,受以下约束:

  1. 主动执行被阻止: 将后续交互链接到一个 in_progress 状态返回一个 400 Bad Request 错误。等待交互到达 completed 在开始下一项之前先声明一下。
  2. 托管智能体环境参数: 当托管智能体链接交互时(例如 antigravity-preview-09-2026),请求必须包含两者 previous_interaction_id 和 environment.

以下示例展示了如何链接交互:

python
import time
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})
agent_model = "antigravity-preview-09-2026"

# First interaction: Provision sandbox environment and execute first instruction
interaction1 = client.interactions.create(
    agent=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(
    agent=agent_model,
    input="List all files in the project/ directory.",
    previous_interaction_id=interaction1.id,
    environment="remote",
    background=True
)

取消和删除 #

使用取消和删除请求控制正在运行的执行并管理存储:

  • 取消(POST /interactions/{id}/cancel): 停止正在运行的任务。状态转变为 cancelled。服务器上的清理操作可能会导致 GET 请求中的状态更新之前出现轻微延迟。
  • 删除(DELETE /interactions/{id}): 从服务器中删除交互记录。后续 GET 请求返回 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")

后续步骤 #

搜索标题、API 名称或正文内容