我尝试了很多其它开发 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.js 就是现代 LLM 应用开发里的那层「胶水」——它把模型、Prompt、工具、检索器这些零件统一抽象成一个可组合的 Runnable，让你用声明式的管道（LCEL）去拼装复杂的 AI 流程，而不是自己手写一堆 imperative（命令式）的胶水脚本。

你可以把它想象成 AI 世界里的 Express 中间件：每个环节都长一个样子，插上去就能用，想换一个环节也不用动其它代码。

环境准备

正式写代码前，先把环境铺好。整个系列我会尽量用**本地模型（Ollama）**做演示，这样你不用花一分钱、不用申请 API Key 就能全程跟着跑；等真要上线了，换成 OpenAI / Anthropic 也就是改一行代码的事（这正是 LangChain 的价值所在）。

# 1. 核心包 + 主包（Node.js 22+）npm install langchain @langchain/core# 2. 本地模型集成（我们这期用 Ollama）npm install @langchain/ollama# 3. 如果你想直接用云端模型，装对应的集成包即可，二选一# npm install @langchain/openai# npm install @langchain/anthropic

Ollama 本地跑一个模型也很简单：

# 安装 Ollama 后，拉一个中文效果不错的小模型ollama pull qwen2.5:7b

核心

Runnable、LCEL、Message 是 LangChain 的三根顶梁柱。只要把这三个概念吃透，后面所有花里胡哨的东西你都能一眼看穿它的本质。

一切皆 Runnable

在 LangChain.js 里，几乎所有组件都实现了 Runnable 接口，对外提供一套统一的调用方式：

以下这些类型全都是 Runnable：ChatOllama（模型）、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() 方法把它们串起来：

const chain = prompt.pipe(model).pipe(outputParser);

和旧式 Chain 的区别

LangChain 早期提供过 LLMChain、ConversationChain 这些类，现在已经废弃了。新代码请一律用 LCEL：

// 旧写法（已废弃，勿用）// const chain = new LLMChain({ llm, prompt });// 新写法（LCEL，JS 只能这么写）const chain = prompt.pipe(model).pipe(outputParser);

用 LCEL 有什么好处？我总结下来是「白嫖」了一堆能力：每个环节可以独立测试；整条链自动支持流式（stream）、批量（batch）、异步；还天然接入 LangSmith 做可观测/追踪；再加上 TypeScript 的类型推断，前后环节的类型对不对，编辑器直接给你标红。

RunnableSequence 显式写法

除了 .pipe()，你还可以用 RunnableSequence.from 把顺序显式声明出来：

import { RunnableSequence } from "@langchain/core/runnables";const chain = RunnableSequence.from([prompt, model, outputParser]);

两种写法完全等价。.pipe() 更简洁，日常首选；RunnableSequence.from 则适合动态组装链路的场景（比如根据配置在数组里增删环节）。

Message 类型

对话模型（比如 ChatOllama）的输入和输出都不是纯字符串，而是一组 Message 对象数组。LangChain 定义了四种最常用的 Message：

一次「多轮对话 + Tool calling」的完整消息流大概长这样：

SystemMessage → HumanMessage → AIMessage(tool_calls) → ToolMessage → AIMessage(最终回复)

这张图你现在可能还没完全体会到它的分量，但我先剧透一句：下一章的 Agent，本质上就是围绕这条消息流反复循环——模型说要调工具，我们执行工具、把结果塞回去，再让模型接着说，直到它给出最终答案。 Message 就是这一切的载体。

而且 Message 是 LangChain 和 OpenAI / Ollama 等各家 API 之间的标准中间格式，换模型的时候你的业务逻辑完全不用动。

与 Python 版 LangChain 的差异简述

如果你之前学过 Python 版的 LangChain，那恭喜，概念是完全通用的，主要差异集中在包结构和类型系统上：

invoke / stream 的语义两边是一致的，所以学会 JS 版后你也能快速看懂 Python 项目，反之亦然。唯一要反复提醒自己的还是那句话：JS 里没有 |，用 .pipe()。

代码示例

示例 1：最简 LCEL 管道

import { ChatOllama } from "@langchain/ollama";import { ChatPromptTemplate } from "@langchain/core/prompts";import { StringOutputParser } from "@langchain/core/output_parsers";// 1. 定义 Prompt 模板const prompt = ChatPromptTemplate.fromMessages([["system", "你是一个简洁的技术助手，回答控制在三句话以内。"],["human", "{question}"],]);// 2. 实例化本地模型const model = new ChatOllama({model: "qwen2.5:7b",temperature: 0.3,});// 3. 输出解析器：从 AIMessage 中提取纯文本 contentconst outputParser = new StringOutputParser();// 4. LCEL 组合：注意 JS 用 .pipe()，不是 |const chain = prompt.pipe(model).pipe(outputParser);// 5. 调用const answer = await chain.invoke({ question: "什么是 Runnable？" });console.log(answer); // 纯字符串，而非 AIMessage 对象

示例 2：多 Message 对话

直接使用 Message 数组，适合需要精细控制对话历史的场景：

import { ChatOllama } from "@langchain/ollama";import {SystemMessage,HumanMessage,AIMessage,} from "@langchain/core/messages";const model = new ChatOllama({ model: "qwen2.5:7b" });// 构造多轮对话上下文const messages = [new SystemMessage("你是一位 Node.js 导师，用中文回答，举例时用 TypeScript。"),new HumanMessage("Promise 和 async/await 有什么区别？"),new AIMessage("Promise 是异步操作的容器，async/await 是基于 Promise 的语法糖……"),new HumanMessage("能给我一个 async/await 的代码例子吗？"),];const response = await model.invoke(messages);console.log(response.content);

ChatPromptTemplate 适合模板化输入；直接传 Message 数组则适合 Agent、多轮记忆这类需要动态追加消息的场景。