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

​
前置条件

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

​
启用跟踪

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

​
快速开始

无需额外代码即可将追踪记录到 LangSmith。只需像平常一样运行您的代理代码： 
from langchain.agents import create_agent


def send_email(to: str, subject: str, body: str):
    """向收件人发送电子邮件。"""
    # ... 邮件发送逻辑
    return f"Email sent to {to}"

def search_web(query: str):
    """在网上搜索信息。"""
    # ... 网络搜索逻辑
    return f"Search results for: {query}"

agent = create_agent(
    model="gpt-4.1",
    tools=[send_email, search_web],
    system_prompt="你是一个可以发送电子邮件和搜索网络的助手。"
)

# 运行代理 - 所有步骤将自动被跟踪
response = agent.invoke({
    "messages": [{"role": "user", "content": "搜索最新的 AI 新闻并通过邮件将摘要发送给 john@example.com"}]
})
默认情况下，追踪记录将被记录到名为 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 上编辑此页面 或 提交问题。
通过 MCP 将这些文档连接到 Claude、VSCode 等，获取实时答案。