从“能跑的 Agent”到“敢上生产的 Agent”
——一个生产级交易型 AI Agent 的完整架构设计与实践
在过去一年里，我刻意避免去做“看起来很炫”的 AI Demo，而是选择从一个极其具体、简单但高风险的业务场景入手：
商品查询 → 下单 → 订单确认 → 执行交易因为这是第一个会让我认真思考：
“如果 LLM 出错，系统还能不能兜住？”的问题。
这篇文章完整介绍一个我自研的生产级交易型智能体（AI Shopping Guide）：
它不是 Prompt 工程展示，也不是工具堆砌，而是一个真正考虑了状态、权限、回滚、安全与可观测性的 AI 应用系统。
一、为什么要“反直觉”地做一个这么复杂的系统？
在大量 Agent 项目中，我反复看到三种常见风险：
- LLM 拥有直接写业务状态的能力
- 系统状态与对话状态混杂在 Prompt 中
- 出错只能靠“再问一次”
这些在“查资料 / 写代码”类 Agent 中问题不大，但在交易型系统中是致命的。
所以这个项目从第一天起，就立了三条不可妥协的原则：
| 原则 | 一句话解释 |
|---|---|
| LLM 零写权限 | LLM 永远不能直接修改任何业务状态 |
| 状态机硬闸门 | 关键动作必须经过 FSM 决策 |
| 纯函数执行 | 订单编辑是确定性的、可回滚的 |
二、整体架构概览：职责清晰，而不是“一个 Agent 解决一切”
系统采用清晰分层 + 克制设计，而不是把所有能力堆进一个 Agent。
前端 (Next.js / React) ↓ API Routes (BFF + 安全拦截) ↓ ToolLoopAgent（执行引擎） ↓ FSM（状态与权限控制） ↓ 工具系统（查询 / 下单 / 存储） ↓ Redis / Vector / 可观测性为什么不是“一个大 Agent”？
因为在生产环境里，Agent ≠ 系统控制器。
LLM 擅长理解意图，但不适合：
- 管理状态
- 处理边界条件
- 保证一致性
- 做最终执行决策
所以我把它降级为“建议者”。
三、Agent 设计：ToolLoopAgent + prepareStep 路由模式
系统并没有让 LLM 自由选择工具，而是通过ToolLoopAgent + prepareStep明确控制每一轮行为。
Agent Loop 核心思想
Step 0：必须先问 FSM —— 我现在能不能干这件事？ Step 1：如果是交易路径，走强约束执行 Step 2+：才允许进入 auto 模式自由查询这种模式解决了一个关键问题：
“Agent 是在思考，还是在执行？”
而不是让这两件事混在一起。
四、FSM：整个系统最重要的“安全闸门”
这是一个极简但强约束的三态 FSM：
| 状态 | 含义 |
|---|---|
| IDLE | 空闲 / 查询态 |
| AWAITING_CONFIRMATION | 等待用户确认 |
| EXECUTING | 系统自动执行 |
核心规则（非常重要）
- 只有 EXECUTING 状态，系统才允许 createOrder
- LLM 在 AWAITING_CONFIRMATION 状态下被禁止调用业务工具
- 所有状态变更必须由代码触发，不接受 LLM 直写
FSM 不是“为了优雅”，而是为了兜底。
五、订单系统：纯函数草稿编辑，而不是“让 LLM 写 JSON”
订单编辑的核心不是 Prompt，而是一个纯函数：
applyActionsToDraft(draft, actions) → newDraft | error为什么这是整个系统的“定海神针”？
- 每一步编辑确定性
- 任一 action 失败整体回滚
- 不依赖 LLM 的“猜测正确性”
LLM 只负责输出**“我想做什么”**，
而系统代码负责决定：
“你能不能这么做，以及结果是什么”
六、检索系统：不迷信向量，不排斥传统方法
在商品搜索上，我没有走“纯向量”的流行路线，而是选择：
BM25 + 向量检索 + 动态权重融合
原因很现实：
| 场景 | BM25 | Vector |
|---|---|---|
| 冷启动 | ✅ | ❌ |
| 可解释性 | ✅ | ❌ |
| 语义泛化 | ❌ | ✅ |
系统会根据 query 特征自动调整权重，而不是一刀切。
七、防御深度：一个请求，要经过 6 层防护
| 层级 | 防护点 |
|---|---|
| L0 | 会话 / 页面 / Tab 隔离 |
| L1 | 前置拦截（负数、nonsense） |
| L2 | Agent 意图分类 |
| L3 | FSM 状态闸门 |
| L4 | 业务字段级校验 |
| L5 | 本轮地址隔离 |
这不是“过度设计”，而是对 LLM 不确定性的尊重。
八、可观测性：看得见 Agent 在“想什么”
系统接入 Langfuse，但做了两个关键约束：
- 可观测 ≠ 强依赖
- 追踪失败不影响业务
每一次：
- FSM 状态转移
- 工具调用
- 记忆读写
都有独立 Span，可以完整还原 Agent 行为路径。
九、这套架构解决了什么问题？
| 问题 | 是否解决 |
|---|---|
| LLM 幻觉 | ✅ |
| 非法写状态 | ✅ |
| 交易误执行 | ✅ |
| 多轮对话错乱 | ✅ |
| 可回放 / 可调试 | ✅ |
十、总结：这是一个“工程视角”的 Agent，而不是 Prompt 展示
这个项目我最满意的地方不在于功能多少，而在于：
- 我敢把它放到生产环境
- 我敢让别人 review 架构
- 我敢在面试中被深挖每一个决策
Agent 的未来，不是“更聪明的模型”，
而是“更克制的系统设计”。
项目演示
📹 视频演示：
https://pan.baidu.com/s/1mMAHbi_Vz26D6gQfXHmfGQ?pwd=gqfn