可观测性与监控

概述

AI Agent系统的可观测性（Observability）比传统软件更具挑战性。Agent的非确定性行为、多步骤执行、外部工具调用等特征使得调试和监控变得复杂。本节介绍Agent专用的可观测性工具和最佳实践。

可观测性三支柱

graph TD
    A[Agent可观测性] --> B[追踪 Tracing]
    A --> C[指标 Metrics]
    A --> D[日志 Logging]

    B --> B1[端到端执行链路]
    B --> B2[每步LLM调用详情]
    B --> B3[工具调用追踪]

    C --> C1[延迟分布]
    C --> C2[Token使用量]
    C --> C3[成功率/错误率]

    D --> D1[Agent推理过程]
    D --> D2[工具输入输出]
    D --> D3[错误堆栈]

    style A fill:#e3f2fd

专用追踪工具

LangSmith

LangChain 官方的追踪和评估平台：

核心功能：

功能	说明
Tracing	完整的Agent执行链路可视化
Evaluation	自定义评估器，批量评测
Datasets	管理测试数据集
Monitoring	生产环境实时监控
Playground	在线调试提示和Agent

追踪数据结构：

# LangSmith自动追踪Agent执行
from langsmith import traceable

@traceable(name="agent_task")
def run_agent(task):
    # 每个LLM调用、工具调用自动记录
    plan = llm.plan(task)         # → trace: planning
    for step in plan:
        result = tool.execute(step)  # → trace: tool_call
        feedback = llm.reflect(result)  # → trace: reflection
    return final_result

追踪信息包含：

输入/输出的完整内容
Token使用量（输入/输出/总计）
延迟（首token时间、总时间）
模型和参数信息
父子关系（调用链）

Langfuse

开源的LLM可观测性平台：

特点：

完全开源，支持自托管
兼容OpenAI、Anthropic、LangChain等
提供Web UI进行追踪分析
支持自定义评分和标注

from langfuse import Langfuse

langfuse = Langfuse()

# 创建追踪
trace = langfuse.trace(name="agent_run", user_id="user_123")

# 记录LLM调用
generation = trace.generation(
    name="planning",
    model="claude-sonnet-4-20250514",
    input=messages,
    output=response,
    usage={"input": 1500, "output": 300}
)

# 记录工具调用
span = trace.span(
    name="web_search",
    input={"query": "AI agents 2024"},
    output={"results": [...]}
)

其他工具

工具	类型	特点
Arize Phoenix	开源	可视化强，支持embedding分析
Helicone	SaaS	代理层，零代码集成
Portkey	SaaS	多模型网关 + 监控
Braintrust	SaaS	评估 + 监控

OpenTelemetry for Agents

Agent追踪标准

将OpenTelemetry标准扩展到Agent系统：

from opentelemetry import trace

tracer = trace.get_tracer("agent-service")

def agent_step(task):
    with tracer.start_as_current_span("agent_step") as span:
        span.set_attribute("agent.step_number", step_num)
        span.set_attribute("agent.model", "claude-sonnet")

        # LLM调用
        with tracer.start_as_current_span("llm_call") as llm_span:
            llm_span.set_attribute("llm.model", model_name)
            llm_span.set_attribute("llm.tokens.input", input_tokens)
            llm_span.set_attribute("llm.tokens.output", output_tokens)
            response = call_llm(prompt)

        # 工具调用
        with tracer.start_as_current_span("tool_call") as tool_span:
            tool_span.set_attribute("tool.name", tool_name)
            tool_span.set_attribute("tool.success", True)
            result = call_tool(tool_name, params)

语义约定

Agent系统的OpenTelemetry语义约定（提案中）：

属性	说明
`gen_ai.system`	AI系统（openai, anthropic）
`gen_ai.request.model`	请求的模型名
`gen_ai.usage.input_tokens`	输入token数
`gen_ai.usage.output_tokens`	输出token数
`gen_ai.agent.step`	Agent步骤编号
`gen_ai.tool.name`	使用的工具名

关键监控指标

核心指标

指标	计算方式	告警阈值（示例）
P50/P95/P99延迟	响应时间百分位	P95 > 30s
Token使用量	每任务总token	> 100K tokens
错误率	失败数/总数	> 5%
任务完成率	成功数/总数	< 90%
每任务成本	总费用/任务数	> $1.00
工具调用次数	每任务平均调用	> 20次
缓存命中率	命中数/总请求数	< 50%

业务指标

指标	说明
用户满意度	CSAT评分
任务回避率	Agent拒绝处理的比例
人工接管率	需要转人工的比例
重复任务率	相同任务重复提交的比例

告警策略

分级告警

graph TD
    A[监控指标] --> B{异常检测}
    B -->|轻微| C[Info日志]
    B -->|中度| D[Warning通知]
    B -->|严重| E[Critical告警]
    B -->|紧急| F[Emergency处理]

    C --> G[记录]
    D --> H[Slack通知]
    E --> I[PagerDuty告警]
    F --> J[自动熔断 + 紧急通知]

异常检测

\[ \text{Anomaly Score}(x) = \frac{|x - \mu|}{\sigma} \]

当分数超过阈值（如 $3\sigma$）时触发告警。

智能告警

趋势告警：指标持续恶化时提前告警
关联告警：多个指标同时异常时合并告警
自适应阈值：基于历史数据自动调整阈值
告警收敛：避免告警风暴

日志聚合

结构化日志

import structlog

logger = structlog.get_logger()

def agent_step(task_id, step_num, action):
    logger.info(
        "agent_step_executed",
        task_id=task_id,
        step_num=step_num,
        action=action.type,
        tool=action.tool_name,
        input_tokens=action.input_tokens,
        output_tokens=action.output_tokens,
        latency_ms=action.latency_ms,
        success=action.success,
    )

日志级别设计

级别	内容	频率
DEBUG	完整的LLM输入输出	开发环境
INFO	步骤摘要和关键决策	生产环境
WARNING	重试、降级、异常	始终开启
ERROR	失败、异常终止	始终开启

实践建议

从追踪开始：先实现完整的执行链路追踪
关注成本：成本监控应该是首要关注的指标
区分环境：开发环境记录更详细，生产环境适度精简
保护隐私：日志中脱敏用户敏感信息
定期审查：定期检查监控数据，发现优化机会

参考文献

LangChain. "LangSmith Documentation." 2024.
Langfuse. "Open Source LLM Engineering Platform." 2024.
OpenTelemetry. "Semantic Conventions for GenAI." 2024.

交叉引用： - 成本监控 → 成本优化与缓存 - 可靠性指标 → 可靠性与鲁棒性