LangSmith 01：追踪——让 Agent 运行过程可见

#1、本篇任务：从一次错误回答找到具体失败步骤

应用日志常只告诉你请求失败；Agent 却可能在路由、检索、工具、模型或输出校验任一层出错。LangSmith Trace 用父子 run 记录完整调用树，使一次用户请求可以沿步骤检查。

本课为退款助手建立 support_run → retrieve/order/tool → compose 的追踪层级。

#2、Run 与 Trace 的关系

一个 run 表示一个工作单元，多个父子 run 组成 trace：

复制support_run
  ├─ classify_intent
  ├─ retrieve_policy
  │    └─ rerank
  ├─ get_order
  └─ compose_answer
       └─ model_call

根 run 对应用户可见结果；子 run 对应可独立计时、失败和评测的步骤。不要把每次字符串拼接都追踪，也不要只追踪最终模型调用。

#3、LangChain/LangGraph 自动追踪

配置 LangSmith 环境变量并启用 tracing 后，LangChain 模型、工具和 Agent 通常会自动形成层级。为 run 添加稳定名称、tags 和 metadata，便于按环境与版本筛选。

metadata 推荐包含 environment、release、prompt_version、index_version、request_id、匿名 tenant/user ID。禁止放认证 token、密钥、身份证、完整支付数据或不必要的原始文档。

#4、追踪框架外函数

Python：

复制from langsmith import traceable

@traceable(name="retrieve_policy", run_type="retriever")
def retrieve_policy(question: str, tenant_id: str):
    return retriever.search(question, filter={"tenant_id": tenant_id})

@traceable(name="support_answer", run_type="chain")
def answer(request):
    chunks = retrieve_policy(request.question, request.tenant_id)
    return compose(request.question, chunks)

TypeScript：

复制import { traceable } from "langsmith/traceable";

const retrievePolicy = traceable(
  async (question: string, tenantId: string) => retriever.search(question, tenantId),
  { name: "retrieve_policy", run_type: "retriever" },
);

serverless 运行时要确保 trace 在进程退出前提交；普通服务可使用后台发送降低请求延迟。具体配置按部署环境和当前 SDK 文档设置。

#5、设计追踪字段字典

在 API 入口生成 request ID，并显式传遍 runtime；深层函数不要另起 ID。关键审计保存在业务数据库，不能只依赖 trace 平台。

#6、脱敏和采样

根 run、子 Agent、工具异常和附件都要脱敏。高风险写操作与错误请求通常全量追踪；大量普通成功请求可采样。发布窗口临时提高采样，稳定后降低。记录采样策略，否则基于样本计算的失败率会误导。

Trace SDK 故障不应让主业务失败；但应产生内部 metric，避免长时间“静默失明”。

#7、本篇验收

模拟 RAG 无命中、订单工具超时和输出 schema 失败。仅看 trace 就能指出失败节点、输入摘要、版本、耗时和错误码；trace 中找不到伪造 API key、邮箱和地址；关闭 tracing 后主请求仍能工作。

下一课用这些 trace 建立固定排障流程、反馈队列和监控指标。

官方阅读：Observability Quickstart。