用确定性计算与人工审批约束退款智能体
作者基于 Google ADK 和参考仓库介绍退款智能体的架构,强调退款计算应交给确定性逻辑,敏感操作应设置人工审批。文章指出提示词不能作为安全边界,其“零幻觉”说法仍需实际验证。
AI 深度解读
退款 Agent 最危险的地方,是把「听懂用户」和「决定打多少钱」交给同一个模型。作者用 Google ADK 搭了一套退款系统:gemini-2.5-flash 负责理解意图、调用工具和解释结果,Python 负责金额、状态和支付,回调负责拦截违规操作。
这套方案值得看的,是它怎样把一次聊天拆成可检查的业务流程。不过,标题里的「零幻觉」和「生产级」需要分开判断:原文展示了金额保护机制与本地测试场景,没有给出线上运行数据。
模型可以理解退款,但不能决定付款金额
作者反对把退货政策全部塞进 system prompt,再让模型边聊天边算钱。理由很直接:模型可能算错,提示词也不能充当权限边界。即便写了「退款不得超过 $150」,真正执行支付时仍然需要代码检查。
RefundOrchestratorAgent 的分工因此很明确:LLM 充当语义路由器,把用户的话转成工具调用,再把结构化 JSON 解释成自然语言。Python 工具负责全部状态、计算和修改操作,包括数据库查询、费用扣除与支付网关调用。
关键不是要求模型遵守金额,而是让支付工具只能拿到经过校验的金额。
具体做法是:calculate_refund_amount() 完成计算后,after_tool_callback 把净退款额 net_refund_amount 存入 tool_context.state["verified_refund_amount"]。调用 execute_payment_refund 时,before_tool_callback 会覆盖模型传入的金额,注入这份已验证的状态值。
这比「请严格使用计算结果」可靠得多。模型即使传错参数,也无法直接改变支付金额。
作者把这些生命周期回调称为 Policy Plane,可以理解为工具执行前的业务检查层:授权、调用顺序、金额上限和预算,都应由它约束。不过,原文没有展示完整回调实现,不能仅凭架构描述确认每条限制都已覆盖。
一笔退款为什么要经过三类人工关口
作者没有把退款包装成一个大工具,而是拆成五个阶段,让每一步都有明确的继续条件。
第一步收集订单号。输入必须符合 ^ORD-[0-9]{5}$,经过 Pydantic 校验后,才能使用带 ? 绑定的参数化 SQL 查询 SQLite。订单缺失或输入无效,就回复订单不可用并停止。格式校验负责限制输入形状,参数化查询负责避免输入被当作 SQL 执行,两者作用不同。
第二步是第一次 Human-in-the-Loop(HITL,人在回路中)确认:展示商品和实付金额,询问退货原因,再调用 capture_return_feedback(order_id, reason_category, comment)。这一步先确认「退的是哪笔订单、为什么退」,避免后续计算建立在错误上下文上。
第三步并行检查物流、政策与风险:
- get_return_logistics(order_id) 检查是否达到 DELIVERED_AT_WAREHOUSE。
- fetch_refund_policy(category_id) 获取退货期限与费用比例。
- check_fraud_score(cust_id, oid) 评估退款频次风险。
包裹尚未入库,就在这里停止。用户愿意退款,不代表业务条件已经满足。
第四步调用 calculate_refund_amount(),展示商品金额、扣费和净退款额,等待用户明确回复「Yes」或「Confirm」。这是第二次确认,授权的是具体金额。
第五步才允许付款。before_tool_callback 检查金额是否不超过 $150.00,且 fraud_flagged=False;通过后注入验证金额与 idempotency_key,再执行支付。不通过则阻断付款,调用 create_hitl_ticket() 进入财务审核队列,这是第三类人工关口。
三个本地样例把规则落到了具体金额:
| 订单 | 数据与预期行为 |
|---|---|
| ORD-98765 | 服装商品 $90.00,加运费 $10.00,合计 $100.00,已经入库。NO_LONGER_NEEDED 扣除 10% 补货费,即 $9.00,退款 $91.00;DEFECTIVE 免补货费,退款 $100.00。 |
| ORD-55555 | 电子商品 $240.00,已经入库,但超过 $150.00 上限,转人工并返回 FIN-HITL-55555。 |
| ORD-11111 | 服装订单 $80.00,物流为 IN_TRANSIT,在第三阶段暂停,等待仓库扫描。 |
这些是作者准备的测试场景与预期行为。原文没有附测试运行报告,也没有提供真实支付记录。
控制成本和防止越界,也要放进执行链路
作者在 GenerateContentConfig 中设置 max_output_tokens=300、temperature=0.0,限制回答长度并降低输出随机性。300 是输出 token 上限,不能据此推断整次会话存在完整的费用硬上限;temperature=0.0 也不能保证回答永远正确。
另外两项优化针对上下文。prompts.py 保持静态,不混入时间戳或用户标识,以利于 Gemini 的提示词缓存;after_tool_callback 则在 get_order_details 的结果进入模型前,裁掉原始时间戳、审计日志等内部元数据。
思路合理,但作者没有给出缓存命中率、token 消耗或延迟的前后对比,「大幅节省」仍缺少量化证据。
越界控制也使用回调。before_model_callback 拦截无关请求,固定回复只能处理退货退款;tool_context.state 记录连续相同的助手回答,同一个澄清问题重复两次后触发兜底,避免对话一直打转。这里没说清无关请求如何识别,也没说明重复检测能否处理意思相同、措辞不同的回答。
项目按职责拆分:agent.py 连接 LlmAgent 与回调,config.py 集中配置,schemas/ 放输入输出约束,tools/ 放读写与计算,guardrails/ 放拦截逻辑。refund_agent/db.py 初始化 local_refund_store.db,tests/unit/ 覆盖 SQL 注入、金额计算和上限,.github/workflows/ci.yml 在每次 push 后运行 pytest。
原文给出的启动命令如下,可用于安装依赖、运行测试并打开 ADK 调试界面:
git clone https://github.com/your-username/adk-refund-agent.git
cd adk-refund-agent
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env # 填入 GOOGLE_API_KEY
pytest # 运行 SQL 注入防御与退款计算单元测试
adk web --port 8000 # 交互测试 ORD-98765、ORD-55555 和 ORD-11111
先留意第一行:your-username 是占位符,原文开头给出的参考仓库归属是 gouravchawla334,不能直接照抄。作者所说的离线能力主要来自本地数据库与测试数据;交互式模型调用仍需配置 GOOGLE_API_KEY,原文没有说明整套 Agent 能脱离云端运行。
我的判断
我认同这套方案的权限划分。相较于靠长提示词约束模型,它把金额保护和支付拦截放进了代码,适合退款这类规则明确、错误代价高的任务。
但「零幻觉」说得太满。代码接管计算,能缩小金额错误的空间;模型仍可能解释错政策、遗漏费用说明,或者误解用户同意的对象。保护最终支付金额,不能自动证明整段对话都准确。
「生产级」也有未交代的前提。订单号格式正确,不等于当前用户有权查看或退款;原文提到授权检查,却没展示身份与订单归属如何绑定。它注入了 idempotency_key,也没说明重试时键如何保持稳定,以及支付成功、状态写入失败时怎样恢复。
还有一个状态问题:已验证金额必须绑定到具体订单、退货原因和本次确认。用户中途换订单或修改原因后,旧金额和旧确认是否失效,原文没有说清。
对固定的五阶段流程,常规状态机同样可以完成大部分工作。Agent 的额外价值在于接收自由文本、追问并解释结果。作者没有给出与表单流程、状态机或其他 Agent 方案的对照数据,因此目前更适合把它视为一份有参考价值的工程设计,而不是已经验证的最优解。PostgreSQL、Model Context Protocol(MCPToolset)和自动化 adk eval 回归测试,也都属于后续计划。
能拿来做什么
- 在 Node 或 Python 的 AI 业务工具中,把金额计算与支付执行分开,并让支付端读取服务端验证结果,避免直接信任模型参数。
- 前端展示退款明细时,让用户确认具体订单与具体金额;订单或退货原因变化后,重新计算并重新确认。
- 先复用普通退款、超额转人工、物流未入库这三类测试路径,再补查原文未展示的订单归属、重复提交和状态恢复逻辑。
- 使用 AI 编程助手实现这类系统时,先明确工具输入输出、状态失效条件和支付前检查,再编写提示词,让权限限制成为代码能验证的规则。