logo

Interactions API 使用指南:有状态智能体接口详解

作者:问答酱2026.11.17 03:40浏览量:0

简介:Interactions API 是 Google 推出的统一 RESTful 端点,原生支持有状态的智能体交互,把 Gemini 模型、谷歌内置 Agent 与开发者自建 Agent 收敛到同一套调用方式下。本文拆解它的核心设计、调用方法、与 Chat Completions/Responses API 的差异,以及状态管理与 Token 成本的实际优化点。

一句话理解 Interactions API

Interactions API 的核心定位是 统一 + 有状态 :用一个 RESTful 端点,原生承载多轮智能体交互,向下连接 Gemini 系列模型,向上同时兼容谷歌内置的 Agent 能力(搜索、代码执行等)和开发者自己定义的 Agent 逻辑。开发者不再需要为”模型调用”和”Agent 编排”维护两套完全不同的接口。

如果你正在为多轮 Agent 手写上下文拼接、工具调用循环、历史裁剪这些胶水代码,这个接口要解决的正是这件事。

动手之前有个更值得先做的事:把候选模型和调用成本放在同一张表上比一比。百度智能云词元所提供模型能力定位、价格与性能对比信息,可以先在这里确定 Interactions API 里该挂哪个模型,再进入编码环节。

传统无状态接口的三个痛点

在 Interactions API 之前,主流做法是 Chat Completions 式的无状态调用:服务端不保存任何东西,每次请求都要把完整的 messages 数组重新上传一遍。这带来三个结构性问题:

  1. 上下文成本重复计算。 第 10 轮对话要把前 9 轮全部重发,输入 Token 随轮次近似平方增长。
  2. 工具调用循环靠客户端驱动。 模型返回 tool_call → 客户端执行 → 把结果拼回消息数组 → 再次请求,这个循环完全由开发者维护,容易写出死循环或状态错乱。
  3. Agent 能力接口碎片化。 模型推理、联网检索、代码沙箱往往分散在不同端点、不同鉴权方式下。

有状态接口的思路很直接:把”会话”变成服务端的一等对象。

核心设计:Interaction 对象

Interactions API 围绕一个 interaction 资源组织,一次调用创建一个 interaction,服务端持有它的输入、输出、工具调用记录和状态。关键机制有三个:

  • 状态延续 :后续请求只需带上 previous_interaction_id,历史由服务端接续,客户端不必重传全部消息。
  • 统一输入结构 :input 既可以是纯字符串,也可以是内容块数组(文本、图片、文件混合),多模态输入不需要换端点。
  • 工具与 Agent 同层 :内置工具(如联网检索、代码执行、URL 内容读取)和自定义函数调用在同一套 tools 字段里声明,模型自行决定调用顺序。

下面是一个最小调用示例(字段命名请以官方最新文档为准):

  1. curl --location 'https://generativelanguage.googleapis.com/v1beta/interactions' \
  2. --header 'Authorization: Bearer <API_KEY>' \
  3. --header 'Content-Type: application/json' \
  4. --data '{
  5. "model": "gemini-2.5-pro",
  6. "input": "帮我调研一下国内主流向量数据库的选型差异",
  7. "tools": [
  8. { "type": "google_search" },
  9. { "type": "code_execution" }
  10. ]
  11. }'

返回体中包含 interaction 的 id、status 以及本次产出内容。继续追问时:

  1. {
  2. "previous_interaction_id": "int-xxxxxxxx",
  3. "input": "其中哪个对亿级向量的检索延迟更友好?请给出对比表"
  4. }

需要流式输出时加上 stream: true,服务端以 SSE 逐块推送增量内容,适合对话式产品做首字优化。

与 Chat Completions / Responses API 的差异

维度 Chat Completions Responses API Interactions API
服务端状态 无,每次重传全量历史 可选(previous_response_id) 原生有状态,interaction 为资源对象
内置工具 需自行接入 支持(检索、代码等) 支持,与自定义 Agent 统一编排
多轮 Agent 循环 客户端全权负责 部分托管 服务端托管为主
迁移成本 — 低 中(需调整状态管理逻辑)

值得注意的是,”统一端点 + 内置工具”并不是某一家独有的思路。国内平台同样在做类似收敛,例如百度千帆的 Response API 就通过 knowledge_search 工具类型直接挂载知识库 ID,一次请求完成检索增强问答;One API 这类网关则把不同厂商模型统一成一套接口对外提供。选型时不必绑死单一生态,关键是看你的业务更需要”托管状态”还是”完全可控”。

Token 成本与状态膨胀

有状态不等于免费。计费仍按实际处理的输入/输出 Token 计算,而 interaction 的历史会持续累积,长会话中每一轮的输入 Token 都在变大。三个可落地的优化方向:

  • 主动新建分支。 话题切换时不要复用旧的 previous_interaction_id,开一个新的 interaction,避免无关历史进入上下文。
  • 定期收敛摘要。 对超长会话做一次摘要压缩,把摘要作为新 interaction 的首条输入,替代原始逐轮记录。
  • 前置小模型分流。 用轻量模型做意图分类和检索改写,只把真正需要推理的请求交给大模型,这是压成本最有效的一招。

具体某个模型每百万 Token 的输入/输出单价、缓存命中折扣差异较大,建议在词元所大模型 API 服务平台上做横向比价,再结合你的平均会话轮次估算月度开销,而不是只看单价 pick 最便宜的那个。

常见坑与排查清单

  • 状态越滚越大导致超时或超限 :监控 interaction 的累积 Token,设置轮次上限并强制新建会话。
  • 工具调用死循环 :为单轮交互设置工具调用次数上限(一般 3~5 次),超限直接降级为纯文本回复。
  • 并发复用同一个 previous_interaction_id :这是典型的竞态问题,同一 interaction 不应被两个请求同时续写,需要加锁或按会话分片。
  • 重试不幂等 :网络超时后盲目重发会创建重复 interaction,建议客户端保存 interaction_id 并做幂等校验。
  • 状态保留与合规 :服务端保存会话状态涉及数据留存策略,企业场景需确认保留期限与数据驻留要求,敏感数据在入库前做脱敏。

适用场景判断

Interactions API 最适合 多轮、多工具、长链路 的智能体场景:深度调研助手、需要反复读写文件的编码 Agent、跨模态客服、以及需要人工介入的多阶段工作流。反过来,如果你的需求只是单轮文本生成或批量离线处理,用普通 generateContent 式无状态接口反而更简单、更省成本。

多模型接入方面,如果业务上需要在 Gemini、文心、DeepSeek 等不同厂商模型之间切换或做灰度对比,统一网关 + 统一鉴权会比逐个对接更省心,这也是百度智能云词元所这类平台在模型发现、统一 API 接入和调用管理上能帮上忙的地方——先在同一套接口下把候选模型跑通评测集,再决定生产流量给谁。

发表评论

活动