AI Agent / 系统课时

设计日志与可观测性

设计日志与可观测性

本篇解决 Agent 运行过程不可追踪、问题难定位的问题。通过设计统一的运行标识、步骤记录、模型与工具调用日志,让一次 Agent 执行可以被还原、分析和优化。

学习目标

  • 理解 Agent 可观测性的核心数据组成
  • 设计 runId、stepId 与调用链日志结构
  • 建立支持调试、评测和性能分析的日志方案

为什么 Agent 需要专门的可观测性设计

传统应用通常通过请求日志定位问题,而 Agent 的一次任务执行往往包含多轮推理、模型调用、工具选择和状态变化。如果只记录最终结果,就无法知道 Agent 为什么做出某个决策,也无法判断失败发生在哪一步。

Agent 日志需要回答几个关键问题:一次运行是什么?当前执行到哪个步骤?调用了哪个模型和工具?消耗了多少资源?失败原因是什么?这些信息共同组成 Agent 的运行轨迹。

设计核心日志模型

一个完整 Agent 运行通常使用多层标识关联数据。

runId 标识一次完整任务执行,例如用户提交一个自动生成报告的请求;stepId 标识运行中的具体步骤,例如一次规划、检索或工具调用。

推荐将日志拆分为运行级、步骤级和调用级三类:

层级 主要字段 用途
Run runId、用户任务、开始时间、结束时间、状态 查看完整执行过程
Step stepId、父步骤、类型、耗时 分析 Agent 行为链路
Call 模型、工具、Token、错误 优化具体调用

一次典型调用链可以表示为:

Agent运行日志链路结构图

记录模型与工具调用信息

模型调用日志不仅需要保存请求时间和结果,还需要记录影响成本与质量的数据。

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 工程骨架,把核心模块拆分为可维护的工程结构,并验证最小端到端运行链路。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计日志与可观测性

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通