如何使用LangSmith来追踪和监控人工智能代理的行为

在本教程中，我将向您展示如何使用LangSmith来追踪和监控本地的AI代理。我们会构建一个简单的本地AI代理，然后为其启用LangSmith追踪功能，这样我们就能通过Web界面查看模型调用情况、工具使用情况以及请求处理延迟等信息。

我们将使用LangChain v1、Ollama、Qwen以及Python这些工具。除了用于实现观测功能的组件外，所有操作都在您的本地机器上完成，因此代理本身不会产生任何与模型API相关的费用。

背景知识

构建本地的AI代理本身是一件相对简单的事情。但真正困难的部分在于：当代理在接收到不同的指令后行为发生改变，或者开始使用错误的工具，又或者在没有明显原因的情况下运行速度变慢时，我们该如何诊断问题。

对于普通的软件来说，我们通常会通过日志和各种指标来了解系统中发生了什么变化。AI代理也同样需要这些信息，但除此之外，我们还必须能够清楚地了解请求处理过程中实际的决策流程。一条用户输入的信息可能会触发模型的调用、一个或多个工具的运行，以及一系列中间步骤，最终才会产生相应的输出结果。

如果我们只关注最终的输出结果，那么我们就會错过很多重要的信息。我们虽然能察觉到某些问题发生了，但却无法确定问题的具体根源所在。

正因为如此，可观测性对于AI代理来说至关重要。在本教程中，我们将为本地LangChain代理启用LangSmith追踪功能，这样我们就能详细分析每一个请求的处理过程，了解哪些工具被调用过，以及代理是如何一步步完成任务的。

为了顺利跟随本教程的操作步骤，您的机器上需要安装Ollama。本教程适用于macOS、Windows和Linux系统。我使用的是一台配备32GB内存的MacBook Pro，但如果您使用的是内存容量较小的机器，也可以选择规模较小的Qwen模型来完成相同的设置。

什么是可观测性与监控？

监控功能能让我们及时发现系统中存在的问题，比如延迟增加、故障频发、工具错误增多，或者某些资源的使用量逐渐上升等等。

而可观测性则有助于我们理解这些问题产生的原因。它允许我们详细查看请求处理过程中的每一个细节，包括输入指令的内容、模型的调用情况、所使用的工具以及最终的输出结果等。对于AI代理来说，这意味着我们需要仔细分析指令内容、模型运行过程、工具使用情况，以及所有步骤的执行时间等信息。

在实际应用中，可观测性通常包括以下三个方面：

跟踪记录：请求执行的完整步骤路径
日志信息：事件发生、输出结果及错误情况的记录
指标数据：随时间变化的数值数据，如延迟时间、故障次数和使用频率等

对于人工智能代理来说，这些内容非常重要，因为仅仅依赖最终的结果往往是不够的。如果输出结果有误或响应速度过慢，我们就需要通过可观测性工具来查明问题究竟出在模型本身、输入指令、所使用的工具，还是代理运行过程中的其他环节。我们的目标是弄清楚到底发生了什么，以及问题出现在哪里。

什么是LangSmith？

LangSmith是LangChain提供的可观测性平台，用于追踪、调试、评估和监控大语言模型应用及代理程序的运行情况。

LangSmith的核心概念包括：

项目：用于存放相关跟踪记录的容器
跟踪记录：一次请求从开始到结束的完整执行过程
执行步骤：跟踪记录中的单个操作，例如大语言模型的调用或工具函数的调用
对话流程：用于分组多轮交互的对话内容

使用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() == "退出":
            break

        result = agent.invoke(
            {"messages": [{"role": "用户", "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 
准备就绪！可以向智能体提问了。

你：你好，最近怎么样？
回答：我挺好的！你呢？今天有什么我可以帮忙的吗？

你：现在是什么时间？
[tool call] current_time({})

回答：当前的本地时间是2026年7月17日13:56。还有其他想了解的信息吗？

你：“LangSmith is awesome”这个短语一共有多少个单词？
[tool call] word_count({'text': 'LangSmith is awesome'}

回答：“LangSmith is awesome”这个短语包含3个单词。如果还需要帮助，请告诉我！

你：法国的首都是什么？
回答：法国的首都是巴黎。

现在，让我们来看看LangSmith是如何追踪这些请求的。请访问LangSmith的Web界面并登录，然后点击你的项目，你就可以看到以下信息：

你项目中的所有追踪记录
请求与响应内容
工具调用的相关信息
令牌消耗情况
延迟时间及其他关键指标

从上面的输出中，我可以看到有四条追踪记录（每次智能体被调用都会生成一条追踪记录）：

在LangSmith UI中显示MyAgentApp项目中的所有四条追踪记录的图片

仔细查看第二条追踪记录，就可以看到请求内容、响应结果以及工具调用信息，同时还能了解消耗了多少令牌。

在LangSmith UI中显示MyAgentApp项目中的一条追踪记录的图片，包括请求与响应内容

我还可以查看我的应用程序的整体使用情况、延迟时间、错误率等其他指标。这些信息有助于了解你的AI智能体的整体运行状态。

最后，我还可以设置警报机制，以便在出现问题时及时收到通知。例如，我们可以配置一个名为“高使用率”的警报，当应用程序在过去5分钟内被调用的次数超过一定次数时，就会触发这个警报。

上述设置为您提供了一种非常便捷的方法，用于为您的人工智能代理配置可观测性及监控功能。

后续步骤

一旦追踪功能正常运行，下一步就可以添加元数据和标签，这样就能更方便地对追踪数据进行过滤和分析。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也是完全可行的。

一个开源的替代方案是Langfuse。它提供了类似的功能，包括对大语言模型调用过程、工具执行情况、耗时数据以及输入输出信息的追踪记录，同时还支持自定义仪表盘和基于元数据的过滤功能。

总结

在本教程中，我们使用LangChain v1、Ollama、Qwen以及Python为本地人工智能代理配置了可观测性功能。最终得到的结果是一个简单的监控系统，它可以显示代理执行了哪些操作、调用了哪些工具，以及每个步骤所花费的时间。

接下来，您可以通过添加元数据、为开发环境和生产环境创建不同的项目，或者尝试使用像Langfuse这样的开源工具来进一步扩展这个配置方案。核心流程始终保持不变：运行代理程序、捕获追踪数据、分析结果，并利用这些信息来优化系统性能。

如果您喜欢本教程，可以在我的博客上阅读更多文章（最近的文章包括一系列关于系统设计的论文），也可以在我的个人网站上查看我的工作成果，同时还可以在LinkedIn上关注我的最新动态。