Agent 上线检查清单：日志、监控、告警、回滚和灰度发布

周五下午,你准备把客服 Agent 开给 5% 用户,灰度参数都配好了:流量比例、观察窗口、告警阈值。最后检查时发现三个问题:

1. 没有 feature flag,只能重新部署才能关闭
2. 不知道如何把人工审批队列里的任务切回旧版本
3. 不确定已发送的邮件算不算工具副作用,回滚要不要撤回

这三个问题,都不是 HTTP 500 或响应时间能告诉你的。Agent 上线要比 Web 服务多看八个维度:trace、tool calls、guardrails、HITL、eval、cost、secrets、checkpoint。本文把这八个维度串成四组清单:发布前门禁、灰度观察、发布后监控、事故回滚。

一、发布前门禁:十个必须通过的检查点

1.1 Trace 完整性检查

发布前必须确认 trace 能还原一次完整的 Agent run,否则事故时无法复盘。OpenAI Agents SDK 内置 tracing,记录 LLM generations、tool calls、handoffs、guardrails 和 custom events,但这些信息能否在生产环境中完整留存,需要逐项检查。

检查清单:

• run ID、trace ID、span ID 是否正确关联,能从错误日志追溯到具体请求
• model call、tool call、guardrail result 是否完整记录,没有缺失字段
• 耗时、token 使用量、错误码字段是否可用,能算出成本和性能基线
• trace 保留策略和脱敏规则是否明确,不会因为存储成本或合规风险删除
• 开发环境与生产环境的 trace 导出行为是否一致

如果 trace 只记录了 LLM call,没有 tool call 或 guardrail result,灰度时看到 HTTP 200,其实可能工具参数错了或权限越界了。

1.2 敏感数据脱敏策略

生产环境 trace 可能包含 PII、secret、客户数据,上线前必须决定捕获策略和脱敏策略。OpenAI Agents SDK 提供 trace_include_sensitive_data 配置,控制是否记录 LLM 和 tool call 的完整输入输出。

检查清单:

• trace_include_sensitive_data 配置位置和默认值是否明确
• PII 检测与脱敏规则是否覆盖姓名、邮箱、手机号等常见字段
• Secret 隔离是否到位,API key、数据库密码不会出现在 trace 或日志中
• 客户数据是否按公开/内部/机密分级,不同级别的脱敏策略有差异
• 脱敏后的 trace 是否仍可用于调试

生产环境建议使用自动 PII 检测 + 分级脱敏,既满足合规要求,又能保留调试能力。

1.3 Guardrails 监控门禁

guardrails 用于校验用户输入和 agent 输出,可用较快或便宜的模型拦截不合规请求。OpenAI Agents SDK 的 tool input guardrail 在函数工具调用前运行。但 guardrails 不是绝对防线,发布前必须确认它是可观测、可告警、可回滚的。

检查清单:

• input guardrail 拦截率基线是否已测定
• output guardrail 误杀率/漏杀率是否已知
• tool input guardrail 是否在工具调用前运行
• guardrail trip 告警阈值是否配置
• false positive 快速反馈路径是否畅通

guardrails 监控门禁的要求是:拦截率要有基线,误杀要有反馈,告警要有阈值。

1.4 Tool Calls 可观测性

工具调用失败是 Agent 最常见的失败模式。HTTP 接口可能返回 200,但工具参数错了、权限越界了、外部服务超时了。这些失败在普通服务监控里看不到,只在 trace 里有记录。

检查清单:

• 每个工具的成功率/失败率基线是否已测定
• 工具调用延迟分布(P50/P95/P99)是否已知
• 权限边界是否明确,哪些工具可调用哪些资源有白名单或黑名单
• 失败模式分类是否完整,超时/权限/参数错误/外部服务故障有不同处理策略
• 重试策略和熔断阈值是否配置

工具可观测性要求:每个工具都有成功率基线,失败有分类,超时有熔断。

1.5 HITL 队列监控准备

人工审批队列(Human-in-the-Loop, HITL)堆积是灰度时容易被忽略的风险。LangGraph checkpointers 在每个 super-step 保存 graph state,支持 HITL、time travel、fault tolerance,但队列长度和审批超时需要单独监控。

检查清单:

• HITL 队列长度告警阈值是否配置
• 审批超时自动处理策略是否明确,拒绝/转人工/降级有明确规则
• 中断后 resume 路径是否已验证
• 新版本切换时队列中的任务如何处理

HITL 队列监控的要求是:队列长度有阈值,超时有策略,中断能恢复。

1.6 Eval Regression Suite

发布前必须跑自有 regression suite,防止能力退化。regression suite 应包含真实任务,而不是只用 synthetic examples。如果回归通过率低于基线,说明新版本可能有问题,不应上线。

检查清单:

• regression suite 包含的真实任务数量是否足够
• 通过率基线是否明确(建议 ≥95%)
• 失败用例分类是否清晰
• suite 运行时间是否可控(建议 ≤15 分钟)
• 灰度失败样本回灌机制是否准备好

regression suite 是最后一道门禁。如果通过率低于 95%,建议先修复再上线。

1.7 Cost Budget 与 Rate Limit

平台级费用边界和速率限制是最后一道防线。OpenAI 官方建议配置 usage tracking、billing limits、notification threshold、项目级 spend/rate limits,不应只依赖业务代码里的预算判断。

检查清单:

• 项目级 spend limit 是否配置
• usage notification threshold 是否设置(建议 70%/90%)
• rate limit 是否按用户/租户分级
• 成本突增告警是否配置(按小时环比)
• 降级策略是否明确,超预算时关闭高成本工具/切换模型/限制用户

Cost Budget 的要求是:预算有上限,告警有阈值,超限有降级。

1.8 Secrets 隔离与审计

密钥泄露是 Agent 最严重的安全事故。Agent 可能通过工具调用访问数据库、第三方 API、内部服务,每个调用都需要审计。actor/subject/tool/resource 四个字段必须完整记录。

检查清单:

• actor/subject/tool/resource 完整字段是否记录
• 密钥存储是否隔离,API key、数据库密码不会出现在环境变量或配置文件中
• 工具调用前密钥验证是否执行
• 审计日志保留周期是否明确(建议 1 年)
• 密钥轮换计划是否制定

审计日志是事故复盘的重要依据。

1.9 Checkpoint 恢复验证

长任务 Agent 失败后必须能恢复到正确状态。LangGraph checkpointers 在每个 super-step 保存 graph state,支持 time travel debugging 和 fault-tolerant execution,但恢复路径需要单独测试。

检查清单:

• checkpoint 保存频率是否明确,每个 super-step 或每个重要节点都有保存
• 失败后恢复测试是否已执行
• 恢复后状态正确性是否验证
• 半完成任务清理策略是否明确

Checkpoint 恢复是长任务 Agent 的基础能力。

1.10 Feature Flag 与 Kill Switch

必须能不重新部署就关闭 Agent。OpenFeature 提供标准的 feature flag 实现,支持按 tenant、用户、任务类型分级,以及百分比分流。

检查清单:

• feature flag 是否按 tenant/用户/任务类型分级
• kill switch 是否能在 1 分钟内生效
• 百分比分流是否支持,能用于灰度发布
• flag 状态监控和审计是否配置

Feature Flag 的要求是:分级控制、快速生效、状态审计。

二、灰度观察:前 10-30 分钟看什么

发布前门禁通过了,不代表灰度时不会出问题。Agent 灰度要比普通服务多看两层指标:服务指标(HTTP 错误率、响应时间)和 Agent 指标(tool failure rate、guardrail trip rate、cost per run、HITL queue)。

2.1 流量比例与观察窗口

灰度不能凭感觉。Kubernetes 和 AWS 都建议从小流量开始,设置足够评估期,监控指标后再逐步扩大。流量比例和时间参数需要明确定义。

检查清单:

• 初始流量比例是否明确(建议 5-10%)
• 最小观察窗口是否设置(建议 10-30 分钟)
• 观察窗口内请求数量下限是否配置
• 逐步扩大流量的条件是否定义

流量比例和观察窗口是灰度的基础参数。如果 5% 流量在 10 分钟内就触发告警,说明新版本有严重问题,应立即回滚。

2.2 服务指标监控

HTTP 错误率、响应时间、吞吐是灰度第一层指标,普通服务上线也会看这些。但如果只看第一层,可能漏掉 Agent 特有的失败模式。

检查清单:

• HTTP 5xx 错误率阈值是否配置(建议 ≤1%)
• 响应时间 P95 阈值是否明确
• 吞吐量环比变化是否监控
• CPU/内存使用率是否监控
• 网络错误率是否监控

服务指标是第一层防线,但不是全部。Agent 可能 HTTP 200,但工具调用失败、guardrail 被绕过、成本突增。

2.3 Agent 指标监控

Agent 特有指标是灰度第二层,也是普通服务监控不会覆盖的维度。这些指标在 trace 里才有记录,HTTP log 里看不到。

检查清单:

• tool failure rate 是否按工具分类监控
• guardrail trip rate 是否按类型分类监控
• cost per run 是否环比监控
• HITL 队列长度是否实时监控
• eval drift 是否可选监控

Agent 指标监控的要求是:按工具和类型分类,而不是看平均值。

2.4 告警条件与自动回滚

灰度必须能自动回滚,不能只靠人工盯屏。AWS 文档建议用 CloudWatch alarms 触发自动回滚,定义明确的触发条件和回滚路径。

检查清单:

• 自动回滚触发条件是否定义
• 回滚后流量切换路径是否明确
• 回滚后观察窗口是否设置
• 人工确认与升级流程是否定义

自动回滚的要求是:触发条件明确、回滚路径清晰、人工确认必要。

三、发布后持续监控:不能只看上线那一刻

灰度通过不等于生产就绪。发布后需要持续监控 trace 质量、成本使用、guardrails 效果和 eval 回归,防止能力退化或成本突增。

3.1 Trace 质量监控

发布后 trace 可能丢失、延迟、字段缺失,影响事故复盘和调试能力。trace 质量监控要独立于服务指标监控。

检查清单:

• trace 完整性是否监控,run ID 关联度低于基线应告警
• trace 延迟是否监控,写入到可查询的时间超过阈值应告警
• trace 采样率是否配置,高流量时降采样减少存储成本
• trace 存储成本是否监控

Trace 质量监控的要求是:完整性有基线、延迟有阈值、成本有预算。

3.2 Cost 与 Usage 持续监控

成本突增是 Agent 最常见的生产事故。token 使用异常、模型滥用、工具调用频率突增,都可能导致成本爆炸。OpenAI 官方建议配置 usage tracking 和 notification threshold。

检查清单:

• 每日 cost 趋势是否监控,环比/同比都能发现异常
• token 使用量是否按模型/按用户监控
• 高成本工具是否识别
• cost 预算消耗速率是否监控
• 超预算自动熔断是否配置

Cost 监控的要求是:趋势有对比、模型有分类、预算有熔断。

3.3 Guardrails 持续监控

guardrail 拦截率变化可能意味着攻击或误杀。input guardrail 拦截率升高可能是恶意 prompt 增加,output guardrail 误杀率升高可能是规则太严格。

检查清单:

• input guardrail 拦截率趋势是否监控
• output guardrail 误杀率是否监控
• guardrail false positive/negative 反馈收集是否完善
• 定期评估 guardrails 规则是否执行

Guardrails 监控的要求是:拦截率有趋势、误杀有反馈、规则有更新。

3.4 Eval 持续回归

发布后需要持续验证能力没有退化。每日或每周运行 regression suite,失败用例自动告警,新失败用例加入 suite。

检查清单:

• 每日/每周 regression suite 运行是否自动化
• 失败用例是否自动告警
• 新失败用例是否加入 suite
• regression suite 版本管理是否完善

Eval 回归的要求是:定期运行、失败告警、用例回灌。

四、事故回滚:最难的是工具副作用

Agent 回滚比普通服务复杂。普通服务回滚代码版本就够了,Agent 回滚还要处理已执行的工具副作用、半完成的 workflow、人工审批队列里的任务。

4.1 代码回滚

代码回滚是最简单的回滚方式。Kubernetes Deployment 支持 rolling update 和 rollback,但回滚窗口要控制在 5 分钟内。

检查清单:

• 代码版本回滚路径是否明确
• 回滚后流量切换是否验证
• 回滚后验证(smoke test)是否执行
• 回滚窗口是否设置(建议 ≤5 分钟)

代码回滚的要求是:路径明确、切换验证、窗口限制。

4.2 工具副作用回滚

Agent 最难回滚的是已执行的工具副作用。发送邮件、创建订单、调用外部 API,这些操作不会因为代码回滚就撤销。需要区分幂等操作和非幂等操作,设计补偿动作。

检查清单:

• 已执行工具操作是否识别,trace 里能找到所有已执行的工具调用
• 幂等性操作是否可重复执行
• 非幂等操作是否有补偿动作,发送撤回邮件/取消订单/调用撤销 API
• 半完成任务清理策略是否明确
• 人工兜底流程是否定义

工具副作用回滚的要求是:识别已执行操作、判断幂等性、设计补偿动作。

4.3 HITL 队列清理

回滚时人工审批队列可能留下半完成任务。新版本 Agent 可能把任务升级成 HITL,回滚后旧版本可能不需要人工审批,队列中的任务需要重新分配或回退。

检查清单:

• 队列中任务是否识别(按版本标签)
• 任务重新分配策略是否明确
• 审批超时处理是否定义
• 人工确认流程是否完善

HITL 队列清理的要求是:按版本识别、有重新分配策略、超时有处理。

4.4 Trace 与 Audit 日志保留

事故后复盘需要完整的 trace 和审计日志。OpenTelemetry 将 logs 作为 telemetry signals 之一,可与现有 logging frameworks 集成。

检查清单:

• trace 保留周期是否明确(建议 30-90 天)
• 审计日志保留周期是否明确(建议 1 年)
• 敏感数据脱敏规则是否完善
• 合规性要求是否满足(按行业)

Trace 与 Audit 保留的要求是:周期满足需求、脱敏规则完善、合规性达标。

4.5 失败样本回灌 Eval Suite

事故后需要把失败样本加入 regression suite,防止同类事故再次发生。样本提取需要从 trace 里找到失败 case,人工标注失败原因和预期行为。

检查清单:

• 失败样本提取是否有工具或脚本
• 样本标注是否有人工确认
• 加入 regression suite 是否有流程
• 防止同类事故再次发生是否有机制

失败样本回灌的要求是:提取有工具、标注有人工、加入有流程、验证有修复。

结论

Agent 上线要比普通 Web 服务多看八个维度:trace、tool calls、guardrails、HITL、eval、cost、secrets、checkpoint。这八个维度串成四组清单:

发布前门禁(10个检查点):Trace 完整性、敏感数据脱敏、Guardrails 监控、Tool Calls 可观测性、HITL 队列准备、Eval Regression Suite、Cost Budget 与 Rate Limit、Secrets 隔离与审计、Checkpoint 恢复验证、Feature Flag 与 Kill Switch。发布前逐项勾选,不通过的不能上线。

灰度观察(4个检查点):流量比例与观察窗口、服务指标监控、Agent 指标监控、告警条件与自动回滚。灰度不只是看 HTTP 错误率,还要看 tool failure rate、guardrail trip rate、cost per run、HITL queue length。

发布后监控(4个检查点):Trace 质量监控、Cost 与 Usage 持续监控、Guardrails 持续监控、Eval 持续回归。灰度通过不等于生产就绪,需要持续监控防止能力退化或成本突增。

事故回滚(5个检查点):代码回滚、工具副作用回滚、HITL 队列清理、Trace 与 Audit 日志保留、失败样本回灌 Eval Suite。回滚不只是回滚代码版本,还要处理已执行的工具副作用、半完成的 workflow、人工审批队列。

建议把这四组清单存为模板,每次发布前逐项勾选。如果某个检查点不通过,先修复再上线,而不是带着已知问题灰度。