至于版本基准。LangChain.js v1 系列，资料核对日期：--。

本手册面向 Node.js / TypeScript 开发者，目标不是逐字翻译官方文档。而是把 LangChain.js 的主要 API、调用关系、常见组合方式和工程实践整理成一份可以直接落地的中文开发文档。

LangChain.js 是一个用于应用拆成若干可组合模块：模型、消息、提示词、工具、Agent、RAG 检索、结构化输出、流式事件、记忆和观测。

在 v1 系列里LangChain.js 的主线是：

• 用 createAgent 快速创建可调用工具、可流式输出、可加中间件的生产级 Agent。
• 用 initChatModel 或具体 provider 包创建聊天模型。
• 用标准 messages 表示对话上下文。
• 用 tool 暴露外部函数、API、数据库、搜索等能力。话说回来，
• 用 Runnable/LCEL 把 Prompt、Model、Parser、Retriever 等步骤组合成调用链。
• 用 @langchain/classic 兼容旧版 chains、内存向量库和部分老式 RAG API。
• 复杂状态机、分支、多 Agent 编排底层由 LangGraph 支撑。

典型调用关系：

flowchart LR
U --> M
M --> A
A --> L
L -->|需要外部动作| T
T --> A
A -->|需要知识库| R
R --> A
A --> O
O --> RES

. 版本和包结构

截至 --，通过 npm 核对到的版本：

. 包职责三层划分建议

$ # 应用层：
$ # LangChain 主要协议层：
$ # 集成/兼容层：

. 安装与项目初始化 

Pain Point： 很多新手在安装时会混淆 ESM 与 CommonJS，导致 import 错误。推荐统一使用 ESM 并在 package.json 中声明 `"type":"module"`。

官方 v1 文档要求 Node.js +。推荐使用 ESM：
# 初始化项目 
npm init -y
# 安装主要依赖 
npm install langchain @langchain/core zod
# 安装 provider 包 
npm install @langchain/openai
# 可选功能 
npm install @langchain/textsplitters @langchain/classic @langchain/langgraph
# 如需社区加载器 
npm install @langchain/community

. package.json 推荐配置 
{
""type": ""module""。""scripts": {
""dev": ""tsx src/index.ts"
},""dependencies{\ n " lang chain " ^ . ",\ n "... \ n },\ n "... devDependencies ... \ n } \ n }

. 环境变量示例 
export OPENAI_API_KEY=""
export LANGCHAIN_MODEL= "openai:gpt-4o-mini"
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=""
export LANGSMITH_PROJECT= "my-langsmith-project"

Pain Point： 生产环境千万不要把 Provider API Key 暴露到浏览器端；请使用后端代理或 Edge Function 转发请求。老实说，

. 最小可运行示例 
import { createAgent。tool } from "langchain";import { z } from "zod";const getWear = tool(
async => {
return `${city} 今天晴，温度约 25°C。
`，},{
name的观点是，"get_wear",description: "查询城市天气"。schema: z.object({
从city来看，z.string.describe,}),}
);const agent = createAgent({
model的观点是，process.env.LANGCHAIN_MODEL?，"openai:gpt-4o-mini",tools:。prompt:
"你是一个简洁可靠的中文助手。需要实时信息时先调用工具。",})，const result = await agent.invoke({
messages:,});console.log，.content);

Pain Point： 初学者经常忘记把自定义 Tool 加入 Agent 的 `tools` 参数，导致模型无法触发工具调用。请务必检查 `createAgent` 配置中的 `tools` 列表是否完整。

. 调用链拆解 
agent.invoke
→ Agent读取 messages + prompt
→ Chat Model 判断是否需要工具
→ generate tool call: get_wear
→ LangChain 调用 getWear 工具函数
→ 工具结果作为 ToolMessage 回到 Agent 状态
→ Chat Model
推理生成最终回复
→ result.messages 返回完整消息轨迹

. 主要概念总览 



概念
代表 API
输入
输出
常见位置




Message
HumanMessage,AIMessage,ToolMessage
文本/内容块
标准消息对象
所有聊天模型 & Agent


Chat Model
initChatModel,ChatOpenAI
messages / prompt value
AIMessage / stream chunk
推理主要


Tool
tool。DynamicStructuredTool
schema 验证后的参数
字符串或结构化结果
Agent 或 bindTools 使用场景


Runnable 
RunnableSequence,.pipe
/泛型输入 & 泛型输出         LCEL 链式组合 

 Output ParserStringOutputParser ,JsonOutputParser
模型输出 -> string / JSON / typed object


. Message API 

LangeChain.js 使用数组形式的消息来表示对话，可采用轻量对象或类实例两种写法：

. 对象写法示例 
{“language”:“javascript”}
const messages =;

. 类写法示例 
{“language”:“javascript”}
import { SystemMessage,HumanMessage } from “langchain”;const messages =;

. 常用消息类型一览 





Message 类型 


    程序指令，定义角色边界与输出风格 

    使用者输入 

    模型输出。可包含 tool_calls 、 usage 等元数据 

    工具执行结果，通常带 tool_call_id 


所有消息的基类，用于类型推导 


Pain Point： 有些开发者把程序提示写进 `HumanMessage` 内容里这会导致模型把程序指令当作使用者提问，从而产生意外行为。务必使用 `role:"system"` 或 `SystemMessage` 来定义程序指令。

. AIMessage 常见属性 

{「言語」＝「javascript」}
const ai = await model.invoke;按理说，console.log;老实说，// 文本或内容数组
console.log;怎么说呢，// 模型请求调用的工具
console.log;console.log，

. 内容块 支持说明 ​​​​​​

LangeChain 在不同 Provider 上统一了 `<代码>`contentBlocks` 接口，以便处理多模态内容、工具调用等场景。多数情况下直接读取 `message.content` 即可；若需细粒度处理，请参考官方文档中 ContentBlock 定义。话说回来，

{「语言」＝「javascript」}
import { initChatModel } from “langchain”;const model = await initChatModel(
process.env.LANGCHAIN_MODEL?，“openai:gpt‑4o‑mini”,{ temperature:0.7 }
);const response = await model.invoke();话说回来，console.log;