核心定位与价值主张

LangChain.js 的核心价值在于提供一个灵活的框架，使开发者能够：

• 链式组合：将多个组件组合成复杂的工作流
• 第三方集成：轻松接入各种 LLM 提供商和工具
• 模块化设计：各组件独立可替换，便于维护和升级
• 开发效率：提供开箱即用的抽象，加速应用开发

生态系统架构

LangChain.js 采用多包架构，将不同功能模块分离到独立的包中，以提高可维护性和灵活度。

graph TD
    A[用户应用] --> B[langchain 主包]
    A --> C[@langchain/classic 经典包]
    B --> D[@langchain/core 核心包]
    C --> D
    B --> E[@langchain/textsplitters 文本分割]
    D --> F[Provider 包]
    F --> G[langchain-openai]
    F --> H[langchain-anthropic]
    F --> I[langchain-google-common]

核心包结构

@langchain/core 核心包

@langchain/core 是整个生态系统的基础库，定义了 LangChain 的核心抽象和接口。它包含：

• 消息系统：定义各种消息类型和消息处理逻辑
• 语言模型接口：统一的 LLM 调用抽象
• 工具系统：定义工具的创建和调用方式
• 输出解析器：将 LLM 输出解析为结构化数据
• 事件系统：支持流式事件和状态更新

资料来源：libs/langchain-core/README.md

langchain 主包

langchain 是面向现代 Agent 开发的主包，提供了构建 AI Agent 的高级 API。

#### 主要特性

#### Agent 架构

graph LR
    A[用户输入] --> B[Agent 核心]
    B --> C[工具调用]
    C --> D[外部服务]
    D --> B
    B --> E[响应输出]

langchain 包支持通过中间件扩展功能，例如人机交互中间件（Human-in-the-Loop），允许在 Agent 执行过程中进行干预和控制。

资料来源：libs/langchain/README.md, libs/langchain/src/agents/middleware/hitl.ts:1-100

@langchain/classic 经典包

@langchain/classic 是为了向后兼容而保留的包，包含从 LangChain v0.x 移出的功能。

#### 何时使用

建议使用 @langchain/classic 的场景：

#### 何时不使用

对于新项目，应使用 langchain v1.0，新 API 提供：

• 更清晰的 createAgent 构建方式
• 更好的性能优化
• 更聚焦的 API 表面
• 活跃的开发支持

#### 迁移路径

// 旧导入（已弃用）
import { LLMChain } from "langchain";

// 新导入
import { LLMChain } from "@langchain/classic";

资料来源：libs/langchain-classic/README.md, libs/langchain-classic/src/util/entrypoint_deprecation.ts:1-50

@langchain/textsplitters 文本分割包

@langchain/textsplitters 提供各种文本分割器实现，是 RAG（检索增强生成）管道的常用组件。

#### 支持的分割模式

#### 基本使用

import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";

const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
});

const output = await splitter.createDocuments([htmlText]);

资料来源：libs/langchain-textsplitters/README.md, examples/src/langchain-classic/indexes/html_text_splitter.ts:1-50

Provider 包生态

Provider 包提供了与各个 LLM 服务商的集成。

主要 Provider

Provider 架构

graph TD
    A[统一接口] --> B[langchain-core]
    B --> C[OpenAI 适配器]
    B --> D[Anthropic 适配器]
    B --> E[Google 适配器]
    C --> F[OpenAI API]
    D --> G[Anthropic API]
    E --> H[Google API]

每个 Provider 包都实现了统一的接口规范，确保应用可以在不同 LLM 之间切换而不需要大量代码改动。

资料来源：libs/providers/langchain-openai/src/chat_models/index.ts, libs/providers/langchain-anthropic/src/chat_models.ts, libs/providers/langchain-google-common/src/utils/anthropic.ts

工具调用支持

Provider 包普遍支持：

• 函数调用：通过 withStructuredOutput() 实现结构化输出
• 工具使用：内置工具调用和工具管理
• 流式处理：支持流式响应和增量输出

import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(
  async (input) => `Weather in ${input.location}`,
  {
    name: "get_weather",
    description: "Get weather for a location",
    schema: z.object({ location: z.string() }),
  }
);

开发工具与模板

创建新集成

create-langchain-integration 提供了创建新 Provider 包的标准模板：

npm install @langchain/<PACKAGE_NAME>

新包需要配置与 @langchain/core 的版本对齐：

{
  "dependencies": {
    "@langchain/<PACKAGE_NAME>": "^0.0.0",
    "@langchain/core": "^0.3.0"
  },
  "resolutions": {
    "@langchain/core": "^0.3.0"
  }
}

资料来源：libs/create-langchain-integration/template/README.md

核心抽象与接口

消息系统

LangChain.js 定义了完整的消息类型体系：

import { AIMessageChunk } from '@langchain/core/messages';
import { concat } from '@langchain/core/utils';

资料来源：libs/langchain-core/src/messages/block_translators/openai.ts, libs/langchain-core/src/testing/matchers.ts:1-100

事件系统

核心库提供了完整的事件系统，支持流式处理和状态追踪：

interface ContentBlockDeltaEvent {
  event: "content-block-delta";
  index: number;
  delta: ContentBlockDelta;
}

资料来源：libs/langchain-core/src/language_models/event.ts

索引系统

LangChain.js 提供了文档索引的基础设施，用于 RAG 场景：

graph LR
    A[文档] --> B[DocumentLoader]
    B --> C[TextSplitter]
    C --> D[Document 数组]
    D --> E[RecordManager]
    D --> F[VectorStore]

索引功能使用 RecordManager 追踪文档状态，支持增量更新和删除管理。

资料来源：libs/langchain-core/src/indexing/base.ts

版本演进与兼容性

v1.0 架构变化

LangChain v1.0 进行了重要的架构调整：

1. 核心功能下沉：@langchain/core 成为基础抽象层
2. 功能分离：@langchain/classic 承接遗留功能
3. 现代 API：langchain 主包专注于 Agent 构建
4. Provider 解耦：各 Provider 独立维护

弃用警告

导入路径迁移会产生弃用警告：

// 旧路径
import { SomeClass } from "langchain";

// 新路径
import { SomeClass } from "@langchain/classic";

可通过环境变量抑制警告：

LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS=true

资料来源：libs/langchain-classic/src/util/entrypoint_deprecation.ts

安装与依赖管理

推荐的依赖配置

为确保各包之间的 @langchain/core 版本一致，建议在项目中添加版本锁定：

{
  "resolutions": {
    "@langchain/core": "^0.3.0"
  },
  "overrides": {
    "@langchain/core": "^0.3.0"
  },
  "pnpm": {
    "overrides": {
      "@langchain/core": "^0.3.0"
    }
  }
}

开发依赖

克隆仓库后的标准开发流程：

pnpm install
pnpm build
pnpm test
pnpm lint && pnpm format

资料来源：libs/langchain-textsplitters/README.md, libs/create-langchain-integration/template/README.md

总结

LangChain.js 生态系统通过模块化设计提供了灵活的 LLM 应用构建能力：

• 核心层：@langchain/core 提供统一抽象
• 主包：langchain 专注现代 Agent 开发
• 兼容层：@langchain/classic 支持平滑迁移
• 集成层：多种 Provider 包连接各 LLM 服务商
• 工具层：文本分割等实用工具支持 RAG 场景

这种架构既保证了新项目的开发效率，也照顾了现有代码的向后兼容性，使 LangChain.js 成为构建 LLM 应用的可靠选择。

概述

LangChain.js 的系统架构采用模块化设计，核心抽象层位于 @langchain/core 包中，为上层应用提供统一的接口和组件。架构设计遵循以下原则：可组合性、可扩展性和类型安全。整个系统以 Runnable 抽象为核心，构建了一套完整的大语言模型应用开发框架。

LangChain.js 的核心抽象主要包括：Runnable 执行单元、Callbacks 事件系统、Memory 记忆管理、Tools 工具系统、Chat Models 聊天模型接口，以及 Vector Stores 向量存储接口。这些抽象共同构成了构建复杂 LLM 应用的基石。

核心架构图

graph TB
    subgraph "核心抽象层 @langchain/core"
        Runnable[Runnable 执行单元]
        Callbacks[Callbacks 事件系统]
        Memory[Memory 记忆管理]
        Tools[Tools 工具系统]
        ChatModels[Chat Models 接口]
        VectorStores[Vector Stores 接口]
    end
    
    subgraph "应用层"
        Agents[Agent 代理]
        Chains[Chain 链]
        VectorRetrieval[向量检索]
    end
    
    subgraph "集成层"
        Providers[第三方集成]
    end
    
    Runnable --> Callbacks
    Runnable --> Memory
    Runnable --> Tools
    Runnable --> ChatModels
    Runnable --> VectorStores
    
    Agents --> Runnable
    Chains --> Runnable
    VectorRetrieval --> VectorStores
    
    Providers --> ChatModels
    Providers --> Tools
    Providers --> VectorStores

Runnable 执行单元

设计理念

Runnable 是 LangChain.js 最核心的抽象，它代表了任何可以被执行的组件。所有的 Chain、Agent、Tool、Memory 等都实现或扩展了 Runnable 接口。这种设计使得系统中的任意组件都可以被统一地组合、管道化和执行。

Runnable 接口定义了一套标准的执行方法，包括同步调用、批量处理、流式输出等。这确保了无论组件的具体实现如何，调用者都可以用统一的方式与它们交互。

核心接口方法

可组合性

graph LR
    A[输入] --> B[Prompt]
    B --> C[LLM]
    C --> D[Output Parser]
    D --> E[最终结果]
    
    style B fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#e8f5e8

Runnable 支持两种组合方式：顺序组合和并行组合。顺序组合通过 pipe() 方法实现，将前一个 Runnable 的输出作为下一个 Runnable 的输入。并行组合则可以将多个 Runnable 同时应用于同一输入，然后合并结果。

Callbacks 事件系统

架构设计

Callbacks 系统提供了一套完整的事件通知机制，允许在 Runnable 执行过程中的各个阶段插入自定义逻辑。这种设计实现了关注点分离：核心逻辑与监控、调试、日志记录等辅助功能解耦。

事件系统采用发布-订阅模式，定义了清晰的事件生命周期钩子。开发者可以通过实现 CallbackHandler 接口来订阅感兴趣的事件，并在事件触发时执行相应操作。

主要事件类型

使用场景

Callbacks 系统常用于以下场景：

1. 性能监控：测量各个 Runnable 的执行时间
2. 日志记录：记录完整的调用链和中间结果
3. 流式输出：实时处理模型生成的内容片段
4. 调试开发：在执行过程中输出中间状态
5. 成本追踪：统计 token 使用量和 API 调用次数

Memory 记忆管理

抽象接口

Memory 接口定义了与对话历史交互的标准方式。它允许 Chain 和 Agent 在多次调用之间保持状态，实现真正的多轮对话能力。Memory 的设计独立于具体的存储后端，支持内存、数据库、文件系统等多种实现。

sequenceDiagram
    participant User as 用户
    participant Chain as Chain
    participant Memory as Memory
    
    User->>Chain: 第一轮输入
    Chain->>Memory: 读取历史
    Memory-->>Chain: 历史消息
    Chain->>LLM: 组合输入
    LLM-->>Chain: 响应
    Chain->>Memory: 保存对话
    Chain-->>User: 返回结果
    
    User->>Chain: 第二轮输入
    Chain->>Memory: 读取历史
    Memory-->>Chain: 历史消息
    Chain->>LLM: 组合输入
    LLM-->>Chain: 响应
    Chain->>Memory: 保存对话
    Chain-->>User: 返回结果

核心方法

Memory 系统支持多种实现方式，包括基础缓冲记忆、会话窗口记忆、摘要记忆等。开发者可以根据应用需求选择合适的记忆策略，或实现自定义的 Memory 类。

Tools 工具系统

工具定义接口

Tools 系统允许 LLM 调用外部函数和 API，扩展了模型的能力边界。每个 Tool 都是一个独立的 Runnable，具有明确定义的输入模式（通过 Zod schema 定义）和返回值格式。

graph TD
    LLM[LLM] -->|决定调用| ToolCall[Tool Call]
    ToolCall --> Tool[Tool 执行]
    Tool --> Result[结果]
    Result --> LLM
    
    subgraph "Tool 定义"
        Name[名称]
        Desc[描述]
        Schema[输入模式]
        Func[执行函数]
    end
    
    Tool --> Name
    Tool --> Desc
    Tool --> Schema
    Tool --> Func

工具属性

工具调用流程

1. 描述注册：工具注册时提供名称和描述
2. 意图识别：LLM 根据用户问题和工具描述判断是否需要调用
3. 参数生成：LLM 根据工具的 schema 生成调用参数
4. 安全执行：系统验证参数并执行工具
5. 结果返回：工具执行结果返回给 LLM 继续处理

Tools 系统还支持动态工具调用配置，允许在运行时修改工具行为和可见性。

Chat Models 聊天模型接口

接口设计

Chat Models 接口抽象了所有聊天语言模型的通用能力，提供了一套标准化的 API。通过这个接口，LangChain.js 可以统一地与不同的 LLM 提供商（如 OpenAI、Anthropic、Cohere 等）交互。

接口设计遵循流式优先的原则，所有模型都支持流式输出，允许实时处理生成的内容。这对于需要即时反馈的应用场景至关重要。

核心能力

消息类型

接口定义了标准化的消息类型系统，包括：

• HumanMessage：用户发送的消息
• AIMessage：AI 生成的响应
• SystemMessage：系统级指令
• ToolMessage：工具执行结果
• AIMessageChunk：流式输出的消息片段

Vector Stores 向量存储接口

检索增强生成支持

Vector Stores 接口为检索增强生成（RAG）提供了向量存储和相似性检索的基础设施。接口设计兼容多种向量数据库，包括本地内存存储和云服务（如 Pinecone、Weaviate、Chroma 等）。

graph LR
    A[文档] --> B[文档加载器]
    B --> C[文本分割器]
    C --> D[嵌入模型]
    D --> E[向量存储]
    
    F[用户查询] --> G[嵌入模型]
    G --> H[相似性搜索]
    H --> E
    E --> I[相关文档]
    I --> J[LLM 生成]

核心方法

索引管理

向量存储支持灵活的索引管理，允许：

• 增量更新文档而无需重建整个索引
• 基于元数据过滤搜索结果
• 配置不同的相似性度量方法（余弦相似度、欧氏距离等）

模块协作示例

以下流程图展示了一个典型 RAG 应用中各模块的协作方式：

sequenceDiagram
    participant User as 用户
    participant Chain as Chain
    participant Memory as Memory
    participant Retriever as Retriever
    participant VS as Vector Store
    participant LLM as LLM
    
    User->>Chain: 用户查询
    Chain->>Memory: 获取对话上下文
    Memory-->>Chain: 历史消息
    Chain->>Retriever: 检索请求
    Retriever->>VS: 向量相似性搜索
    VS-->>Retriever: 相关文档
    Retriever-->>Chain: 上下文文档
    Chain->>LLM: 组合查询+上下文
    LLM-->>Chain: 生成回答
    Chain->>Memory: 保存对话
    Chain-->>User: 返回结果

类型系统与验证

Zod Schema 集成

LangChain.js 深度集成了 Zod 进行类型验证和模式定义。这种集成提供了：

1. 编译时类型检查：TypeScript 编译器可以验证类型安全
2. 运行时验证：确保输入输出符合预期格式
3. 自动类型推断：减少手写类型定义的工作量
4. LLM 输出验证：验证模型生成的响应是否符合 schema

层级化类型定义

最佳实践建议

组件设计原则

1. 优先使用接口：通过抽象接口编程，提高代码的可测试性和可替换性
2. 利用类型系统：充分利用 TypeScript 和 Zod 的类型检查能力
3. 模块化组合：将复杂逻辑拆分为可复用的 Runnable 组件

性能优化

1. 流式处理：对实时性要求高的场景使用流式 API
2. 批量操作：批量处理多个独立请求以提高吞吐量
3. 缓存策略：对不频繁变化的计算结果进行缓存

错误处理

1. 使用 Callbacks：通过事件系统监控执行过程中的错误
2. 类型验证：在处理外部输入前进行严格的类型验证
3. 优雅降级：为可能的失败场景准备降级方案

概述

LangChain.js 中的 Agent 与 Chains 模块构成了构建 LLM 驱动应用的核心架构。Agent 负责动态决策和工具调用，而 Chains 则提供了将多个组件组合成连贯工作流的机制。这两者共同支持了从简单的问答系统到复杂的自主代理应用。

核心架构

Agent 类型系统

LangChain.js 定义了完善的类型系统来支持不同类型的 Agent 实现：

// 资料来源：libs/langchain-core/src/agents/types.ts
export type N = typeof START | "model_request" | "tools";

类型推断助手允许开发者从 Agent 配置中提取特定类型：

// 资料来源：libs/langchain-core/src/agents/types.ts
/**
 * Shorthand helper to extract the Tools type from an AgentTypeConfig or ReactAgent.
 */
export type InferAgentTools<T> = InferAgentType<T, "Tools">;

中断机制

Agent 系统支持中断功能，用于实现 Human-in-the-Loop (HITL) 模式：

// 资料来源：libs/langchain/src/agents/middleware/hitl.ts
export interface Interrupt<TValue = unknown> {
  // 表示中断状态的接口
}

Interrupt 配置支持动态描述生成：

// 资料来源：libs/langchain/src/agents/middleware/hitl.ts
const formatToolDescription: DescriptionFactory = (
  toolCall: ToolCall,
  state: AgentBuiltInState,
  runtime: Runtime<unknown>
) => {
  return `Tool: ${toolCall.name}\nArguments:\n${JSON.stringify(toolCall.args, null, 2)}`;
};

Agent 实现类型

ReAct Agent

ReAct (Reasoning + Acting) Agent 结合了推理和行动能力，通过中间步骤处理复杂任务。

OpenAI Functions Agent

针对 OpenAI 函数调用能力优化的 Agent，利用结构化输出进行工具选择。

Structured Chat Agent

支持结构化聊天交互的 Agent，适合需要复杂参数的工具调用场景。

Chains 实现

LLMChain

LLMChain 是最基本的链实现，用于将提示模板与 LLM 结合：

// 资料来源：libs/langchain-classic/src/chains/llm_chain.ts
const llmChain = new LLMChain({ prompt, llm, verbose });

问答链加载

LangChain 提供了灵活的问答链加载机制：

// 资料来源：libs/langchain-classic/src/chains/question_answering/load.ts
export function loadQAStuffChain(
  llm: BaseLanguageModelInterface,
  params: StuffQAChainParams = {}
) {
  const { prompt = QA_PROMPT_SELECTOR.getPrompt(llm), verbose } = params;
  const llmChain = new LLMChain({ prompt, llm, verbose });
  const chain = new StuffDocumentsChain({ llmChain, verbose });
  return chain;
}

支持三种主要的问答链类型：

参数配置

// 资料来源：libs/langchain-classic/src/chains/question_answering/load.ts
export interface StuffQAChainParams {
  prompt?: BasePromptTemplate;
  verbose?: boolean;
}

export interface MapReduceQAChainParams {
  returnIntermediateSteps?: MapReduceDocumentsChainInput["returnIntermediateSteps"];
  combineMapPrompt?: BasePromptTemplate;
  combinePrompt?: BasePromptTemplate;
  combineLLM?: BaseLanguageModelInterface;
  verbose?: boolean;
}

工具调用系统

AIMessage 与 Tool Calls

AIMessage 类集成了工具调用支持，处理消息内容块转换：

// 资料来源：libs/langchain-core/src/messages/ai.ts
if (this.tool_calls) {
  const missingToolCalls = this.tool_calls.filter(
    (block) =>
      !blocks.some((b) => b.id === block.id && b.name === block.name)
  );
  blocks.push(
    ...(missingToolCalls.map((block) => ({
      type: "tool_call" as const,
      id: block.id,
      name: block.name,
      args: block.args,
    })) as ContentBlock.Tools.ToolCall[])
  );
}

Action 接口

// 资料来源：libs/langchain/src/agents/middleware/hitl.ts
export interface Action {
  /**
   * 动作类型或名称（如 "add_numbers"）
   */
  name: string;
  /**
   * 动作所需参数的键值对（如 {"a": 1, "b": 2}）
   */
  args: Record<string, any>;
}

Scratchpad 格式化

Agent 使用 scratchpad 记录中间推理步骤，支持 XML 格式：

// 资料来源：libs/langchain-classic/src/agents/format_scratchpad/xml.ts
export function formatXml(intermediateSteps: AgentStep[]) {
  let log = "";
  for (const step of intermediateSteps) {
    const { action, observation } = step;
    log += `<tool>${action.tool}</tool><tool_input>${action.toolInput}\n</tool_input><observation>${observation}</observation>`;
  }
  return log;
}

架构流程图

graph TD
    A[用户输入] --> B[Agent 决策]
    B --> C{选择工具?}
    C -->|是| D[执行工具]
    D --> E[获取观察结果]
    E --> B
    C -->|否| F[生成最终响应]
    B --> G{需要人工确认?}
    G -->|是| H[中断并等待]
    H --> I[人类决策]
    I --> B
    G -->|否| F

消息传递流程

sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant M as AIMessage
    participant T as 工具

    U->>A: 输入请求
    A->>M: 生成消息
    M->>M: 处理 tool_calls
    M->>M: 转换 contentBlocks
    A->>T: 调用工具
    T->>A: 返回结果
    A->>U: 最终响应

配置与中间件

InterruptOnConfig 配置

// 资料来源：libs/langchain/src/agents/middleware/hitl.ts
const config: InterruptOnConfig = {
  allowedDecisions: ["approve", "edit"],
  description: formatToolDescription,
  argsSchema: z.record(z.any()).optional(),
};

配置参数说明

测试匹配器

LangChain 提供了专门的测试匹配器用于验证 Agent 行为：

// 资料来源：libs/langchain-core/src/testing/matchers.ts
export const langchainMatchers = {
  toBeHumanMessage,
  toBeAIMessage,
  toBeSystemMessage,
  toBeToolMessage,
  toHaveToolCalls,
  toHaveToolCallCount,
  toContainToolCall,
  toHaveToolMessages,
  toHaveBeenInterrupted,
  toHaveStructuredResponse,
};

最佳实践

工具选择策略

1. 评估任务复杂度：简单任务使用单一工具，复杂任务考虑多工具协作
2. 定义清晰的工具描述：确保 Agent 能准确理解工具用途
3. 处理工具调用失败：实现降级策略和错误恢复机制

Chain 组合建议

1. 从 LLMChain 开始：验证基础功能后再组合复杂链
2. 使用输入输出映射：确保数据在链之间正确传递
3. 添加错误处理：为每个链组件添加适当的异常处理

版本迁移

@langchain/classic 包保留了 v0.x 版本的链实现，用于向后兼容：

// 资料来源：libs/langchain-classic/README.md
- `LLMChain` - Basic chain for calling an LLM with a prompt template
- `ConversationalRetrievalQAChain` - Chain for conversational question-answering
- `RetrievalQAChain` - Chain for question-answering over documents

新项目推荐使用 createAgent API 获取更好的性能和更清晰的接口。

概述

LangChain.js 的向量存储与检索系统是构建检索增强生成（RAG）应用的核心基础设施。该系统提供了一套完整的接口和实现，用于将文档转换为向量表示、存储在各种向量数据库中，并通过语义相似性进行高效检索。

系统设计遵循模块化原则，提供了统一的 VectorStore 接口规范，使得不同的向量存储后端可以无缝切换。开发者可以根据数据规模、查询性能和部署需求选择合适的存储方案，同时保持上层应用代码的一致性。

LangChain.js 支持多种主流向量数据库集成，包括内存存储（用于开发测试）、Pinecone、Qdrant、MongoDB Atlas Search、PostgreSQL PGVector 等，为企业级应用提供了丰富的选择。

核心架构

系统组件关系

LangChain.js 的向量存储与检索系统由多个核心组件构成，这些组件协同工作以实现完整的文档处理和检索流程。

graph TD
    A[文档输入] --> B[文本分割器 Text Splitters]
    B --> C[向量化 Embeddings]
    C --> D[向量存储 VectorStore]
    D --> E[检索器 Retrievers]
    E --> F[应用层]
    
    G[Embedding Models] --> C
    
    H[Pinecone] --> D
    I[Qdrant] --> D
    J[MongoDB] --> D
    K[PGVector] --> D
    L[Memory] --> D

数据处理流程

文档从原始格式到可检索向量的转换过程涉及多个阶段，每个阶段都有明确的职责边界。

graph LR
    A[原始文档] --> B[文本分割]
    B --> C[小文档块]
    C --> D[调用 Embeddings API]
    D --> E[向量 + 元数据]
    E --> F[存储到 VectorStore]
    
    G[用户查询] --> H[查询向量化]
    H --> I[相似度搜索]
    I --> J[返回相关文档]

向量存储接口

VectorStore 基类

VectorStore 是所有向量存储实现的基础抽象接口，定义了向量存储的核心操作方法。所有具体的向量存储实现都继承自这个接口，确保了 API 的一致性和可替换性。

接口主要包含以下几个核心方法：

class VectorStore {
  // 添加文档到向量存储
  async addDocuments(documents: Document[]): Promise<void>
  
  // 通过相似度搜索查找相关文档
  async similaritySearch(
    query: string, 
    k?: number
  ): Promise<Document[]>
  
  // 带相似度分数的搜索
  async similaritySearchWithScore(
    query: string,
    k?: number
  ): Promise<[Document, number][]>
  
  // 删除文档
  async delete(ids?: string[]): Promise<void>
  
  // 跨链支持
  asRetriever(config?: SimilarityRetrieverConfig): BaseRetriever
}

内存向量存储

MemoryVectorStore 是最简单的向量存储实现，将所有向量存储在内存中。这种实现适用于开发测试、小规模数据集，或作为原型验证阶段的首选方案。由于数据存储在内存中，应用重启后数据会丢失，不适合生产环境使用。

import { MemoryVectorStore } from 'langchain/vectorstores/memory'
import { OpenAIEmbeddings } from '@langchain/openai'

const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
})

const vectorStore = new MemoryVectorStore(embeddings)

const documents = [
  { pageContent: "文档内容示例", metadata: { source: "doc1" } },
  { pageContent: "另一篇文档内容", metadata: { source: "doc2" } }
]

await vectorStore.addDocuments(documents)

const results = await vectorStore.similaritySearch("查询文本", 2)

第三方向量存储集成

Pinecone 集成

Pinecone 是一个托管的向量数据库服务，提供高性能的向量存储和检索能力。LangChain.js 通过 @langchain/pinecone 包提供了完整的集成支持。

#### 安装配置

npm install @langchain/pinecone @langchain/core @pinecone-database/pinecone

#### 使用示例

import { PineconeStore } from '@langchain/pinecone'
import { Pinecone } from '@pinecone-database/pinecone'
import { OpenAIEmbeddings } from '@langchain/openai'

const pinecone = new Pinecone()
const index = pinecone.Index('your-index-name')

const vectorStore = await PineconeStore.fromExistingIndex(
  new OpenAIEmbeddings(),
  { pineconeIndex: index }
)

Qdrant 集成

Qdrant 是一个开源的向量相似度搜索引擎，支持混合搜索和过滤。@langchain/qdrant 包提供了与 Qdrant 的完整集成。

#### 安装配置

npm install @langchain/qdrant

#### 核心特性

MongoDB Atlas Search

MongoDB Atlas Search 提供了基于 Lucene 的全文搜索能力，结合 MongoDB 的文档模型，可以存储和检索带有多维向量的文档。@langchain/mongodb 包提供了这一集成。

PGVector 集成

对于已在使用 PostgreSQL 的团队，PGVector 提供了在关系数据库中存储和检索向量的能力。@langchain/pgvector 包支持这一集成，使得可以利用现有的 PostgreSQL 基础设施。

#### 配置参数

检索器系统

检索器（Retriever）是连接向量存储和应用逻辑的关键组件。LangChain.js 提供了多种检索器实现，以适应不同的检索场景和需求。

父文档检索器

ParentDocumentRetriever 解决了小文本块丢失上下文信息的问题。该检索器首先检索与查询相关的小文本块，然后返回这些小块所属的完整父文档。

graph TD
    A[用户查询] --> B[检索小块]
    B --> C[获取父文档ID]
    C --> D[加载完整父文档]
    D --> E[返回带上下文的结果]
    
    F[小块1] --> G[父文档A]
    H[小块2] --> G
    I[小块3] --> J[父文档B]

这种策略在保持检索精确性的同时，确保返回的内容具有完整的上下文信息，特别适用于需要返回较长连续文本的场景。

多查询检索器

MultiQueryRetriever 通过使用语言模型生成多个不同角度的查询，然后对所有查询的结果进行去重合并，从而提高检索的召回率。

import { MultiQueryRetriever } from 'langchain/retrievers/multi_query'

const retriever = MultiQueryRetriever.fromLLM({
  llm: chatModel,
  retriever: baseRetriever,
  includeOriginal: true,
  verbose: true,
})

检索器配置

所有检索器都支持通过配置对象进行定制化设置，主要配置选项包括：

文本分割器

文本分割器是将长文档拆分为适合嵌入和检索的小块的关键组件。@langchain/textsplitters 包提供了多种分割策略。

递归字符分割器

RecursiveCharacterTextSplitter 是最常用的分割器，它按照预定义的字符优先级递归地分割文本，确保语义完整性。

import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters"

const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
})

const output = await splitter.createDocuments([text])

分割参数说明

语言特定分割

分割器支持针对不同内容类型进行优化配置：

// Markdown 文档
const mdSplitter = RecursiveCharacterTextSplitter.fromLanguage("markdown", {
  chunkSize: 1000,
  chunkOverlap: 100,
})

// 代码文件
const codeSplitter = RecursiveCharacterTextSplitter.fromLanguage("js", {
  chunkSize: 500,
  chunkOverlap: 50,
})

// HTML 文档
const htmlSplitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
})

Embeddings 集成

Embeddings 是将文本转换为向量表示的模型。LangChain.js 通过标准化的接口支持多种 Embeddings 提供商。

接口定义

interface Embeddings {
  embedQuery(text: string): Promise<number[]>
  embedDocuments(texts: string[]): Promise<number[][]>
}

支持的提供商

最佳实践

数据处理流程

构建高效的向量检索系统需要遵循系统化的数据处理流程。在数据准备阶段，应根据内容类型选择合适的分割策略：结构化文档使用语义分割，代码文件按函数或类分割，网页内容按 HTML 标签语义分割。

graph TD
    A[数据收集] --> B[数据清洗]
    B --> C[内容分类]
    C --> D[选择分割策略]
    D --> E[文本分割]
    E --> F[向量化]
    F --> G[质量检查]
    G --> H{是否合格}
    H -->|否| E
    H -->|是| I[存储向量]
    I --> J[索引优化]

查询优化

在进行相似性搜索时，应充分利用向量数据库的过滤功能，在向量相似度计算前先进行元数据过滤，以减少搜索范围并提高准确性。对于复杂的查询场景，考虑使用混合搜索策略，结合向量相似度和关键词匹配。

生产环境考虑

生产环境中应重点关注向量存储的索引配置、查询延迟监控、以及 Embeddings 模型的选择。对于大规模数据集，Pinecone 或 Qdrant 等专用向量数据库通常比通用数据库提供更好的性能。同时应建立 Embeddings 缓存机制，避免对相同文本重复进行向量化计算。

相关资源

• 官方文档
• @langchain/textsplitters 文档
• @langchain/pinecone 文档
• @langchain/qdrant 文档

概述

LangChain.js 的主要模型提供商集成模块为开发者提供了统一的接口，用于对接多个主流 AI 服务提供商的 chat models。这些集成通过标准化的抽象层，使得应用程序能够在不同提供商之间无缝切换，同时保持代码的兼容性和可维护性。

集成模块位于 libs/providers/ 目录下，支持的提供商包括 OpenAI、Anthropic、Google Vertex AI、Google GenAI、Mistral AI 等主流 LLM 服务商。每个提供商都实现了统一的 chat model 接口规范，确保了调用方式的一致性。

架构设计

核心抽象层

LangChain.js 采用分层架构设计，模型提供商集成位于基础设施层之上，为上层应用提供统一的 AI 能力访问接口。

graph TD
    A[应用层 Application] --> B[链与代理层 Chains & Agents]
    B --> C[模型抽象层 Model Abstraction]
    C --> D[提供商集成层 Provider Integrations]
    D --> E[OpenAI]
    D --> F[Anthropic]
    D --> G[Google Vertex]
    D --> H[Mistral AI]
    E --> I[外部 API 服务]
    F --> I
    G --> I
    H --> I

消息标准化

每个模型集成都实现了消息格式的标准化转换，确保不同提供商的消息结构能够被正确处理。核心的消息类型定义位于 libs/langchain-core/src/messages/message.ts，包括工具定义（MessageToolDefinition）、工具集（MessageToolSet）等关键数据结构。

graph LR
    A[用户消息] --> B[标准化消息格式]
    B --> C[Provider-specific 转换]
    C --> D[API 请求格式]
    D --> E[模型提供商]

核心功能特性

统一调用接口

所有 chat model 实现都遵循统一的调用模式，支持 invoke 方法进行同步调用和 stream 方法进行流式响应处理。这种设计使得开发者可以在不修改应用代码的情况下更换底层模型提供商。

// 统一的调用方式
const result = await llm.invoke(input);
for await (const chunk of await llm.stream(input)) {
  console.log(chunk);
}

资料来源：libs/providers/langchain-anthropic/src/chat_models.ts

结构化输出

模型集成支持通过 withStructuredOutput() 方法实现结构化输出，该功能使用提供商的原生工具调用能力来约束输出格式到特定的 JSON schema。

资料来源：libs/providers/langchain-anthropic/src/chat_models.ts

工具调用支持

集成模块提供了完整的工具调用（Tool Calling）支持，允许模型调用外部工具和函数。这一功能通过 tool() 辅助函数实现，支持 Zod schema 定义工具参数。

import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(
  async (input) => `Weather in ${input.location}`,
  {
    name: "get_weather",
    description: "Get weather for a location",
    schema: z.object({ location: z.string() }),
  }
);

资料来源：libs/providers/langchain-anthropic/src/chat_models.ts

OpenAI 集成

基本配置

OpenAI 集成提供了对 GPT 系列模型的访问支持，核心实现在 libs/providers/langchain-openai/src/chat_models/index.ts。

import { ChatOpenAI } from "@langchain/openai";

const llm = new ChatOpenAI({
  model: "gpt-4o",
  temperature: 0.7,
  // 其他配置参数...
});

流式响应处理

OpenAI 集成支持流式输出，响应包含内容块、元数据和 token 使用统计信息。

AIMessageChunk {
  "id": "chatcmpl-9u4NWB7yUeHCKdLr6jP3HpaOYHTqs",
  "content": ""
}
AIMessageChunk {
  "content": "J"
}
AIMessageChunk {
  "content": "'adore"
}

资料来源：libs/providers/langchain-openai/src/chat_models/index.ts

Anthropic 集成

特性概述

Anthropic 集成专门针对 Claude 系列模型进行了优化，提供了额外的特性支持，包括高级工具使用和搜索功能。

资料来源：libs/providers/langchain-anthropic/src/chat_models.ts

消息块翻译

Anthropic 集成实现了消息块翻译器（BlockTranslator）接口，用于在标准格式和提供商特定格式之间进行转换：

BlockTranslator = {
  translateContent: (message) => {
    if (typeof message.content === "string") {
      return convertToV1FromChatCompletions(message);
    }
    return convertToV1FromResponses(message);
  },
  translateContentChunk: (message) => { /* ... */ },
};

资料来源：libs/langchain-core/src/messages/block_translators/openai.ts

向量存储与嵌入集成

内存向量存储

LangChain.js 提供了 MemoryVectorStore 实现，用于在内存中存储和检索文档向量。该存储与嵌入模型配合使用，支持添加文档和相似性搜索功能。

import { MemoryVectorStore } from 'langchain/vectorstores/memory';
import { OpenAIEmbeddings } from '@langchain/openai';

const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
});

const vectorStore = new MemoryVectorStore(embeddings);

// 添加文档
await vectorStore.addDocuments(documents);

// 相似性搜索
const results = await vectorStore.similaritySearch("thud", 1);

资料来源：libs/langchain-classic/src/vectorstores/memory.ts

嵌入模型配置

嵌入模型是 RAG（检索增强生成）管道的核心组件，用于将文本转换为向量表示。每个模型提供商都提供了相应的嵌入实现。

消息与工具系统

消息结构

LangChain.js 定义了标准化的消息结构体系，包括基础消息类型、工具定义和工具调用块等核心组件。

classDiagram
    class MessageToolDefinition {
        +TInput input
        +TOutput output
    }
    
    class MessageToolSet {
        +[key: string]: MessageToolDefinition
    }
    
    class MessageToolCallBlock {
        +string type
        +string name
        +Record args
        +string? id
    }
    
    MessageToolSet --> MessageToolDefinition : contains

资料来源：libs/langchain-core/src/messages/message.ts

工具调用块类型

工具调用块是消息系统中表示工具调用的关键数据结构，其类型定义如下：

type $MessageToolCallBlock<TStructure extends MessageStructure> = {
  type: "tool_call";
  name: string;
  args: TStructure["tools"][keyof TStructure["tools"]]["input"];
  id?: string;
};

资料来源：libs/langchain-core/src/messages/message.ts

标准消息内容转换

内容转换工具

castStandardMessageContent 函数是 LangChain.js 消息处理的核心工具，用于标准化消息内容格式：

function castStandardMessageContent<T extends BaseMessage>(message: T) {
  const Cls = message.constructor as Constructor<T>;
  return new Cls({
    ...message,
    content: message.contentBlocks,
    response_metadata: {
      ...message.response_metadata,
      output_version: "v1",
    },
  });
}

该函数将消息的内容块转换为标准内容格式，并附加 v1 输出版本元数据，确保了不同提供商之间的兼容性。

资料来源：libs/langchain-core/src/language_models/utils.ts

安装与配置

依赖管理

每个模型提供商包都依赖 @langchain/core 作为 peer dependency。建议在项目 package.json 中统一管理依赖版本以避免冲突：

{
  "dependencies": {
    "@langchain/anthropic": "^0.0.9",
    "@langchain/openai": "^0.0.9",
    "@langchain/core": "^0.3.0"
  },
  "overrides": {
    "@langchain/core": "^0.3.0"
  }
}

资料来源：libs/providers/langchain-anthropic/README.md

环境变量配置

不同的提供商需要设置相应的 API 密钥：

# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Google Cloud
export GOOGLEAPPLICATIONCREDENTIALS="/path/to/credentials.json"

最佳实践

提供商选择指南

错误处理策略

实现模型调用时应考虑网络错误、速率限制和配额耗尽等异常情况。建议使用指数退避重试机制，并实现适当的降级策略。

性能优化建议

1. 批量处理：将多个请求合并为批量调用（如果提供商支持）
2. 流式响应：对于长文本输出，使用流式响应减少等待时间
3. 缓存：对重复查询实现结果缓存
4. 连接复用：保持 HTTP 连接活跃以减少建立开销

相关资源

• 官方文档：LangChain.js 文档
• API 参考：Provider 包文档
• 示例代码：examples 目录

概述

LangChain.js 的扩展提供商系统是一个模块化架构，允许通过不同的提供商 SDK 集成各种大语言模型（LLM）服务。每个提供商都实现了统一的接口规范，同时保留了各自平台特有的功能特性。工具集成是这些提供商的核心能力之一，它使得 AI 模型能够调用外部函数来执行特定任务，如计算、搜索、数据处理等。

在 LangChain.js 的架构中，工具集成涉及三个主要层面的抽象：工具定义层、消息传输层和提供商适配层。工具定义使用统一的 TypeScript 类型系统描述工具的输入输出结构，消息传输层负责在不同格式之间进行转换，而提供商适配层则处理与各个 AI 服务提供商的特定集成细节。

工具定义系统

核心类型定义

LangChain.js 在 libs/langchain-core/src/messages/message.ts 中定义了工具系统的核心类型结构。这些类型构成了整个工具集成的基础架构，提供了类型安全的工具定义和调用机制。

export interface MessageToolDefinition<TInput = unknown, TOutput = unknown> {
  input: TInput;
  output: TOutput;
}

export interface MessageToolSet {
  [key: string]: MessageToolDefinition;
}

资料来源：libs/langchain-core/src/messages/message.ts:1-15

MessageToolDefinition 接口使用泛型参数定义工具的输入和输出类型，允许开发者为每个工具指定精确的数据结构。MessageToolSet 接口则是一个映射类型，将工具名称与对应的工具定义关联起来。

工具调用块结构

工具调用块（Tool Call Block）是消息中表示工具调用的数据结构，包含工具名称、参数和可选的调用标识符。这个结构在 MessageStructure 的工具扩展部分定义：

type CalcToolCall = $MessageToolCallBlock<MyStructure>;
// Resolves to:
// {
//   type: "tool_call";
//   name: "calculator";
//   args: { operation: string, numbers: number[] };
//   id?: string;
// }

资料来源：libs/langchain-core/src/messages/message.ts:50-70

这种结构设计确保了工具调用的自包含性，每个调用都包含足够的上下文信息来执行对应的工具函数。id 字段是可选的，允许在不需要追踪单个调用的情况下省略。

消息格式转换层

OpenAI 格式翻译器

LangChain.js 的 block_translators 模块提供了不同消息格式之间的转换能力。在 libs/langchain-core/src/messages/block_translators/openai.ts 中实现的 BlockTranslator 是核心的转换逻辑：

BlockTranslator = {
  translateContent: (message) => {
    if (typeof message.content === "string") {
      return convertToV1FromChatCompletions(message);
    }
    return convertToV1FromResponses(message);
  },
  translateContentChunk: (message) => {
    if (typeof message.content === "string") {
      return convertToV1FromChatCompletionsChunk(message);
    }
    return convertToV1FromResponsesChunk(message);
  },
};

资料来源：libs/langchain-core/src/messages/block_translators/openai.ts:1-15

翻译器根据消息内容类型选择不同的转换路径。对于字符串内容，它使用 Chat Completions 格式的转换器；对于数组格式的内容，则使用 Responses API 格式的转换器。这种设计允许系统同时支持 OpenAI 的两种主要 API 风格。

标准消息内容转换

libs/langchain-core/src/language_models/utils.ts 中的 castStandardMessageContent 函数提供了标准消息内容的转换能力，确保消息格式在不同版本之间保持兼容性：

function castStandardMessageContent<T extends BaseMessage>(message: T) {
  const Cls = message.constructor as Constructor<T>;
  return new Cls({
    ...message,
    content: message.contentBlocks,
    response_metadata: {
      ...message.response_metadata,
      output_version: "v1",
    },
  });
}

资料来源：libs/langchain-core/src/language_models/utils.ts:8-20

该函数通过重建消息实例来确保内容块被正确格式化，同时在响应元数据中添加版本标识，便于后续处理和调试。

AIMessage 工具集成

内容块生成逻辑

AIMessage 类在 libs/langchain-core/src/messages/ai.ts 中实现了复杂的工具调用整合逻辑。其 contentBlocks getter 方法负责合并基础内容与工具调用信息：

override get contentBlocks(): ContentBlock[] {
  if (
    "model_provider" in this.response_metadata &&
    typeof this.response_metadata.model_provider === "string"
  ) {
    const translator = getTranslator(this.response_metadata.model_provider);
    if (translator) {
      return translator.translateContent(this as AIMessage);
    }
  }

  const blocks = super.contentBlocks;

  if (this.tool_calls) {
    const missingToolCalls = this.tool_calls.filter(
      (block) =>
        !blocks.some((b) => b.id === block.id && b.name === block.name)
    );
    blocks.push(
      ...(missingToolCalls.map((block) => ({
        type: "tool_call" as const,
        id: block.id,
        name: block.name,
        args: block.args,
      })) as ContentBlock.Tools.ToolCall[])
    );
  }

  return blocks;
}

资料来源：libs/langchain-core/src/messages/ai.ts:1-35

该逻辑首先检查响应元数据中是否包含模型提供商信息，如果有则使用对应的翻译器进行格式转换。如果不存在翻译器，则采用默认逻辑，将 tool_calls 数组中的工具调用转换为内容块。过滤逻辑确保不会重复添加已存在于基础内容中的工具调用。

类型守卫机制

AIMessage 类提供了静态类型守卫方法来安全地识别消息类型：

static isInstance<T extends MessageStructure>(
  obj: BaseMessage<T>
): obj is BaseMessage<T> & AIMessage<T>;
static isInstance(obj: unknown): obj is AIMessage;

资料来源：libs/langchain-core/src/messages/ai.ts:60-68

这两个重载分别处理泛型和非泛型场景，允许在类型安全的情况下进行类型收窄和断言。

提供商工具格式处理

OpenAI 工具格式

libs/providers/langchain-openai/src/utils/tools.ts 中定义了 OpenAI 特定的工具格式转换逻辑：

IClient.Chat.ChatCompletionCustomTool = {
  getFormat: () => {
    if (!tool.format) {
      return undefined;
    }
    if (tool.format.type === "grammar") {
      return {
        type: "grammar" as const,
        grammar: {
          definition: tool.format.definition,
          syntax: tool.format.syntax,
        },
      };
    }
    if (tool.format.type === "text") {
      return {
        type: "text" as const,
      };
    }
    return undefined;
  },
  return {
    type: "custom",
    custom: {
      name: tool.name,
      description: tool.description,
      format: getFormat(),
    },
  };
};

资料来源：libs/providers/langchain-openai/src/utils/tools.ts:1-35

OpenAI 支持多种工具格式类型，包括 grammar 格式（包含语法定义和语法规则）和 text 格式。这种灵活性允许开发者为不同的用例选择最合适的格式定义方式。custom 类型包装了所有自定义工具，确保符合 OpenAI API 的工具规范。

Anthropic 流式响应

Anthropic 提供商在 libs/providers/langchain-anthropic/src/chat_models.ts 中处理流式响应，其输出格式与 OpenAI 不同，使用 additional_kwargs 传递工具元数据：

AIMessageChunk {
  "id": "msg_01N8MwoYxiKo9w4chE4gXUs4",
  "content": "",
  "additional_kwargs": {
    "id": "msg_01N8MwoYxiKo9w4chE4gXUs4",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-4-5-20250929"
  },
  "usage_metadata": {
    "input_tokens": 25,
    "output_tokens": 1,
    "total_tokens": 26
  }
}

资料来源：libs/providers/langchain-anthropic/src/chat_models.ts:50-75

Anthropic 的流式响应以增量方式返回内容块，每个 AIMessageChunk 包含部分内容。这种设计优化了响应延迟，使得用户可以尽快看到初始输出。

Agent 工具集成

Agent 类型定义

libs/langchain/src/agents/types.ts 中定义了 Agent 的类型系统，包括工具配置选项：

interface AgentConfig {
  model: string | AgentLanguageModelLike;
  
  tools?: (ServerTool | ClientTool)[];
  
  systemMessage?: string | SystemMessage;
}

资料来源：libs/langchain/src/agents/types.ts:1-20

Agent 配置中的 tools 字段接受 ServerTool 或 ClientTool 类型的数组，允许 Agent 访问可用的工具集合。系统消息可以是简单的字符串或包含数组内容的 SystemMessage，后者支持更复杂的结构化内容。

工具调用中间件

libs/langchain/src/agents/middleware/hitl.ts 实现了人机协作的中间件系统，允许在工具执行前进行干预：

export interface Action {
  name: string;
  args: Record<string, any>;
}

export interface InterruptOnConfig {
  description?: z.union([z.string(), DescriptionFunctionSchema]).optional();
  argsSchema?: z.record(z.any()).optional();
}

资料来源：libs/langchain/src/agents/middleware/hitl.ts:1-30

Action 接口定义了工具调用的基本结构，包含动作名称和参数记录。InterruptOnConfig 提供了描述工具的选项，可以是静态字符串或动态函数，允许在执行前格式化工具调用的展示信息。

测试与验证

工具相关匹配器

LangChain.js 提供了专门的测试匹配器来验证工具调用行为，在 libs/langchain-core/src/testing/matchers.ts 中实现：

export const langchainMatchers = {
  toBeHumanMessage,
  toBeAIMessage,
  toBeSystemMessage,
  toBeToolMessage,
  toHaveToolCalls,
  toHaveToolCallCount,
  toContainToolCall,
  toHaveToolMessages,
  toHaveBeenInterrupted,
  toHaveStructuredResponse,
};

资料来源：libs/langchain-core/src/testing/matchers.ts:1-15

这些匹配器提供了丰富的工具调用验证能力：

工具调用匹配器的使用示例：

expect(message).toHaveToolCalls([
  { name: "calculator", args: { operation: "add", a: 1, b: 2 } },
  { name: "translator", args: { text: "hello", targetLanguage: "french" } }
]);

资料来源：libs/langchain-core/src/testing/matchers.ts:25-40

架构流程图

graph TD
    A[用户定义工具] --> B[MessageToolDefinition]
    B --> C[工具注册到模型]
    C --> D[模型生成工具调用]
    D --> E[工具调用块创建]
    E --> F{提供商类型}
    F -->|OpenAI| G[Chat Completions / Responses API]
    F -->|Anthropic| H[additional_kwargs]
    F -->|其他| I[提供商特定格式]
    G --> J[BlockTranslator转换]
    H --> J
    I --> J
    J --> K[标准v1格式]
    K --> L[Agent执行工具]
    L --> M[工具响应消息]
    M --> N[继续对话循环]

不同提供商的工具调用差异

最佳实践

工具定义规范

在 LangChain.js 中定义工具时，应遵循以下规范以确保最佳的跨提供商兼容性：

1. 使用精确的 TypeScript 类型：为工具的输入和输出定义完整的类型，避免使用 any 类型
2. 提供清晰的描述：工具描述应准确反映功能，便于模型理解何时调用
3. 使用 Zod Schema：通过 Zod 定义参数验证架构，确保传入参数的有效性

消息处理建议

处理包含工具调用的消息时，建议采用以下策略：

1. 始终检查翻译器：在处理提供商特定格式时，先检查是否存在对应的翻译器
2. 合并重复工具调用：使用 AIMessage 中的过滤逻辑避免重复添加
3. 处理缺失字段：工具调用块中的 id 是可选的，应有合理的降级处理

扩展新提供商

为新的 AI 服务提供商添加工具集成支持时，需要实现以下组件：

1. 创建提供商特定的工具格式转换器
2. 实现 BlockTranslator 接口的转换方法
3. 在 getTranslator 注册新的翻译器
4. 编写集成测试验证功能正确性

总结

LangChain.js 的扩展提供商与工具集成系统通过分层架构实现了灵活而强大的工具调用能力。核心类型系统提供了统一的工具定义规范，消息格式转换层确保了不同提供商之间的互操作性，而 Provider 适配层则处理了各个平台的特定实现细节。

这套系统的主要优势包括：类型安全的消息处理、统一的工具定义接口、灵活的消息格式转换，以及完善的测试支持。开发者可以通过实现对应的翻译器和适配器，将新的 AI 提供商集成到 LangChain.js 生态系统中，同时保持与其他提供商的一致性体验。

概述与设计目标

LangChain.js 的多环境部署支持旨在验证包的导出结构（exports）与目标运行时环境的兼容性。不同的部署环境对模块格式、异步处理和文件系统访问有着截然不同的要求，LangChain.js 通过自动化测试确保这些差异不会导致运行时错误。

核心设计原则包括：

• 环境无关性：核心抽象层独立于特定运行时环境
• 导出兼容性：通过 package.json 的 exports 字段精细控制不同环境的入口点
• 异步标准化：统一 AsyncLocalStorage 和 AbortSignal 等跨环境 API 的行为

资料来源：libs/langchain-core/src/utils/signal.ts:1-50

支持的部署环境

LangChain.js 维护了一套针对主流运行时和构建工具的兼容性测试：

资料来源：environment_tests/README.md 资料来源：environment_tests/test-exports-bun/src/entrypoints.js 资料来源：environment_tests/test-exports-cf/src/entrypoints.js

测试框架架构

目录结构

environment_tests/
├── README.md                    # 测试框架说明文档
├── docker-compose.yml           # Docker 编排配置
├── test-exports-bun/            # Bun 运行时测试
│   └── src/
│       └── entrypoints.js       # 入口点导出验证
├── test-exports-cf/              # Cloudflare Workers 测试
│   └── src/
│       └── entrypoints.js
├── test-exports-vercel/          # Vercel Edge Functions 测试
│   └── src/
│       └── entrypoints.js
└── test-exports-vite/            # Vite 构建工具测试
    └── src/
        └── entrypoints.js

资料来源：environment_tests/docker-compose.yml

测试流程

graph TD
    A[开始测试] --> B[加载 Docker Compose 配置]
    B --> C{选择测试环境}
    C -->|Bun| D[运行 test-exports-bun]
    C -->|Cloudflare| E[运行 test-exports-cf]
    C -->|Vercel| F[运行 test-exports-vercel]
    C -->|Vite| G[运行 test-exports-vite]
    D --> H[验证入口点导出]
    E --> H
    F --> H
    G --> H
    H --> I{所有测试通过?}
    I -->|是| J[测试成功]
    I -->|否| K[报告环境兼容性问题]

Docker 容器化测试环境

LangChain.js 使用 Docker Compose 管理多环境测试容器，确保测试环境的一致性和可重复性。

服务配置

测试框架定义了多个服务容器，每个容器运行特定的运行时环境：

• 基础镜像选择：针对不同运行环境选择合适的基础镜像
• 依赖安装：在容器启动时安装项目依赖
• 测试执行：运行入口点验证脚本

资料来源：environment_tests/docker-compose.yml

核心导出机制

package.json exports 字段

LangChain.js 通过 package.json 的 exports 字段实现条件导出，为不同环境提供定制化的模块入口：

// 条件导出的典型配置
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "default": "./dist/index.js"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "import": "./dist/utils.js"
    }
  }
}

资料来源：libs/langchain-core/package.json:1-30

入口点验证

每个环境测试包包含一个 entrypoints.js 文件，用于验证关键导出是否正确可用：

// test-exports-bun/src/entrypoints.js 示例
export * from "@langchain/core";
// 验证核心导出在 Bun 环境中可访问

资料来源：environment_tests/test-exports-bun/src/entrypoints.js

异步与信号处理

LangChain.js 的核心模块实现了跨环境兼容的异步处理机制，这对于在边缘计算环境中运行至关重要。

AbortSignal 支持

核心模块支持标准的 AbortSignal 接口，允许调用者取消异步操作：

// libs/langchain-core/src/utils/signal.ts
export interface AbortSignalLike {
  readonly aborted: boolean;
  addEventListener: (type: "abort", listener: () => void) => void;
  removeEventListener: (type: "abort", listener: () => void) => void;
}

资料来源：libs/langchain-core/src/utils/signal.ts:1-30

AsyncLocalStorage 适配

在不支持 AsyncLocalStorage 的环境中（如某些边缘运行时），LangChain.js 提供了优雅的降级处理机制，确保核心功能不受影响。

边缘计算环境特殊考虑

Cloudflare Workers

Cloudflare Workers 环境对代码有以下限制：

资料来源：environment_tests/test-exports-cf/src/entrypoints.js

Vercel Edge Functions

Vercel Edge Functions 运行在 V8 isolates 上，与 Cloudflare Workers 类似需要避免使用 Node.js 特定 API。

开发工作流

本地测试

开发者可以使用以下命令在本地运行多环境测试：

# 启动所有测试环境容器
docker-compose up

# 运行特定环境测试
pnpm --filter test-exports-bun test
pnpm --filter test-exports-cf test

CI/CD 集成

多环境测试通常集成到持续集成流程中，确保每次代码变更不会破坏特定环境的兼容性：

1. 检出代码
2. 安装依赖
3. 构建核心包
4. 运行各环境测试
5. 收集并报告结果

最佳实践

包开发者指南

1. 避免 Node.js 特定 API：使用 web 标准 API 或条件导入
2. 使用条件导出：在 package.json 中正确配置 exports 字段
3. 测试所有目标环境：在开发周期早期发现问题
4. 处理缺失的全局对象：如 AsyncLocalStorage 不可用时的降级方案

环境检测模式

// 检测当前环境类型
const isEdge = typeof EdgeRuntime !== "undefined";
const isNode = typeof process !== "undefined" && process.versions?.node;
const isBrowser = typeof window !== "undefined";

相关资源

• LangChain.js 主仓库
• @langchain/core 核心包
• 环境测试框架

概述

LangChain.js 是一个采用 monorepo 架构的 TypeScript 项目，使用 pnpm workspaces 进行依赖管理，并通过多层次的测试策略确保代码质量。依赖管理策略涵盖了版本控制、依赖范围测试和标准化测试，而测试策略则包括单元测试、集成测试、标准单元测试和标准集成测试等多种测试模式。

该项目的依赖管理核心目标是确保所有 @langchain/* 包共享相同版本的 @langchain/core，避免因核心库版本不一致导致的兼容性问题。资料来源：libs/langchain-core/package.json()

Monorepo 架构

工作区结构

LangChain.js 使用 pnpm workspaces 管理多包工作区，所有包位于 libs/ 目录下。资料来源：pnpm-workspace.yaml()

graph TD
    A[langchainjs Root] --> B[pnpm-workspace.yaml]
    A --> C[package.json]
    A --> D[libs/]
    
    D --> E[langchain-core]
    D --> F[langchain-classic]
    D --> G[langchain-textsplitters]
    D --> H[providers/]
    D --> I[community/]
    
    H --> H1[langchain-anthropic]
    H --> H2[langchain-aws]
    H --> H3[langchain-cohere]
    H --> H4[langchain-xai]
    H --> H5[langchain-mistralai]
    H --> H6[langchain-tavily]

包类型分类

依赖管理策略

核心依赖一致性

LangChain.js 要求所有包共享同一个 @langchain/core 实例。核心库采用 tilde 依赖版本策略，确保向后兼容性。资料来源：libs/langchain-core/README.md()

{
  "peerDependencies": {
    "@langchain/core": "~0.3.0"
  },
  "devDependencies": {
    "@langchain/core": "~0.3.0"
  }
}

依赖覆盖机制

项目推荐在用户项目的 package.json 中添加依赖覆盖配置，以强制所有包使用相同版本的核心库：

graph LR
    A[用户项目] --> B[dependencies]
    A --> C[resolutions]
    A --> D[overrides]
    A --> E[pnpm.overrides]
    
    B --> F[@langchain/core]
    B --> G[@langchain/anthropic]
    B --> H[@langchain/cohere]
    
    C --> F
    D --> F
    E --> F

支持的包管理器及其覆盖字段：

资料来源：libs/providers/langchain-anthropic/README.md()

依赖范围测试

项目通过 Docker 环境测试不同依赖版本组合的兼容性，确保包在依赖版本变化时仍能正常工作。

#### Docker 测试环境配置

依赖范围测试使用 Docker Compose 定义测试环境：

services:
  test:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - .:/app
    environment:
      - NODE_ENV=test
    command: pnpm test:ranges

资料来源：dependency_range_tests/docker-compose.yml()

#### 自动更新依赖脚本

项目提供脚本自动更新依赖到最新版本：

// update_resolutions_latest.js
async function updateResolutions() {
  // 获取 @langchain/core 最新版本
  const latestCore = await getLatestVersion("@langchain/core");
  
  // 更新所有包的 resolutions
  await updateWorkspaceResolutions(latestCore);
}

该脚本遍历工作区中的所有包，将 @langchain/core 依赖更新到最新版本，验证兼容性后提交更改。资料来源：dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js()

测试策略

测试类型概览

LangChain.js 采用多层次的测试策略，确保代码质量和向后兼容性：

graph TD
    A[测试策略] --> B[单元测试]
    A --> C[集成测试]
    A --> D[标准测试]
    A --> E[导出测试]
    A --> F[依赖范围测试]
    
    B --> B1[vitest run]
    C --> C1[vitest run --mode int]
    D --> D1[standard-unit]
    D --> D2[standard-int]
    E --> E1[test:exports:docker]
    F --> F1[test:ranges:docker]

资料来源：package.json()

单元测试

单元测试使用 Vitest 框架运行，每个包在 src/ 目录下包含 tests/ 文件夹：

# 运行单元测试
pnpm test

# 运行集成测试
pnpm test:int

# 监视模式运行
pnpm test:watch

资料来源：libs/langchain-core/package.json()

标准测试框架

@langchain/standard-tests 是项目内部的标准化测试框架，为所有 LangChain 包提供一致的测试接口。资料来源：internal/standard-tests/src/index.ts()

#### 标准测试模块结构

classDiagram
    class StandardTests {
        +runUnitTests()
        +runIntegrationTests()
        +runChatModelTests()
        +runEmbeddingsTests()
        +runVectorStoreTests()
    }
    
    class UnitTestRunner {
        +run()
        +validateOutput()
    }
    
    class IntegrationTestRunner {
        +run()
        +setupFixtures()
        +teardown()
    }
    
    StandardTests --> UnitTestRunner
    StandardTests --> IntegrationTestRunner

#### 测试模式

# 运行标准测试
pnpm test:standard:unit
pnpm test:standard:int
pnpm test:standard

资料来源：package.json()

导出兼容性测试

导出测试验证包的导出接口在不同环境（ESM/CJS）下的兼容性：

graph LR
    A[导出测试] --> B[ESM环境]
    A --> C[CJS环境]
    A --> D[Docker容器]
    
    B --> E[import测试]
    C --> F[require测试]
    D --> G[跨环境验证]

使用 Docker 环境进行导出测试：

pnpm test:exports:docker

资料来源：package.json()

依赖范围测试

依赖范围测试验证包在不同核心库版本下的行为：

graph TD
    A[依赖范围测试] --> B[Docker环境]
    A --> C[版本矩阵]
    A --> D[兼容性验证]
    
    C --> C1[@langchain/core ^0.2.0]
    C --> C2[@langchain/core ^0.3.0]
    C --> C3[@langchain/core latest]
    
    D --> D1[API兼容性]
    D --> D2[类型检查]
    D --> D3[运行时测试]

运行依赖范围测试：

pnpm test:ranges:docker

资料来源：package.json()

CI/CD 集成

Turbo 构建系统

项目使用 Turbo 进行构建和测试编排：

{
  "scripts": {
    "test:unit:ci": "turbo test",
    "build": "turbo build"
  }
}

Turbo 的优势：

资料来源：package.json()

过滤规则

CI 配置使用过滤器排除不需要测试的包：

# 排除导出测试、示例和创建集成模板
pnpm test:unit:ci --filter="!test-exports-*" --filter="!examples" --filter="!create-langchain-integration"

包开发指南

创建新集成包

项目提供了集成包模板 create-langchain-integration，开发者可以使用该模板快速创建新的提供商集成。资料来源：libs/create-langchain-integration/template/README.md()

新包开发流程：

1. 使用模板创建包结构
2. 添加 @langchain/core 为 peer dependency 和 dev dependency
3. 实现集成代码
4. 添加单元测试和集成测试
5. 运行标准测试验证
6. 提交更改

包配置示例

{
  "name": "@langchain/example-provider",
  "version": "0.0.1",
  "type": "module",
  "dependencies": {
    "@example/sdk": "^1.0.0"
  },
  "peerDependencies": {
    "@langchain/core": "~0.3.0"
  },
  "devDependencies": {
    "@langchain/core": "~0.3.0"
  }
}

最佳实践

依赖管理

测试覆盖

构建验证

在发布包之前，确保完成以下验证步骤：

graph LR
    A[代码编写] --> B[单元测试]
    B --> C[集成测试]
    C --> D[标准测试]
    D --> E[导出测试]
    E --> F[依赖范围测试]
    F --> G[发布]

概述

LangChain.js 的扩展开发体系包含以下核心组件：

项目结构

LangChain.js 使用 pnpm monorepo 管理所有包，每个扩展包遵循统一的目录结构：

libs/
├── create-langchain-integration/   # 集成创建脚手架
│   ├── create-app.ts               # CLI 入口
│   └── template/                  # 包模板目录
│       └── package.json           # 模板 package.json
├── providers/                      # 官方提供商集成
│   ├── langchain-anthropic/
│   ├── langchain-aws/
│   └── langchain-cohere/
├── langchain-core/                 # 核心抽象层
├── langchain-textsplitters/        # 文本分割实现
└── langchain-mcp-adapters/         # MCP 协议适配器

创建新集成包

使用脚手架工具

LangChain.js 提供了自动化工具来生成新的集成包骨架：

pnpm create @langchain/integration <package-name>

该命令调用 create-app.ts 中的逻辑，生成符合规范的包结构。脚手架会自动配置：

• TypeScript 编译配置
• 包名命名规范（@langchain/<name>）
• 依赖版本锁定策略

包模板结构

生成的模板包含以下关键文件：

package.json 配置要求

集成包的 package.json 必须遵循以下配置规范：

{
  "name": "@langchain/<package-name>",
  "version": "0.0.1",
  "type": "module",
  "dependencies": {
    "<vendor-sdk>": "^<version>"
  },
  "peerDependencies": {
    "@langchain/core": "^1.0.0"
  },
  "devDependencies": {
    "@langchain/core": "workspace:^"
  }
}

关键配置说明：

资料来源：libs/create-langchain-integration/template/package.json

依赖管理策略

@langchain/core 版本锁定

为确保所有 LangChain 包使用相同版本的 @langchain/core，需要在项目根目录的 package.json 中添加版本覆盖配置：

{
  "resolutions": {
    "@langchain/core": "^0.3.0"
  },
  "overrides": {
    "@langchain/core": "^0.3.0"
  },
  "pnpm": {
    "overrides": {
      "@langchain/core": "^0.3.0"
    }
  }
}

资料来源：libs/providers/langchain-anthropic/README.md

MCP 适配器开发

Model Context Protocol (MCP) 适配器允许 LangChain 与外部 MCP 服务器通信，访问其提供的工具。

客户端架构

graph TD
    A[LangChain Agent] --> B[MCPClient]
    B --> C[MCP Server]
    C --> D[Remote Tools]
    B --> E[MCPTools]
    E --> A

核心组件

MCPTools 类 提供 MCP 工具到 LangChain 工具的转换：

// 将 MCP 工具适配为 LangChain 可用格式
export class MCPTools {
  constructor(
    private client: MCPClient,
    private toolNames?: string[]
  ) {}

  getTools(): Tool[] {
    // 返回适配后的工具列表
  }
}

资料来源：libs/langchain-mcp-adapters/src/tools.ts

客户端初始化

import { MCPClient } from "./client";

const client = new MCPClient({
  name: "my-mcp-client",
  version: "1.0.0",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
});

资料来源：libs/langchain-mcp-adapters/src/client.ts

构建和测试

构建脚本

集成包应包含标准的构建和测试脚本：

构建流程

LangChain.js 使用 turbo 作为构建编排工具：

pnpm build --filter @langchain/<package-name>

单包构建命令：

cd libs/providers/langchain-anthropic
pnpm build

测试规范

• 单元测试文件命名：<name>.test.ts
• 集成测试文件命名：<name>.int.test.ts
• 测试文件位置：src/tests/ 或根目录 tests/

资料来源：libs/langchain-textsplitters/README.md

贡献代码

贡献流程

graph LR
    A[Fork 仓库] --> B[创建功能分支]
    B --> C[开发实现]
    C --> D[编写测试]
    D --> E[提交 Pull Request]
    E --> F[Code Review]
    F --> G[合并到主分支]

代码规范

• 遵循 TypeScript 最佳实践
• 使用 ESLint 进行代码检查
• 使用 Prettier 进行代码格式化
• 确保所有新功能包含测试覆盖

提交规范

pnpm lint && pnpm format

运行提交前的检查：

pnpm lint:eslint && pnpm lint:dpdm

dpdm 工具检查动态导入的循环依赖问题。

资料来源：CONTRIBUTING.md

包导出配置

package.json exports 字段

新包应配置 exports 字段以支持按需导入：

{
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./<subpath>": {
      "import": "./dist/<subpath>.js",
      "types": "./dist/<subpath>.d.ts"
    }
  }
}

添加新导出后，需要执行 pnpm build 重新生成入口文件。

资料来源：libs/langchain-textsplitters/README.md

最佳实践

1. 版本兼容性

• 使用 ~ 而非 ^ 来锁定 @langchain/core 依赖
• 允许补丁版本更新，限制次版本兼容性

"peerDependencies": {
  "@langchain/core": "~0.3.0"
}

2. ESM 和 CJS 兼容

构建步骤应生成兼容两种模块系统的代码。使用 tsdown 进行编译：

tsdown src/index.ts --dts

3. 文档编写

每个集成包应包含 README.md，包含：

• 安装说明
• 环境变量配置
• 基本使用示例
• API 参考链接

4. 类型安全

• 导出完整的 TypeScript 类型定义
• 使用 Zod 进行运行时验证
• 避免使用 any 类型

扩展包注册表

常见问题

Q: 如何为现有包添加新功能？

在 src/ 目录创建新文件，然后在 src/index.ts 中导出。修改后运行 pnpm build 更新构建产物。

Q: 如何测试包之间的依赖关系？

使用 pnpm why <package> 检查依赖树，确保没有意外的版本冲突。

Q: MCP 适配器支持哪些 MCP 服务器？

理论上支持所有符合 MCP 协议规范的服务器，包括文件操作、数据库访问、API 调用等类型。

核心功能概览

LangChain.js 提供了丰富的功能模块，帮助开发者构建模块化、可组合的 LLM 应用程序。以下表格总结了主要功能模块及其用途：

文本分割器使用指南

文本分割是 RAG（检索增强生成）流水线中的关键步骤。LangChain.js 提供了多种文本分割器实现，最常用的是 RecursiveCharacterTextSplitter。

HTML 文档分割示例

以下示例展示了如何分割 HTML 文档：

import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";

const text = `<!DOCTYPE html>
<html>
  <head>
    <title>🦜️🔗 LangChain</title>
    <style>
      body { font-family: Arial, sans-serif; }
      h1 { color: darkblue; }
    </style>
  </head>
  <body>
    <div>
      <h1>🦜️🔗 LangChain</h1>
      <p>⚡ Building applications with LLMs through composability ⚡</p>
    </div>
  </body>
</html>`;

const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
});
const output = await splitter.createDocuments([text]);

资料来源：examples/src/langchain-classic/indexes/html_text_splitter.ts:1-28

分割器配置参数

开发与测试

@langchain/textsplitters 包的开发流程如下：

# 安装依赖
pnpm install

# 构建包
pnpm build
# 或从仓库根目录
pnpm build --filter @langchain/textsplitters

# 运行测试
pnpm test        # 单元测试
pnpm test:int    # 集成测试

资料来源：libs/langchain-textsplitters/README.md

代理中间件系统

LangChain.js 的代理系统支持中间件扩展，允许开发者在代理执行过程中插入自定义逻辑。

中间件状态解析

代理中间件使用状态模式管理状态架构，支持两种主要类型：

function parseMiddlewareState(
  stateSchema: unknown,
  state: Record<string, unknown>
): Record<string, unknown> {
  // 处理 LangGraph StateSchema（具有 fields 属性）
  if (StateSchema.isInstance(stateSchema)) {
    const result: Record<string, unknown> = {};
    for (const key of Object.keys(stateSchema.fields)) {
      if (key in state) {
        result[key] = state[key];
      }
    }
    return result;
  }

  // 使用 interopParse 处理 Zod schemas
  if (isInteropZodSchema(stateSchema)) {
    return interopParse(stateSchema as InteropZodObject, state);
  }

  throw new Error(`Invalid state schema type: ${typeof stateSchema}`);
}

资料来源：libs/langchain/src/agents/utils.ts:1-40

HITL 中断配置

人机交互（HITL）中间件提供了精细的中断控制能力：

export interface InterruptOnConfig {
  /**
   * 允许的决策列表
   */
  allowedDecisions?: string[];
  /**
   * 动态可调用描述
   */
  description?: z.union([z.string(), DescriptionFunctionSchema]).optional();
  /**
   * 如果允许编辑，则关联参数的 JSON schema
   */
  argsSchema?: z.record(z.any()).optional();
}

资料来源：libs/langchain/src/agents/middleware/hitl.ts:1-50

中间件架构流程

graph TD
    A[用户输入] --> B[代理处理器]
    B --> C{检查中间件}
    C -->|存在 HITL| D[显示工具调用信息]
    C -->|其他中间件| E[执行中间件逻辑]
    D --> F[等待用户批准/编辑]
    E --> G[继续执行]
    F --> G
    G --> H[返回结果]

动态工具描述示例

import type {
  AgentBuiltInState,
  Runtime,
  DescriptionFactory,
  ToolCall,
  InterruptOnConfig
} from "langchain";

const formatToolDescription: DescriptionFactory = (
  toolCall: ToolCall,
  state: AgentBuiltInState,
  runtime: Runtime<unknown>
) => {
  return `Tool: ${toolCall.name}\nArguments:\n${JSON.stringify(toolCall.args, null, 2)}`;
};

const config: InterruptOnConfig = {
  allowedDecisions: ["approve", "edit"],
  description: formatToolDescription
};

聊天模型集成

LangChain.js 提供了统一的接口来集成多种聊天模型提供商。

Anthropic 模型

ChatAnthropicMessages 类扩展了基础聊天模型，支持完整的 Anthropic API 功能：

export class ChatAnthropicMessages<
  CallOptions extends ChatAnthropicCallOptions = ChatAnthropicCallOptions,
>
  extends BaseChatModel<CallOptions, AIMessageChunk>
  implements AnthropicInput
{
  static lc_name() {
    return "ChatAnthropic";
  }

  get lc_secrets(): { [key: string]: string } | undefined {
    return {
      anthropicApiKey: "ANTHROPIC_API_KEY",
      apiKey: "ANTHROPIC_API_KEY",
    };
  }
}

资料来源：libs/providers/langchain-anthropic/src/chat_models.ts:1-30

OpenAI 模型

OpenAI 聊天模型同样提供了流式输出和完整响应支持：

for await (const chunk of await llm.stream(input)) {
  console.log(chunk);
}

输出示例：

AIMessageChunk {
  "id": "chatcmpl-9u4NWB7yUeHCKdLr6jP3HpaOYHTqs",
  "content": ""
}
AIMessageChunk {
  "content": "J"
}
AIMessageChunk {
  "content": "'adore"
}

资料来源：libs/providers/langchain-openai/src/chat_models/index.ts:1-50

工具调用与结构化输出

聊天模型支持两种结构化输出方式：

import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(
  async (input) => `Weather in ${input.location}`,
  {
    name: "get_weather",
    description: "Get weather for a location",
    schema: z.object({ location: z.string() }),
    extras: { defer_loading: true },
  }
);

事件系统

LangChain.js 的事件系统用于追踪和响应语言模型运行时的状态变化。

内容块事件

/**
 * 内容块增量更新时触发
 */
export interface ContentBlockDeltaEvent {
  event: "content-block-delta";
  /** 正在更新的块的位置索引 */
  index: number;
  /** 增量内容块 */
  delta: ContentBlockDelta;
}

/**
 * 内容块完成时触发
 */
export interface ContentBlockFinishEvent {
  event: "content-block-finish";
  /** 完成的块的位置索引 */
  index: number;
  /** 最终内容块 */
  content: ContentBlock;
}

资料来源：libs/langchain-core/src/language_models/event.ts:1-30

使用量事件

/**
 * 提供商报告使用量更新时触发
 * 每个事件携带运行快照（非增量）
 */
export interface UsageUpdateEvent {
  event: "usage";
  /** 当前使用量快照 */
  usage: Partial<UsageMetadata>;
}

提供商事件

/**
 * 用于原生提供商事件的透传
 */
export interface ProviderEvent {
  event: "provider";
  /** 提供商标识符 */
  provider: string;
  /** 来自提供商 SDK 的原始事件类型名 */
  name: string;
  /** 来自提供商 SDK 的原始事件载荷 */
  payload: unknown;
}

事件处理流程

graph LR
    A[流式调用] --> B[接收 AIMessageChunk]
    B --> C{检查事件类型}
    C -->|content-block-delta| D[更新文本内容]
    C -->|content-block-finish| E[标记块完成]
    C -->|usage| F[更新 token 统计]
    C -->|provider| G[透传原始事件]
    D --> H[累积完整响应]
    E --> H
    F --> H
    G --> H

聚合流式块

import { AIMessageChunk } from '@langchain/core/messages';
import { concat } from '@langchain/core/utils';

let fullForMetadata: AIMessageChunk | undefined;
for await (const chunk of await llm.stream(input)) {
  fullForMetadata = fullForMetadata
    ? concat(fullForMetadata, chunk)
    : chunk;
}
console.log(fullForMetadata?.usage_metadata);
// 输出: { input_tokens: 25, output_tokens: 20, total_tokens: 45 }

包依赖管理最佳实践

当在项目中使用多个 LangChain 包时，建议统一 @langchain/core 版本以避免兼容性问题：

{
  "name": "your-project",
  "version": "0.0.0",
  "dependencies": {
    "@langchain/anthropic": "^0.3.0",
    "@langchain/core": "^0.3.0"
  },
  "resolutions": {
    "@langchain/core": "^0.3.0"
  },
  "overrides": {
    "@langchain/core": "^0.3.0"
  },
  "pnpm": {
    "overrides": {
      "@langchain/core": "^0.3.0"
    }
  }
}

资料来源：libs/create-langchain-integration/template/README.md

迁移与弃用处理

LangChain.js 在演进过程中会迁移某些功能，开发者应注意弃用警告：

if (
  getEnvironmentVariable("LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS") !== "true"
) {
  console.warn(warningText);
}

通过设置环境变量 LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS=true 可以抑制迁移警告。

资料来源：libs/langchain-classic/src/util/entrypoint_deprecation.ts

常见模式总结

这些示例代码和最佳实践为开发者提供了构建生产级 LLM 应用的坚实基础。建议从简单的示例开始，逐步探索更高级的功能。

Pitfall Log / 踩坑日志

项目：langchain-ai/langchainjs

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：[Feature request] React Native support。

1. 配置坑 · 来源证据：[Feature request] React Native support

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature request] React Native support
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_39933028ef894033b30ff784e81f185f | https://github.com/langchain-ai/langchainjs/issues/4239 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：@langchain/[email protected]

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@langchain/[email protected]
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_36a7a58d5cd84bda8dde7918402a6f8a | https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.46 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：Must pass in at least 1 record to upsert.

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Must pass in at least 1 record to upsert.
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_26c3acaad9e14ed3953206f25870c0b0 | https://github.com/langchain-ai/langchainjs/issues/10890 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | README/documentation is current enough for a first validation pass.

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | last_activity_observed missing

6. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium

8. 安全/权限坑 · 来源证据：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4d2a6bed33284a3cbd2f3319321d9e4c | https://github.com/langchain-ai/langchainjs/issues/10894 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

9. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | release_recency=unknown