LangChain 可观测性与调试

这篇适合谁、读完能做到什么

适合已经用 LangChain 写出第一个智能体、但不清楚它为什么这样做的开发者。读完你应该能给智能体打开追踪，跑一次任务，并在 LangSmith 里找到它每一步调用了哪个工具、和模型交互了什么。

追踪是什么，LangSmith 是什么

用 create_agent 创建的 LangChain 智能体会自动支持追踪，追踪数据通过 LangSmith 收集^[1]。LangSmith 是一个用来捕获、调试、评估和监控智能体行为的平台^[1]。

一条追踪（trace）记录智能体执行的每一步，从用户的初始输入到最终回复，包括所有工具调用、模型交互和决策点^[1]。这些执行数据可以帮你调试问题，比较智能体在不同输入下的表现，也可以在生产环境里观察使用模式^[1]。

准备：账号和 API 密钥

开始之前需要两样东西^[1]：

一个 LangSmith 账号。可以免费注册，也可以在 smith.langchain.com 登录。
一个 LangSmith API 密钥，按照页面上的「Create an API key」指引创建^[1]。

上手：设置环境变量

启用追踪需要设置四个环境变量：LANGSMITH_AGENT_ID、LANGSMITH_AGENT_ENVIRONMENT、LANGSMITH_TRACING 和 LANGSMITH_API_KEY。示例把 LANGSMITH_AGENT_ENVIRONMENT 设为 local，把 LANGSMITH_TRACING 设为 true^[1]。在 shell 里这样写：

export LANGSMITH_AGENT_ID="<your-agent-id>"
export LANGSMITH_AGENT_ENVIRONMENT="local"
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>

<your-agent-id> 和 <your-api-key> 换成你自己的值。设置完成后，不需要在代码里额外写任何日志逻辑^[1]。

第一条追踪：跑一个带工具的智能体

下面的 Python 例子定义了两个工具，send_email 和 search_web，然后用 create_agent 创建智能体，并让它执行一个任务^[1]：

from langchain.agents import create_agent


def send_email(to: str, subject: str, body: str):
    """Send an email to a recipient."""
    # ... email sending logic
    return f"Email sent to {to}"

def search_web(query: str):
    """Search the web for information."""
    # ... web search logic
    return f"Search results for: {query}"

agent = create_agent(
    model="gpt-6.1-sol",
    tools=[send_email, search_web],
    system_prompt="You are a helpful assistant that can send emails and search the web."
)

# Run the agent - all steps will be traced automatically
response = agent.invoke({
    "messages": [{"role": "user", "content": "Search for the latest AI news and email a summary to john@example.com"}]
})

两个工具函数里的注释写着 email sending logic 和 web search logic，说明它们只是占位实现，真正的发送邮件和搜索逻辑需要你自己补上。agent.invoke 执行之后，这一次任务的每一步都会被自动追踪，追踪结果会出现在设置时指定的目的地^[1]。

TypeScript 的写法相同：用 createAgent 从 langchain 引入，工具同样是两个函数，调用方式是 agent.invoke^[1]。

追踪里能看到什么

在追踪中，你能看到智能体的完整执行过程：先是用户的那句请求，然后是模型决定调用哪个工具，接着是工具的返回结果，最后是给用户的回复^[1]。遇到问题时，可以对照每一步找出是模型没有选对工具，还是工具返回的内容有误。

页面把 Python 和 JavaScript 两部分分开写，概念完全一样，只是语法不同^[1]。

对调试来说，追踪的好处是不用在代码里到处加打印语句，也不必靠猜测去解释智能体为什么选择了某个工具。只要打开这次执行的追踪，就能顺着步骤看到每一次工具调用和模型交互。当一次任务的结果不符合预期，你可以先找到出错的那一步，再决定是改提示词、改工具的描述，还是改工具本身的实现^[1]。

限制和常见问题

本文的示例只展示了追踪的启用方式，页面没有给出如何筛选追踪、如何设置评估或告警。这些需要去 LangSmith 的相关文档里查^[1]。
追踪需要 API 密钥。如果追踪没有出现，先检查 LANGSMITH_TRACING 是否为 true，以及密钥是否正确导出到运行智能体的那个 shell 里^[1]。
追踪结果出现在哪里，由设置时的配置决定^[1]。