可观测性与追踪

智能体是多轮循环的"黑盒"：它调了哪些模型、选了哪个工具、为什么中途停下来，出了问题全凭猜。可观测性就是给这个黑盒装上仪表盘，让每次运行都可回放、可定位、可优化。

可观测三支柱

支柱	回答的问题	智能体里的体现
日志 Logs	发生了什么	每轮用户输入、模型输出、工具入参出参
指标 Metrics	发生了多少	token 数、调用次数、延迟、错误率、成本
追踪 Traces	一件事的完整链路	一次任务从开始到结束的调用树

普通应用看前三者已足够；智能体最关键是追踪——它把多次模型调用与工具调用串成一条完整链路。

Agent 追踪要记什么

• LLM 调用：模型名、prompt、响应、token 用量与费用；
• 工具调用：工具名、参数、返回摘要、耗时、成败；
• 规划轨迹：思考过程、任务拆解、反思修正；
• 上下文：每次调用实际携带的历史与检索内容。

有了这些，才能回答"哪一步选错了工具、哪一步最贵、为什么绕了远路"。

Langfuse 快速上手

Langfuse 是常用的 LLM 可观测平台，提供云服务也支持自托管：

# 自托管示例（生产请用官方编排与持久化配置，以官方文档为准）
docker run -d --name langfuse -p 3000:3000 langfuse/langfuse

SDK 接入后用装饰器或手动 span 记录关键步骤：

from langfuse import Langfuse

langfuse = Langfuse(public_key="pk-xxx", secret_key="sk-xxx", host="http://localhost:3000")

trace = langfuse.trace(name="order-agent", session_id="s-1001")
span = trace.span(name="tool_search_order")   # 记录一次工具调用
span.update(input={"order_id": 42}, output={"status": "ok"})
trace.update(output={"final": "已找到订单"})

核心概念是父子 span：一次任务是一个 trace（根），其下每次 LLM/工具调用是一个 span（子），子还能再挂子，最终形成一棵树。UI 里展开这棵树，就能看到"先调了谁、后调了谁、卡在哪个节点"。

语义标准化

可观测性生态正向 OpenTelemetry 收敛，其 GenAI 语义约定（semantic conventions）为 LLM 调用、token 用量等定义了统一属性名，便于跨平台分析。相关组件是否支持以官方文档为准。

小结

日志、指标、追踪三支柱里，追踪对智能体最关键：把 LLM 调用、工具调用、规划轨迹与成本记录成父子 span 的 trace 树。用 Langfuse 这类平台自托管或云接入，配合 OpenTelemetry 标准语义，即可把"黑盒智能体"变成可回放可定位的系统。