Gemini ReAct 多步 Agent 循环实战:规划、工具编排与终止条件

首页 / 文章 / 技术教程 / Gemini ReAct 多步 Agent 循环实战:规划、工具编排与终止条件

Gemini ReAct 多步 Agent:客服/运维场景、步数预算、工具白名单与终止条件。api.itzyk.top OpenAI 兼容。

作者:智枢 ZhiShu · 发布:2026-10-26 · 更新:2026-11-14

一、为什么 Function Calling 还不够? 单轮工具调用适合「查一次天气再回答」。真实 Agent——客服改备注、运维查告警再重启、内部「先查库存再下单再开票」——往往要: 规划 → 调工具 → 观察 → 再决策 ,循环 3~8 步,还要处理空结果与打转。 本文将基于面向开发者的 OpenAI 兼容 AI API 网关—— 智枢ZhiShu / Itzyk API(api.itzyk.top) ,把 Gemini ReAct(Reason + Act)落成可运行的多步循环: base url 指向 https://api.itzyk.top/v1 , tools / tool calls 与 OpenAI 一致,配套终止条件、步数预算、工具白名单与费用控制。默认模型: gemini-3.6-flash 。 适用业务场景 | 场景 | 典型工具组合 | 必须有的硬约束 | |------|--------------|----------------| | 客服 Copilot | 查单 → 改备注 → 总结 | 写操作幂等 + 人工闸 | | 运维助手 | 查指标 → 查日志 → 建议操作 | 高风险动作默认只读 | | 内部履约编排 | 查库存 → 下单 → 开票 | MAX STEPS + 审计 trace | 事实锚点:Agent 工具调用走 POST /v1/chat/completions + OpenAI 风格 tools ;鉴权 Authorization: Bearer sk-... 。 适合:已会单轮 Function Calling https://api.itzyk.top/articles/gemini-function-calling-tools-guide 、要做客服/运维 Copilot/内部编排的后端。结构化结果落地见 结构化 JSON 输出 https://api.itzyk.top/articles/gemini-structured-json-output-guide 。 --- 二、ReAct 循环的最小状态机 一轮用户问题对应一个 run 关键不在「会调 tools」,而在 状态落在哪里 | 状态 | 存放 | 用途 | |------|------|------| | messages | 内存 / Redis | 每步完整上下文 | | step | 计数器 | 硬上限 | | tool trace | 审计表 | 排错与计费归因 | | run id | 请求头/DB | 幂等与对账 | Itzyk网关负责鉴权、限流、按 Token 计费与转发; 工具实现与循环控制全在你侧 。每次请求仍要带上当前需要的 tools 定义。 准备 注册与模型权限在 Itzyk控制台完成,价格与限流以控制台公布为准。 --- 三、Python:可终止的 ReAct 骨架 下面用两个假工具演示「查单 → 改备注」多步流。生产里把函数换成真实 HTTP,并给每个工具加超时与幂等键。 验证点:控制台应看到至少一次 get order 与一次 update order note ;最终回复引用真实 status / note ,而不是模型臆造。 --- 四、终止条件:比 MAX STEPS 更细 硬上限必须有,但只靠它会「跑满才失败」。建议叠加 1. 无工具即终 :模型返回纯文本 → 成功退出。 2. 同工具同参重复 :连续两步 name+args 哈希相同 → 注入 system 旁路:「工具结果未变,请直接回答或换策略」,再给 1 步机会。 3. 业务完成标志 :例如 update order note.ok==true 且用户目标已覆盖 → 可强制再调一次「只总结、禁工具」( tool choice="none" )。 4. 错误类熔断 : tool not allowed / 连续 exec failed → 立即自然语言道歉并结束,避免空转烧 Token。 --- 五、消息拼装陷阱(Agent 最常见 401/协议错之外的坑) - 漏 assistant.tool calls :只贴 role=tool 会导致上游拒识或行为漂移。 - arguments 不是 JSON 字符串 :SDK 里通常是字符串;本地 json.loads 前要容错。 - 并行 tool calls :一轮可能多个;全部执行完再请求下一步,不要「执行一个就立刻再 chat」除非你明确串行化。 - 把巨量 tool 结果原样塞回 :日志截断到 2~4KB;否则上下文暴涨,下一步又贵又慢。长文档应先切块摘要再问答。 - system 与工具描述打架 :system 说「必须调工具」,工具描述又写「可直接猜」——以白名单执行为准,描述保持克制。 --- 六、安全:工具是远程代码的入口 Agent 循环把模型输出变成你进程里的函数调用。底线 - 白名单 : DISPATCH 只有显式注册的名字;拒绝动态 eval 。 - 参数校验 :用 JSON Schema / pydantic;拒绝额外字段、超长字符串、路径穿越。 - 副作用分级 :只读工具可宽松;写库/打款必须二次确认或人类审批闸门。 - 鉴权上下文 :工具内用「当前登录用户」查库,不要信模型传入的 user id 。 - 密钥 :只放环境变量;不要写进 messages。 --- 七、费用与步数:Agent 是乘法器 一次用户问题 ≈ N 次 chat.completions + 工具侧成本。粗算 控制手段 | 手段 | 做法 | |------|------| | 默认 Flash | 循环内用 gemini-3.6-flash ;仅最终润色可切 Pro | | 短工具结果 | 返回结构化小 JSON,禁止整页 HTML | | 滑动窗口 | 保留 system + 最近 K 轮 tool 对;更早的压成一条摘要 | | 步数告警 | step≥4 打点;生产看 P95 steps | | 402/429 | 不在循环内无脑重试;余额不足先充值,限流则退避 | Itzyk按实际 Token 计费;循环失败已产生的调用通常仍会计入用量,故「早停」比「跑满再看」更省。 --- 八、与结构化输出、评测的衔接 - 最终给业务系统的不只是聊天话术时,在 最后一轮 要求 JSON(或再开一次非工具调用做结构化)。 - Agent 回归:固定 20 条用例(含 not found、重复调用、双工具并行),断言 tool trace 顺序与最终字段。 - 不要用「看起来像答对了」代替 trace 断言;Agent 的正确性在路径上。 --- 九、Node.js 同构循环(要点) 协议相同,差异在 SDK 字段名。核心仍是:有 tool calls 就执行并回灌,没有就返回。 生产里把 DISPATCH 换成带超时的 AbortSignal 包装;工具超过 3s 未返回就记 timeout ,让模型改策略而不是挂死整次 run。 --- 十、排错手册:循环「看起来坏了」时先查什么 | 现象 | 优先排查 | |------|----------| | 模型不调工具 | tools 是否传入;description 是否说明「必须查库」;temperature 是否过高 | | 调了假工具名 | 白名单拒绝并回传 tool not allowed ;收紧 enum/名称 | | 第二步忘掉第一步结果 | 是否漏写 assistant.tool calls 或 tool 消息 | | 费用飙升 | MAX STEPS、工具结果体积、是否在 429 上重试整段 run | | 用户看到胡编订单 | system 是否禁止臆造;not found 是否只重试一次 | | 偶发空回复 | 检查 finish reason;必要时 force finalize | 本地复现时固定 temperature=0 、打印每步 tool trace 。仍不稳定再用 curl 排错 对照单次非 Agent 请求,排除 Key/模型/余额问题。 多轮会话记忆(跨用户回合)与单次 Agent run 内记忆不同:前者见 多轮会话;本文只保证 一次 run 内 messages 完整。 --- 十一、人类审批闸门(高风险写操作) 对「退款、改价、删数据」类工具,不要让模型直接执行。模式 1. 模型只能调 propose refund (只读提案,写审计表 pending )。 2. 返回给用户:「已生成退款提案 P123,金额 ¥80,请确认」。 3. 用户点确认后, 业务 API 调 commit refund proposal id ,不再经过模型。 这样 Agent 负责理解与起草,资金动作走你们既有权限体系。提案 JSON 可用结构化输出钉死字段。 --- 十二、上线检查表 1. MAX STEPS 、单工具超时、工具白名单写入配置,可热更新。 2. 每步 run id/step/tool/latency/tokens 可查;支持按 run 回放。 3. 写操作工具有幂等键或业务唯一约束;高风险走审批闸门。 4. 演练:工具超时、空结果、同参死循环、402 余额不足、并行双 tool calls。 5. 回归集至少覆盖 not found / 成功写备注 / 预算用尽 三类。 6. 控制台核对模型 code 与预算。 7. --- 十三、工具描述怎么写才「够用且不泄权」 description 与 parameter

本文发布于 Itzyk API(AI API 网关,OpenAI 兼容)。更多: 文章中心 · 开发者文档 · API 服务 · 价格。

llms.txt · sitemap · robots · 文章

京ICP备19037501号-3