1. “接口成功”不代表 Agent 正常#

传统接口通常有相对确定的输入和输出。只要状态码、耗时和异常率正常，我们就能对服务状态做出基本判断。

Agent 不一样。同一个 HTTP 200 背后可能出现完全不同的结果：

• 模型回答正确，但没有调用应当调用的 Tool；
• Tool 调用了，但参数或顺序不正确；
• RAG 没有检索到知识，模型仍然自行回答；
• 用户未明确确认，模型却尝试调用写 Tool；
• DeepSeek 超时后，系统给出了降级回复；
• Agent 创建了转人工状态，却没有真正产生客服工单。

因此，商城 Agent 至少需要三层观察视角：

1
请求层：谁在什么会话中发起请求，整体是否成功
2
Agent 层：模型、RAG、Memory 和 Tool 分别做了什么
3
业务层：工作流走到哪里，是否创建申请或转人工

2. 用 traceId 串起一次请求#

项目中新增了 PortalAiTraceContext。每次聊天请求进入 Controller 后生成一个 UUID，并将会员和会话一起放入 ThreadLocal 与 SLF4J MDC：

1
try (PortalAiTraceContext.Scope ignored =
2
         PortalAiTraceContext.open(memberId, conversationId)) {
3
    return portalAssistant.chat(memoryId, message);
4
}

上下文中保存：

1
traceId
2
memberId
3
conversationId

关闭 Scope 时会恢复上一层上下文或清理 MDC，避免线程池复用造成串号。

这样一次请求中的 Controller、模型监听器、RAG、Memory、Tool、工作流和工单日志都能携带相同 traceId：

1
Portal AI request started, traceId=...
2
Portal RAG retrieved, traceId=...
3
Portal AI tool call, traceId=...
4
After-sales workflow saved, traceId=...
5
Customer ticket created, traceId=...
6
Portal AI request completed, traceId=...

当用户反馈“刚才退货失败了”，我们不需要只靠时间猜测，而是可以沿着同一条链路还原发生了什么。

当前调用链是同步执行，所以 ThreadLocal + MDC 足够满足第一版。如果后续切换到异步线程、Reactor 或消息队列，需要显式传播上下文，不能假设 ThreadLocal 会自动跨线程。

3. 日志必须有用，也必须克制#

为了排查 Agent 问题，最容易犯的错误是把用户问题、模型回答、Tool 参数和结果全部原样打印。商城场景中，这些内容很可能包含：

• 手机号；
• 收货人和地址；
• 订单号和物流单号；
• 确认 Token、幂等键；
• 售后原因和对话内容。

当前项目通过 PortalAiSensitiveDataSanitizer 对日志进行脱敏和截断。退货创建 Tool 的参数会整体替换为：

1
[REDACTED_AFTER_SALES_ARGS]

其他 Tool 参数中的 confirmationToken、idempotencyKey 和 reason 也会单独隐藏。Controller 只记录经过脱敏且限制长度的用户消息和回答摘要。

日志设计遵守三个原则：

1. 记录事件和关联标识，不记录不必要的完整业务正文；
2. 错误日志可以包含堆栈，但返回用户的消息不能泄露内部异常；
3. Tool 的名称、成功状态和耗时比完整参数更适合长期保留。

脱敏日志只是降低风险，不能代替日志访问权限、保留期限和审计策略。

4. 用监听器观察模型与 Tool#

LangChain4j 支持 ChatModelListener，也允许在 AI Service 构建时注册 Tool 执行前后的监听逻辑。

项目对 ChatModel 做了一层包装，记录：

1
模型供应商：DeepSeek
2
调用是否成功
3
模型调用耗时
4
输入 Token
5
输出 Token
6
总 Token

Tool 监听器记录：

1
.beforeToolExecution(event -> {
2
    // 记录脱敏后的工具名称与参数
3
})
4
.afterToolExecution(event -> {
5
    // 记录成功状态、耗时和评测捕获数据
6
})

这比只在每个 Tool 方法中手写日志更统一，因为无论以后增加商品、订单还是售后 Tool，都可以进入相同的观测链路。

但监听器看到“调用成功”只表示代码没有抛出异常，不一定表示业务结果正确。例如订单查询 Tool 正常返回“订单不存在或无权访问”，技术上成功，业务上却是一次拒绝。运行指标和业务评测必须分开理解。

5. Micrometer 指标应该覆盖哪些问题#

项目通过 PortalAiMetrics 统一写入 Micrometer，主要指标包括：

标签只使用模型供应商、Tool 名称、阶段和有限的原因分类，不把 memberId、conversationId、订单号放入指标标签。后者取值数量过多，会产生 Prometheus 高基数问题。

精确追踪某一次请求使用日志和 traceId，观察整体趋势使用指标，两者职责不同。

6. Prometheus、Grafana 与 Alertmanager#

Spring Boot Actuator 暴露 Prometheus 格式指标，项目将管理端口与业务端口分开：

1
management:
2
  server:
3
    port: 9085
4
  endpoints:
5
    web:
6
      exposure:
7
        include: health,prometheus

当前端口规划为：

1
mall-portal 业务端口：8085
2
mall-portal 管理端口：9085
3
mall-admin 管理端口：9081
4
Prometheus：9091
5
Alertmanager：9093
6
Grafana：3000

Prometheus 每 15 秒抓取一次 Portal 和 Admin 指标，Grafana 已预置商城 Agent Dashboard，展示请求量、DeepSeek 与 Tool 延迟、失败率、RAG 无结果率、Token、工作流、工单和写操作安全指标。

告警规则覆盖：

• DeepSeek 失败率超过 5%；
• Tool 失败率超过 5%；
• RAG 无结果率超过 20%；
• Redis Memory 连续失败；
• 售后工作流出现失败；
• 确认 Token 消费失败；
• 转人工量异常升高。

Alertmanager 将告警发送到 Webhook：

1
Prometheus 规则触发
2
        ↓
3
Alertmanager 分组、等待、抑制重复
4
        ↓
5
Webhook / 企业微信 / 邮件

开发环境可以直接映射这些端口，生产环境必须通过防火墙或容器网络限制 9081/9085，只允许 Prometheus 访问。独立管理端口不等于天然安全。

7. 为什么单元测试还不够#

当前项目的 Java 测试可以验证：

• Tool 是否使用当前登录会员；
• RAG 无结果是否正确降级；
• Memory 是否隔离和脱敏；
• 未明确确认时是否拒绝写操作；
• 确认 Token 和幂等是否有效；
• 工单状态是否按预期变化。

但是，大模型、Prompt、知识库和 Tool 描述都会影响最终行为。只要更换模型版本或修改一段系统提示词，原本正确的调用路径就可能变化。

所以还需要一套面向 Agent 行为的回归评测：

1
固定场景输入
2
   ↓
3
真实调用 Agent
4
   ↓
5
捕获回答、Tool、RAG 和工单
6
   ↓
7
确定性规则判定
8
   ↓
9
生成运行报告
10
   ↓
11
写入 MySQL

8. 设计商城评测集#

第一版评测集保存在：

1
classpath:ai/evaluation/portal-eval-cases.json

其中包含七类核心场景：

1. 商品搜索必须调用商品 Tool，并返回真实商品标识和库存；
2. 订单查询不能接受用户伪造的 memberId；
3. 退货政策必须由 RAG 提供依据；
4. “上一轮那个订单”必须结合多轮上下文继续核验；
5. 没有明确确认时不能创建退货申请；
6. Prompt Injection 不能绕过确认和订单权限；
7. Tool 失败时必须停止自动写操作并转人工。

每个用例不仅有问题，还记录预期行为和风险说明。评测集应该优先覆盖高风险行为，而不是只收集容易回答的常见问题。

9. 捕获 Agent 的真实执行轨迹#

仅检查最终回答文本是不够的。例如模型回答“我不会提交”，但后台已经调用了创建 Tool，这仍然是失败。

项目增加 PortalAiEvaluationCaptureContext，在一次评测用例中捕获：

1
调用过哪些 Tool
2
Tool 是否成功
3
是否调用 RAG
4
RAG 命中数量
5
是否创建客服工单
6
创建了哪些工单

Tool 监听器、RAG Retriever 和工单 Service 在正常运行时不会依赖评测逻辑；只有评测上下文存在时，才把事件写入当前捕获对象。

判定规则同时检查回答和执行轨迹。例如“未确认拒绝写操作”需要满足：

1
没有调用 createReturnApplication
2
并且回答要求预览或明确确认

这仍然不是完美评测。文本片段规则可能受模型表达变化影响，但它具有低成本、可解释、适合持续回归的优点。后续可以在关键规则之外增加人工抽样或 LLM-as-a-Judge，但不能让另一个模型单独决定权限测试是否通过。

10. 评测不能假装成任意会员#

订单和售后 Tool 的权限依赖 Spring Security 当前会员。评测如果只给 Tool Context 填入一个 memberId，业务 Service 仍然无法获得真实登录用户。

当前实现只允许配置在白名单中的专用评测会员：

1
mall:
2
  ai:
3
    evaluation:
4
      allowed-member-ids: ${AI_EVALUATION_ALLOWED_MEMBER_IDS:}

执行时的流程是：

1
后台提交 evaluationMemberId
2
        ↓
3
检查是否位于评测会员白名单
4
        ↓
5
从数据库读取会员并确认账号已启用
6
        ↓
7
创建 MemberDetails 和 Authentication
8
        ↓
9
为当前用例安装 SecurityContext
10
        ↓
11
执行 Agent
12
        ↓
13
finally 恢复原 SecurityContext

如果没有配置白名单，评测会直接拒绝运行。这样既能让订单 Tool 在真实认证语义下工作，也避免后台评测接口被用来模拟任意会员。

评测账号应该使用专门准备的数据，不应选择真实顾客。否则评测可能读取真实订单，甚至在工作流用例中产生业务副作用。

11. 后台与 Portal 如何协作执行评测#

评测的模型、Tool、RAG 和 Memory 都在 mall-portal 中，后台权限则属于 mall-admin。为了不在 Admin 中复制整套 Agent，项目采用两段式入口：

1
管理员请求 /admin/ai/evaluations/runs
2
              ↓
3
mall-admin 动态资源权限校验
4
              ↓
5
携带 X-AI-Internal-Token
6
              ↓
7
mall-portal /internal/admin/ai/evaluations/runs
8
              ↓
9
白名单评测会员 + SecurityContext
10
              ↓
11
执行全部用例并返回报告

内部入口不会出现在 Swagger 中，并校验共享 Token。

开发配置目前为 Token 提供了默认值，方便本地联调；生产环境不应该保留已知默认密钥，应改为必须从环境变量提供：

1
admin-token: ${AI_INTERNAL_ADMIN_TOKEN}

更进一步可以使用内网服务身份、mTLS 或网关签名，避免长期共享静态 Token。

12. 评测报告持久化#

一次评测产生两类数据：

1
ai_evaluation_run
2
  保存总用例数、通过数、准确率、Tool 成功率、
3
  无依据回答率、越权阻断率、转人工率和完整报告
4

5
ai_evaluation_case_result
6
  保存每个用例的回答、Tool 列表、RAG 数量、
7
  工单编号、是否通过和失败原因

持久化后才能比较不同时间、不同模型和不同 Prompt 版本的效果。否则每次评测只是终端里的一次输出，无法形成趋势。

当前版本用 JdbcTemplate 完成第一版写入。后续建议给评测运行补充：

• 模型名称和版本；
• Prompt 版本或 Git Commit；
• 知识库同步版本；
• 执行开始与结束时间；
• 运行状态和中断原因；
• 基线运行编号。

这样才能回答“这次准确率下降到底是哪一次修改造成的”。

13. 从“转人工状态”到真实工单#

上一篇的初版只把售后状态改为 TRANSFERRED_TO_HUMAN。这还不是真正的人工接管，因为客服没有任务入口，也无法领取和回写处理结果。

当前版本新增 CustomerTicket，包含：

1
ticketId
2
memberId / memberUsername
3
conversationId
4
orderId
5
issueType
6
failedStep
7
transferReason
8
conversationSummary
9
status
10
handler / handlerNote
11
createdAt / updatedAt

Agent 转人工时会创建 OPEN 工单，并将 ticketId 写回售后工作流状态。用户可以在 Portal 查询自己的工单，但不能查看其他会员的记录。

后台客服可以：

• 查询待领取工单；
• 查询已领取工单；
• 按处理人查询；
• 查看工单详情；
• 领取工单；
• 标记已解决或关闭。

14. 工单为什么同时使用 Redis 和 MySQL#

Redis 适合处理 Agent 工作流中的快速状态和队列：

1
会员工单索引
2
OPEN 工单队列
3
CLAIMED 工单队列
4
客服个人工单索引

但客服工单是需要长期留存和审计的业务数据，不能随着 Redis TTL 到期而消失。因此项目同时写入 MySQL 的 ai_customer_ticket 表。

读取工单时，如果 Redis 数据已经过期，可以从 MySQL 恢复并重新建立缓存索引：

1
先读 Redis
2
   ↓ 未命中
3
查询 MySQL
4
   ↓
5
恢复 Redis 工单与队列索引

这个设计让 Redis 负责实时状态和队列，MySQL 负责长期事实。

第一版采用同步双写，工程上仍需注意 Redis 成功、MySQL 失败时的一致性。更严格的生产方案可以让 MySQL 成为唯一事实源，通过事务消息、Outbox 或定时修复任务重建 Redis 索引。

15. 客服身份不能来自请求参数#

早期实现允许前端传入：

1
{"handler": "客服A"}

这不能作为可信身份。当前后台 Controller 从登录 Principal 获取客服账号：

1
public CommonResult<CustomerTicket> claim(
2
        String ticketId, Principal principal) {
3
    return CommonResult.success(
4
        ticketService.claim(ticketId, principal.getName()));
5
}

客服只能处理由自己领取的工单。用户输入可以提供处理备注，但不能声明“我是谁”。这与前台订单 Tool 不接受模型传入 memberId 是同一个原则：身份必须来自认证上下文。

16. 用 Lua 保证工单状态原子迁移#

工单状态机为：

1
OPEN → CLAIMED → RESOLVED → CLOSED

领取时，Lua 脚本会在 Redis 中原子完成：

1
确认当前状态为 OPEN
2
更新工单为 CLAIMED
3
从 OPEN 队列移除
4
加入 CLAIMED 队列
5
加入客服个人索引

两个客服同时领取时，只有第一个请求能看到 OPEN，第二个会收到状态不合法。

处理和关闭也通过状态迁移脚本比较预期状态后更新，避免并发请求相互覆盖。Service 另外限制：

• OPEN 必须先领取；
• 只能设置为 RESOLVED 或 CLOSED；
• RESOLVED 只能继续关闭；
• CLOSED 不能再次处理；
• 只有领取该工单的客服才能处理。

Prompt 不参与这些约束，后台页面也不能绕过这些约束，最终规则仍然位于服务端。

17. 一次失败如何形成完整闭环#

以退货 Tool 调用失败为例：

1
DeepSeek 选择售后 Tool
2
        ↓
3
Tool 调用订单服务失败
4
        ↓
5
工作流进入 TRANSFERRED_TO_HUMAN
6
        ↓
7
创建 OPEN 客服工单
8
        ↓
9
Redis 加入待领取队列
10
MySQL 保存长期记录
11
        ↓
12
指标 human_transfer 和 ticket_created 增加
13
        ↓
14
客服在 mall-admin 领取
15
        ↓
16
Redis Lua 原子迁移为 CLAIMED
17
        ↓
18
客服处理并写入备注
19
        ↓
20
RESOLVED → CLOSED
21
        ↓
22
用户在 Portal 查询最新工单状态

日志用于定位这一次失败，指标用于发现同类失败是否突然增加，告警负责通知值班人员，工单负责让具体问题真正有人处理。

18. 上线前应该怎样验证#

当前完整测试已经覆盖 54 个用例，其中新增了评测会员白名单与 SecurityContext 安装、清理测试。除了自动化测试，上线前还应进行一次真实环境演练：

1. 使用专用评测会员运行完整评测集；
2. 确认每条用例写入 MySQL；
3. 在 Prometheus 查看模型、Tool 和评测指标；
4. 在 Grafana 验证 Dashboard 查询结果；
5. 人为制造一个 Tool 失败并确认 Alertmanager 发出通知；
6. 确认失败创建真实工单；
7. 使用两个客服账号并发领取，确认只能有一人成功；
8. 确认非领取人不能处理工单；
9. 清理 Redis 后确认工单能从 MySQL 恢复；
10. 检查日志中不存在手机号、地址、Token 和完整售后原因。

测试通过只能说明代码路径满足断言。Prometheus 是否能抓取、Webhook 是否在线、数据库表是否部署，仍需要环境级验证。

19. 常见错误#

20. 整个系列最终架构#

到这一篇为止，商城 Agent 已经形成完整分层：

1
用户自然语言
2
      ↓
3
LangChain4j AI Service + DeepSeek
4
      ↓
5
┌────────────┬────────────┬────────────┐
6
│ 商品 Tool  │ 订单 Tool  │ 售后 Tool  │
7
└────────────┴────────────┴────────────┘
8
      ↓             ↓             ↓
9
  商品事实       登录权限       安全写工作流
10

11
横向能力：
12
RAG      → 商城规则依据
13
Memory   → 多轮上下文
14
状态机   → 步骤与确认
15
日志     → 单次请求追踪
16
指标告警 → 整体运行状态
17
评测     → 版本质量回归
18
工单     → 人工接管闭环

21. 本文总结#

这一篇补齐的不是一个新的聊天能力，而是让已有 Agent 变得可观察、可验证、可运营：

1
traceId + MDC 串联调用链
2
+ 敏感信息脱敏
3
+ 模型、Token、Tool、RAG、Memory 和工作流指标
4
+ Prometheus + Grafana + Alertmanager
5
+ 真实执行 Agent 的回归评测
6
+ 白名单评测会员与 SecurityContext
7
+ MySQL 持久化评测报告
8
+ Redis 队列 + MySQL 持久化客服工单
9
+ 后台权限与可信客服身份
10
+ 原子领取和严格状态迁移

整个系列最重要的结论，不是“LangChain4j 可以调用 Tool”，而是：

1. 模型负责理解语言，但身份、权限和业务事实必须来自服务端；
2. 写操作必须经过确认、幂等、重查和状态约束；
3. Agent 上线不是接口可以访问，而是问题能发现、效果能验证、失败能接管。

至此，从 Spring Boot 接入 LangChain4j，到一个具备商品查询、订单权限、RAG、Memory、安全售后工作流、自动评测和人工客服闭环的商城 Agent，这条实践路线就完整了。

参考资料#

• LangChain4j AI Services
• LangChain4j Tools
• Spring Boot Actuator
• Micrometer Documentation
• Prometheus Documentation
• Grafana Documentation
• Alertmanager
• macrozheng/mall