当你只能看到最终输出时，AI 智能体可能会很难调试。

在本教程中，Darsh 将向你展示如何使用 LangSmith、LangChain、Ollama 和 Qwen 来追踪和监控一个本地 AI 智能体。

你将检查模型和工具调用、追踪延迟和使用情况，并利用追踪来理解智能体行为在何处出错。

https://freecodecamp.org/news/how-to-trace-and-monitor-ai-agents-with-langsmith/…

如何使用 LangSmith 追踪和监控 AI 智能体

来源：https://www.freecodecamp.org/news/how-to-trace-and-monitor-ai-agents-with-langsmith/

在本教程中，我将向你展示如何使用 LangSmith 追踪和监控一个本地 AI 智能体。我们将构建一个小的本地 AI 智能体，然后为其启用 LangSmith 追踪，以便你可以在 Web UI 中检查模型调用、工具使用和请求延迟。

我们将使用 LangChain v1、Ollama、Qwen 和 Python。除了可观测性层之外，所有内容都在你自己的机器上运行，因此智能体本身没有模型 API 费用。

目录

• 背景
• 什么是可观测性和监控？
• 什么是 LangSmith？
• 动机与架构
• 步骤 1：安装 Ollama 并拉取模型
• 步骤 2：安装 Python 依赖
• 步骤 3：启用 LangSmith 追踪
• 步骤 4：构建智能体
• 示例输出
• 下一步
• 结论

背景

构建一个本地 AI 智能体是容易的部分。更难的部分在后面，当智能体在提示词更改后行为异常，开始使用错误的工具，或者在没有明显原因的情况下变慢时。

对于常规软件，我们通常依赖日志和指标来理解发生了什么变化。智能体也需要这些，但它们还需要能够看到请求内部的实际决策链。单个用户消息可能触发一次模型调用、一次或多次工具调用，以及在返回最终答案之前的多个中间步骤。

如果我们只看最终输出，就会错过大部分关键信息。我们可以判断出有问题，但不知道问题出在哪里。

这就是可观测性对 AI 智能体重要的原因。在本教程中，我们将为一个本地 LangChain 智能体设置 LangSmith 追踪，以便检查每个请求，查看调用了哪些工具，并逐步了解智能体的行为。

要跟着做，你需要在本机上安装 Ollama。本教程适用于 macOS、Windows 和 Linux。我使用的是 32 GB RAM 的 MacBook Pro，但你可以选择较小的 Qwen 模型在内存较低的机器上运行相同的设置。

什么是可观测性和监控？

监控告诉我们有问题。它提供了诸如更高延迟、更多故障、更多工具错误或使用量随时间增加等信号。

可观测性帮助我们理解问题原因。它让我们能够检查请求内部发生的情况。对于 AI 智能体来说，这意味着要查看提示词、模型调用、工具调用、输出以及每个步骤的时间。

在实践中，可观测性通常包括三件事：

• 追踪：请求的完整逐步路径
• 日志：事件、输出和错误的记录
• 指标：随时间跟踪的数字，如延迟、故障和使用量

对于 AI 智能体来说，这点很重要，因为仅凭最终答案通常是不够的。如果输出错误或缓慢，我们需要一种方法来查看问题来自模型、提示词、工具选择还是智能体循环中间的某个环节。目标是理解发生了什么以及问题出在哪里。

什么是 LangSmith？

LangSmith 是 LangChain 的可观测性平台，用于追踪、调试、评估和监控 LLM 应用和智能体。

LangSmith 的核心概念包括：

• 项目：相关追踪的容器
• 追踪：一个请求的完整执行过程
• 运行：追踪中的单个步骤，例如 LLM 调用或工具调用
• 线程：对话或会话分组，适用于多轮智能体

使用 create_agent 构建的 LangChain 智能体自动支持 LangSmith 追踪，这意味着你无需更改代码即可捕获模型调用、工具调用和执行步骤。追踪结果会在每次智能体调用时自动上传到 LangSmith 服务器。

LangSmith 的功能包括请求追踪、逐步运行检查、延迟和使用监控、仪表板、基于项目的组织、回归警报等。

动机与架构

监控是构建智能体之后自然的下一步。一旦智能体工作，下一个问题是它是否可靠地工作，以及当它不工作时我们能否调试它。这在生产环境中尤为重要，因为如果没有追踪、指标和请求级别的可见性，调试真实用户问题会困难得多。

为了简单起见，我们将监控一个带有两个工具的小型本地智能体：一个用于获取当前时间，另一个用于计数单词。智能体通过 Ollama 本地运行，而 LangSmith 捕获追踪数据，以便我们在浏览器中检查并进行调试/监控。

步骤 1：安装 Ollama 并拉取模型

首先，为你所在平台安装 Ollama 应用程序。我们将使用 qwen3.5:4b。

ollama pull qwen3.5:4b

如果你的机器内存较低，可以使用 qwen3.5:0.8b 替代。

步骤 2：安装 Python 依赖

创建一个虚拟环境并安装所需的包：

python3 -m venv venv 
source venv/bin/activate 
pip install langchain langchain-core langchain-ollama langsmith

本教程需要 langchain>=1.0.0。

步骤 3：启用 LangSmith 追踪

在 https://smith.langchain.com/ 上创建一个免费的 LangSmith 账户。登录后，创建一个名为 MyAgentApp 的新项目。

（LangSmith 页面用于创建新项目。我们将创建 MyAgentApp 项目） 然后为项目生成一个 API 密钥，并在终端中设置环境变量。LangSmith 网页会显示要设置的值。

export LANGSMITH_TRACING=true
export LANGSMITH_ENDPOINT=https://api.smith.langchain.com
export LANGSMITH_API_KEY=your_langsmith_api_key
export LANGSMITH_PROJECT="MyAgentApp"

此时，你的应用已准备好向 LangSmith 发送追踪数据。

步骤 4：构建智能体

下面是一个使用 Ollama、LangChain 和两个简单工具的最小化 AI 智能体。这是我们在 如何使用工具调用和内存构建你自己的本地 AI 智能体 中创建的工具调用智能体的简化版本。

无需额外的追踪/LangSmith 设置。

将此文件保存为 trace_agent.py：

from datetime import datetime

from langchain.agents import create_agent
from langchain_core.tools import tool
from langchain_ollama import ChatOllama

CHAT_MODEL = "qwen3.5:4b"   # Ollama 聊天模型。必须支持工具调用。

SYSTEM_PROMPT = (
    "你是一个有用的助手，可以使用工具获取当前时间和统计文本中的单词数。"
    "当用户的请求需要工具时，使用工具。"
    "如果问题不需要工具，直接回答。"
    "如果工具返回错误，请简洁地解释错误。"
)

# ----- 工具 -----
@tool
def current_time() -> str:
    """返回当前本地日期和时间。
    当用户询问当前时间或日期时使用此工具。
    """
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

@tool
def word_count(text: str) -> int:
    """统计一段文本中的单词数。
    当用户询问一段文字的长度或要求统计他们分享的内容中的单词时使用此工具。
    返回单词数（整数）。
    """
    return len(text.split())

TOOLS = [current_time, word_count]

# ----- 智能体 -----

def build_agent():
    model = ChatOllama(model=CHAT_MODEL, reasoning=False, temperature=0)

    return create_agent(
        model=model,
        tools=TOOLS,
        system_prompt=SYSTEM_PROMPT
    )

def main():
    agent = build_agent()

    print("准备就绪！向智能体提问。\n")

    # 记录此轮之前已有的消息数量，以便从返回的状态中仅提取新消息（工具调用 + 最终答案）。
    prev_message_count = 0

    while True:
        question = input("你: ").strip()
        if not question or question.lower() == "exit":
            break

        result = agent.invoke(
            {"messages": [{"role": "user", "content": question}]}
        )

        # 仅查看此轮中添加的消息，而不是完整历史。
        new_messages = result["messages"][prev_message_count:]

        # 打印此轮中产生的所有工具调用。
        for msg in new_messages:
            tool_calls = getattr(msg, "tool_calls", None)
            if tool_calls:
                for call in tool_calls:
                    print(f"[工具调用] {call['name']}({call['args']})")

        print(f"\n回答: {result['messages'][-1].content}\n")

        # 更新下一轮的计数。
        prev_message_count = len(result["messages"])

if __name__ == "__main__":
    main()

由于这个智能体是使用 LangChain 的智能体 API 创建的，LangSmith 追踪应该会自动捕获端到端的执行过程：输入、模型交互、工具调用和最终输出，无需额外配置。

运行智能体：

python trace_agent.py

示例输出

输出如下所示。我向智能体问了四个问题。它调用了工具来获取时间和统计单词长度。

$ python trace_agent.py 
准备就绪！向智能体提问。

你: 你好，你好吗？

回答: 我很好！你呢？今天有什么我可以帮你的吗？

你: 现在几点了
[工具调用] current_time({})

回答: 当前本地日期和时间是 2026 年 7 月 17 日 13:56。还有其他需要了解的吗？

你: "LangSmith is awesome" 的单词数是多少
[工具调用] word_count({'text': 'LangSmith is awesome'})

回答: 短语 "LangSmith is awesome" 的单词数是 3。如果需要其他帮助，请告诉我！

你: 法国的首都是哪里

回答: 法国的首都是巴黎。

现在，我们将看到 LangSmith 如何追踪请求。前往 LangSmith Web UI 并登录。点击你的项目，你可以看到：

• 项目中的追踪
• 请求和响应
• 工具调用信息
• 令牌消耗
• 延迟信息和其他关键指标

对于上述输出，我可以看到四个追踪（每次智能体调用都会创建自己的追踪）：

（图片显示 MyAgentApp 项目中的所有四个追踪）

检查追踪 2，我可以看到请求、响应和工具调用信息。我还可以看到消耗的令牌。

（图片显示 MyAgentApp 项目中的一个追踪请求和响应）

我可以看到我的应用的整体计数、延迟、错误率和其他指标。这有助于检查 AI 智能体的整体使用情况和健康状况。

（图片显示带有计数、延迟和错误率指标的监控仪表板）

最后，我可以设置警报，以便在出现问题时监控和通知。例如，我们可以配置一个名为“高使用量”的警报，如果过去 5 分钟内的运行次数超过一次，就会发出警报。

（图片显示 LangSmith UI 中的警报设置窗口）

上述设置为你提供了一种非常快速的方法来为你的 AI 智能体设置可观测性和监控。

下一步

追踪正常工作后，下一步改进是添加元数据和标签，以便更容易筛选和分析追踪数据。LangSmith 支持自定义元数据和标签，用于按环境、应用版本、用户层级或工作流标记请求。

例如，你可以在配置中添加以下选项：

• environment=dev
• agent_name=local-ollama-agent
• model=qwen3

result = agent.invoke(
    {"messages": [{"role": "user", "content": question}]},
    config={
        "tags": ["dev", "local-ollama-agent"],
        "metadata": {
            "environment": "dev",
            "agent_name": "local-ollama-agent",
            "model": "qwen3"
        }
    }
)

这在跨智能体、模型和环境进行比较时非常有用。

一个需要注意的地方是 LangSmith 是专有软件。使用它意味着你的追踪数据会被发送到 LangSmith 的托管服务，并且随着使用量增长通常会产生费用。在本教程中，由于追踪量很小，它是免费的。对于大多数项目来说，使用 LangSmith 是可以的。

一个开源的 LangSmith 替代方案是 Langfuse。它提供 LLM 可观测性，包括追踪、会话、元数据、仪表板和指标，并且可以自托管。它提供类似的功能，例如捕获 LLM 调用、工具执行、时间、输入、输出和元数据的追踪，以及可自定义的仪表板和基于元数据的筛选。

结论

在本教程中，我们为一个本地 AI 智能体添加了可观测性，使用了 LangSmith、LangChain v1、Ollama、Qwen 和 Python。结果是一个简单的监控和可观测性设置，显示了智能体做了什么、调用了哪些工具以及每个步骤花了多长时间。

从这里开始，你可以通过添加元数据、为开发和生产环境创建单独的项目，或尝试 Langfuse 等开源替代方案来扩展设置。核心循环保持不变：运行智能体、捕获追踪、检查结果，并利用该信号来改进系统。

如果你喜欢本教程，你可以在我的博客（最近的文章包括系统设计论文系列）、我的个人网站以及 LinkedIn 上找到更多我的文章。

免费学习编程。freeCodeCamp 的开源课程已帮助超过 40,000 人找到了开发者工作。开始学习