Trace / Span

链路追踪

记录 Agent 每一步调用，方便事后排查。

详解

Trace（链路）是一次完整请求从开始到结束的全程记录，由若干 Span（节点）组成，每个 Span 对应一个具体操作：LLM 调用、工具执行或检索查询。Span 之间有父子关系，形成树状结构。单次 API 调用出错直接看报错就够了，但 Agent 可能经历十几步工具调用，出错时你需要知道：哪一步出了问题、那一步的输入是什么、工具返回了什么——没有 Trace 就像黑盒里摸象。标准化协议是 OpenTelemetry（OTel），2024 年扩展了 `gen_ai.*` 语义规范，定义了模型名、token 数、完成原因等字段；主流框架均有自动埋点插件。每个 Span 至少应记录：时间戳、输入/输出内容、token 消耗、成功/失败状态。

一个类比

就像快递的物流轨迹：「06-24 09:00 揽件 → 06-24 14:00 到达转运中心 → 06-25 08:00 派件中」，每个节点记录了时间和状态。如果包裹没到，你能精确看到卡在哪个环节——不是「不知道在哪里」，而是「从上海转运中心发出后就没有下一条记录了」。Agent 的 Trace 就是这套物流轨迹，每个 LLM 调用和工具执行都是一个打卡节点。

举个例子

# 用 Langfuse 给 Agent 每步操作加 trace（pip install langfuse）
from langfuse import Langfuse
import anthropic

lf = Langfuse()  # 从环境变量读取 LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY
client = anthropic.Anthropic()

def traced_agent_call(user_input: str) -> str:
    # 创建根 Trace（代表这次完整的用户请求）
    trace = lf.trace(name="agent-request", input={"user": user_input})

    # 第一步：LLM 推理（记录为子 Span）
    span_llm = trace.span(name="llm-call", input={"prompt": user_input})
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=256,
        messages=[{"role": "user", "content": user_input}]
    )
    output = resp.content[0].text
    span_llm.end(output={"response": output,
                          "input_tokens": resp.usage.input_tokens,
                          "output_tokens": resp.usage.output_tokens})

    # 关闭根 Trace
    trace.update(output={"final": output})
    return output

result = traced_agent_call("解释什么是上下文窗口")
print(result)
# 登录 Langfuse 控制台即可看到完整调用链、耗时、token 明细

PYTHON 示例