LangGraph.js 在 Web 环境中的使用指南

前言

在现代 Web 开发中，JavaScript 运行时环境多种多样，从传统的浏览器环境到各种服务器端运行时如 Node.js、Deno、边缘计算平台等。LangGraph.js 作为一个功能强大的图计算框架，在设计时考虑到了这些不同环境的兼容性问题。本文将深入探讨如何在 Web 环境中正确使用 LangGraph.js，特别是那些不支持 async_hooks API 的环境。

环境兼容性概述

LangGraph.js 核心功能依赖于 Node.js 的 async_hooks API 来实现便捷的追踪和回调传播。这一设计在以下环境中表现良好：

• Node.js
• Deno
• 边缘计算平台
• Edge runtime

然而，浏览器环境并不支持 async_hooks API。为了解决这个问题，LangGraph.js 提供了专门的 Web 入口点。

Web 专用入口点

LangGraph.js 提供了 @langchain/langgraph/web 入口点，这个版本：

1. 不初始化也不导入 async_hooks
2. 导出与主入口点完全相同的功能
3. 专为浏览器等不支持 async_hooks 的环境设计

基础使用示例

import {
  END,
  START,
  StateGraph,
  Annotation,
} from "@langchain/langgraph/web";
import { BaseMessage, HumanMessage } from "@langchain/core/messages";

// 定义图状态
const GraphState = Annotation.Root({
  messages: Annotation<BaseMessage[]>({
    reducer: (x, y) => x.concat(y),
  }),
});

// 定义节点函数
const nodeFn = async (_state: typeof GraphState.State) => {
  return { messages: [new HumanMessage("Hello from the browser!")] };
};

// 构建图
const workflow = new StateGraph(GraphState)
  .addNode("node", nodeFn)
  .addEdge(START, "node")
  .addEdge("node", END);

// 编译并执行
const app = workflow.compile({});
const finalState = await app.invoke({ messages: [] });

console.log(finalState.messages[finalState.messages.length - 1].content);

安全注意事项

在浏览器环境中使用 LangGraph.js 时，必须特别注意安全问题：

1. 切勿在前端代码中暴露任何敏感信息
2. 对于聊天模型，建议使用可以在客户端无认证运行的方案
3. 重要操作应当始终在服务端完成

配置传递机制

由于浏览器缺乏 async_hooks 支持，当在节点内调用 Runnable 时（如调用聊天模型），需要手动传递 config 对象以确保：

1. 追踪功能正常工作
2. .streamEvents() 能够流式传输中间步骤
3. 其他回调相关功能正常运作

配置传递示例

const nodeFn = async (_state: StateType, config?: RunnableConfig) => {
  const nestedFn = RunnableLambda.from(
    async (input: string, _config?: RunnableConfig) => {
      return new HumanMessage(`Hello from ${input}!`);
    }
  ).withConfig({ runName: "nested" });
  
  // 关键：传递 config 参数
  const responseMessage = await nestedFn.invoke("a nested function", config);
  return { messages: [responseMessage] };
};

常见问题解决方案

问题1：无法获取嵌套函数的流事件

原因：未正确传递 config 对象

解决方案：

1. 确保节点函数接收 config 参数
2. 在调用嵌套 Runnable 时传递该 config

问题2：追踪信息丢失

原因：async_hooks 不可用且未手动传递配置

解决方案：

1. 使用 @langchain/langgraph/web 入口点
2. 按照上述方式手动传递配置

最佳实践

1. 环境检测：在代码中检测运行环境，自动选择合适的入口点
2. 配置传递：建立严格的配置传递规范，确保所有嵌套调用都能获得必要的配置
3. 错误处理：为配置缺失的情况添加明确的错误提示
4. 性能监控：在关键节点添加性能监控点，特别是在浏览器环境中

进阶主题

对于需要更复杂功能的开发者，可以考虑：

1. 自定义中间件：在配置传递过程中添加自定义处理逻辑
2. 状态管理：结合前端状态管理库（如 Redux）管理图状态
3. 性能优化：针对浏览器环境优化大型图的处理性能

总结

在 Web 环境中使用 LangGraph.js 需要注意以下几点：

1. 选择正确的入口点（@langchain/langgraph/web）
2. 正确处理配置传递
3. 遵守安全最佳实践
4. 了解不同环境的限制和特性

通过遵循这些指导原则，开发者可以充分利用 LangGraph.js 的强大功能，同时在各种 Web 环境中保持应用的稳定性和安全性。