macro report / diagnosis-agent / 2026.08
Agent 怎么做，
业务怎么懂
从一个诊断 Agent 项目，看 Agent 怎么搭、怎么做好、什么值得复用
02 / fit业务决定效果Tool + Prompt 贴近真实排查
03 / evolve评测推动进化记忆、反馈与版本迭代形成闭环
00 / the short answer / Mercedes case
一个真实案例：Agent 需要懂业务，才能把问题查清楚
customer question
奔驰客户端为什么能通过鉴权？
allow_connect 已经限制了客户端 ID。
关键不是给出一个猜测，而是还原“实际用了什么证书、哪条规则做了决定”。
01 / MQTT 接口证书现状核对当前绑定证书、CN、状态和有效期。
02 / MySQL 审计生命周期还原注册、激活、删除和状态变更。
03 / 连接日志连接对齐核对 TLS 实际使用证书和连接时间线。
04 / ACL 决策关键证据No matched ACL policy 明确拒绝；成功连接实际使用新 JITP 证书并命中 allow_connect。
框架能让 Agent 快速搭起来；要把问题查清楚，Agent 需要理解业务，知道该查什么、如何串起证据。
01 / how to organize the work
Agent 可以有不同的组织方式，但组织方式不是业务能力
01 / single agent
单 Agent
一个模型理解任务，直接选择并调用工具。
用户问题模型工具 / 结果
02 / manager + subagents
主 Agent + 子 Agent
主 Agent 拆解复杂目标，再把子任务交给专家。
03 / agent team
Agent Team
多个相对平等的 Agent 围绕目标协作。
共同目标Agent AAgent B
Agent CAgent D
它们解决“谁来协作”，不自动解决“查什么、怎么判断”。
02 / how to build it
Agent 已有多种成熟实现路径，搭起来越来越快
SDKClaude / Codex SDK
直接使用模型的工具调用和 Agent 能力，自己组织业务流程。
适合：快速验证、强定制、贴近模型能力
LCLangChain / LangGraph
提供 Agent、工具、状态、编排和多 Agent 协作的基础组件。
适合：复杂流程、状态管理、工程化运行
WFDify 等 Workflow
通过可视化流程组合模型、工具和节点，降低搭建成本。
适合：快速组合、低代码交付、业务试验
这些路径主要解决“怎么快速搭起来”；真正的业务效果，还要看 Tool 和 Prompt。
03 / the real composition
Agent = Model + Tool + Prompt
框架帮助把三者组装起来；Tool + Prompt 才把通用模型变成业务 Agent。
04 / from framework to business / MQTT Agent
MQTT Agent：前置分诊 + 主子 Agent，形成可核对的证据链
执行流程
Triage：前置分诊识别意图，校验实例、客户端、时间，决定是否进入 MQTT 诊断
Orchestrator：主 Agent拆解目标，决定调用哪些子 Agent、顺序和上下文
领域子 AgentMQTT / Log / Metrics / Runtime，各自查询一类事实
汇总证据主 Agent 汇总结果，形成结论并支持用户追问
前置分诊 / Triage先判断“是什么问题”，补齐对象和范围
意图 / 实体 / 时间
主 Agent / Orchestrator拆解目标，安排子 Agent 的任务和顺序
任务 / 上下文 / 协作
领域子 Agent每个子 Agent 只负责一类业务事实
MQTT / Log / Metrics / Runtime
汇总输出把多处事实拼成一条可解释结论
证据链 / 结论 / 追问
关键设计：分诊负责分对问题，主 Agent 负责拆对任务，子 Agent 负责查准事实。
05 / business understanding / tool
工具设计：给 Agent 足够能力，也给它明确入口
太窄写死一个流程
固定案例可以覆盖，但换一个现象、时间或对象就失去适应性。
太宽把能力全部丢给模型
看似什么都能查，却让 Agent 在参数、结果和数据量里找不到重点。
好工具的作用，是让 Agent 能用合适的搜索方式，找到可以核对的关键事实。
| 要查的事实 | 工具提供什么 |
|---|
| 当前状态 | 实例、会话、连接、订阅 |
| 事件与审计 | 日志、操作记录、拒绝原因 |
| 趋势变化 | 指标、时间线、异常变化 |
| 运行时现场 | Heap Dump、线程、GC 证据 |
项目中对应 GraphQL、CLS、Prometheus、JVM / MAT 等查询能力。
06 / business understanding / prompt
Prompt：把业务人员的排查顺序教给 Agent
01 / 先理解理解问题识别现象、范围、时间、对象和用户假设。
02 / 再选择选择方向判断数据域、Agent、工具和搜索词。
03 / 最后验证验证结论补足证据，发现冲突，知道何时继续或追问。
角色和边界工具选择停止条件输出要求
Prompt 的价值，是把业务人员的排查经验教给模型。
07 / business understanding / runtime
从复杂问题看 Tool + Prompt 的作用
conversation 1 / 发现问题从 Pod 异常重启定位到缓存膨胀
01 / Agent：RuntimeAgentGC allocation stall、Pod 异常重启；GC 日志不可用，先用 live histogram + heap dump + MAT 建立基线。
02 / Prompt + MQTT Skill：理解对象2.4GB 可达堆里出现百万级队列对象；结合项目语义识别 retained top：WildcardManager 411.7MB、PullAPIWrapper 364.0MB。
03 / Tool：沿引用链排除用 MAT 和 OQL 继续核对：ProcessQueue 几乎都由 live Session 的 processQueueMap 持有；7:1 是结构性放大，但不是后续增长主因。
04 / Tool：再次抓堆做对比Pod 继续涨到约 5GB 后重新抓取现场：对比两份 Heap Dump，寻找偏离 Session / ProcessQueue 规模增长的对象。
05 / Prompt：用业务模型锁定根因PullAPIWrapper.pullFromWhichNodeTable 的 MessageQueue 约 144.6 万 → 306.6 万，retained heap 364.0MB → 769.7MB，新增约 405.7MB。
结论：问题集中在 PullAPIWrapper 内部 MessageQueue 缓存的非线性累积。
conversation 2 / 修复后验证升级后确认原问题是否消失
01 / Prompt：明确验证目标用户明确追问：之前 PullAPIWrapper 占用很多内存，优化后效果如何。
02 / Tool：再次抓堆并核对两次现场中均为 2 个 PullAPIWrapper；每个 retained heap 248B，pullFromWhichNodeTable 均为 0 个元素。
03 / Prompt：区分新的增长MAT reachable heap 779.8MB → 957.5MB，但新增主要与 Session 3,902 → 6,337、ProcessQueue 162,533 → 263,102 同步。
结论：PullAPIWrapper 优化有效；后续增长应按连接 / Session 规模继续判断，不再归因于原缓存问题。
08 / evaluation / mark the gap
没有评测，Agent 只能凭感觉迭代
01 / 看过程看过程
看得到调了什么、查到什么、结论依据什么。
02 / 标问题标问题
指出遗漏、错误前提和不必要的调用。
03 / 变反馈变反馈
把一次反馈整理成可复用的改进记录。
真实反馈样例- “没有验证客户端 ID”
- “共享订阅语义在追问中丢失”
- “这个场景不需要 MQTTAgent”
标注对象- 结论是否有证据
- Agent / Tool 是否选对
- 关键上下文是否保持
诊断过程用户反馈改进记录下一轮迭代
09 / evaluation / turn feedback into change
一次反馈，如何变成下一轮改进
改提示词改当前行为
“没验证客户端 ID” → 先校验对象，再进入专家排查。
补业务方法补专业经验
共享订阅语义遗漏 → 补充判断方法、查询模板和反例。
沉淀案例形成好坏案例
高质量诊断形成好案例；错误路径成为下一次的反面教材。
调工具边界减少无效调用
不需要 MQTTAgent → 优化路由和委派，让协作更准确。
反馈不是记录，而是下一轮 Agent 的改进输入。
用户反馈案例 / 知识库Prompt / Skill / Tool 更新
10 / business knowledge / three layers
业务知识如何进入 Agent：Prompt → Skill → 历史知识库
业务经验分三层
每一层解决不同问题，用户反馈决定应该更新哪一层。
三层业务经验
01 / 当前行为
行为层：Prompt
角色、边界、停止条件和工具策略；约束 Agent 当前怎么行动、何时追问、哪些事实必须验证。
02 / 专业方法
方法层：Skill
业务目录、操作方法、查询模板和反例；按需告诉 Agent 该查什么、怎么查。
03 / 历史经验
经验层：历史知识库
好案例作为可复用经验，反面案例作为提醒；通过相似检索影响选路和搜索词。
Prompt 管当前行为，Skill 管专业方法，历史知识库管经验先验。
11 / center-level reuse / a practical boundary
中心级复用：共享持续迭代能力，不必统一所有 Agent
业务团队负责保留业务差异
问题定义、Tool、Prompt、领域知识、排查路径和 Agent 组织方式。
因为这些内容离业务事实最近。
可以共同沉淀共享业务经验
评测样本、用户反馈、好坏案例和版本结果。
因为它们可以跨项目支持学习。
中心优先共建支撑持续迭代
反馈采集、评测运行、过程观测和版本对比。
因为它们能降低迭代和比较成本。
如果要做中心级复用，优先复用评测、记忆和反馈基础设施，而不是强行统一所有 Agent 的实现框架。
appendix / 01 / migration mapping
Knot 迁移：实现映射过去了，效果不佳
same Prompt / Skill / Tool
Knot 已接入同一套 Prompt、Skill 和工具，但两个验收 case 仍未复现原 Agent 的诊断结果。
原 Agent / baseline先分诊，再诊断
01Triage分类、校验实例 / 客户端 / 时间，生成 context
02DiagnosisManager查历史经验，决定路由、委派和证据是否足够
03领域 AgentMQTT / Log / Metrics 查询各自负责的事实
Knot / current主 Agent 规划，子 Agent 执行查询
主 Agent规划查询 / 委派
类比 DiagnosisManager；结合 MQTT Proxy 知识库，决定查哪些事实、交给哪个子 Agent
LogAgentquery-catalog4 个日志工具
MetricsAgentmetric-catalogPrometheus 工具
MQTTAgentgraphql-queryMQTT MCP
修改 Agent 对话列表历史经验管理对话 API 重放
能力缺陷 01无法通过工具注入 contextKnot 没有提供修改 Agent 对话列表的能力，Triage 结果无法注入后续对话。
能力缺陷 02历史经验没有迁入MQTT Proxy 知识库已接入，但原 Agent 的历史案例和记忆管理没有对应入口。
能力缺陷 03无法自动回归缺少 API、对话分叉和调试入口，coding agent 不能批量重放与验证。
能力缺陷 04无法自定义脚本只能使用 MCP；RuntimeAgent 需要下载 COS 文件时，脚本路径无法迁移。
能力缺陷 05不支持 A2ARocketMQAgent 依赖 A2A 协作方式，当前无法迁移。
同一套 Prompt + Skill + Tool ≠ 同样的诊断结果。
appendix / 02 / case 1 / sql scope
case 1：SQL 没有限制 namespace，结果失去可信度
用户问题
mqtt-bz3nxb5n 在 14:26 左右，哪些 topic 或 clientid 在大量 PUBLISH？
原 Agent / 可验收实例边界写进 SQL
__TAG__.namespace:"mqtt-bz3nxb5n"
AND action:"PUBLISH"
| select "topic", count(*) as msg_count
from log group by "topic" order by msg_count desc
Knot / AgentLens 实际 SQL漏掉 namespace
action:"PUBLISH" AND bound:"INBOUND"
| SELECT topic, count(*) AS cnt
FROM log GROUP BY topic ORDER BY cnt DESC
LIMIT 20
原 Agent / 正确执行执行 Prompt 默认规则
未提供时间范围 → 自动使用目标时间前后各 30 分钟
14:26 → 13:56–14:56
Knot / 错误执行指令遵循能力差
反问用户时间范围，形成多一轮交互
额外确认，token 成本上升
MCP 参数有 instance_id≠SQL 已限制 namespace
原 Agent112.1KKnot · 两轮218.63K1.95×
数据范围先错了，后面的热点统计再精致也不能作为结论。
appendix / 03 / case 2 / root cause
case 2：Prompt / Skill / Tool 相同，Knot 仍然误判根因
用户问题
go_away 重连后不消费，业务容器重启后恢复：到底哪里出了问题？
原 Agent / 有证据的链路从事件下钻到协议行为
16:49:00go_away 断连MQTT 事件
16:49:02重连，cleanStart=trueMQTT 事件
之后无 SUBSCRIBE/SUBACK，无 OUTBOUND审计日志
重启重新建立订阅，消费恢复客户反馈 + 事件
根因：clean session 重连后，SDK 没有重新订阅。
Knot / 迁移后排查过程查了数据，但证据不足
query-cataloggraphql-queryexecute_log_query
go_away重连成功
直接下结论“业务进程内部状态未恢复”缺少订阅 / 投递证据
错误归因：把可能解释说成了根因。
原 Agent274.9KKnot464.74K1.69×Prompt / Skill / Tool 都在，也不代表诊断对
appendix / 04 / result comparison
结果对比：Knot 更耗 token，结果还更差
2 / 2核心 case 未通过同一套 Prompt、Skill 和 Tool 已接入，但没有复现原 Agent 的诊断结果
case 1 / 高频 PUBLISHSQL 范围错误
诊断结果namespace 漏掉 · 统计不可采信1.95×
case 2 / go_away 后不消费根因判断错误
诊断结果证据不足 · 根因不成立1.69×
不是“效果接近但还需优化”而是成本更高，同时没有通过两个基本验收 case。
appendix / 05 / current gaps
Gap：当前 Knot 还不能承接这个 Agent
01 / 功能无法通过工具注入 contextKnot 没有提供修改 Agent 对话列表的能力，无法把 Triage 结果注入后续对话。
02 / 诊断效果关键约束没有稳定执行Prompt 已规定默认前后各 30 分钟，但 Knot 仍追问时间；case 1 还漏掉 namespace。
03 / token重复查询推高成本case 1 约 1.95×，case 2 约 1.69×；上下文和路由失真带来重复工作。
04 / 迭代无法自动回放和回归缺少 API、对话分叉和可编程 harness，coding agent 无法批量重放、修改和回归。
05 / 文件处理无法执行自定义脚本只能使用 MCP，不能下载 COS 文件；RuntimeAgent 无法迁移。
06 / Agent 协作不支持 A2ARocketMQAgent 依赖 A2A 协作方式，当前无法迁移。
可能原因 / 待验证Harness 黑盒，模型行为调优可能不足无法看到 Prompt 拼装、context 注入和执行约束；同一套 Prompt、路由、工具选择和停止条件，未必针对不同模型调优。相较 LangChain / LangGraph / DeepAgents 等成熟开源项目，Knot 的 Harness 质量仍需要验证。
当前结论不能承接当前 MQTT Agent无论问题来自上下文传递、主 Agent 规划、Harness 或模型行为调优，当前两个 case 都已验收失败。