可观测性 (Observability)

当你使用 LangChain 构建和运行智能体时，你需要了解它们的行为：它们调用了哪些工具、生成了什么提示以及如何做出决策。使用 createAgent 构建的 LangChain 智能体通过 LangSmith 自动支持追踪，这是一个用于捕获、调试、评估和监控 LLM 应用行为的平台。

追踪 (Traces) 记录智能体执行的每一步，从初始用户输入到最终响应，包括所有工具调用、模型交互和决策点。这些执行数据帮助你调试问题、评估不同输入下的性能，以及监控生产环境中的使用模式。

本指南向你展示如何为 LangChain 智能体启用追踪，并使用 LangSmith 分析其执行。

先决条件

开始之前，请确保你具备以下条件：

启用追踪

所有 LangChain 智能体都自动支持 LangSmith 追踪。要启用它，设置以下环境变量：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>

快速开始

无需额外代码即可将追踪记录到 LangSmith。只需像平常一样运行你的智能体代码：

import { createAgent } from "@langchain/agents";

function sendEmail(to: string, subject: string, body: string): string {
    // ... 发送邮件逻辑
    return `邮件已发送给 ${to}`;
}

function searchWeb(query: string): string {
    // ... 网络搜索逻辑
    return `搜索结果：${query}`;
}

const agent = createAgent({
    model: "gpt-4o",
    tools: [sendEmail, searchWeb],
    systemPrompt: "你是一个可以发送邮件和搜索网络的助手。"
});

// 运行智能体 - 所有步骤将自动追踪
const response = await agent.invoke({
    messages: [{ role: "user", content: "搜索最新的 AI 新闻并将摘要发送到 test@example.com" }]
});

默认情况下，追踪将记录到名为 default 的项目。要配置自定义项目名称，请参阅记录到项目。

选择性追踪

你可以使用 LangSmith 的 tracing_context 上下文管理器选择性地追踪特定调用或应用程序的部分：

import langsmith as ls

# 这将被追踪
with ls.tracing_context(enabled=True):
    agent.invoke({"messages": [{"role": "user", "content": "发送测试邮件到 test@example.com"}]})

# 这将不会被追踪（如果未设置 LANGSMITH_TRACING）
agent.invoke({"messages": [{"role": "user", "content": "发送另一封邮件"}]})

记录到项目

静态配置

你可以通过设置 LANGSMITH_PROJECT 环境变量为整个应用程序设置自定义项目名称：

export LANGSMITH_PROJECT=my-agent-project

动态配置

你可以在代码中为特定操作设置项目名称：

import langsmith as ls

with ls.tracing_context(project_name="email-agent-test", enabled=True):
    response = agent.invoke({
        "messages": [{"role": "user", "content": "发送欢迎邮件"}]
    })

向追踪添加元数据

你可以使用自定义元数据和标签注释追踪：

import langsmith as ls

with ls.tracing_context(
    metadata={"user_id": "user_123", "environment": "production"},
    tags=["email", "test"]
):
    response = agent.invoke({
        "messages": [{"role": "user", "content": "发送报告邮件"}]
    })

查看追踪

运行智能体后，你可以在 LangSmith 控制台中查看追踪：

  1. 登录 LangSmith
  2. 导航到你的项目
  3. 点击任意追踪以查看详细执行信息

追踪视图显示：

生产环境监控

LangSmith 提供生产监控功能：

最佳实践

下一步