我尝试了很多其它开发 Agent 的 Node.js 技术栈兜兜转转一圈下来我发现似乎只有 LangChain.js、LangGraph.js 才是最终的归途。Mastra 很好如果只是做独立的 Agent 确实不错但如果要集成到自己的系统里面去我觉得 Mastra 提前内置的那一堆东西会显得很臃肿而且它自己就是一个独立的 Node.js 服务很难塞进你已有的后端服务里面。LangChain.js、LangGraph.js 的自由度很高意味着你可以攒出高度自定义的 AI 逻辑还能方便地集成进自己的系统所以这一期我们就来正式入门 LangChain.js、LangGraph.js。这个系列我想解决的其实是一个很朴素的问题只要你会 Node.js就能自己写出一个 Agent。不需要先去啃一遍 Python也不需要另起一个孤立的服务用你最熟悉的 TypeScript把 Agent 直接长在你现有的项目里。本篇是入门篇先把地基打牢——搞清楚 LangChain 到底是什么、它的三个核心概念Runnable / LCEL / Message以及怎么跑起第一个例子。下一章我们再深入模型与 Prompt把ChatOllama、PromptTemplate/ChatPromptTemplate以及流式输出这些日常最常打交道的东西讲透。简介说白了LangChain.js 就是现代 LLM 应用开发里的那层「胶水」——它把模型、Prompt、工具、检索器这些零件统一抽象成一个可组合的Runnable让你用声明式的管道LCEL去拼装复杂的 AI 流程而不是自己手写一堆 imperative命令式的胶水脚本。你可以把它想象成 AI 世界里的 Express 中间件每个环节都长一个样子插上去就能用想换一个环节也不用动其它代码。官方文档现在的入口在这里后面章节我会经常带你去翻因为版本迭代很快以官网为准最靠谱JS 文档主站https://docs.langchain.com/oss/javascriptAPI Referencehttps://reference.langchain.com/javascript⚠️ 版本提示langchain包目前要求Node.js 22。开始之前先node -v确认一下版本太低后面装依赖会踩坑。环境准备正式写代码前先把环境铺好。整个系列我会尽量用**本地模型Ollama**做演示这样你不用花一分钱、不用申请 API Key 就能全程跟着跑等真要上线了换成 OpenAI / Anthropic 也就是改一行代码的事这正是 LangChain 的价值所在。# 1. 核心包 主包Node.js 22npminstalllangchain langchain/core# 2. 本地模型集成我们这期用 Ollamanpminstalllangchain/ollama# 3. 如果你想直接用云端模型装对应的集成包即可二选一# npm install langchain/openai# npm install langchain/anthropicOllama 本地跑一个模型也很简单# 安装 Ollama 后拉一个中文效果不错的小模型ollama pull qwen2.5:7bLangChain 的一个核心设计每个模型厂商是一个独立的集成包langchain/ollama、langchain/openai……核心抽象都在langchain/core。所以换模型 换包 换一行new业务逻辑一行都不用改。核心Runnable、LCEL、Message是 LangChain 的三根顶梁柱。只要把这三个概念吃透后面所有花里胡哨的东西你都能一眼看穿它的本质。一切皆 Runnable在 LangChain.js 里几乎所有组件都实现了Runnable接口对外提供一套统一的调用方式方法用途invoke(input)单次调用返回完整结果stream(input)流式调用逐块chunk返回batch(inputs)批量调用多个输入以下这些类型全都是 RunnableChatOllama模型、ChatPromptTemplate模板、StringOutputParser解析器甚至你自己写的一个普通函数用RunnableLambda包一下也能变成 Runnable。这个设计的意义在哪无论底层是 Ollama、OpenAI 还是你自定义的一段逻辑上层代码永远用同一种姿势invoke/stream去调它。这意味着替换、测试、Mock 都变得极其简单——这正是我认为 LangChain 比其它框架更适合「集成进现有系统」的根本原因。LCEL把零件串成管道LCEL 全称LangChain Expression Language是官方推荐的组合方式。核心思路一句话就能讲清楚把上一个 Runnable 的输出喂给下一个 Runnable 当输入像流水线一样一节一节接起来输入 → Prompt → Model → OutputParser → 输出等价于函数式编程里的管道outputParser(model(prompt(input)))只不过写起来顺眼得多。在 JS 里我们用.pipe()方法把它们串起来constchainprompt.pipe(model).pipe(outputParser);⚠️这是一个大坑很多从 Python 转过来的人会栽在这Python 版 LangChain 可以用|运算符写成prompt | model | parser非常优雅。但 JavaScript 不支持运算符重载所以在 JS 里你不能写prompt | model | parser|在 JS 里是按位或含义完全不同。JS 里请一律使用.pipe()。记住这一点能帮你省下半小时的 debug。和旧式 Chain 的区别LangChain 早期提供过LLMChain、ConversationChain这些类现在已经废弃了。新代码请一律用 LCEL// 旧写法已废弃勿用// const chain new LLMChain({ llm, prompt });// 新写法LCELJS 只能这么写constchainprompt.pipe(model).pipe(outputParser);用 LCEL 有什么好处我总结下来是「白嫖」了一堆能力每个环节可以独立测试整条链自动支持流式stream、批量batch、异步还天然接入 LangSmith 做可观测/追踪再加上 TypeScript 的类型推断前后环节的类型对不对编辑器直接给你标红。RunnableSequence 显式写法除了.pipe()你还可以用RunnableSequence.from把顺序显式声明出来import{RunnableSequence}fromlangchain/core/runnables;constchainRunnableSequence.from([prompt,model,outputParser]);两种写法完全等价。.pipe()更简洁日常首选RunnableSequence.from则适合动态组装链路的场景比如根据配置在数组里增删环节。Message 类型对话模型比如ChatOllama的输入和输出都不是纯字符串而是一组Message对象数组。LangChain 定义了四种最常用的 Message类型角色典型用途SystemMessage系统设定 AI 的角色、行为规则HumanMessage用户用户的提问或指令AIMessage助手模型的回复Tool calling 时会带上tool_callsToolMessage工具工具执行的结果回传给模型一次「多轮对话 Tool calling」的完整消息流大概长这样SystemMessage → HumanMessage → AIMessage(tool_calls) → ToolMessage → AIMessage(最终回复)这张图你现在可能还没完全体会到它的分量但我先剧透一句下一章的 Agent本质上就是围绕这条消息流反复循环——模型说要调工具我们执行工具、把结果塞回去再让模型接着说直到它给出最终答案。Message 就是这一切的载体。而且 Message 是 LangChain 和 OpenAI / Ollama 等各家 API 之间的标准中间格式换模型的时候你的业务逻辑完全不用动。与 Python 版 LangChain 的差异简述如果你之前学过 Python 版的 LangChain那恭喜概念是完全通用的主要差异集中在包结构和类型系统上维度PythonJavaScript / TypeScript包名langchain、langchain_communitylangchain/core、langchain/ollama等LCEL 语法prompt | model | parserprompt.pipe(model).pipe(parser)无|运算符Schema 验证Pydanticzod类型运行时 duck typing编译期 TypeScript 类型invoke/stream的语义两边是一致的所以学会 JS 版后你也能快速看懂 Python 项目反之亦然。唯一要反复提醒自己的还是那句话JS 里没有|用.pipe()。代码示例示例 1最简 LCEL 管道import{ChatOllama}fromlangchain/ollama;import{ChatPromptTemplate}fromlangchain/core/prompts;import{StringOutputParser}fromlangchain/core/output_parsers;// 1. 定义 Prompt 模板constpromptChatPromptTemplate.fromMessages([[system,你是一个简洁的技术助手回答控制在三句话以内。],[human,{question}],]);// 2. 实例化本地模型constmodelnewChatOllama({model:qwen2.5:7b,temperature:0.3,});// 3. 输出解析器从 AIMessage 中提取纯文本 contentconstoutputParsernewStringOutputParser();// 4. LCEL 组合注意 JS 用 .pipe()不是 |constchainprompt.pipe(model).pipe(outputParser);// 5. 调用constanswerawaitchain.invoke({question:什么是 Runnable});console.log(answer);// 纯字符串而非 AIMessage 对象示例 2多 Message 对话直接使用 Message 数组适合需要精细控制对话历史的场景import{ChatOllama}fromlangchain/ollama;import{SystemMessage,HumanMessage,AIMessage,}fromlangchain/core/messages;constmodelnewChatOllama({model:qwen2.5:7b});// 构造多轮对话上下文constmessages[newSystemMessage(你是一位 Node.js 导师用中文回答举例时用 TypeScript。),newHumanMessage(Promise 和 async/await 有什么区别),newAIMessage(Promise 是异步操作的容器async/await 是基于 Promise 的语法糖……),newHumanMessage(能给我一个 async/await 的代码例子吗),];constresponseawaitmodel.invoke(messages);console.log(response.content);ChatPromptTemplate适合模板化输入直接传 Message 数组则适合 Agent、多轮记忆这类需要动态追加消息的场景。到这里你已经能跑起一条最基础的「一问一答」链路了。至于怎么把模型调得更听话temperature、baseUrl等参数、PromptTemplate和ChatPromptTemplate到底怎么选、以及怎么做打字机式的流式输出——这些都是下一章「模型与 Prompt」的主场我们下篇细聊。