智能体运行的可观测性与日志

你无法改进你看不到的东西。智能体上线后,可观测性就是你的"眼睛"。

传统软件的运行是确定性的:同样的输入产生同样的输出,出错时看日志就能定位。智能体不同:同样的输入可能产生不同的输出,错误可能是"输出合理但不对"而非报错。这种不确定性让可观测性变得更加重要,也更加困难。

可观测性的三个支柱

支柱	回答的问题	实现方式
日志(Logging)	发生了什么?	记录每次调用的输入输出
指标(Metrics)	整体表现如何?	聚合统计关键数值
追踪(Tracing)	问题出在哪一步?	贯穿完整调用链路

三者配合,才能从宏观到微观全面掌握智能体的运行状况。

日志该记什么

智能体的日志与传统软件不同,需要记录更多"语义"层面的信息。

每次模型调用的记录

{
  "timestamp": "2026-08-19T10:23:45Z",
  "session_id": "sess_abc123",
  "user_id": "user_456",
  "model": "claude-sonnet-4",
  "system_prompt_hash": "a1b2c3d4",
  "messages_count": 8,
  "input_tokens": 2340,
  "output_tokens": 580,
  "tools_available": ["search", "calculator"],
  "tools_called": [{"name": "search", "params": {"q": "AI配音"}}],
  "latency_ms": 3200,
  "status": "success",
  "finish_reason": "tool_use"
}

每次工具调用的记录

{
  "timestamp": "2026-08-19T10:23:46Z",
  "session_id": "sess_abc123",
  "tool_name": "search",
  "input_params": {"q": "AI配音"},
  "output_summary": "返回10条结果",
  "output_tokens_estimate": 1500,
  "latency_ms": 800,
  "status": "success"
}

注意:不要把完整的工具输出记入日志(可能包含用户数据且体量巨大),记摘要即可。如果需要完整输出,单独存储并关联ID。

用户交互记录

{
  "session_id": "sess_abc123",
  "user_message": "帮我查一下最近的AI配音工具",
  "agent_response_summary": "推荐了5款AI配音工具",
  "user_feedback": null,
  "turns_in_session": 4,
  "session_duration_s": 45
}

关键指标

质量指标

• 任务完成率:用户会话中成功完成任务的占比。
• 用户满意度:用户主动反馈(点赞/点踩)的比例。
• 人工接管率:智能体转人工的频率。高接管率说明智能体能力不足。
• 重复提问率:用户对同一问题重复提问的频率。高重复率说明首次回答不满意。

性能指标

• 首字延迟(TTFT):用户发出消息到收到第一个字的平均时间。
• 轮次延迟:单轮对话的平均响应时间。
• 工具调用延迟:各工具的平均执行时间。
• 总任务时间:从用户开始到任务完成的端到端时间。

成本指标

• 单会话Token消耗:每个用户会话平均消耗的token数。
• 单任务API费用:每个任务的平均API调用成本。
• 工具调用成本:外部API的调用费用。
• 成本趋势:日/周/月的成本变化趋势。

安全指标

• 提示注入检测次数:被识别为注入攻击的输入数量。
• 越权尝试次数:智能体尝试执行超权限操作的次数(应为0)。
• 内容安全拦截次数:输出被内容安全过滤拦截的次数。

链路追踪

多步任务中,一个用户请求可能触发多次模型调用和工具调用。链路追踪把整个过程串联起来:

[用户请求] 帮我分析这篇文章的SEO问题
  │
  ├─ [模型调用 #1] 分析用户意图 → 决定调用read_article工具
  │   ├─ [工具调用] read_article("article_123") → 3200字内容
  │   └─ 耗时: 1.2s | Token: 3500入+120出
  │
  ├─ [模型调用 #2] 分析文章内容 → 决定调用seo_check工具
  │   ├─ [工具调用] seo_check(content) → SEO报告
  │   └─ 耗时: 2.1s | Token: 4200入+280出
  │
  └─ [模型调用 #3] 综合分析 → 生成最终建议
      └─ 耗时: 1.8s | Token: 3800入+450出

总耗时: 5.1s | 总Token: 15850 | 状态: 成功

有了链路追踪,当用户反馈"太慢了"或"回答不对"时,可以快速定位是哪个环节的问题:是工具调用慢?还是某次模型调用的输出质量差?

日志分析实践

常见分析场景

性能瓶颈定位:按耗时排序Top 10的会话,分析哪类任务最慢、慢在哪个环节。

质量回归排查:对比本周和上周的任务完成率,如果下降,查看新引入的失败模式。

成本异常调查:单日成本突然上升,按用户/任务类型/模型维度拆解,找到成本增长源。

安全事件审计:筛选被标记为疑似注入的对话,人工复核是否有实际攻击。

日志保留策略

• 最近7天:完整日志,包含详细输入输出,用于实时排查。
• 7-30天:摘要日志,只保留关键指标和错误记录,用于趋势分析。
• 30天以上:只保留聚合统计,用于长期报告。

合理的保留策略既满足排查需求,又控制存储成本。涉及用户隐私的日志要按合规要求处理。

可观测性不是为了"记录一切",而是为了"在需要时能看到需要的信息"。日志和监控的设计应该从"我要解决什么问题"出发,而不是盲目地全量记录。