后台执行
对于深入研究、复杂推理或多步智能体执行等长时间运行的任务,连接超时可能会中断标准 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 创建资源时。
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}")
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-4-hydrogen",
input: "Write a guide on space exploration.",
background: true,
});
console.log(`Created background interaction ID: ${interaction.id}`);
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model("gemini-4-hydrogen")
.input(InteractionsInput.of("Write a guide on space exploration."))
.background(true)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Created background interaction ID: " + interaction.id().orElse(""));
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-hydrogen"),
Input: interactions.NewInteractionsInput("Write a guide on space exploration."),
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.ID != nil {
fmt.Printf("Created background interaction ID: %s\n", *res.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-4-hydrogen",
"input": "Write a guide on space exploration.",
"background": true
}'
gemini-api agent run "Write a guide on space exploration." -m gemini-4-hydrogen \
--background --stream=false --jq '.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,536token。开gemini-4-carbon,gemini-4-argon, 和gemini-4-hydrogen,你可以设置max_output_tokens最多1,048,576token 使用 长解码.
后台执行的数据保留 #
后台执行(background=True) 要求 store=True (默认),以便服务器可以在您轮询或流式传输结果时存储交互。路过 background=True 使用 store=False 返回一个 400 错误。
存储的后台交互遵循标准 Interactions API数据存储和保留 政策:
- 付费等级: 保留用于 55天 (可配置为 7, 14, 28, 或 55 天) Google AI Studio).
- 免费等级: 保留用于 1日.
要提前删除后台交互, 删除互动 检索结果后。
检索结果 #
使用以下任一方法获取后台交互结果 投票 或 流媒体.
轮询模式(非阻塞) #
轮询使用非阻塞 GET 请求定期检查交互状态,直到达到最终状态。
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}")
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}`);
}
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
Client client = new Client();
Interaction interaction =
client.interactions
.get(GetInteractionByIdRequest.builder().id("YOUR_INTERACTION_ID").build())
.interaction()
.get();
while (InteractionStatus.IN_PROGRESS.equals(interaction.status().orElse(null))) {
Thread.sleep(5000);
interaction =
client.interactions
.get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())
.interaction()
.get();
}
if (InteractionStatus.COMPLETED.equals(interaction.status().orElse(null))) {
System.out.println(interaction.outputText().orElse(""));
} else {
System.out.println(
"Finished with status: " + interaction.status().map(InteractionStatus::value).orElse(""));
}
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: "YOUR_INTERACTION_ID",
})
if err != nil {
log.Fatal(err)
}
interaction := res.Interaction
for interaction.Status == interactions.InteractionStatusInProgress {
time.Sleep(5 * time.Second)
res, err = client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: *interaction.ID,
})
if err != nil {
log.Fatal(err)
}
interaction = res.Interaction
}
if interaction.Status == interactions.InteractionStatusCompleted {
if interaction.OutputText != nil {
fmt.Println(*interaction.OutputText)
}
} else {
fmt.Printf("Finished with status: %s\n", interaction.Status)
}
}
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"
gemini-api agent status YOUR_INTERACTION_ID -o json
流式传输模式 #
如果网络中断导致流断开连接,则流可以从上次接收到的事件恢复。每个三角洲都包含一个独特的 event_id 在其有效负载中。将此 ID 传递为 last_event_id 从该事件恢复流。
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)
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interactionId = "YOUR_INTERACTION_ID";
async function streamWithReconnect(id = interactionId) {
let lastEventId = "";
while (true) {
try {
// Retrieve the stream. If resuming, pass last_event_id in options
const eventStream = await client.interactions.get(id, {
stream: true,
last_event_id: lastEventId
});
for await (const event of eventStream) {
if (event.event_id) {
lastEventId = event.event_id;
}
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) {
const message = error instanceof Error ? error.message : String(error);
console.log(`\n[Connection lost: ${message}. Reconnecting in 3s...]`);
await new Promise(resolve => setTimeout(resolve, 3000));
}
}
}
await streamWithReconnect(interactionId);
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.InteractionCompletedEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import com.google.genai.gaos.utils.EventStream;
Client client = new Client();
String interactionId = "YOUR_INTERACTION_ID";
String lastEventId = null;
boolean completed = false;
while (!completed) {
try (EventStream<InteractionSSEStreamEvent> stream =
client.interactions
.get(
GetInteractionByIdRequest.builder()
.id(interactionId)
.stream(true)
.lastEventId(lastEventId)
.build())
.events()) {
for (InteractionSSEStreamEvent streamEvent : stream) {
InteractionSSEEvent event = streamEvent.data().orElse(null);
if (event instanceof StepDelta) {
StepDelta stepDelta = (StepDelta) event;
if (stepDelta.eventId().isPresent()) {
lastEventId = stepDelta.eventId().get();
}
if (stepDelta.delta().isPresent() && stepDelta.delta().get() instanceof TextDelta) {
System.out.print(((TextDelta) stepDelta.delta().get()).text().orElse(""));
System.out.flush();
}
} else if (event instanceof InteractionCompletedEvent) {
completed = true;
break;
}
}
} catch (Exception e) {
System.out.println("\n[Connection lost: " + e.getMessage() + ". Reconnecting in 3s...]");
Thread.sleep(3000);
}
}
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
interactionID := "YOUR_INTERACTION_ID"
var lastEventID *string
completed := false
for !completed {
res, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: interactionID,
Stream: genai.Ptr(true),
LastEventID: lastEventID,
})
if err != nil {
fmt.Printf("\n[Connection lost: %v. Reconnecting in 3s...]\n", err)
time.Sleep(3 * time.Second)
continue
}
stream := res.InteractionSSEStreamEvent
for stream.Next() {
event := stream.Value()
if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
if stepDelta.EventID != nil {
lastEventID = stepDelta.EventID
}
if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
fmt.Print(textDelta.GetText())
}
} else if event.GetDataInteractionCompleted() != nil {
completed = true
break
}
}
if err := stream.Err(); err != nil {
fmt.Printf("\n[Stream error: %v. Reconnecting in 3s...]\n", err)
_ = stream.Close()
time.Sleep(3 * time.Second)
continue
}
_ = stream.Close()
}
}
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"
gemini-api agent status YOUR_INTERACTION_ID --stream --last-event-id YOUR_LAST_EVENT_ID
多轮对话 #
随后的交互可以使用链接到后台对话 previous_interaction_id,受以下约束:
- 主动执行被阻止: 将后续交互链接到一个
in_progress状态返回一个400 Bad Request错误。等待交互到达completed在开始下一项之前先声明一下。 - 托管智能体环境参数: 当托管智能体链接交互时(例如
antigravity-preview-09-2026),请求必须包含两者previous_interaction_id和environment.
以下示例展示了如何链接交互:
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
)
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const agentModel = "antigravity-preview-09-2026";
// First interaction: Provision sandbox environment and execute first instruction
const interaction1 = await client.interactions.create({
agent: 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({
agent: agentModel,
input: "List all files in the project/ directory.",
previous_interaction_id: interaction1.id,
environment: "remote",
background: true
});
import com.google.genai.Client;
import com.google.genai.types.HttpOptions;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
Client client = Client.builder().httpOptions(HttpOptions.builder().apiVersion("v1beta").build()).build();
String agentModel = "antigravity-preview-09-2026";
// First interaction: Provision sandbox environment and execute first instruction
CreateModelInteraction params1 =
CreateModelInteraction.builder()
.model(agentModel)
.input(InteractionsInput.of("Create a folder named project/ and write hello.py inside."))
.environment(CreateModelInteractionEnvironment.of("remote"))
.background(true)
.build();
Interaction interaction1 =
client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();
// Wait for completion
while (true) {
Interaction check =
client.interactions
.get(GetInteractionByIdRequest.builder().id(interaction1.id().get()).build())
.interaction()
.get();
if (!InteractionStatus.IN_PROGRESS.equals(check.status().orElse(null))) {
break;
}
Thread.sleep(2000);
}
// Second interaction: Chain using previousInteractionId and environment
CreateModelInteraction params2 =
CreateModelInteraction.builder()
.model(agentModel)
.input(InteractionsInput.of("List all files in the project/ directory."))
.previousInteractionId(interaction1.id().get())
.environment(CreateModelInteractionEnvironment.of("remote"))
.background(true)
.build();
Interaction interaction2 =
client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();
package main
import (
"context"
"log"
"time"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
agentModel := interactions.Model("antigravity-preview-09-2026")
remoteEnv := interactions.NewCreateModelInteractionEnvironment("remote")
// First interaction: Provision sandbox environment and execute first instruction
res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: agentModel,
Input: interactions.NewInteractionsInput("Create a folder named project/ and write hello.py inside."),
Environment: &remoteEnv,
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
// Wait for completion
for {
check, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
ID: *res1.Interaction.ID,
})
if err != nil {
log.Fatal(err)
}
if check.Interaction.Status != interactions.InteractionStatusInProgress {
break
}
time.Sleep(2 * time.Second)
}
// Second interaction: Chain using PreviousInteractionID and Environment
_, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: agentModel,
Input: interactions.NewInteractionsInput("List all files in the project/ directory."),
PreviousInteractionID: res1.Interaction.ID,
Environment: &remoteEnv,
Background: genai.Ptr(true),
}),
})
if err != nil {
log.Fatal(err)
}
}
# 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 '{
"agent": "antigravity-preview-09-2026",
"input": "List all files in the project/ directory.",
"previous_interaction_id": "FIRST_INTERACTION_ID",
"environment": "remote",
"background": true
}'
FIRST_ID=$(gemini-api agent run "Create a folder named project/ and write hello.py inside." \
--agent antigravity-preview-09-2026 --body '{"environment": "remote"}' \
--background --stream=false --jq '.id')
# Wait until `gemini-api agent status "$FIRST_ID" --jq '.status'` returns "completed".
gemini-api agent run "List all files in the project/ directory." \
--agent antigravity-preview-09-2026 --previous-interaction-id "$FIRST_ID" \
--body '{"environment": "remote"}' --background --stream=false --jq '.id'
取消和删除 #
使用取消和删除请求控制正在运行的执行并管理存储:
- 取消(
POST /interactions/{id}/cancel): 停止正在运行的任务。状态转变为cancelled。服务器上的清理操作可能会导致 GET 请求中的状态更新之前出现轻微延迟。 - 删除(
DELETE /interactions/{id}): 从服务器中删除交互记录。后续 GET 请求返回404 Not Found错误。
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")
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");
import com.google.genai.Client;
Client client = new Client();
// Cancel a running interaction
client.interactions.cancel("YOUR_INTERACTION_ID");
// Delete the interaction record entirely
client.interactions.delete("YOUR_INTERACTION_ID");
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
// Cancel a running interaction
_, err = client.Interactions.Cancel(ctx, operations.CancelInteractionByIDRequest{
ID: "YOUR_INTERACTION_ID",
})
if err != nil {
log.Fatal(err)
}
// Delete the interaction record entirely
_, err = client.Interactions.Delete(ctx, operations.DeleteInteractionRequest{
ID: "YOUR_INTERACTION_ID",
})
if err != nil {
log.Fatal(err)
}
}
# 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"
gemini-api agent cancel YOUR_INTERACTION_ID
gemini-api agent delete-interaction YOUR_INTERACTION_ID
后续步骤 #
- 阅读 Interactions API概述 了解会话和状态管理。
- 请参阅 流式交互 有关实时事件更新的详细信息的指南。
- 探索 托管智能体快速入门 构建有状态多轮智能体。