部署和监控

本单元目标

学完本单元后，你将能够为已构建的 AI Agent 配置结构化日志、设置错误追踪与告警规则，并基于监控指标完成一次线上故障的定位与回滚决策。

概念讲解

当 Agent 从原型走向生产环境，"能跑"与"稳定跑"之间隔着一条由可观测性（Observability）构成的护城河。传统软件监控关注 CPU、内存等基础设施指标，但 Agent 的监控核心是推理链路——即一次用户请求如何经过意图识别、工具调用、上下文组装、模型生成等多个环节。任何一个环节的静默失败（如工具返回超时但 Agent 未报错）都会导致用户体验降级，而日志若不携带 trace_id，你根本无法把分散的日志片段串联成一次完整请求的生命周期。

实践中，你需要三层防护：结构化日志（将 JSON 格式的 event 写入统一管道，而非散落的 print）、链路追踪（为每次请求生成唯一 ID，贯穿所有子调用）、错误追踪与告警（对异常进行聚合去重，而非被日志洪流淹没）。例如，当你的 Agent 调用外部天气 API 失败时，错误追踪系统不仅记录堆栈，还应自动附带当时的模型温度参数、重试次数和上下文窗口占用率——这些才是定位 Agent 行为异常的真正线索。监控的终极目标不是"看到错误"，而是"在用户投诉前看到错误，并知道从哪里下手"。

实操演练

1. 在 Agent 主入口函数中注入 `trace_id` 生成逻辑，使用 `uuid.uuid4()` 创建请求级唯一标识，并通过 `contextvars` 将其传递到所有子函数。
2. 将现有 `print()` 日志全部替换为结构化日志库（如 `structlog` 或 `python-json-logger`），强制输出字段：`timestamp`、`level`、`trace_id`、`event_name`、`duration_ms`。
3. 接入错误追踪服务（如 Sentry），在 Agent 的工具调用装饰器上添加 `@capture_exception`，并设置 `extra` 参数携带模型名称与 token 消耗量。
4. 在追踪服务中配置告警规则：当同一 `trace_id` 下工具调用失败率超过 20% 或单次请求延迟超过 5 秒时，触发 P2 级告警到钉钉/邮件。
5. 部署 Agent 至测试环境，使用脚本模拟 100 次并发请求，在追踪面板中筛选出 `status=error` 的请求，验证能否通过 `trace_id` 完整回溯其推理链路。

练习任务

1. 为你的 Agent 增加一条自定义告警：当模型连续 3 次返回空结果（`content` 为空且未调用工具）时，自动记录当时的完整对话上下文快照，并输出为独立 JSON 文件。
2. 基于上述监控数据，撰写一份 200 字以内的"故障复盘报告"，包含：错误根因、影响范围（基于 trace_id 统计的请求数）、以及你添加的预防性监控指标。