Agent：从原理、架构到工程落地（案例篇）

如果把前面文章讲的原理放到更真实的生产环境里，最典型、也最能体现 Agent 价值的场景之一，就是云产品部署故障排查。

这类问题有几个天然特点：

故障往往发生在发布、扩缩容、配置变更之后
证据分散在多个系统里：监控、日志、发布平台、配置中心、K8s、网关、服务网格
排查过程不是线性的，往往需要不断切换假设
一旦误判，会直接影响恢复速度，甚至扩大事故范围

所以，这类任务非常适合 Agent 参与，但前提不是"让模型自由发挥"，而是把它放在一个可验证、可回退、可审计的排障框架里。

下面通过一个完整案例，说明这个 Agent 是如何工作的。

一、故障背景：一次"看起来像网络问题"的发布事故

假设你在一家云产品公司，负责一套对象存储 API 网关。

某天上午 10:15，监控平台发出告警：

gateway-api 请求成功率从 99.95% 降到 98.7%
p95 延迟从 40ms 升到 1.8s
5xx 错误开始上升
客服侧同步收到用户反馈：部分上传请求失败

与此同时，发布平台显示：

10:08 有一次网关灰度发布
10:11 新版本开始在 20% 流量上生效
10:14 指标开始明显异常

值班同学第一反应往往会是：

是不是网关本身有问题？
是不是上游客户端流量异常？
是不是下游存储服务抖动？
是不是 DNS / 负载均衡出问题了？
是不是新版本引入了连接池、超时或重试配置错误？

这时，Agent 就可以开始介入了。

二、任务定义：Agent 不负责"拍答案"，而负责"收敛诊断"

在这个场景里，Agent 的职责不是直接给出"根因是 X"，而是完成一个完整的诊断闭环：

确认异常是否与发布强相关
判断问题发生在网关层、下游层还是网络层
选择最值得查看的证据
根据证据动态调整假设
输出可验证的根因与建议动作

换句话说，Agent 不是"结论生成器"，而是"诊断推进器"。

三、系统架构：Workflow 固定采集，Agent 负责推理

在生产环境里，这类系统最稳妥的方式通常是 Workflow + Agent 混合架构。

1. Workflow 负责固定动作

这些动作不需要模型决策，应该直接由代码执行：

拉取告警详情
拉取最近 30 分钟指标
拉取发布记录
拉取配置 diff
查询网关日志
查询下游服务状态
拉取 K8s Pod 事件
收集 trace 样本
标准化并写入证据文件

2. Agent 负责动态推理

模型基于证据做判断：

当前更像是网关问题还是下游问题
是否与新发布高度相关
是否要继续看连接池、TLS、DNS、超时、重试、线程池
哪个假设优先验证
是否可以收束结论并建议回滚

这种分工很重要：

确定性动作交给系统，不确定性判断交给模型。

四、Agent Loop 如何执行

这个排障 Agent 的主循环，本质上仍是经典四步：

感知 -> 决策 -> 行动 -> 反馈

1. 一轮循环的输入

Agent 每一轮拿到的上下文通常包括：

当前故障摘要
已完成的证据列表
最近一次工具调用结果
当前候选假设
剩余可用工具
轮次预算和终止条件

2. 一轮循环的输出

模型可能输出三种结果之一：

继续调用工具
切换假设
收束并输出结论

五、第一步：先判断是不是"发布相关故障"

输入给 Agent 的信息

系统会自动汇总一页结构化上下文：

故障开始时间：10:14
灰度发布时间：10:08
灰度比例：20%
异常指标：成功率下降、p95 延迟升高、5xx 上升
服务范围：gateway-api
受影响请求：上传类接口为主

Agent 的初步判断

Agent 不会直接下结论，而是先建立几个候选方向：

新版本引入了性能退化
下游存储服务变慢
网关路由或连接池配置异常
TLS / DNS / 网络抖动
某类请求触发了新版本 bug

这一步的重点不是"哪个一定对"，而是先形成一个可验证的假设空间。

六、第二步：优先看低风险、高信息密度证据

Agent 的第一轮工具选择通常会偏保守，优先获取高价值信息：

发布 diff
网关错误日志
Pod 事件
上下游 latency 分布
trace 样本
连接池 / 线程池 / 重试计数

工具返回的关键摘要

系统返回后，Agent 看到几件事：

新版本修改了请求超时配置，从 800ms 改成了 3s
日志里大量出现 upstream timeout
trace 显示大部分耗时卡在 storage-service 请求
网关自身 CPU 正常，线程池没有耗尽
失败请求主要集中在大文件上传接口
某些请求在重试后成功，但整体延迟显著抬高

这说明问题不像是网关完全失效，更像是请求链路中的某个下游阶段被拖慢了。

七、第三步：沿着证据链继续追查，而不是扩大噪声

这是 Agent 最关键的能力之一：

不是看到一个异常就到处乱查，而是沿着最强证据链继续收敛。

当前最强假设

此时，Agent 的最强假设变成：

新版本把网关超时配置放宽了，导致原本应该快速失败的请求在下游等待更久，进一步放大了尾延迟；同时 storage-service 的响应本身也存在波动。

为了验证这个假设，Agent 会继续选择几个关键方向：

查 storage-service 自身延迟
查发布前后超时、重试、连接池配置
查大文件上传请求占比
查 trace 中最慢 span
查是否是特定请求体积触发慢路径

新一轮工具返回

storage-service 的 p95 也同步升高
storage-service 日志中出现大量 S3 read timeout
只有大对象上传请求受影响最明显
新版本在网关层增加了一次内容签名校验
trace 显示签名校验后才发起 storage 请求，整体串行链路更长

这时 Agent 的结论进一步收敛：

网关新版本在发布中引入了额外签名校验和超时配置变化，导致请求链路变长；下游 storage-service 本身也存在短时波动，两者叠加放大了尾延迟。

八、第四步：Agent 判断是"主因"还是"放大器"

生产排障里很重要的一点是：

不要把所有异常都混成一个根因。

更准确的做法是区分：

主因
放大因素
伴随现象

在这个案例里，Agent 可能会这样区分：

主因

网关新版本引入额外签名校验，导致上传请求路径变长
新超时策略使慢请求停留时间过长

放大因素

storage-service 同时有短暂波动
大对象上传集中在高峰时段

伴随现象

5xx 上升
成功率下降
p95 / p99 明显恶化

这种结构化判断，比单纯给出一个"根因是 storage-service"更有工程价值。

九、第五步：Harness 验证结论是否足够可靠

这时候系统不能再让模型无限扩展搜索，而是要进入 Harness 阶段。

Harness 至少做四件事：

1. 验收基线检查

要回答几个关键问题：

证据是否足以支持"发布相关"？
是否存在更强的反证？
是否能解释尾延迟和 5xx 同时上升？
是否能区分主因和放大因素？

2. 边界检查

确认 Agent 不能直接执行高危动作，比如：

不能自动回滚生产
不能修改网关配置
不能关闭监控或绕过校验
不能对外输出未验证结论

3. 反馈闭环

如果证据还不足，继续补查；

如果证据已经足够，强制进入收束。

4. 回退路径

如果模型判断摇摆不定，直接降级为：

输出"不确定，需要人工确认"
给出下一步建议
保存完整调查过程供复盘

十、最终诊断报告应该长什么样

一个好的诊断 Agent，最后输出的不只是"答案"，而是一份可以直接被值班同学使用的报告。

示例输出

故障结论

gateway-api 的上传请求延迟升高，主要由灰度版本引入的签名校验和超时配置变化导致，请求链路变长；同时下游 storage-service 出现短时波动，放大了尾延迟。

关键证据

故障开始时间与灰度时间高度重合
网关新版本引入额外签名校验
上传类请求受影响最明显
trace 显示请求耗时集中在 storage RPC
日志中存在大量 upstream timeout
回滚灰度后指标开始恢复

风险判断

当前故障不表现为完全不可用
但尾延迟和失败率仍可能持续影响用户上传体验
若高峰持续，错误率可能进一步恶化

建议动作

回滚网关灰度版本
临时恢复旧超时配置
对 storage-service 做健康检查
检查是否可以把签名校验前移或缓存化
补充上传链路的关键监控指标

未验证项

是否仅特定文件大小触发慢路径
是否存在个别机房网络抖动
storage-service 波动是否与其他任务竞争资源有关

置信度

这种输出才是生产级 Agent 的价值所在。

十一、为什么这个案例比"普通问答"更难

因为它不是回答一个静态问题，而是在执行一个动态诊断任务。

在这个过程中，Agent 需要同时处理四件事：

理解现象
选择证据
修正假设
及时收束

如果没有良好的上下文工程、Harness 和状态外化，它很容易出现几个问题：

证据太多，反而抓不住重点
初始假设被错误放大
工具结果堆满上下文，后续推理退化
没有回退机制，导致循环浪费成本
报告只有结论，没有证据链

十二、这个案例里的上下文设计怎么做

这种场景尤其适合做分层上下文。

1. 常驻层

放置：

诊断原则
禁止直接操作生产
结论必须有证据链
优先沿发布窗口排查

2. 按需加载层

放置：

部署、网关、存储链路的 Skills
常见故障模式
诊断手册

3. 运行时注入层

放置：

当前告警
服务名
时间窗口
最新发布记录
当前证据摘要

4. 记忆层

放置：

历史事故模式
常见回滚原因
上次类似故障的处理经验

5. 系统层

放置：

工具权限
回滚审批
告警开关
审计日志

这套分层能明显减少 Context Rot，让 Agent 的判断更稳定。

十三、一个可复用的落地模板

如果你要把"云产品部署故障排查 Agent"做成系统，可以直接按下面的模板实现。

阶段一：告警接入

接收告警
自动聚合服务上下文
拉取最近发布和配置变更

阶段二：证据采集

网关日志
下游状态
监控图表
trace 样本
K8s 事件

阶段三：候选假设生成

发布引发性能退化
配置错误
下游波动
网络问题
请求模式变化

阶段四：定向验证

顺着最强假设继续查
排除弱假设
收敛主因与放大因素

阶段五：输出与回退

生成诊断报告
给出止血建议
必要时人工接管
保留完整调查过程

十四、结语：Agent 的价值不是替人判断，而是把判断过程工程化

这个案例说明，真正有用的 Agent，不是"自动说答案"，而是把资深工程师的排障过程拆解成可执行、可验证、可审计的系统流程。

它的价值体现在：

自动收集证据
动态调整排查方向
避免无效试探
形成可复盘的证据链
帮助值班同学更快收敛根因

所以，生产级 Agent 的关键从来不是"更自由"，而是"更可控"。