一、前言
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 基础
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 开发导论
- LLM 应用演进的三个阶段
- 什么是 AI Agent：自主性、工具调用、多步推理
- LangChain 生态全景：LangChain / LangGraph / LangSmith / Deep Agents
- 为什么选择 TypeScript 版本：类型安全、Node.js 生态、前端同构
第二章：环境搭建与快速上手
- 开发环境配置（Node.js 20+、TypeScript 5+、pnpm）
- 安装 LangChain.js v1.3.1 及常用集成包
- 第一个 Agent：天气查询示例（10 行代码）
- LangSmith 集成：让 Agent 的每一步都可观测
第二部分：核心基础（第三章 ~ 第六章）
目标：系统掌握 LangChain.js 的六大核心模块。
第三章：模型抽象层（Models & Messages）
- 统一模型接口的设计哲学
- 接入主流 Provider：OpenAI、Anthropic、Google、Ollama
- 流式输出（Streaming）的正确姿势
- 结构化输出：Zod Schema 驱动的类型安全返回
第四章：提示词工程（Prompt Engineering）
- PromptTemplate：变量注入与模板复用
- ChatPromptTemplate：多角色消息构建
- Few-shot 提示与示例选择器
- 提示词的版本管理与最佳实践
第五章：工具系统（Tools & MCP）
- 工具的本质：赋予 Agent 行动能力
- 定义自定义工具：
tool()API 与 Zod 校验 - 内置工具库与动态工具选择
- MCP（Model Context Protocol）集成：连接外部工具生态
第六章：记忆与状态管理（Memory & State）
- 短期记忆：消息历史的自动维护
- 长期记忆：跨会话的信息持久化
- 自定义状态 Schema：扩展 Agent 的上下文
- 常见记忆模式与坑点
第三部分：进阶（第七章 ~ 第十章）
目标：理解 Agent 的底层机制，掌握复杂应用场景的构建方式。
第七章：Agent 架构深度解析
createAgent()的内部工作原理- LangGraph 图式运行时：节点、边与状态机
- ReAct 推理模式的实现与优化
- 中间件系统：在执行各阶段注入自定义逻辑
第八章：RAG 检索增强生成
- 为什么需要 RAG：知识截止与私有数据
- 文档加载、切割与 Embedding
- 向量数据库选型与集成（Pinecone / Chroma / PGVector）
- 检索策略进阶：混合检索、重排序、查询改写
第九章：多 Agent 系统
- 多 Agent 的协作模式：串行、并行、委托
- 子 Agent 隔离与资源管理
- Human-in-the-loop：在关键节点引入人工审核
- Agent 间的消息传递与状态共享
第十章：上下文工程与安全
- Context Engineering 的核心思想
- 动态上下文压缩与 Token 预算管理
- Guardrails：输入过滤与输出校验
- 生产环境的安全边界设计
第四部分：实战（第十一章 ~ 第十四章）
目标：通过三个完整项目，将所有知识点融会贯通。
第十一章：实战一 ------ 智能客服系统
- 架构设计、知识库搭建、多轮对话、生产部署
第十二章：实战二 ------ 代码助手 Agent
- 代码理解、工具链集成（运行代码/读写文件）、流式交互
第十三章：实战三 ------ 企业知识库问答
- 多源数据接入、混合检索、权限控制、可观测性
第十四章：可观测性、测试与生产运维
- LangSmith 深度使用、评估框架、性能调优、运维最佳实践
八、如何阅读
1. 推荐阅读路径
如果你是 LLM 应用开发新手，建议按章节顺序阅读，不要跳过第一部分------那些背景知识会在你后续遇到困惑时帮你找到方向。
如果你已经有过 LLM 应用开发经验，可以快速浏览第一部分建立对 LangChain.js 的整体印象，然后从第三章开始重点阅读。
如果你只是想解决某个具体问题，可以直接跳到相关章节。每章都尽量做到独立，必要时会标注前置依赖。
2. 关于代码示例
所有代码示例遵循以下原则：
- 所有代码都可以在 Node.js 20+ 环境下直接运行
- 较长的代码会分段呈现，并逐段解析
- 每章的完整代码示例可以在配套仓库中找到
bash
# 每章示例代码的运行方式统一如下：
cd chapter-XX
pnpm install
pnpm run dev3. 关于标注约定
文章中会使用以下几种特殊标注：
💡 提示：补充说明，帮助你更好地理解概念
⚠️ 注意：容易踩坑的地方，请格外留意
🔍 深入探讨：适合进阶读者的原理性内容，初次阅读可以跳过
🆚 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 开发世界的一块可靠的垫脚石。