langchainjs 解读
项目信息
- 项目名称：langchainjs
- 项目描述：LangChain.js 是一个 TypeScript 的 LLM 应用工程化框架，通过统一的 Runnable 接口将模型、工具、向量存储等组件组合成生产级 AI 应用。采用分层 monorepo 架构（核心抽象 → Agent 编排 → Provider 集成），40+ 包协同工作。
- 项目地址：https://github.com/langchain-ai/langchainjs
- 官方文档：https://docs.langchain.com/oss/javascript/langchain/overview
1. 项目概览
1.1 项目定位与核心价值
一句话定位：LangChain.js 是一个面向 TypeScript/JavaScript 生态的LLM 应用工程化框架——不是模型本身，而是让开发者能用统一、可组合的方式将 LLM、工具、向量数据库、记忆系统等"乐高积木"组装成生产级 AI 应用。
仓库规模：
| 维度 | 数值 |
|---|---|
| 总文件数 | 2,508 |
| TypeScript 源文件 | 2,053 |
| 总代码行 | 510,850 |
| 独立包数量 | 40+ (monorepo) |
| Provider 包数 | 33 |
| 核心包版本 | @langchain/core v1.1.48, langchain v1.4.4 |
1.2 核心痛点与解决方案
| 痛点 | LangChain.js 如何解决 |
|---|---|
| LLM 生态碎片化（30+ 提供商） | 统一的 BaseChatModel 接口，一行代码切换模型 |
| Agent 开发复杂度高（工具调用循环、状态管理） | createAgent API + 中间件管道 + LangGraph 状态图 |
| 缺少观测与调试能力 | 内置 Callbacks/Tracers + LangSmith 平台集成 |
| 多运行时兼容（Node/Deno/Bun/CF Workers） | 基于 Web Standards (ReadableStream, fetch) 的流抽象 |
1.3 目标用户
- LLM 应用开发者：需要快速构建 RAG、Agent、聊天机器人
- 框架集成商：需要将 LLM 能力嵌入现有 TypeScript 应用
- Python LangChain 用户的 JS 对应者：相同的抽象概念，不同的运行时
1.4 核心技术栈
| 层级 | 技术选型 |
|---|---|
| 语言 | TypeScript 6.0 (strict mode) |
| 运行时 | Node.js 20/22/24, Deno, Bun, Cloudflare Workers |
| 包管理 | pnpm 10.14 Monorepo + Turborepo |
| Schema 校验 | Zod v3/v4 + Standard Schema |
| Agent 编排 | LangGraph.js (StateGraph) |
| 测试 | Vitest 4.x |
| 工具链 | oxfmt + oxlint (Rust原生) |
1.5 架构选型对比
| 决策 | 选择 | 替代方案 | 权衡原因 |
|---|---|---|---|
| 仓库模式 | Monorepo | 多仓库 | 核心 API 变更能立即在所有 Provider 中反映 |
| Agent 引擎 | LangGraph.js | 自建 while 循环 | 状态图提供检查点、中断、流事件传播等高级特性 |
| Schema 系统 | Zod | 自建 Schema | Zod 是 TS 生态最成熟的运行时 schema，支持类型推导 |
| 旧版兼容 | langchain-classic 独立包 | 主包内条件分支 | 避免主包膨胀，让旧用户显式声明依赖 |
| Provider 独立 | 33 个独立 npm 包 | 单一大包 | 用户只需安装需要的，避免依赖膨胀 |
| 流抽象 | 自定义 IterableReadableStream | 直接使用 Node Stream | 需要同时兼容 Node、Browser、CF Workers、Deno |
2. 整体架构设计
2.1 架构概述
LangChain.js 采用 分层 + 插件化 Monorepo 架构，分为四层：
- 核心抽象层 (@langchain/core)：定义所有上层模块依赖的基础接口——
Runnable、BaseChatModel、StructuredTool、BaseMessage、BaseStore、回调系统等。这是整个框架的"语言"，所有 Provider 和上层包都只依赖这一层。 - Agent 编排层 (langchain)：基于 LangGraph.js 状态图引擎，提供
createAgent/ReactAgent高级 API。实现 ReAct (Reasoning + Acting) 模式，通过中间件 (Middleware) 管道实现横切关注点（工具调用、模型重试、人机协同等）。 - Provider 集成层 (libs/providers/langchain-*)：33 个独立的 npm 包，每个封装一个第三方服务的 BaseChatModel 实现（OpenAI、Anthropic、Google 等）或向量存储实现（Pinecone、Weaviate 等）。通过 peerDependency 依赖 @langchain/core。
- 基础设施层 (internal/)：构建工具、TypeScript 配置、标准测试套件等开发基础设施。
2.2 整体架构图
text
+===========================================================================+
| Agent 编排层 (Agent Orchestration) |
| +-----------------------------------+ +-----------------------------+ |
| | createAgent / ReactAgent | | Middleware Pipeline | |
| | [Model] -> [Tools] -> [Prompt] | | [beforeAgent] -> [after- | |
| | [responseFormat] -> [stateSchema] | | Model] -> [wrap*] -> ... | |
| +---------------+-------------------+ +-------------+---------------+ |
| | | |
+==================|=====================================|==================+
| |
v v
+===========================================================================+
| LangGraph.js (StateGraph Engine) |
| +-----------+ +----------+ +-----------+ +------------------------+ |
| | START |->| AgentNode|->| ToolNode |->| Conditional Edges | |
| | | | (Model) | | (execute) | | [hasToolCalls? -> | |
| | | | | | | | loop/end] | |
| +-----------+ +----------+ +-----------+ +------------------------+ |
+===========================================================================+
|
| (imports/extensions)
v
+===========================================================================+
| 核心抽象层 (@langchain/core) |
| +-------------+ +-------------+ +--------------+ +----------------+ |
| | Runnable | | Messages | | Tools | | Callbacks | |
| | Interface | | [Human, AI, | | [Structured | | [Manager, | |
| | [invoke, | | System, | | Tool, | | Tracer, | |
| | stream, | | Tool] | | DynamicTool] | | LogStream] | |
| | batch] | | | | | | | |
| +------+------+ +------+------+ +------+-------+ +-------+-------+ |
| | | | | |
| +------+------+ +------+------+ +------+-------+ +-------+-------+ |
| | BaseChatModel| | Embeddings | | VectorStore | | BaseStore | |
| | (LLM 抽象) | | (嵌入向量) | | (向量存储) | | (键值存储) | |
| +-------------+ +-------------+ +--------------+ +----------------+ |
+===========================================================================+
|
| (peerDependency: @langchain/core)
v
+===========================================================================+
| Provider 集成层 (33 packages) |
| +----------+ +----------+ +---------+ +----------+ +------------------+ |
| | OpenAI | |Anthropic | | Google | | Ollama | | Vector Stores... | |
| | [GPT-4o, | |[Claude, | |[Gemini, | | [local | | [Pinecone, | |
| | Embed] | | Messages]| | Vertex] | | models] | | Weaviate, Qdrant]| |
| +----------+ +----------+ +---------+ +----------+ +------------------+ |
+===========================================================================+
|
v
+===========================================================================+
| 基础设施层 (Infrastructure) |
| +----------------+ +------------------+ +---------------------------+ |
| | @langchain/ | | @langchain/ | | @langchain/ | |
| | build (tsdown) | | standard-tests | | tsconfig | |
| +----------------+ +------------------+ +---------------------------+ |
+===========================================================================+2.3 目录结构
shell
langchainjs/
├── libs/ # 【核心基建】所有源代码包主目录
│ │
│ ├── langchain-core/ # 【核心基建】@langchain/core - 核心抽象与接口层
│ │ ├── src/
│ │ │ ├── runnables/ # 【核心基建】Runnable 接口系统 (框架基石)
│ │ │ │ ├── base.ts # 【核心基建】Runnable 基类 + 12个组合原语 (3542行)
│ │ │ │ ├── types.ts # 【核心基建】RunnableInterface / RunnableConfig
│ │ │ │ ├── config.ts # 【核心基建】配置合并/打补丁/序列化
│ │ │ │ ├── graph.ts # 【核心基建】Runnable 依赖图 (可视化)
│ │ │ │ ├── router.ts # 【核心基建】RouterRunnable (动态路由)
│ │ │ │ ├── branch.ts # 【核心基建】RunnableBranch (条件分支)
│ │ │ │ ├── history.ts # 【核心基建】RunnableWithMessageHistory
│ │ │ │ ├── passthrough.ts # 【核心基建】RunnablePassthrough
│ │ │ │ ├── iter.ts # 【核心基建】异步迭代器/Generator工具
│ │ │ │ ├── wrappers.ts # 【核心基建】HTTP EventStream 包装器
│ │ │ │ └── tests/ # 【质量保证】Runnable 单元/流事件测试
│ │ │ ├── messages/ # 【核心基建】消息系统 (对话数据载体)
│ │ │ │ ├── base.ts # 【核心基建】BaseMessage 基类
│ │ │ │ ├── ai.ts # 【核心基建】AIMessage / AIMessageChunk
│ │ │ │ ├── human.ts # 【核心基建】HumanMessage
│ │ │ │ ├── system.ts # 【核心基建】SystemMessage
│ │ │ │ ├── tool.ts # 【核心基建】ToolMessage / ToolCall
│ │ │ │ ├── chat.ts # 【核心基建】ChatMessage (通用格式)
│ │ │ │ ├── function.ts # 【核心基建】FunctionMessage (旧版)
│ │ │ │ ├── transformers.ts # 【核心基建】消息格式转换器
│ │ │ │ ├── modifier.ts # 【核心基建】消息修饰器(filterMessages等)
│ │ │ │ ├── content/ # 【核心基建】多模态内容块定义
│ │ │ │ │ ├── index.ts # 【核心基建】ContentBlock 类型联合
│ │ │ │ │ └── data.ts # 【核心基建】图片URL/Base64/Audio/File块
│ │ │ │ ├── block_translators/ # 【核心基建】跨模型内容格式翻译(URL->Base64)
│ │ │ │ └── tests/ # 【质量保证】消息系统测试
│ │ │ ├── tools/ # 【核心基建】工具系统 (Agent 的能力来源)
│ │ │ │ ├── index.ts # 【核心基建】StructuredTool / DynamicTool
│ │ │ │ ├── types.ts # 【核心基建】工具类型定义 (含 ServerTool)
│ │ │ │ ├── utils.ts # 【核心基建】工具数据验证/解析工具
│ │ │ │ └── tests/ # 【质量保证】工具系统测试
│ │ │ ├── language_models/ # 【核心基建】语言模型抽象层
│ │ │ │ ├── base.ts # 【核心基建】BaseLanguageModel 基类
│ │ │ │ ├── chat_models.ts # 【核心基建】BaseChatModel (核心抽象)
│ │ │ │ ├── llms.ts # 【核心基建】BaseLLM (旧版补全接口)
│ │ │ │ ├── profile.ts # 【核心基建】模型 Profile (能力声明)
│ │ │ │ ├── structured_output.ts # 【核心基建】结构化输出管道组装
│ │ │ │ ├── stream.ts # 【核心基建】ChatModelStream (流事件)
│ │ │ │ ├── event.ts # 【核心基建】ChatModelStreamEvent 定义
│ │ │ │ ├── compat.ts # 【核心基建】旧版兼容层
│ │ │ │ └── utils.ts # 【核心基建】消息标准化工具
│ │ │ ├── callbacks/ # 【核心基建】回调系统 (可观测性根基)
│ │ │ │ ├── base.ts # 【核心基建】BaseCallbackHandler
│ │ │ │ ├── manager.ts # 【核心基建】CallbackManager (运行时管理)
│ │ │ │ ├── promises.ts # 【核心基建】异步回调消费
│ │ │ │ └── dispatch/ # 【核心基建】Web/Node 环境回调分发
│ │ │ ├── tracers/ # 【核心基建】追踪器 (LangSmith 集成)
│ │ │ │ ├── base.ts # 【核心基建】BaseTracer
│ │ │ │ ├── tracer_langchain.ts # 【核心基建】LangChainTracer (LangSmith)
│ │ │ │ ├── log_stream.ts # 【核心基建】LogStreamCallbackHandler
│ │ │ │ ├── event_stream.ts # 【核心基建】EventStreamCallbackHandler
│ │ │ │ ├── root_listener.ts # 【核心基建】RootListenersTracer
│ │ │ │ ├── console.ts # 【业务模块】ConsoleCallbackHandler
│ │ │ │ └── run_collector.ts # 【核心基建】RunCollectorCallbackHandler
│ │ │ ├── prompts/ # 【核心基建】Prompt 模板系统
│ │ │ │ ├── base.ts # 【核心基建】BasePromptTemplate
│ │ │ │ ├── chat.ts # 【核心基建】ChatPromptTemplate
│ │ │ │ ├── template.ts # 【核心基建】PromptTemplate (字符串)
│ │ │ │ ├── pipeline.ts # 【核心基建】PipelinePromptTemplate
│ │ │ │ ├── few_shot.ts # 【核心基建】FewShotPromptTemplate
│ │ │ │ └── image.ts # 【核心基建】ImagePromptTemplate
│ │ │ ├── output_parsers/ # 【核心基建】输出解析器
│ │ │ ├── document_loaders/ # 【核心基建】文档加载器基类
│ │ │ ├── documents/ # 【核心基建】Document / DocumentInterface
│ │ │ ├── retrievers/ # 【核心基建】检索器抽象 (BaseRetriever)
│ │ │ │ └── document_compressors/ # 【核心基建】文档压缩器 (ContextualCompression)
│ │ │ ├── embeddings.ts # 【核心基建】嵌入向量抽象类
│ │ │ ├── vectorstores.ts # 【核心基建】向量存储抽象 (VectorStore, 36K行)
│ │ │ ├── stores.ts # 【核心基建】BaseStore / InMemoryStore
│ │ │ ├── caches/ # 【核心基建】BaseCache (LLM响应缓存)
│ │ │ ├── memory.ts # 【核心基建】对话记忆/缓冲
│ │ │ ├── chat_history.ts # 【核心基建】聊天历史管理
│ │ │ ├── indexing/ # 【核心基建】文档索引系统
│ │ │ ├── structured_query/ # 【核心基建】结构化查询翻译器
│ │ │ ├── example_selectors/ # 【核心基建】示例选择器 (Few-shot)
│ │ │ ├── singletons/ # 【核心基建】全局单例 (AsyncLocalStorage)
│ │ │ ├── load/ # 【核心基建】序列化/反序列化 (Serializable)
│ │ │ ├── errors/ # 【核心基建】错误类型定义 (ModelAbortError等)
│ │ │ ├── types/ # 【核心基建】共享类型 (StreamEvent等)
│ │ │ ├── testing/ # 【工具集】测试工具 (FakeChatModel等)
│ │ │ │ └── index.ts # 【工具集】fakeModel / langchainMatchers
│ │ │ └── utils/ # 【工具集】通用工具集
│ │ │ ├── stream.ts # 【工具集】IterableReadableStream实现
│ │ │ ├── async_caller.ts # 【工具集】AsyncCaller (速率限制+重试)
│ │ │ ├── signal.ts # 【工具集】AbortSignal + raceWithSignal
│ │ │ ├── env.ts # 【工具集】环境变量安全读取
│ │ │ ├── json_schema.ts # 【工具集】JSON Schema工具
│ │ │ ├── hash.ts # 【工具集】哈希函数
│ │ │ ├── uuid/ # 【工具集】UUID v7 生成器
│ │ │ ├── jwt.ts # 【工具集】JWT 编解码
│ │ │ ├── math.ts # 【工具集】数学工具 (矩阵相似度)
│ │ │ ├── chunk_array.ts # 【工具集】数组分块
│ │ │ ├── format.ts # 【工具集】字符串格式化
│ │ │ ├── function_calling.ts # 【工具集】函数调用格式转换
│ │ │ ├── standard_schema.ts # 【工具集】Standard Schema互操作
│ │ │ ├── tiktoken.ts # 【工具集】Token计数 (tiktoken)
│ │ │ ├── event_source_parse.ts # 【工具集】SSE解析器
│ │ │ ├── json_patch.ts # 【工具集】JSON Patch (RFC 6902)
│ │ │ ├── testing/ # 【工具集】测试辅助 (FakeChatModel)
│ │ │ └── types/ # 【工具集】类型工具 (Zod互操作等)
│ │ └── package.json # 【配置】96 个 exports 路径 (精细 tree-shaking)
│ │
│ ├── langchain/ # 【业务模块】langchain 主包 - Agent 编排层
│ │ ├── src/
│ │ │ ├── index.ts # 【业务模块】主入口 (Messages/Tools/Agents重导出)
│ │ │ ├── browser.ts # 【业务模块】浏览器环境入口
│ │ │ ├── agents/ # 【业务模块】Agent 系统 (createAgent)
│ │ │ │ ├── index.ts # 【业务模块】createAgent (13个类型重载)
│ │ │ │ ├── ReactAgent.ts # 【业务模块】ReactAgent 核心 (StateGraph构建)
│ │ │ │ ├── middleware.ts # 【业务模块】createMiddleware 工厂函数
│ │ │ │ ├── types.ts # 【业务模块】AgentTypeConfig / CreateAgentParams
│ │ │ │ ├── errors.ts # 【业务模块】Agent 错误类型
│ │ │ │ ├── responses.ts # 【业务模块】响应格式策略 (ToolStrategy等)
│ │ │ │ ├── stream.ts # 【业务模块】Agent 流事件类型
│ │ │ │ ├── runtime.ts # 【业务模块】Runtime 上下文类型
│ │ │ │ ├── annotation.ts # 【业务模块】AgentState Schema 构建
│ │ │ │ ├── utils.ts # 【业务模块】Agent 工具函数
│ │ │ │ ├── model.ts # 【业务模块】AgentLanguageModelLike
│ │ │ │ ├── middleware/ # 【业务模块】内置中间件集合
│ │ │ │ │ ├── types.ts # 【业务模块】AgentMiddleware 接口定义
│ │ │ │ │ ├── utils.ts # 【业务模块】getHookConstraint合并工具
│ │ │ │ │ ├── provider.ts # 【业务模块】Provider 中间件 (模型注入)
│ │ │ │ │ ├── toolCalling.ts # 【业务模块】工具调用中间件
│ │ │ │ │ ├── context.ts # 【业务模块】上下文注入中间件
│ │ │ │ │ ├── dynamic.ts # 【业务模块】动态模型选择中间件
│ │ │ │ │ ├── humanInTheLoop.ts # 【业务模块】人机协同中间件
│ │ │ │ │ ├── modelFallback.ts # 【业务模块】模型降级中间件
│ │ │ │ │ ├── modelRetry.ts # 【业务模块】模型重试中间件
│ │ │ │ │ ├── interrupt.ts # 【业务模块】中断中间件
│ │ │ │ │ ├── limit.ts # 【业务模块】调用限制中间件
│ │ │ │ │ ├── resume.ts # 【业务模块】恢复中间件
│ │ │ │ │ ├── summarize.ts # 【业务模块】对话摘要 (上下文压缩)
│ │ │ │ │ ├── todo.ts # 【业务模块】待办列表中间件
│ │ │ │ │ └── providerStrategy.ts # 【业务模块】Provider 策略中间件
│ │ │ │ └── nodes/ # 【业务模块】StateGraph 节点实现
│ │ │ │ ├── AgentNode.ts # 【业务模块】AgentNode (模型调用节点)
│ │ │ │ ├── ToolNode.ts # 【业务模块】ToolNode (工具执行节点)
│ │ │ │ ├── BeforeAgentNode.ts # 【业务模块】beforeAgent 钩子节点
│ │ │ │ ├── BeforeModelNode.ts # 【业务模块】beforeModel 钩子节点
│ │ │ │ ├── AfterModelNode.ts # 【业务模块】afterModel 钩子节点
│ │ │ │ ├── AfterAgentNode.ts # 【业务模块】afterAgent 钩子节点
│ │ │ │ ├── types.ts # 【业务模块】节点类型定义
│ │ │ │ └── utils.ts # 【业务模块】节点工具函数
│ │ │ ├── chat_models/ # 【业务模块】通用聊天模型入口
│ │ │ │ └── universal.ts # 【业务模块】initChatModel("provider:model")
│ │ │ ├── tools/ # 【业务模块】Headless Tool 工具
│ │ │ │ ├── index.ts # 【业务模块】工具导出
│ │ │ │ └── headless.ts # 【业务模块】tool() 辅助函数 (无实现工具)
│ │ │ ├── hub/ # 【业务模块】LangChain Hub 集成
│ │ │ ├── prompts/ # 【业务模块】高级 Prompt 模板
│ │ │ │ └── selectors/ # 【业务模块】Prompt 选择器
│ │ │ ├── storage/ # 【业务模块】持久化存储适配器
│ │ │ │ ├── encoder_backed.ts # 【业务模块】编码器存储
│ │ │ │ ├── file_system.ts # 【业务模块】文件系统存储
│ │ │ │ └── in_memory.ts # 【业务模块】内存存储
│ │ │ └── load/ # 【业务模块】Hub/JSON 加载器
│ │ └── package.json # 【配置】langchain 包 (peer: @langchain/core)
│ │
│ ├── langchain-classic/ # 【废弃】经典 Chains 实现 (向后兼容)
│ │ └── src/
│ │ ├── chains/ # 【废弃】Chain 系统 (LLMChain/ConversationChain)
│ │ ├── agents/ # 【废弃】旧版 Agent (Executor 模式)
│ │ ├── memory/ # 【废弃】旧版 Memory (Buffer/Summary)
│ │ ├── tools/ # 【废弃】旧版工具 (ChainTool等)
│ │ ├── output_parsers/ # 【废弃】旧版输出解析器
│ │ ├── embeddings/ # 【废弃】旧版嵌入 (已移至 core)
│ │ ├── vectorstores/ # 【废弃】旧版向量存储 (已移至 providers)
│ │ ├── retrievers/ # 【废弃】旧版检索器
│ │ ├── document_loaders/ # 【废弃】旧版文档加载器
│ │ ├── document_transformers/ # 【废弃】旧版文档变换器
│ │ ├── prompts/ # 【废弃】旧版 Prompt 模板
│ │ ├── callbacks/ # 【废弃】旧版回调
│ │ ├── schema/ # 【废弃】旧版 Schema
│ │ ├── smith/ # 【废弃】LangSmith 实验
│ │ ├── hub/ # 【废弃】旧版 Hub 集成
│ │ ├── experimental/ # 【废弃】实验性功能
│ │ └── evaluation/ # 【废弃】评估工具
│ │
│ ├── langchain-textsplitters/ # 【工具集】@langchain/textsplitters
│ │ └── src/ # 【工具集】文本分割器 (Recursive/Markdown等)
│ │
│ ├── langchain-mcp-adapters/ # 【业务模块】MCP 协议适配器
│ │ └── src/ # 【业务模块】MCP Client/Server 集成
│ │
│ └── providers/ # 【业务模块】提供商集成 (33个独立包)
│ ├── langchain-openai/ # 【业务模块】OpenAI (GPT-4o, Whisper, Embed)
│ ├── langchain-anthropic/ # 【业务模块】Anthropic (Claude Opus/Sonnet)
│ ├── langchain-google/ # 【业务模块】Google AI (Gemini 等)
│ ├── langchain-google-genai/ # 【业务模块】Google GenAI SDK
│ ├── langchain-google-vertexai/ # 【业务模块】Google Vertex AI
│ ├── langchain-google-vertexai-web/ # 【业务模块】Vertex AI Web 环境
│ ├── langchain-google-common/ # 【工具集】Google 提供商共享代码
│ ├── langchain-google-gauth/ # 【工具集】Google 认证 (Service Account)
│ ├── langchain-google-webauth/ # 【工具集】Google OAuth Web 认证
│ ├── langchain-google-cloud-sql-pg/ # 【业务模块】Google Cloud SQL (PGVector)
│ ├── langchain-aws/ # 【业务模块】AWS Bedrock
│ ├── langchain-cohere/ # 【业务模块】Cohere
│ ├── langchain-deepseek/ # 【业务模块】DeepSeek
│ ├── langchain-groq/ # 【业务模块】Groq Cloud
│ ├── langchain-ollama/ # 【业务模块】Ollama (本地LLM)
│ ├── langchain-mistralai/ # 【业务模块】Mistral AI
│ ├── langchain-together-ai/ # 【业务模块】Together AI
│ ├── langchain-fireworks/ # 【业务模块】Fireworks AI
│ ├── langchain-xai/ # 【业务模块】xAI (Grok)
│ ├── langchain-ibm/ # 【业务模块】IBM Watson
│ ├── langchain-perplexity/ # 【业务模块】Perplexity
│ ├── langchain-openrouter/ # 【业务模块】OpenRouter
│ ├── langchain-cloudflare/ # 【业务模块】Cloudflare Workers AI
│ ├── langchain-exa/ # 【业务模块】Exa 搜索
│ ├── langchain-tavily/ # 【业务模块】Tavily 搜索
│ ├── langchain-pinecone/ # 【业务模块】Pinecone 向量库
│ ├── langchain-weaviate/ # 【业务模块】Weaviate 向量库
│ ├── langchain-qdrant/ # 【业务模块】Qdrant 向量库
│ ├── langchain-pgvector/ # 【业务模块】PGVector (PostgreSQL)
│ ├── langchain-mongodb/ # 【业务模块】MongoDB Atlas Vector
│ ├── langchain-redis/ # 【业务模块】Redis 向量存储
│ ├── langchain-neo4j/ # 【业务模块】Neo4j 图数据库
│ └── langchain-turbopuffer/ # 【业务模块】Turbopuffer
│
├── internal/ # 【工具集】内部构建/测试基础设施
│ ├── build/ # 【工具集】@langchain/build (tsdown构建)
│ ├── tsconfig/ # 【工具集】@langchain/tsconfig (共享TS配置)
│ ├── standard-tests/ # 【工具集】标准测试套件 (ChatModelUnitTests等)
│ ├── test-helpers/ # 【工具集】测试辅助工具
│ └── model-profiles/ # 【工具集】模型 Profile 生成
│
├── examples/ # 【配置】10个示例项目
├── dependency_range_tests/ # 【配置】依赖版本范围测试 (Docker)
├── environment_tests/ # 【配置】多环境兼容性测试 (Docker)
├── docs/ # 【配置】文档源码
├── .github/ # 【配置】CI/CD、Issue/PR模板
├── .changeset/ # 【配置】Changeset 版本管理
│
├── package.json # 【配置】根 monorepo 配置 (pnpm+turbo)
├── pnpm-workspace.yaml # 【配置】工作区: libs/*, libs/providers/*, internal/*
├── turbo.json # 【配置】Turborepo 构建任务编排
├── AGENTS.md # 【配置】AI Agent 开发指南
├── CONTRIBUTING.md # 【配置】贡献者指南
├── README.md # 【配置】项目 README
├── LICENSE # 【配置】MIT 许可证
└── deno.json # 【配置】Deno 运行时兼容配置3. 模块依赖与调用关系
3.1 全局入口与核心路由
逻辑说明：用户通过 langchain 包的 createAgent() 入口创建 Agent。createAgent 内部通过 ReactAgent 构造器构建一个 LangGraph StateGraph，注册 AgentNode（模型调用节点）和 ToolNode（工具执行节点），并注入中间件管道。Agent 的核心执行循环是：接收用户消息 → AgentNode 调用 LLM → 检查是否有工具调用 → 有则进入 ToolNode 执行 → 返回结果 → AgentNode 再次调用 LLM → 直到没有工具调用 → 返回最终回答。
调用拓扑 (plainText)：
text
createAgent(params) (libs/langchain/src/agents/index.ts)
+-- ReactAgent.constructor() (libs/langchain/src/agents/ReactAgent.ts)
|
+---> createAgentState() (annotation.ts) - 合并 Agent 状态 + 中间件状态
|
+---> new StateGraph() (LangGraph.js) - 创建状态图
| |
| +---> .addNode(AGENT_NODE_NAME, AgentNode) - 注册模型调用节点
| +---> .addNode(TOOLS_NODE_NAME, ToolNode) - 注册工具执行节点
| +---> .addNode("beforeAgent", BeforeAgentNode) - 中间件前置钩子
| +---> .addNode("beforeModel", BeforeModelNode) - 中间件模型前钩子
| +---> .addNode("afterModel", AfterModelNode) - 中间件模型后钩子
| +---> .addNode("afterAgent", AfterAgentNode) - 中间件后置钩子
| +---> .addEdge(START, "beforeAgent")
| +---> .addEdge("beforeAgent", "beforeModel")
| +---> .addEdge("beforeModel", AGENT_NODE_NAME)
| +---> .addConditionalEdges(AGENT_NODE_NAME, ...) - 条件路由
| +---> .addEdge(TOOLS_NODE_NAME, "beforeModel")
| |
| +---> .compile() -> CompiledStateGraph
|
+---> AgentNode.invoke()
| +---> initChatModel(model) - 模型初始化/解析
| +---> wrapModelCall (middleware chain) - 中间件管道包装
| +---> model.invoke(messages, tools, ...) - 实际 LLM 调用
| +---> responseFormat 处理 - 结构化输出解析
|
+---> ToolNode.invoke()
+---> wrapToolCall (middleware chain) - 中间件工具包装
+---> tool.invoke(args, config) - 实际工具执行
user.invoke() / user.stream()
+-- CompiledStateGraph.invoke() / .stream()
+-- AgentNode -> ToolNode -> AgentNode -> ... -> END3.2 核心业务实体与关联
实体定义：
- Agent：智能体实例，封装了模型 + 工具 + 中间件 + 状态的完整配置
- Message：对话消息，包括 HumanMessage（用户输入）、AIMessage（模型回复，含 tool_calls）、ToolMessage（工具执行结果）、SystemMessage（系统提示）
- Tool：可被 Agent 调用的工具，由 Zod Schema 定义输入格式
- Middleware：横切关注点处理器，能在 Agent 生命周期的 6 个钩子点介入
- State：Agent 运行时状态，包含 messages 数组、结构化响应、中间件自定义状态
- RunnableConfig：调用配置，包含 callbacks、tags、metadata、recursionLimit 等
实体引用拓扑 (plainText)：
text
[ReactAgent] 1 -----> 1 [CompiledStateGraph] (LangGraph)
|
+-- 1 -----> N [Middleware]
|
+-- 1 -----> N [Tool] (ClientTool | ServerTool)
|
+-- 1 -----> 1 [BaseChatModel] (LLM)
|
+-- 1 -----> 1 [AgentState]
|
+-- 1 -----> N [BaseMessage]
| |
| +-- [HumanMessage]
| +-- [AIMessage]
| | +-- N [ToolCall]
| +-- [ToolMessage]
| +-- [SystemMessage]
|
+-- 1 -----> 1 [structuredResponse]? (Zod schema output)
[BaseChatModel] 1 <--extends-- N [Provider Models]
|
+-- [ChatOpenAI] (@langchain/openai)
+-- [ChatAnthropic] (@langchain/anthropic)
+-- [ChatGoogleGenerativeAI] (@langchain/google-genai)
+-- ... (30+ providers)
[Tool] 1 ---> 1 [Zod Schema] (参数定义)
[Middleware] 1 ---> 1 [StateSchema]? (可选自定义状态)
[Middleware] 1 ---> N [Tool]? (可选注册工具)4. 核心模块详解
模块一：Runnable 系统 (@langchain/core/runnables)
设计说明：Runnable 是 LangChain.js 最核心的抽象接口，所有组件（ChatModel、Tool、Chain、Retriever）都实现了 RunnableInterface。它定义了三个核心方法：invoke（单次调用）、stream（流式输出）、batch（批量调用）。Runnable 基类提供了丰富的组合原语：RunnableSequence（管道串联）、RunnableMap/RunnableParallel（并行执行）、RunnableBranch（条件路由）、RunnableWithFallbacks（降级策略）、RunnableBinding（参数绑定）。
内部结构图 (plainText)：
text
+-----------------------------------------------------------------------+
| RunnableInterface<In, Out, Config> |
| +invoke(input, config?): Promise<Out> |
| +stream(input, config?): Promise<IterableReadableStream<Out>> |
| +batch(inputs[], config?): Promise<Out[]> |
| +transform(generator, config): AsyncGenerator<Out> |
+-----------------------------------+-----------------------------------+
| implements
+-------------------------+--------------------------+
| | |
+---------v--------+ +------------v-----------+ +-----------v-----------+
| Runnable | | RunnableBinding | | RunnableLambda |
| (Base Class) | | (参数绑定/工具绑定) | | (函数式包装) |
| +pipe() | | +bound: Runnable | | +func: Function |
| +withFallbacks() | | +bind(args): Binding | | +invoke() / .stream() |
| +withConfig() | +------------------------+ +------------------------+
| +withRetry() |
+--------+---------+
|
+----+----+------+----------+----------+
| | | | |
+---v--+ +---v--+ +-v------+ +v-------+ +v--------+
|Seq- | |Map/ | |Branch | |Assign | |History |
|uence | |Par- | |(条件) | |(字段 | |(消息 |
|(串行) | |allel | | | | 赋值) | | 历史) |
+------+ +------+ +--------+ +--------+ +---------+模块二：ReactAgent 与中间件系统 (langchain/agents)
设计说明：ReactAgent 是整个框架的"大脑"，基于 LangGraph StateGraph 实现 ReAct 模式。其核心设计理念是中间件管道——通过 6 个生命周期钩子（beforeAgent、beforeModel、wrapModelCall、afterModel、wrapToolCall、afterAgent）允许开发者以洋葱模型方式介入 Agent 行为。每个中间件还可以注册自己的 State Schema（持久化状态）、Context Schema（只读上下文）、Tools（额外工具）和 StreamTransformers（流变换器）。Agent 内部以 StateGraph 的方式编排这些节点：START → beforeAgent → beforeModel → AgentNode(model) → {tools? → ToolNode → beforeModel} → afterModel → afterAgent → END。
内部结构图 (plainText)：
text
+=======================================================================+
| ReactAgent<Types> |
| +options: CreateAgentParams |
| +#graph: CompiledStateGraph (LangGraph) |
| +invoke(state): Promise<MergedAgentState> |
| +stream(state, streamMode?): Promise<IterableReadableStream> |
+-----------------------------------+-----------------------------------+
|
(内部 StateGraph 节点编排)
|
+-------+ +-----------+ +----------+ +----------+ +-------+
| START |--->| beforeAgent|--->|beforeModel|--->|AgentNode |--->| END |
+-------+ +-----+-----+ +-----+----+ +-----+----+ +-------+
| | |
| | | (has tool calls?)
| | +------v-------+
| | | ToolNode |
| | | (execute) |
| | +------+-------+
| | |
| +<---- (loop)---+
| (no tool calls)
v |
+-----+-----+ v
| afterAgent |<---- (done) ----+
+-----+-----+
|
v
+-----+
| END |
+-----+
Middleware Hook Pipeline (洋葱模型):
beforeAgent -> beforeModel -> [wrapModelCall -> model.invoke()] -> afterModel -> wrapToolCall -> afterAgent
(每个 wrap* hook 可以多层嵌套，先注册的中间件在最外层)模块三：消息系统 (@langchain/core/messages)
设计说明：消息系统是 LangChain 的数据传输层。所有与 LLM 的交互都通过消息对象进行。核心类型包括
HumanMessage（用户输入）、AIMessage（模型回复，含可选的tool_calls和contentBlocks）、ToolMessage（工具执行结果，含tool_call_id关联）、SystemMessage（系统提示）。v1 中新增了多模态内容块（contentBlocks），支持文本、图片（URL/Base64）、音频等多种内容格式的统一表示和跨模型翻译。内部结构图 (plainText)：
text
+-----------------------------------------------------------------------+
| BaseMessage |
| +content: string | ContentBlock[] |
| +contentBlocks: ContentBlock[] (lazy parsed) |
| +additional_kwargs?: Record |
| +response_metadata?: Record |
| +id?: string |
| +name?: string |
+-----------------------------------+-----------------------------------+
| | |
+-----------v------+ +--------v--------+ +-------v---------+
| HumanMessage | | AIMessage | | SystemMessage |
| (用户输入) | | (模型回复) | | (系统提示) |
| | | +tool_calls?: | +-----------------+
| | | ToolCall[] |
+------------------+ | +usage_metadata?|
| +contentBlocks |
+--------+--------+
|
+--------v--------+
| ToolMessage |
| (工具执行结果) |
| +tool_call_id |
| +content: string|
+-----------------+
ContentBlock Types (多模态内容):
[TextContentBlock] [ImageURLBlock] [ImageBase64Block] [AudioBlock] [FileBlock]
| | | | |
+--- block_translators/ (跨模型格式翻译器，如 URL->Base64 转换)5. 关键数据流程
场景说明
用户调用 Agent 进行工具增强问答：用户输入 "What's the weather in San Francisco?" → Agent 将消息传递给 LLM → LLM 决定需要调用天气查询工具 → Agent 执行工具 → 工具返回天气数据 → Agent 将结果再次传给 LLM → LLM 生成自然语言回答 → 返回给用户。
流转时序图
6. 接口与契约规范 (Interface & Contract Specs)
6.1 核心内部模块契约 (TypeScript Interfaces)
typescript
/**
* Runnable 接口 - LangChain 最核心的抽象
* 所有组件（ChatModel、Tool、Retriever、Chain）都实现此接口
*/
export interface RunnableInterface<
RunInput = any,
RunOutput = any,
CallOptions extends RunnableConfig = RunnableConfig,
> extends SerializableInterface {
lc_serializable: boolean;
invoke(input: RunInput, options?: Partial<CallOptions>): Promise<RunOutput>;
batch(
inputs: RunInput[],
options?: Partial<CallOptions> | Partial<CallOptions>[],
batchOptions?: RunnableBatchOptions
): Promise<(RunOutput | Error)[]>;
stream(
input: RunInput,
options?: Partial<CallOptions>
): Promise<IterableReadableStreamInterface<RunOutput>>;
transform(
generator: AsyncGenerator<RunInput>,
options: Partial<CallOptions>
): AsyncGenerator<RunOutput>;
getName(suffix?: string): string;
}
/**
* Agent 中间件接口 - 洋葱模型钩子系统
*/
export interface AgentMiddleware<
TSchema extends StateDefinitionInit | undefined = any,
TContextSchema extends InteropZodObject | ... | undefined = any,
TFullContext = any,
TTools extends readonly (ClientTool | ServerTool)[] = readonly (ClientTool | ServerTool)[],
TStreamTransformers extends ReadonlyArray<() => StreamTransformer<any>> = readonly [],
> {
readonly [MIDDLEWARE_BRAND]: true;
name: string;
stateSchema?: TSchema;
contextSchema?: TContextSchema;
tools?: TTools;
streamTransformers?: TStreamTransformers;
/** 工具调用包装器 */
wrapToolCall?: WrapToolCallHook<TSchema, TFullContext>;
/** 模型调用包装器 */
wrapModelCall?: WrapModelCallHook<TSchema, TFullContext>;
/** Agent 调用前钩子 */
beforeAgent?: BeforeAgentHook<TSchema, TFullContext>;
/** 模型调用前钩子 */
beforeModel?: BeforeModelHook<TSchema, TFullContext>;
/** 模型调用后钩子 */
afterModel?: AfterModelHook<TSchema, TFullContext>;
/** Agent 调用后钩子 */
afterAgent?: AfterAgentHook<TSchema, TFullContext>;
}
/**
* Chat Model 核心接口
*/
export abstract class BaseChatModel<
CallOptions extends BaseChatModelCallOptions = BaseChatModelCallOptions,
OutputMessageType extends BaseMessageChunk = AIMessageChunk,
> extends BaseLanguageModel<OutputMessageType, CallOptions> {
abstract _llmType(): string;
/** 绑定工具到模型 */
bindTools(tools: BindToolsInput[], kwargs?: Partial<CallOptions>): RunnableBinding;
/** 结构化输出 */
withStructuredOutput<
RunOutput extends Record<string, any> = Record<string, any>,
>(outputSchema: InteropZodType<RunOutput> | SerializableSchema, ...): Runnable<...>;
/** 获取模型标识参数 */
_identifyingParams(): Record<string, any>;
/** 获取 LangSmith 追踪参数 */
_getLsParams(options: this["ParsedCallOptions"]): LangSmithParams;
}
/**
* Tool 核心接口
*/
export abstract class StructuredTool<
SchemaT = ToolInputSchemaBase,
> extends BaseLangChain<...> {
abstract name: string;
abstract description: string;
abstract schema: SchemaT | InteropZodType;
/** 工具调用方法 */
abstract _call(
arg: ToolInputSchemaOutputType<SchemaT>,
runManager?: CallbackManagerForToolRun,
config?: ToolRunnableConfig
): Promise<ToolReturnType>;
}
/**
* 键值存储抽象
*/
export abstract class BaseStore<K, V> extends Serializable {
abstract mget(keys: K[]): Promise<(V | undefined)[]>;
abstract mset(keyValuePairs: [K, V][]): Promise<void>;
abstract mdelete(keys: K[]): Promise<void>;
abstract yieldKeys(prefix?: string): AsyncGenerator<K | string>;
}6.2 createAgent API 契约 (TypeScript)
typescript
/**
* createAgent 核心参数类型
*/
export interface CreateAgentParams<
StructuredResponseFormat extends Record<string, any> = Record<string, any>,
TStateSchema extends StateDefinitionInit | undefined = undefined,
ContextSchema extends AnyAnnotationRoot | InteropZodObject = AnyAnnotationRoot,
TResponseFormat = any,
> {
/** LLM 模型：字符串标识("openai:gpt-4o")或实例 */
model: string | BaseChatModel | ((state: any, runtime: Runtime) => BaseChatModel);
/** 可用工具列表 */
tools?: readonly (ClientTool | ServerTool)[];
/** 系统提示词 */
prompt?: string | SystemMessage | ((state: any) => string | SystemMessage);
/** 结构化输出格式 (Zod Schema 或 JSON Schema) */
responseFormat?: InteropZodType<StructuredResponseFormat> | JsonSchemaFormat | ToolStrategy;
/** 自定义状态 Schema (扩展 Agent 状态) */
stateSchema?: TStateSchema;
/** 中间件数组 */
middleware?: readonly AnyAgentMiddleware[];
/** 上下文 Schema */
contextSchema?: ContextSchema;
/** Agent 名称 */
name?: string;
/** 工具行为版本 ("v1" | "v2") */
version?: "v1" | "v2";
/** 流变换器 */
streamTransformers?: ReadonlyArray<() => StreamTransformer<any>>;
/** 检查点保存器 (持久化状态) */
checkpointer?: BaseCheckpointSaver;
/** 存储后端 (长期记忆) */
store?: BaseStore;
/** LangGraph 默认配置 */
defaultConfig?: RunnableConfig;
}7. 快速开始
7.1 环境配置
bash
# 需要 Node.js >= 20, pnpm 10.14
node -v # 应 >= 20
pnpm -v # 应 >= 10.14
# 安装依赖
pnpm install
# 构建核心包
pnpm --filter @langchain/core build7.2 典型用例
typescript
import { createAgent, tool } from "langchain";
import { z } from "zod";
// 1. 初始化模型
const model = "openai:gpt-4o";
// 2. 定义工具
const weatherTool = tool(
({ city }) => `Weather in ${city}: 72°F, sunny`,
{ name: "get_weather", schema: z.object({ city: z.string() }) }
);
// 3. 创建 Agent
const agent = createAgent({
model,
tools: [weatherTool],
prompt: "You are a helpful weather assistant.",
});
// 4. 调用
const result = await agent.invoke({
messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
});7.3 关键命令
bash
pnpm test # 运行所有测试
pnpm lint # 代码检查
pnpm format # 代码格式化
pnpm --filter langchain build # 构建主包
pnpm --filter @langchain/core test # 运行核心包测试