AI Agent 可观测性：生产环境的监控、日志与链路追踪

引言

当 AI Agent 在生产环境出问题时，第一个问题总是相同的：**发生了什么？**与传统软件不同——传统软件你可以读取栈跟踪和日志——AI Agent 引入了新的复杂性层级：非确定性模型输出、工具调用失败、记忆状态漂移，以及可能在任何环节断裂的多步推理链。

可观测性不仅仅是为了更快地修复 bug。它是信任的基础。能够洞察 Agent 决策过程的团队可以自信地部署；而无法洞察的团队会花数小时调试”它为什么会这样做？”这类问题，而不是构建新功能。

本指南涵盖 AI Agent 可观测性的三大支柱——日志、指标和链路追踪——以及你今天就可以使用的实用实现模式。

—

为什么 AI Agent 需要不同的可观测性

传统应用日志关注请求流程和数据库查询。AI Agent 增加了几个新维度：

如果没有适当的可观测性，你就在盲飞。404 错误很明显；但一次静默幻觉（消耗了 2.50 美元 API 费用并损害了用户信任）则不然。

—

AI Agent 可观测性的三大支柱

1. 结构化日志

结构化日志是 Agent 活动的机器可读记录。与纯文本日志不同，结构化格式（JSON）让你能够大规模查询、过滤和可视化 Agent 行为。

AI Agent 的关键日志模式：

{
  "timestamp": "2026-09-07T10:30:00Z",
  "agent_id": "support-agent-01",
  "session_id": "sess_abc123",
  "event": "tool_call",
  "tool": "search_knowledge_base",
  "input": {"query": "return policy"},
  "output_length": 1247,
  "duration_ms": 342,
  "model": "gpt-4o",
  "tokens_used": {"prompt": 856, "completion": 124, "total": 980}
}

最佳实践：

2. 指标与监控

指标提供高层健康信号。日志告诉你发生了什么，指标告诉你是否正常工作。

关键 Agent 指标：

| 指标 | 显示内容 | 告警阈值 |
|——|———-|———-|
| 每小时 Token 用量 | 成本趋势 | 超过基线 200% |
| 工具调用成功率 | 可靠性 | 低于 95% |
| 响应延迟 P99 | 用户体验 | 交互式 Agent 超过 10s |
| 按类型分类的错误率 | 失败模式 | 出现任何新错误类型 |
| 会话时长分布 | 参与质量 | 双峰分布 |
| 模型回退率 | 基础设施健康 | 回退率超过 10% |

实现方式：

3. 分布式链路追踪

链路追踪跟踪单个请求经过的每一个组件。对于 AI Agent，这意味着跟踪从用户输入到模型推理、工具调用、记忆读取和最终响应的完整旅程。

AI Agent 的追踪结构：

“`
┌─────────────────────────────────────────────────────────────┐
│ Span: user_request (总计 100ms) │
├─────────────────────────────────────────────────────────────┤
│ ├─ Span: model_inference (65ms) │
│ │ ├─ 输入: “我的订单状态是什么？” │
│ │ ├─ 模型: gpt-4o │
│ │ └─ 输出: [思考 tokens] → tool_call │
│ ├─ Span: tool_execution (200ms) │
│ │ ├─ 工具: order_lookup │
│ │ ├─ 输入: {order_id: “ORD-123”} │
│ │ └─ 输出: {status: “已发货”, eta: “2天”} │
│ └─ Span: model_inference (80ms) │
│ ├─ 输入: [上下文 + 工具结果] │
│ └─ 输出: “您的订单已发货…” │
└─────────────────────────────────────────────────────────────┘
“`

Agent 链路追踪工具：

—

实用实现模式

模式 1：可观测性包装器

使用可观测性装饰器包装 Agent 的核心循环，自动捕获：

from functools import wraps
import time
import logging

def with_observability(agent_function):
    @wraps(agent_function)
    def wrapper(*args, **kwargs):
        start_time = time.time()
        session_id = kwargs.get('session_id', generate_id())
        
        log.info({
            "event": "agent_start",
            "session_id": session_id,
            "input": str(kwargs.get('user_input'))[:500]
        })
        
        try:
            result = agent_function(*args, **kwargs)
            
            log.info({
                "event": "agent_complete",
                "session_id": session_id,
                "duration_ms": int((time.time() - start_time) * 1000),
                "output_length": len(result) if result else 0
            })
            return result
            
        except Exception as e:
            log.error({
                "event": "agent_error",
                "session_id": session_id,
                "error_type": type(e).__name__,
                "error_message": str(e)[:500]
            })
            raise
    return wrapper

模式 2：工具调用插桩

每次工具调用都应该被插桩以捕获：

def instrumented_tool_call(tool_name, tool_func):
    @wraps(tool_func)
    def wrapper(*args, **kwargs):
        start = time.time()
        logger.info({
            "event": "tool_start",
            "tool": tool_name,
            "args": sanitize_args(args, kwargs)
        })
        
        try:
            result = tool_func(*args, **kwargs)
            duration = time.time() - start
            
            logger.info({
                "event": "tool_success",
                "tool": tool_name,
                "duration_ms": int(duration * 1000),
                "result_size": len(str(result)) if result else 0
            })
            return result
            
        except Exception as e:
            logger.error({
                "event": "tool_error",
                "tool": tool_name,
                "error": str(e)
            })
            raise
    return wrapper

模式 3：成本跟踪中间件

实现中间件以实时跟踪 API 成本：

class CostTracker:
    def __init__(self):
        self.session_costs = {}
        self.rate_limits = {
            'gpt-4o': {'rpm': 1000, 'tpm': 200000}
        }
    
    def track_usage(self, model, prompt_tokens, completion_tokens):
        session_id = get_current_session()
        cost = calculate_token_cost(model, prompt_tokens, completion_tokens)
        
        if session_id not in self.session_costs:
            self.session_costs[session_id] = {
                'total_cost': 0,
                'token_usage': {'prompt': 0, 'completion': 0},
                'model_counts': {}
            }
        
        self.session_costs[session_id]['total_cost'] += cost
        self.session_costs[session_id]['token_usage']['prompt'] += prompt_tokens
        self.session_costs[session_id]['token_usage']['completion'] += completion_tokens
        
        log_metric('agent_token_cost', cost, {'model': model, 'session': session_id})

—

常见可观测性陷阱

陷阱 1：无过滤地记录一切

问题：记录完整的提示和响应正文会产生大量数据量，并可能暴露敏感信息。

解决方案：实施带 sanitization 的选择性日志记录：

陷阱 2：忽视成本指标

问题：团队专注于功能指标而成本飙升。一个配置错误的 Agent 可以在任何人注意到之前耗尽预算。

解决方案：在多个层级设置成本告警：

陷阱 3：无基线对比

问题：没有上下文的指标只是数字。延迟增加 5% 如果没有基准就无法判断是否正常。

解决方案：在稳定期建立基线并与当前指标对比：

—

构建可观测性仪表板

一个好的可观测性仪表板让你在几秒钟内获得答案，而不是几分钟。以下是应该包含的内容：

顶部区域：健康概览

中部区域：详细指标

底部区域：实时活动

仪表化工具：

—

案例研究：将调试时间减少 80%

一个生产 AI 支持 Agent 存在订单查询失败的反复问题。实施可观测性之前：

实施结构化日志和链路追踪之后：

1. 15 分钟内识别根本原因：某个特定工具有 12% 的概率返回格式错误的 JSON
2. 设置了工具失败自动化告警
3. 创建了会话回放功能以复现问题
4. 将平均解决时间从 4 小时缩短到 15 分钟

可观测性投资在第一周就收回了成本。

—

常见问题

问题 1：如何在多个服务间追踪请求？

使用 OpenTelemetry 分布式链路追踪。在入口点设置 trace ID 并在所有服务调用间传播它。大多数可观测性平台如果在相同标准下被插桩，会自动跨服务关联链路。

问题 2：小团队的最低可观测性配置是什么？

从结构化日志（JSON 格式）和基础指标（Token 数量、错误率、延迟）开始。使用 Langfuse 或 Logtail 等托管服务，如果你不想维护基础设施。这能以 20% 的努力获得 80% 的价值。

问题 3：如何处理日志和链路中的 PII？

实施 sanitization 层：

问题 4：我应该记录完整对话还是仅摘要？

默认记录摘要（每轮前 500 字符）。仅在以下情况启用完整记录：

这在可见性和存储成本之间取得平衡。

问题 5：如何检测 Agent 是否”偏离轨道”？

实施行为监控：

问题 6：监控和可观测性的区别是什么？

监控告诉你何时出问题（基于阈值告警）。可观测性帮助你理解为何出问题（链路追踪、结构化日志、指标关联）。生产可靠性两者都需要。

—

下一步

可观测性不是一次性设置——它是一种持续实践。从基础开始：

1. 第 1 周：为所有 Agent 交互实施结构化日志
2. 第 2 周：添加成本跟踪和基础指标
3. 第 3 周：为关键路径设置分布式链路追踪
4. 第 4 周：构建你的第一个仪表板和告警规则
5. 持续进行：根据事件模式和团队反馈进行优化

目标不是完美的可观测性——而是当你的 Agent 在凌晨 2 点行为异常时，能够回答”发生了什么？”的能力。

准备好让你的 Agent 更可靠了吗？访问 [SmaugBrain](https://www.smaugbrain.com/) 探索内置可观测性的生产就绪 AI Agent 框架。