Skip to main content
当您使用 LangChain 构建和运行 agent 时，您需要了解它们的行为：它们调用了哪些 工具，生成了什么提示词，以及它们是如何做决策的。使用 createAgent 构建的 LangChain agent 自动支持通过 LangSmith 进行追踪，LangSmith 是一个用于捕获、调试、评估和监控 LLM 应用程序行为的平台。 Traces 记录了您的 agent 执行的每一步，从最初的用户输入到最终的响应，包括所有工具调用、模型交互和决策点。这些执行数据可以帮助您调试问题、评估不同输入下的性能，并监控生产环境中的使用模式。 本指南向您展示如何为您的 LangChain agent 启用追踪，并使用 LangSmith 分析它们的执行情况。

​
以此为前提

在开始之前，请确保您拥有以下内容：

​
启用追踪

所有 LangChain agent 都自动支持 LangSmith 追踪。要启用它，请设置以下环境变量： 
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>

​
快速开始

无需额外代码即可将 trace 记录到 LangSmith。只需像往常一样运行您的 agent 代码： 
import { createAgent } from "@langchain/agents";

function sendEmail(to: string, subject: string, body: string): string {
    // ... email sending logic
    return `Email sent to ${to}`;
}

function searchWeb(query: string): string {
    // ... web search logic
    return `Search results for: ${query}`;
}

const agent = createAgent({
    model: "gpt-4.1",
    tools: [sendEmail, searchWeb],
    systemPrompt: "You are a helpful assistant that can send emails and search the web."
});

// Run the agent - all steps will be traced automatically
const response = await agent.invoke({
    messages: [{ role: "user", content: "Search for the latest AI news and email a summary to john@example.com" }]
});
默认情况下，trace 将记录到名为 default 的项目中。要配置自定义项目名称，请参阅 记录到项目。

​
Trace selectively

You may opt to trace specific invocations or parts of your application using LangSmith’s tracing_context context manager: 
import langsmith as ls

# This WILL be traced
with ls.tracing_context(enabled=True):
    agent.invoke({"messages": [{"role": "user", "content": "Send a test email to alice@example.com"}]})

# This will NOT be traced (if LANGSMITH_TRACING is not set)
agent.invoke({"messages": [{"role": "user", "content": "Send another email"}]})

​
Log to a project

You can set a custom project name for your entire application by setting the LANGSMITH_PROJECT environment variable:
export LANGSMITH_PROJECT=my-agent-project
You can set the project name programmatically for specific operations:
import langsmith as ls

with ls.tracing_context(project_name="email-agent-test", enabled=True):
    response = agent.invoke({
        "messages": [{"role": "user", "content": "Send a welcome email"}]
    })

​
Add metadata to traces

You can annotate your traces with custom metadata and tags: 
response = agent.invoke(
    {"messages": [{"role": "user", "content": "Send a welcome email"}]},
    config={
        "tags": ["production", "email-assistant", "v1.0"],
        "metadata": {
            "user_id": "user_123",
            "session_id": "session_456",
            "environment": "production"
        }
    }
)
tracing_context also accepts tags and metadata for fine-grained control: 
with ls.tracing_context(
    project_name="email-agent-test",
    enabled=True,
    tags=["production", "email-assistant", "v1.0"],
    metadata={"user_id": "user_123", "session_id": "session_456", "environment": "production"}):
    response = agent.invoke(
        {"messages": [{"role": "user", "content": "Send a welcome email"}]}
    )
This custom metadata and tags will be attached to the trace in LangSmith.
To learn more about how to use traces to debug, evaluate, and monitor your agents, see the LangSmith documentation.
在 GitHub 上编辑此页面 或 提交 issue。
通过 MCP 将这些文档连接 到 Claude, VSCode 等工具以获取实时解答。