AI Agent / 系统课时
设计日志与可观测性
设计日志与可观测性
本篇解决 Agent 运行过程不可追踪、问题难定位的问题。通过设计统一的运行标识、步骤记录、模型与工具调用日志,让一次 Agent 执行可以被还原、分析和优化。
学习目标
- 理解 Agent 可观测性的核心数据组成
- 设计 runId、stepId 与调用链日志结构
- 建立支持调试、评测和性能分析的日志方案
为什么 Agent 需要专门的可观测性设计
传统应用通常通过请求日志定位问题,而 Agent 的一次任务执行往往包含多轮推理、模型调用、工具选择和状态变化。如果只记录最终结果,就无法知道 Agent 为什么做出某个决策,也无法判断失败发生在哪一步。
Agent 日志需要回答几个关键问题:一次运行是什么?当前执行到哪个步骤?调用了哪个模型和工具?消耗了多少资源?失败原因是什么?这些信息共同组成 Agent 的运行轨迹。
设计核心日志模型
一个完整 Agent 运行通常使用多层标识关联数据。
runId 标识一次完整任务执行,例如用户提交一个自动生成报告的请求;stepId 标识运行中的具体步骤,例如一次规划、检索或工具调用。
推荐将日志拆分为运行级、步骤级和调用级三类:
| 层级 | 主要字段 | 用途 |
|---|---|---|
| Run | runId、用户任务、开始时间、结束时间、状态 | 查看完整执行过程 |
| Step | stepId、父步骤、类型、耗时 | 分析 Agent 行为链路 |
| Call | 模型、工具、Token、错误 | 优化具体调用 |
一次典型调用链可以表示为:

记录模型与工具调用信息
模型调用日志不仅需要保存请求时间和结果,还需要记录影响成本与质量的数据。
python
from dataclasses import dataclass
from time import time
@dataclass
class ModelCallLog:
model: str
prompt_tokens: int
completion_tokens: int
latency_ms: int
# 创建一次模型调用记录
log = ModelCallLog(
model="gpt-model",
prompt_tokens=1200,
completion_tokens=350,
latency_ms=800
)
print(log)预期输出
text
ModelCallLog(model='gpt-model', prompt_tokens=1200, completion_tokens=350, latency_ms=800)工具调用还需要额外记录参数摘要、执行结果和异常信息,避免只看到“工具失败”却无法复现问题。
用日志支持调试与优化
完成日志设计后,可以基于数据分析 Agent 表现:
- 根据 Token 消耗发现高成本步骤
- 根据耗时定位慢工具或慢模型调用
- 根据错误分类优化提示词和重试策略
- 根据完整轨迹评估 Agent 决策质量
生产环境中通常不会直接保存全部敏感输入,而是保存必要摘要,并对用户数据、密钥和业务字段进行脱敏处理。
本课总结
- Agent 可观测性的核心是建立完整运行轨迹,而不是简单打印输出。
- runId、stepId 和调用日志共同组成可分析的执行链路。
- 高质量日志能够支持调试、评测、成本控制和性能优化。
下一课预告
下一课将搭建完整 Agent 工程骨架,把核心模块拆分为可维护的工程结构,并验证最小端到端运行链路。
按自己的节奏,确认真正理解。