Gemini Interactions API GA 后适合哪些代理场景

如果代理任务只有一次提示词和一次结果，传统的 generateContent 仍然够用；但一旦任务需要连续对话、工具调用、后台运行或把每一步展示给用户，Gemini Interactions API 的价值就出来了。它在 2026 年 6 月进入 GA，官方把它定位为模型与代理的统一接口。

官方地址：https://ai.google.dev/gemini-api/docs/interactions-overview

Gemini Interactions API 适合把代理执行过程收拢成一个 Interaction

普通生成接口更像“提交输入，等待输出”。Interactions API 则把一次任务建模成 Interaction 资源：输入之后可以出现模型判断、服务端或客户端工具调用、工具结果，最后才是模型输出。这个差异很适合需要审计、重试、前端进度展示的代理。

例如“先检索资料，再调用内部库存工具，最后生成采购建议”不是三个互不相干的请求，而是一条有上下文的任务链。工程上可以把工具权限、超时、人工确认和失败重试放在这条链的边界上。需要注意的是，图示是静态说明图，不代表某次真实运行日志。

多轮状态和长任务决定了 API 的价值

多轮代理最有用的字段是 previous_interaction_id。后续请求引用上一轮 ID，服务端就能继续已有对话，应用不必每次重新拼完整历史。下面的示例只演示调用骨架，API key 应通过环境变量注入。

from google import genai
import os

# 从环境变量读取密钥，避免把凭据写进源码或日志
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

# 第一轮创建 Interaction，返回值包含可继续使用的 id
first = client.interactions.create(
    model="gemini-3.8-flash",
    input="整理这份订单的异常项，并列出需要人工确认的字段",
)

# 第二轮沿用历史；本轮工具和生成配置仍需按需要重新声明
second = client.interactions.create(
    model="gemini-3.8-flash",
    input="根据刚才的异常项，给出审核顺序",
    previous_interaction_id=first.id,
)
print(second.output_text)

如果任务可能运行几分钟，才考虑 background=true，并让前端根据 Interaction 状态轮询或接收事件。若数据不应被服务端保存，则使用 store=false；但无状态请求不能依赖上一轮 ID，也不能与后台执行混用。

三类代理场景值得优先采用

反过来，单轮摘要、一次分类、无需追问的固定格式输出，不必为了“代理”标签强行迁移。选择标准不是 API 新旧，而是任务是否需要可持续的状态和步骤。

迁移前的四项检查

1. 先画出输入、工具、结果和人工确认的顺序，再决定是否需要 Interaction。
2. 明确每轮都要重传的工具定义、系统指令和生成配置，不能误以为历史 ID 会保存全部配置。
3. 把 store、留存期限和删除策略写进数据处理设计，尤其是研究资料和业务字段。
4. 为 in_progress、requires_action、failed 和 incomplete 设计恢复路径，避免只处理成功响应。

延伸问答

Interactions API 是否只能用于复杂代理？

不是。它也能承载普通模型调用，但简单单轮任务使用传统接口更直接，复杂度和留存收益要先算清楚。

引用 previous_interaction_id 后还要传工具吗？

要。历史 ID 主要保留对话历史，工具、系统指令和生成配置属于当前 Interaction 的配置，应在本轮明确声明。

store=false 适合什么情况？

适合不希望服务端保存 Interaction 的无状态请求，但它不能继续上一轮状态，也不能配合后台执行。

什么时候不要急着迁移？

如果任务没有多轮、工具、后台执行或步骤展示需求，先保持简单调用，等业务确实需要状态和轨迹时再迁移。