LangChain.js/DeepAgents可观测性

引言：为什么 LLM 应用需要"X 光机"？

在 Generative AI 的热潮中，我们很容易用 LangChain 等框架快速搭建一个 Demo。然而，当我们将这些应用部署到生产环境时，噩梦往往随之而来：

成本失控：一个死循环的 Agent 在几分钟内消耗了数百美元的 Token。
调试困难：用户反馈"回答错误"，但你不知道是 prompt 问题、检索（RAG）失败，还是 LLM 本身的幻觉。
延迟不可知：一个请求耗时 10 秒，时间到底花在了网络请求、数据库查询还是模型推理上？

对于传统的微服务，我们要的是监控（Monitoring）；而对于充满不确定性的 LLM Agent，我们需要的是可观测性（Observability） ，需要关注的维度大概如下：

链路追踪 (Tracing) ：LLM 应用通常包含多个步骤（Prompt -> LLM -> Tool -> Parser）。我们需要看到完整的执行链路，尤其是 Agent 在"思考"时的中间步骤。
成本监控 (Cost & Token Usage) ：每一次 API 调用都是钱。我们需要精确知道每个功能模块消耗了多少 Token。
延迟分析 (Latency) ：瓶颈是在向量数据库检索，还是 LLM 生成速度太慢？
评估 (Evaluation) ：如何确定修改了 Prompt 后，输出质量没有下降？

工具一：LangSmith (LangChain 官方支持)

LangSmith 是 LangChain 团队推出的全能平台，它与 LangChain.js 的集成是"原生级"的，几乎不需要改动代码。

核心亮点

开箱即用：对于 LangChain.js 应用，只需配置环境变量。
可视化调试：能够清晰地展示 Agent 的递归调用树。
Playground：可以直接在界面上修改 Prompt 并重新运行某个步骤。

如何在 LangChain.js 中集成

你甚至不需要安装额外的 SDK，只需要设置环境变量：

bash 复制代码

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>

或者使用.env文件，并且在根目录下使用bun运行会自动加载

env 复制代码

# .env 文件
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=<your-api-key>

当然如果要自定义workspace和project可以像下面这样设置

env 复制代码

# .env 文件
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=<your-api-key>
LANGSMITH_WORKSPACE_ID=<your-workspace-id>
LANGSMITH_PROJECT=default

如果是个人用户免费应该是只有一个workspace，一个workspace里面可以有多个project

如果你看过上一篇文章：DeepAgents官方文档（一），可以再次执行一次，然后登录 LangSmith 后台，你可以看到这次 invoke 的完整过程，包括 Prompt 渲染后的实际内容、LLM 的原始响应、Token 消耗以及耗时。

工具二：LangFuse (开源与自托管首选)

LangFuse 是一款开源的 LLM 工程化平台。如果你对数据隐私有极高要求，或者希望私有化部署，LangFuse 是最佳选择。它提供了非常强大的 Analytics（分析）面板。

核心亮点

完全开源：支持 Docker 一键部署。
LangChain 集成 ：通过 CallbackHandler 轻松接入。
精细的成本分析：可以按用户、按模型、按功能统计费用。
Prompt 管理：支持在后台管理 Prompt 版本，代码直接拉取。

如何在 LangChain.js 中集成

部署LangFuse

LangFuse有很多种私有部署方式

这里为了方便演示使用DockerCompose部署：

sh 复制代码

# 拉取git仓库
git clone https://github.com/langfuse/langfuse.git
cd langfuse
docker compose up

如果是国内的话，可以将docker-compose.yaml里的docker.io替换成docker.1ms.run加速镜像下载，如果是新的CentOS、Fedora这些系统自带了podman，使用dnf安装一个podman-compose即可代替docker-compose，只需要改成：podman compose up即可

接入SDK

首先安装 SDK：

bash 复制代码

npm i @langfuse/langchain @langfuse/otel @opentelemetry/sdk-node
#或者使用bun、pnpm
bun i @langfuse/langchain @langfuse/otel @opentelemetry/sdk-node
pnpm i  @langfuse/langchain @langfuse/otel @opentelemetry/sdk-node

通过回调函数（Callback）的方式注入监控：

typescript 复制代码

import { tool } from "langchain";
import { TavilySearch } from "@langchain/tavily";
import { z } from "zod";
import { createDeepAgent, FilesystemBackend } from "deepagents";
import { ChatOpenAI } from "@langchain/openai";
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { CallbackHandler } from "@langfuse/langchain";

// 初始化sdk
const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});

sdk.start();

const langfuseHandler = new CallbackHandler({});

// ...

const result = await agent.invoke(
  {
    messages: [{ role: "user", content: "你是谁" }],
  },
  {
    // 这里传入回调
    callbacks: [langfuseHandler],
    // 这里定义sessionId、userId、tags
    metadata: {
      langfuse_session_id: "user-111",
      langfuse_user_id: "user-222",
      langfuse_tags: ["production", "humor-bot"],
    },
  },
);

// 输出Agent的最终响应
console.log(result.messages[result.messages.length - 1].content);

目前测试langchain@1.1.2、deepagents@1.3.0、@langfuse/langchain@4.4.4、langfuse v3.135.1 OSS，tracing会缺少一些数据，比如input、output、llm调用等节点信息，谨慎使用

LangSmith vs LangFuse：如何选择？

维度	LangSmith	LangFuse
集成难度	极低 (仅需环境变量)	低 (需添加 Callback 或 SDK)
开源属性	闭源 (SaaS)	开源 (MIT License)
部署方式	云托管 (企业版支持私有化)	云托管或自托管 (Docker、K8S等)
生态绑定	强绑定 LangChain 生态	框架无关 (支持 LangChain, LlamaIndex, SDK)
特色功能	强大的数据集评估与标注	强大的成本分析与 Prompt 管理

深度代理 (Deep Agents) 场景下的建议

当我们开发复杂的 DeepAgents（具备反思、规划、工具使用能力的智能体）时，可观测性不再是"锦上添花"，而是"救命稻草"。

对于这类应用，建议采取以下策略：

给 Trace 加上 Tags ：例如标记 environment: production 或 agent_version: v2.1，便于 A/B 测试。
记录 User Feedback：LangSmith 和 LangFuse 都支持记录用户点赞/点踩。将用户的反馈与具体的 Trace 关联起来，是优化 Agent 表现的最快路径。
监控工具调用参数 ：Agent 经常会产生幻觉，调用工具时传入错误的 JSON 格式。通过 Trace 查看 tool_input 是调试此类错误的唯一有效手段。

结语

无论是使用 LangChain.js 的生态便利，还是 DeepAgents.js 的深度能力，没有可观测性的 AI 应用就像在黑夜中开车。

如果你追求快速上手 且深度依赖 LangChain，LangSmith 是不二之选。
如果你需要数据合规 、成本控制 或非 LangChain 框架 ，LangFuse 则是你的瑞士军刀。

希望这篇文章能帮助你在 AI 开发的道路上看得更清、走得更远！