深入浅出 LangChain — 导读

一、前言

2022 年底，ChatGPT 的横空出世让整个技术圈意识到：大语言模型（LLM）不只是一个实验室里的玩具，它正在成为一种新的软件基础设施。

随之而来的问题是：作为开发者，我们怎么用它？

最初的答案很简单——直接调 API，拼接字符串，把模型的输出展示给用户。这能解决一批问题，但很快就遇到了天花板：模型不知道最新信息、不能操作外部系统、没法做多步骤推理、对话结束后什么都不记得……

于是，AI Agent 的概念开始成熟。Agent 的核心思路是：把 LLM 当作"大脑"，再配上工具、记忆和规划能力，让它自主地完成复杂任务。一个有工具调用能力的 Agent，可以查天气、写代码、搜索数据库、发邮件——它不再只是回答问题，而是真正地替你做事。

LangChain 正是在这个背景下诞生的框架。它提供了一套标准化的抽象，让开发者不必从零手搓 Agent 的基础设施，而是专注于业务逻辑本身。从 2022 年 10 月发布至今，LangChain 已经历三年多的迭代，在 2025 年 10 月发布的 v1.0.0 中完成了一次彻底的架构升级——所有 Agent 逻辑统一迁移到 LangGraph 运行时之上，从原型友好转向生产就绪。

本系列文章就是围绕的最新的 LangChain（v1.3.1）的TypeScript版本开展，旨在帮开发者快速系统掌握LangChain。

---

二、为什么是 TypeScript版本

LangChain 同时维护 Python 版本和 JavaScript/TypeScript 版本。Python 版本出现更早，社区生态更成熟，网上的教程也多。但选择 TypeScript 版本有几个实际的理由：

类型系统的价值在 AI 开发中被放大。 LLM 的输入输出本质上是非结构化文本，Agent 的状态流转复杂。TypeScript 的静态类型系统能在编译阶段帮你发现大量问题，配合 Zod 做运行时校验，能显著提高代码的可靠性。

Node.js 生态与前端天然同构。 如果你的 AI 应用需要接入 Web 前端、Serverless 函数、或者边缘计算环境，TypeScript 版本的适配成本更低。很多团队本来就在用 Node.js，直接复用现有的工具链和部署体系。

LangChain.js 的 API 设计与 Python 版保持一致。 学会了 TypeScript 版，理解 Python 版的概念没有障碍，两者之间的迁移成本很小。

关于 Python 版本：本书不会深入讲 Python 版本，但在部分章节会标注 Python 和 TypeScript 在 API 层面的差异，方便有需要的读者对照参考。

---

三、本系列文章适合谁读

这本书面向想从传统软件开发转型到 AI Agent 开发的工程师。更具体地说：

最适合的读者画像：

• 有一定的 TypeScript 或 JavaScript 开发经验，熟悉 async/await、模块系统等基础概念
• 知道 ChatGPT 之类的产品是怎么回事，但还没有系统构建过 LLM 应用
• 想在工作中落地 AI 功能，或者想转型做 AI 应用开发
• 不满足于"调个 API 展示结果"，想了解 Agent 背后的完整机制

如果你想知道传统开发和AI Agent开发的区别，可以阅读《2026年前端开发工程师转型AI Agent开发工程师全指南》这篇文章。

有帮助但不必须的背景知识：

• 了解 REST API 的基本工作原理
• 有过任何后端服务的开发经验
• 接触过 Python 或其他语言的 LangChain

不适合这本书的读者：

• 完全没有编程基础（这本书不是编程入门）
• 只对 Python 版本感兴趣（本书代码示例全部为 TypeScript）
• 想深入研究 LLM 模型训练或微调（这本书聚焦应用层开发）

---

四、本系列文章讲什么

该系列文章分为四个递进阶段：

第一部分：入门（第一章 ~ 第二章）

从 AI Agent 开发的全局视角出发，解释清楚 LLM 应用演进的脉络、Agent 的核心概念，以及 LangChain 生态的整体架构。然后带你配好开发环境，跑通第一个 Agent 示例，建立直觉。

第二部分：核心基础（第三章 ~ 第六章）

系统讲解 LangChain.js 的六大核心模块：模型抽象层、提示词工程、工具系统、记忆与状态管理。这部分是全书的骨架，每个模块都会讲清楚"是什么、为什么、怎么用"，并给出可运行的代码示例。

第三部分：进阶（第七章 ~ 第十章）

深入 Agent 的底层机制，包括 LangGraph 的工作原理、RAG 检索增强生成、多 Agent 系统设计、上下文工程与安全护栏。这部分是让你从"能用"到"用好"的关键。

第四部分：实战（第十一章 ~ 第十四章）

三个完整的项目实战：智能客服系统、代码助手 Agent、企业知识库问答系统。每个项目都会从需求分析到生产部署走完全程，最后一章专门讲可观测性、测试与运维。

---

五、预备知识

在开始阅读之前，建议先确认你掌握了以下基础知识：

1. TypeScript 基础

// 需要熟悉的核心概念：
// 1. 类型注解与接口
interface User {
  id: string;
  name: string;
}

// 2. async/await
async function fetchUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

// 3. 泛型
function identity<T>(value: T): T {
  return value;
}

// 4. 模块系统 (ESM)
import { something } from './module';
export { something };

如果这段代码你能看懂，TypeScript 基础就够了。如果还不熟悉，建议先花几小时过一遍 TypeScript 官方手册 的前几章。

2. LLM 基础概念

你不需要深入了解模型的训练原理，但需要知道：

• 什么是 Prompt（提示词）：发给 LLM 的输入文本
• 什么是 Token：LLM 处理文本的基本单位，大约 1 个 token ≈ 0.75 个英文单词，不同模型不一样
• 什么是上下文窗口（Context Window）：LLM 在一次对话中能"看到"的最大 token 数量
• 什么是模型温度（Temperature）：控制输出随机性的参数，0 表示最确定，1 表示更有创意

---

六、全系列思维导图

---

七、章节详细规划

第零章：导读（必读）

内容	说明
背景	AI Agent 浪潮下，为什么 LangChain.js 值得学习
目标	从零构建生产级 AI Agent 应用
适合人群	有一定 TypeScript/Node.js 基础，想转型 AI 开发的工程师
预备知识	TypeScript 基础、async/await、基本 LLM 概念
目录结构	入门 → 核心基础 → 进阶 → 实战 四个递进阶段
阅读建议	每章附有可运行示例，建议边读边实践
涉及技术栈	汇总说明所有章节会用到的技术栈

第一部分：入门（第一章 ~ 第二章）

目标：帮助读者建立 AI Agent 开发的完整认知，并跑通第一个 LangChain.js 应用。

第一章：AI Agent 开发导论

1. LLM 应用演进的三个阶段
2. 什么是 AI Agent：自主性、工具调用、多步推理
3. LangChain 生态全景：LangChain / LangGraph / LangSmith / Deep Agents
4. 为什么选择 TypeScript 版本：类型安全、Node.js 生态、前端同构

第二章：环境搭建与快速上手

1. 开发环境配置（Node.js 20+、TypeScript 5+、pnpm）
2. 安装 LangChain.js v1.3.1 及常用集成包
3. 第一个 Agent：天气查询示例（10 行代码）
4. LangSmith 集成：让 Agent 的每一步都可观测

第二部分：核心基础（第三章 ~ 第六章）

目标：系统掌握 LangChain.js 的六大核心模块。

第三章：模型抽象层（Models & Messages）

1. 统一模型接口的设计哲学
2. 接入主流 Provider：OpenAI、Anthropic、Google、Ollama
3. 流式输出（Streaming）的正确姿势
4. 结构化输出：Zod Schema 驱动的类型安全返回

第四章：提示词工程（Prompt Engineering）

1. PromptTemplate：变量注入与模板复用
2. ChatPromptTemplate：多角色消息构建
3. Few-shot 提示与示例选择器
4. 提示词的版本管理与最佳实践

第五章：工具系统（Tools & MCP）

1. 工具的本质：赋予 Agent 行动能力
2. 定义自定义工具：tool() API 与 Zod 校验
3. 内置工具库与动态工具选择
4. MCP（Model Context Protocol）集成：连接外部工具生态

第六章：记忆与状态管理（Memory & State）

1. 短期记忆：消息历史的自动维护
2. 长期记忆：跨会话的信息持久化
3. 自定义状态 Schema：扩展 Agent 的上下文
4. 常见记忆模式与坑点

---

第三部分：进阶（第七章 ~ 第十章）

目标：理解 Agent 的底层机制，掌握复杂应用场景的构建方式。

第七章：Agent 架构深度解析

1. createAgent() 的内部工作原理
2. LangGraph 图式运行时：节点、边与状态机
3. ReAct 推理模式的实现与优化
4. 中间件系统：在执行各阶段注入自定义逻辑

第八章：RAG 检索增强生成

1. 为什么需要 RAG：知识截止与私有数据
2. 文档加载、切割与 Embedding
3. 向量数据库选型与集成（Pinecone / Chroma / PGVector）
4. 检索策略进阶：混合检索、重排序、查询改写

第九章：多 Agent 系统

1. 多 Agent 的协作模式：串行、并行、委托
2. 子 Agent 隔离与资源管理
3. Human-in-the-loop：在关键节点引入人工审核
4. Agent 间的消息传递与状态共享

第十章：上下文工程与安全

1. Context Engineering 的核心思想
2. 动态上下文压缩与 Token 预算管理
3. Guardrails：输入过滤与输出校验
4. 生产环境的安全边界设计

---

第四部分：实战（第十一章 ~ 第十四章）

目标：通过三个完整项目，将所有知识点融会贯通。

第十一章：实战一 —— 智能客服系统

• 架构设计、知识库搭建、多轮对话、生产部署

第十二章：实战二 —— 代码助手 Agent

• 代码理解、工具链集成（运行代码/读写文件）、流式交互

第十三章：实战三 —— 企业知识库问答

• 多源数据接入、混合检索、权限控制、可观测性

第十四章：可观测性、测试与生产运维

• LangSmith 深度使用、评估框架、性能调优、运维最佳实践

---

八、如何阅读

1. 推荐阅读路径

如果你是 LLM 应用开发新手，建议按章节顺序阅读，不要跳过第一部分——那些背景知识会在你后续遇到困惑时帮你找到方向。

如果你已经有过 LLM 应用开发经验，可以快速浏览第一部分建立对 LangChain.js 的整体印象，然后从第三章开始重点阅读。

如果你只是想解决某个具体问题，可以直接跳到相关章节。每章都尽量做到独立，必要时会标注前置依赖。

2. 关于代码示例

所有代码示例遵循以下原则：

• 所有代码都可以在 Node.js 20+ 环境下直接运行
• 较长的代码会分段呈现，并逐段解析
• 每章的完整代码示例可以在配套仓库中找到

# 每章示例代码的运行方式统一如下：
cd chapter-XX
pnpm install
pnpm run dev

3. 关于标注约定

文章中会使用以下几种特殊标注：

💡 提示：补充说明，帮助你更好地理解概念

⚠️ 注意：容易踩坑的地方，请格外留意

🔍 深入探讨：适合进阶读者的原理性内容，初次阅读可以跳过

🆚 Python 对比：标注 LangChain.js 与 Python 版本的 API 差异

---

九、涉及的核心技术栈

技术	版本	用途
Node.js	20+	运行环境
TypeScript	5+	开发语言
LangChain.js	1.3.1	核心框架
LangGraph	最新	Agent 运行时
Zod	3.x	数据校验
OpenAI API	v4	主要演示用模型
Anthropic API	最新	部分章节演示
Pinecone / Chroma	-	向量数据库（RAG 章节）
LangSmith	-	调试与可观测性

---

十、一点个人的话

AI 应用开发是一个变化极快的领域。LangChain 本身在这三年里就经历了好几次重大的架构演进——从最初的 Chains，到 Agent，再到现在基于 LangGraph 的全新架构。

面对这种快速变化，最重要的不是记住所有 API，而是理解底层的设计思想。当你明白 Agent 为什么要用工具、记忆系统解决了什么问题、LangGraph 的图式运行时有什么好处，你就有能力在框架升级时快速适应，也能在遇到问题时找到根本原因。

本系列文章做到的正是这一点：不只教你怎么用，更解释清楚为什么要这样设计。

希望该系列教程能成为你进入 AI Agent 开发世界的一块可靠的垫脚石。

---

下一章：《第一章 —— AI Agent 开发导论》