LangGraph.js 是 LangChain 团队推出的 JavaScript 版本多智能体工作流框架专门用于构建包含循环和状态管理的复杂 AI Agent 系统。与传统的线性工作流不同LangGraph.js 采用图结构来定义智能体之间的交互关系支持状态机模式和多智能体协作能够处理需要多轮对话、条件分支和动态路由的复杂业务场景。对于需要处理复杂决策流程的 AI 应用来说LangGraph.js 提供了比传统单智能体更可靠的解决方案。它支持每个智能体拥有独立的提示词、工具集和 LLM 配置通过明确的状态转移控制来实现精准的任务分发和结果汇总。本文将重点介绍如何在实际项目中部署和使用 LangGraph.js包括环境搭建、三种典型多智能体模式实现、接口集成和性能优化方案。1. 核心能力速览能力项说明框架类型JavaScript 多智能体工作流框架开源团队LangChain 团队核心功能多智能体协作、状态机管理、循环工作流运行环境Node.js 环境支持主流操作系统显存需求依赖后端 LLM 服务本地主要为逻辑控制启动方式Node.js 脚本启动、API 服务集成接口能力支持 RESTful API 集成可封装为微服务批量任务支持异步批量处理可配置并发控制适合场景复杂决策系统、多步骤任务处理、企业级 AI 应用2. 适用场景与使用边界LangGraph.js 特别适合需要多个 AI 智能体协作完成的复杂任务。比如客户服务系统中的智能路由场景当用户输入一个问题时先由分类智能体判断问题类型然后路由到相应的专家智能体技术支持、账单查询、产品咨询等最后汇总答案返回给用户。这种需要多步骤决策和状态保持的场景正是 LangGraph.js 的优势所在。在企业级应用中LangGraph.js 可以用于构建智能审批流程、多专家咨询系统、复杂数据分析流水线等。每个智能体可以专注于特定领域的任务通过状态机确保流程的规范性和可追溯性。需要注意的是LangGraph.js 本身是工作流编排框架不包含 AI 模型推理能力。实际使用时需要接入外部的 LLM 服务如 OpenAI、本地部署的模型等。对于简单的单轮对话任务使用单智能体可能更高效只有当任务确实需要分解和协作时才需要考虑多智能体方案。3. 环境准备与前置条件在开始使用 LangGraph.js 前需要确保本地开发环境满足以下要求基础环境配置Node.js 18.0 或更高版本npm 或 yarn 包管理器代码编辑器VS Code 推荐LLM 服务准备OpenAI API 密钥或其他兼容的 LLM 服务或者本地部署的 LLM 服务端点验证环境是否就绪# 检查 Node.js 版本 node --version # 检查 npm 版本 npm --version # 创建项目目录 mkdir langgraph-project cd langgraph-project npm init -y4. 安装部署与启动方式LangGraph.js 的安装非常简单主要通过 npm 安装相关依赖# 安装核心依赖 npm install langchain/langgraph langchain/core npm install langchain/openai # 如果使用 OpenAI # 可选安装开发工具 npm install --save-dev typescript types/node基础启动示例创建一个简单的工作流文件basic_workflow.jsimport { StateGraph, END } from langchain/langgraph; import { ChatOpenAI } from langchain/openai; // 定义状态结构 const graphState { messages: { value: (x, y) x.concat(y), default: () [], }, }; // 创建图工作流 const workflow new StateGraph(graphState); // 添加节点 workflow.addNode(assistant, async (state) { const model new ChatOpenAI({ temperature: 0 }); const response await model.invoke(state.messages); return { messages: [response] }; }); // 设置入口点 workflow.setEntryPoint(assistant); // 编译图 const graph workflow.compile(); // 运行工作流 const result await graph.invoke({ messages: [{ role: user, content: Hello, how are you? }], }); console.log(result.messages);启动工作流node basic_workflow.js5. 三种多智能体模式实战5.1 多智能体协作模式在这种模式下多个智能体共享工作记忆每个智能体都能看到其他智能体的完整工作过程。适合需要高度协作和透明度的场景。import { StateGraph, END } from langchain/langgraph; import { ChatOpenAI } from langchain/openai; const graphState { messages: { value: (x, y) x.concat(y), default: () [], }, current_agent: { value: (x, y) y, default: () agent_a, }, }; const workflow new StateGraph(graphState); // 创建两个不同的智能体 const agentA new ChatOpenAI({ temperature: 0.7 }); const agentB new ChatOpenAI({ temperature: 0.3 }); workflow.addNode(agent_a, async (state) { const response await agentA.invoke(state.messages); return { messages: [response], current_agent: agent_b }; }); workflow.addNode(agent_b, async (state) { const response await agentB.invoke(state.messages); return { messages: [response], current_agent: agent_a }; }); // 基于条件路由 workflow.addConditionalEdges( agent_a, (state) { const lastMessage state.messages[state.messages.length - 1].content; return lastMessage.includes(FINAL) ? END : agent_b; } ); workflow.addConditionalEdges( agent_b, (state) { const lastMessage state.messages[state.messages.length - 1].content; return lastMessage.includes(FINAL) ? END : agent_a; } ); workflow.setEntryPoint(agent_a); const graph workflow.compile();5.2 智能体监督模式这种模式下一个监督智能体负责将任务路由给不同的专业智能体每个智能体有独立的工作空间只将最终结果提交到共享状态。import { StateGraph, END } from langchain/langgraph; const graphState { task: { value: (x, y) y, default: () }, specialist: { value: (x, y) y, default: () }, result: { value: (x, y) y, default: () }, }; const workflow new StateGraph(graphState); // 监督节点 - 决定任务分配给哪个专家 workflow.addNode(supervisor, async (state) { const task state.task.toLowerCase(); let specialist ; if (task.includes(技术) || task.includes(代码)) { specialist tech_specialist; } else if (task.includes(设计) || task.includes(UI)) { specialist design_specialist; } else { specialist general_specialist; } return { specialist }; }); // 各个专家节点 workflow.addNode(tech_specialist, async (state) { // 技术专家处理逻辑 return { result: 技术问题解决方案 }; }); workflow.addNode(design_specialist, async (state) { // 设计专家处理逻辑 return { result: 设计方案建议 }; }); workflow.addNode(general_specialist, async (state) { // 通用专家处理逻辑 return { result: 通用问题解答 }; }); // 路由逻辑 workflow.addConditionalEdges( supervisor, (state) state.specialist ); workflow.addEdge(tech_specialist, END); workflow.addEdge(design_specialist, END); workflow.addEdge(general_specialist, END); workflow.setEntryPoint(supervisor);5.3 分层智能体团队模式在分层模式下每个节点本身可以是一个完整的子工作流适合构建企业级的复杂决策系统。import { StateGraph, END } from langchain/langgraph; // 主工作流 const mainWorkflow new StateGraph({ project_brief: { value: (x, y) y, default: () }, current_phase: { value: (x, y) y, default: () planning }, deliverables: { value: (x, y) x.concat(y), default: () [] }, }); // 各个阶段的工作流可以作为独立的图 mainWorkflow.addNode(planning_phase, async (state) { // 调用规划子工作流 return { current_phase: execution, deliverables: [项目计划书] }; }); mainWorkflow.addNode(execution_phase, async (state) { // 调用执行子工作流 return { current_phase: review, deliverables: [实现代码] }; }); mainWorkflow.addNode(review_phase, async (state) { // 调用评审子工作流 return { current_phase: completion, deliverables: [评审报告] }; }); // 线性工作流 mainWorkflow.addEdge(planning_phase, execution_phase); mainWorkflow.addEdge(execution_phase, review_phase); mainWorkflow.addEdge(review_phase, END); mainWorkflow.setEntryPoint(planning_phase);6. 接口 API 与批量任务处理LangGraph.js 可以轻松封装为 API 服务支持批量任务处理。以下是 Express.js 集成示例import express from express; import { workflow } from ./your-workflow.js; const app express(); app.use(express.json()); // 单任务处理接口 app.post(/api/process, async (req, res) { try { const { input, config } req.body; const result await workflow.invoke(input, config); res.json({ success: true, data: result }); } catch (error) { res.status(500).json({ success: false, error: error.message }); } }); // 批量任务处理接口 app.post(/api/batch-process, async (req, res) { try { const { tasks, concurrency 3 } req.body; const results []; // 控制并发数 for (let i 0; i tasks.length; i concurrency) { const batch tasks.slice(i, i concurrency); const batchResults await Promise.all( batch.map(task workflow.invoke(task)) ); results.push(...batchResults); } res.json({ success: true, data: results }); } catch (error) { res.status(500).json({ success: false, error: error.message }); } }); // 工作流状态查询接口 app.get(/api/workflow/:id/status, async (req, res) { // 实现状态查询逻辑 }); const PORT process.env.PORT || 3000; app.listen(PORT, () { console.log(LangGraph API 服务运行在端口 ${PORT}); });批量任务调用示例curl -X POST http://localhost:3000/api/batch-process \ -H Content-Type: application/json \ -d { tasks: [ {input: 任务1内容}, {input: 任务2内容}, {input: 任务3内容} ], concurrency: 2 }7. 性能优化与资源管理虽然 LangGraph.js 本身不直接消耗大量 GPU 资源但在集成 LLM 服务时需要注意性能优化连接池管理import { ConnectionPool } from your-llm-client; // 创建 LLM 连接池 const llmPool new ConnectionPool({ maxConnections: 10, maxRequestsPerConnection: 100, timeout: 30000 }); // 在智能体中使用连接池 workflow.addNode(optimized_agent, async (state) { const connection await llmPool.getConnection(); try { const response await connection.invoke(state.messages); return { messages: [response] }; } finally { llmPool.releaseConnection(connection); } });缓存策略实现import NodeCache from node-cache; const cache new NodeCache({ stdTTL: 300 }); // 5分钟缓存 workflow.addNode(cached_agent, async (state) { const cacheKey JSON.stringify(state.messages); const cached cache.get(cacheKey); if (cached) { return cached; } const response await model.invoke(state.messages); const result { messages: [response] }; cache.set(cacheKey, result); return result; });内存使用监控// 监控工作流内存使用 setInterval(() { const memoryUsage process.memoryUsage(); console.log(内存使用情况:, { rss: ${Math.round(memoryUsage.rss / 1024 / 1024)} MB, heapTotal: ${Math.round(memoryUsage.heapTotal / 1024 / 1024)} MB, heapUsed: ${Math.round(memoryUsage.heapUsed / 1024 / 1024)} MB, }); }, 30000);8. 常见问题与排查方法问题现象可能原因排查方式解决方案工作流编译失败状态定义不完整或节点配置错误检查状态对象的 value 和 default 方法确保每个状态字段都有正确的值处理函数智能体无响应LLM 服务连接问题或超时检查网络连接和 API 密钥增加超时设置添加重试机制内存使用过高工作流循环未正确终止检查条件边缘的逻辑确保有明确的结束条件避免无限循环批量任务卡住并发控制不当或资源竞争监控任务队列状态降低并发数添加任务超时机制状态丢失状态更新逻辑错误检查每个节点的返回值确保状态更新符合预期使用 TypeScript 增强类型安全调试技巧// 启用详细日志 const graph workflow.compile({ debug: true, logger: console.log }); // 添加自定义监控点 workflow.addNode(monitored_agent, async (state) { console.log(进入节点当前状态:, JSON.stringify(state, null, 2)); const startTime Date.now(); try { const result await agent.invoke(state); console.log(节点执行完成耗时: ${Date.now() - startTime}ms); return result; } catch (error) { console.error(节点执行失败:, error); throw error; } });9. 企业级最佳实践项目结构组织src/ agents/ # 智能体定义 specialist/ supervisor/ workflows/ # 工作流定义 approval/ customer-service/ shared/ state.ts # 状态类型定义 tools.ts # 共享工具函数 api/ # API 接口 config/ # 配置文件错误处理与重试import retry from async-retry; workflow.addNode(robust_agent, async (state) { return await retry( async (bail) { try { return await agent.invoke(state); } catch (error) { if (error.code RATE_LIMIT) { throw error; // 重试 } else { bail(error); // 直接失败 } } }, { retries: 3, minTimeout: 1000, randomize: true, } ); });配置管理// config/workflow.js export const workflowConfig { timeout: 300000, // 5分钟超时 maxSteps: 100, // 最大步数限制 retryPolicy: { maxAttempts: 3, backoffMultiplier: 2 }, monitoring: { enabled: true, samplingRate: 0.1 // 10%的请求采样 } };10. 与其他框架对比LangGraph.js 在多智能体框架生态中处于中间层次比 CrewAI 提供更底层的控制比 Autogen 更符合现代开发习惯。与 Autogen 对比LangGraph.js 使用明确的图结构定义Autogen 更偏向对话模式LangGraph.js 集成 LangChain 生态工具链更完整状态管理更直观适合复杂业务流程与 CrewAI 对比CrewAI 更高层抽象快速搭建团队协作LangGraph.js 提供更细粒度的控制能力适合需要自定义路由和状态管理的场景技术选型建议简单多智能体任务CrewAI复杂业务流程和状态管理LangGraph.js研究原型和学术用途Autogen生产环境和企业应用LangGraph.jsLangGraph.js 的学习曲线相对平缓特别是对于已经熟悉 LangChain 生态的开发者。建议从简单的线性工作流开始逐步过渡到复杂的状态机和多智能体模式。在实际项目中重点关注状态设计、错误处理和性能监控这些是保证系统稳定性的关键因素。