agent-observability

用途

生产环境中的智能体（Agent）失败方式与普通服务不同：错误的工具调用、幻觉参数、失控循环、静默的质量回退。本技能用于为 LLM 智能体添加可观测性，通过追踪（traces）、指标（metrics）和回放（replay），让失败可被观察，而不是仅靠猜测。

何时使用

智能体在开发环境正常，在生产环境出错，且没有日志能解释原因
需要将提示词/模型变更与基线进行对比（eval-in-trace）
token/延迟成本持续增长，但不知道是哪个节点造成的
用户报告了糟糕的回答，需要回放确切的会话
存在多个智能体/子智能体，需要单一的追踪树，而不是交错的日志

平台选择

后端	选择时机	托管方式
LangSmith	使用 LangChain/LangGraph 技术栈，希望托管方案	SaaS
Langfuse	需要开源、自托管、多框架支持	SaaS 或自托管
Arize Phoenix	需要 OTel 原生、嵌入/评估漂移、开源优先	本地或自托管

默认建议：需要自托管时选 Langfuse；已在使用 LangGraph 时选 LangSmith；强制要求 OTel 时选 Phoenix。

埋点模式（节点级 span）

# LangGraph + Langfuse
from langfuse.decorators import observe
from langfuse.openai import openai  # auto-traces tool calls

@observe(name="planner_node")
def planner(state):
    return {"plan": llm.invoke(state["task"])}

@observe(name="tool_executor")
def tool_executor(state):
    return {"observation": run_tool(state["action"])}

必需的 span 属性：

input / output（完整，不截断）
model、temperature、max_tokens
tool_name、tool_args、tool_result_status
tokens_in、tokens_out、cost_usd
session_id、user_id、trace_id

Eval-in-trace（追踪内评估）

将自动评分器附加到每个 span，使质量回退与延迟在同一界面中呈现：

from langfuse import Langfuse
langfuse = Langfuse()
langfuse.score(
    trace_id=trace_id,
    name="answer_correctness",
    value=0.92,
    comment="LLM-as-judge vs golden"
)

常见评分项：correctness、tool_call_validity、groundedness、harm、latency_sla。

回放模式

在每个节点入口/出口记录完整状态（Langfuse：metadata={"state": state}）
收到 bug 报告时，按 trace_id 获取追踪
重建状态，从任意节点重新运行——对比输出差异

规模化采样

错误/HITL 路径 100% 追踪
正常路径 10% 采样
对延迟超过 p95 的 span 使用尾部采样
始终记录：工具失败、护栏拦截、预算上限触发

技能介绍

用途