LangSmith 可观测性

LangSmith 为 LangGraph 应用提供追踪、调试、评估和监控能力。在生产环境中，这是排查 Agent 行为的必备工具。

启用 Tracing

环境变量方式

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=your-api-key
export LANGSMITH_PROJECT=my-agent-project  # 可选，默认项目名

设置后，所有 LangGraph 调用会自动被追踪。

代码控制

import langsmith as ls

# 只追踪特定调用
with ls.tracing_context(enabled=True):
    agent.invoke({"messages": [{"role": "user", "content": "你好"}]})

# 这段不会被追踪（如果未设置 LANGSMITH_TRACING）
agent.invoke({"messages": [{"role": "user", "content": "不追踪"}]})

添加元数据

response = agent.invoke(
    {"messages": [{"role": "user", "content": "发邮件给张三"}]},
    config={
        "tags": ["production", "email-agent", "v1.0"],
        "metadata": {
            "user_id": "user_123",
            "session_id": "session_456",
            "environment": "production"
        }
    }
)

通过 tracing_context 批量设置

with ls.tracing_context(
    project_name="email-agent-test",
    enabled=True,
    tags=["test"],
    metadata={"environment": "staging"}
):
    response = agent.invoke(
        {"messages": [{"role": "user", "content": "测试邮件"}]}
    )

数据脱敏

防止敏感数据被记录到 LangSmith：

from langchain_core.tracers.langchain import LangChainTracer
from langsmith import Client
from langsmith.anonymizer import create_anonymizer

# 创建脱敏器：遮蔽身份证号格式
anonymizer = create_anonymizer([
    {"pattern": r"\b\d{17}[\dXx]\b", "replace": "<id_number>"},
    {"pattern": r"\b\d{3}-?\d{2}-?\d{4}\b", "replace": "<ssn>"},
])

tracer_client = Client(anonymizer=anonymizer)
tracer = LangChainTracer(client=tracer_client)

graph = builder.compile().with_config({'callbacks': [tracer]})

在 LangSmith 中可以做什么

功能	说明
查看 Trace	可视化每个节点的执行时间和输入输出
调试异常	对比正常和异常的 trace 找到问题点
性能分析	查看 LLM 调用耗时、Token 消耗
评估	对 trace 打标，构建评估数据集
监控	设置告警，异常时自动通知

最佳实践

1. 生产环境始终开启 tracing
2. 每个请求带上用户 ID 和 session ID 便于排查
3. 使用项目名区分不同环境：project-dev、project-prod
4. 设置数据脱敏避免隐私泄露
5. 结合 @task 查看每个子任务的耗时

参考

• 官方文档：LangSmith Observability
• LangSmith 官方文档