Skip to main content
本迁移指南概述了 LangChain v1 中的主要变更。要了解 v1 新功能的更多信息，请参阅介绍文章。 要升级，请执行以下操作： 
npm install langchain@latest @langchain/core@latest

​
createAgent

在 v1 中，预构建的 react agent 现在位于 langchain 包中。下表概述了功能变更：
部分变更内容
导入路径包从 @langchain/langgraph/prebuilts 移至 langchain
提示词参数重命名为 systemPrompt，动态提示词使用中间件
模型前钩子被带有 beforeModel 方法的中间件取代
模型后钩子被带有 afterModel 方法的中间件取代
自定义状态在中间件中定义，仅支持 zod 对象
模型通过中间件动态选择，不支持预绑定模型
工具工具错误处理移至带有 wrapToolCall 的中间件
结构化输出移除了提示式输出，使用 toolStrategy/providerStrategy
流式节点名称节点名称从 "agent" 改为 "model"
运行时上下文使用 context 属性而非 config.configurable
命名空间简化为专注于智能体构建块，遗留代码移至 @langchain/classic

​
导入路径

react agent 预构建的导入路径已从 @langchain/langgraph/prebuilts 更改为 langchain。函数名称已从 createReactAgent 更改为 createAgent： 
import { createReactAgent } from "@langchain/langgraph/prebuilts"; 
import { createAgent } from "langchain";

​
提示词

​
静态提示词重命名

prompt 参数已重命名为 systemPrompt： 
import { createAgent } from "langchain";

agent = createAgent({
  model,
  tools,
  systemPrompt: "You are a helpful assistant.", 
});

​
SystemMessage

如果在系统提示词中使用 SystemMessage 对象，现在直接使用其字符串内容： 
import { SystemMessage, createAgent } from "langchain";

const agent = createAgent({
  model,
  tools,
  systemPrompt: "You are a helpful assistant.", 
});

​
动态提示词

动态提示词是一种核心的上下文工程模式——它们根据当前对话状态调整您告诉模型的内容。要实现这一点，请使用 dynamicSystemPromptMiddleware： 
import { createAgent, dynamicSystemPromptMiddleware } from "langchain";
import * as z from "zod";

const contextSchema = z.object({
  userRole: z.enum(["expert", "beginner"]).default("user"),
});

const userRolePrompt = dynamicSystemPromptMiddleware((request) => { 
  const userRole = request.runtime.context.userRole;
  const basePrompt = "You are a helpful assistant.";

  if (userRole === "expert") {
    return `${basePrompt} Provide detailed technical responses.`;
  } else if (userRole === "beginner") {
    return `${basePrompt} Explain concepts simply and avoid jargon.`;
  }
  return basePrompt; 
});

const agent = createAgent({
  model,
  tools,
  middleware: [userRolePrompt],
  contextSchema,
});

await agent.invoke({
  messages: [new HumanMessage("Explain async programming")],
  context: {
    userRole: "expert",
  },
})

​
模型前钩子

模型前钩子现在通过带有 beforeModel 方法的中间件实现。这种模式更具可扩展性——您可以在调用模型之前定义多个要运行的中间件，并在智能体之间重用它们。 常见用例包括：
  • 总结对话历史
  • 修剪消息
  • 输入护栏，如 PII 脱敏
v1 包含内置的摘要中间件： 
import { createAgent, summarizationMiddleware } from "langchain";

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-5",
  tools,
  middleware: [
    summarizationMiddleware({
      model: "anthropic:claude-sonnet-4-5",
      maxTokensBeforeSummary: 1000,
    }),
  ],
});

​
模型后钩子

模型后钩子现在通过带有 afterModel 方法的中间件实现。这允许您在模型响应后组合多个处理程序。 常见用例包括：
  • 人工介入审批
  • 输出护栏
v1 包含内置的人工介入中间件： 
import { createAgent, humanInTheLoopMiddleware } from "langchain";

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-5",
  tools: [readEmail, sendEmail],
  middleware: [
    humanInTheLoopMiddleware({
      interruptOn: {
        sendEmail: { allowedDecisions: ["approve", "edit", "reject"] },
      },
    }),
  ],
});

​
自定义状态

自定义状态现在使用 stateSchema 属性在中间件中定义。使用 Zod 声明在智能体运行过程中携带的额外状态字段。 
import * as z from "zod";
import { createAgent, createMiddleware, tool } from "langchain";

const UserState = z.object({
  userName: z.string(),
});

const userState = createMiddleware({
  name: "UserState",
  stateSchema: UserState,
  beforeModel: (state) => {
    // 访问自定义状态属性
    const name = state.userName;
    // 可选择根据状态修改消息/系统提示词
    return;
  },
});

const greet = tool(
  async () => {
    return "Hello!";
  },
  {
    name: "greet",
    description: "Greet the user",
    schema: z.object({}),
  }
);

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-5",
  tools: [greet],
  middleware: [userState],
});

await agent.invoke({
  messages: [{ role: "user", content: "Hi" }],
  userName: "Ada",
});

​
模型

动态模型选择现在通过中间件进行。使用 wrapModelCall 根据状态或运行时上下文交换模型（和工具）。在 createReactAgent 中，这是通过传递给 model 参数的函数完成的。 此功能在 v1 中已移植到中间件接口。

​
动态模型选择

import { createAgent, createMiddleware } from "langchain";

const dynamicModel = createMiddleware({
  name: "DynamicModel",
  wrapModelCall: (request, handler) => {
    const messageCount = request.state.messages.length;
    const model = messageCount > 10 ? "openai:gpt-5" : "openai:gpt-5-nano";
    return handler({ ...request, model });
  },
});

const agent = createAgent({
  model: "openai:gpt-5-nano",
  tools,
  middleware: [dynamicModel],
});

​
预绑定模型

为了更好地支持结构化输出，createAgent 应接收一个普通模型（字符串或实例）和一个单独的 tools 列表。在使用结构化输出时，避免传递预绑定工具的模型。 
// 不再支持
// const modelWithTools = new ChatOpenAI({ model: "gpt-4o-mini" }).bindTools([someTool]);
// const agent = createAgent({ model: modelWithTools, tools: [] });

// 请改用
const agent = createAgent({ model: "openai:gpt-4o-mini", tools: [someTool] });

​
工具

createAgent 的 tools 参数接受：
  • 使用 tool 创建的函数
  • LangChain 工具实例
  • 表示内置提供者工具的对象
使用中间件 wrapToolCall 来集中处理工具的错误处理和日志记录。 
import { createAgent, createMiddleware } from "langchain";

const errorHandling = createMiddleware({
  name: "ToolErrors",
  wrapToolCall: async (request, handler) => {
    try {
      return await handler(request);
    } catch (err) {
      return `Error executing ${request.toolName}: ${String(err)}`;
    }
  },
});

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-5",
  tools: [checkWeather, searchWeb],
  middleware: [errorHandling],
});

​
结构化输出

​
节点变更

结构化输出过去是在与主智能体不同的单独节点中生成的。现在情况不再如此。结构化输出在主循环中生成（无需额外的 LLM 调用），从而降低了成本和延迟。

​
工具和提供者策略

在 v1 中，有两种策略：
  • toolStrategy 使用人工工具调用来生成结构化输出
  • providerStrategy 使用提供者原生的结构化输出生成
import { createAgent, toolStrategy } from "langchain";
import * as z from "zod";

const OutputSchema = z.object({
  summary: z.string(),
  sentiment: z.string(),
});

const agent = createAgent({
  model: "openai:gpt-4o-mini",
  tools,
  // 显式使用工具策略
  responseFormat: toolStrategy(OutputSchema), 
});

​
移除了提示式输出

通过 responseFormat 中的自定义指令进行的提示式输出已被移除，转而支持上述策略。

​
流式节点名称重命名

当从智能体流式传输事件时，节点名称从 "agent" 更改为 "model"，以更好地反映节点的用途。

​
运行时上下文

在调用智能体时，通过 context 配置参数传递静态的、只读的配置。这取代了使用 config.configurable 的模式。 
import { createAgent, HumanMessage } from "langchain";
import * as z from "zod";

const agent = createAgent({
  model: "openai:gpt-4o",
  tools,
  contextSchema: z.object({ userId: z.string(), sessionId: z.string() }),
});

const result = await agent.invoke(
  { messages: [new HumanMessage("Hello")] },
  { context: { userId: "123", sessionId: "abc" } }, 
);
旧的 config.configurable 模式仍然适用于向后兼容，但对于新应用程序或迁移到 v1 的应用程序，建议使用新的 context 参数。

​
标准内容

在 v1 中，消息获得了与提供者无关的标准内容块。通过 message.contentBlocks 访问它们，以获得跨提供者的一致、类型化视图。现有的 message.content 字段对于字符串或提供者原生结构保持不变。

​
变更内容

  • 消息上新的 contentBlocks 属性用于规范化内容。
  • ContentBlock 下新的 TypeScript 类型用于强类型化。
  • 通过 LC_OUTPUT_VERSION=v1 或 outputVersion: "v1" 可选择将标准块序列化到 content 中。

​
读取标准化内容

import { initChatModel } from "langchain";

const model = await initChatModel("openai:gpt-5-nano");
const response = await model.invoke("Explain AI");

for (const block of response.contentBlocks) {
  if (block.type === "reasoning") {
    console.log(block.reasoning);
  } else if (block.type === "text") {
    console.log(block.text);
  }
}

​
创建多模态消息

import { HumanMessage } from "langchain";

const message = new HumanMessage({
  contentBlocks: [
    { type: "text", text: "Describe this image." },
    { type: "image", url: "https://example.com/image.jpg" },
  ],
});
const res = await model.invoke([message]);

​
示例块类型

import { ContentBlock } from "langchain";

const textBlock: ContentBlock.Text = {
  type: "text",
  text: "Hello world",
};

const imageBlock: ContentBlock.Multimodal.Image = {
  type: "image",
  url: "https://example.com/image.png",
  mimeType: "image/png",
};
有关更多详细信息，请参阅内容块参考文档。

​
序列化标准内容

标准内容块默认不序列化到 content 属性中。如果您需要在 content 属性中访问标准内容块（例如，在向客户端发送消息时），可以选择将它们序列化到 content 中。 
export LC_OUTPUT_VERSION=v1
了解更多：消息 和 标准内容块。有关输入示例，请参阅 多模态。

​
简化的包

langchain 包的命名空间已简化，专注于智能体构建块。遗留功能已移至 @langchain/classic。新包仅公开最有用和最相关的功能。

​
导出

v1 包包括：
模块可用内容备注
智能体createAgent, AgentState核心智能体创建功能
消息消息类型、内容块、trimMessages从 @langchain/core 重新导出
工具tool、工具类从 @langchain/core 重新导出
聊天模型initChatModel, BaseChatModel统一的模型初始化

​
@langchain/classic

如果您使用遗留链、索引 API 或先前从 @langchain/community 重新导出的功能，请安装 @langchain/classic 并更新导入： 
npm install @langchain/classic

// v1 (新)
import { ... } from "@langchain/classic";
import { ... } from "@langchain/classic/chains";

// v0 (旧)
import { ... } from "langchain";
import { ... } from "langchain/chains";

​
破坏性变更

​
放弃 Node 18 支持

所有 LangChain 包现在需要 Node.js 20 或更高版本。Node.js 18 已于 2025 年 3 月终止支持。

​
新的构建输出

所有 langchain 包的构建现在使用基于打包器的方法，而不是使用原始的 typescript 输出。如果您曾经从 dist/ 目录导入文件（这不推荐），您需要更新导入以使用新的模块系统。

​
遗留代码移至 @langchain/classic

标准接口和智能体焦点之外的遗留功能已移至 @langchain/classic 包。有关核心 langchain 包中可用内容以及移至 @langchain/classic 的内容的详细信息，请参阅简化包部分。

​
移除已弃用的 API

已弃用并计划在 1.0 中移除的方法、函数和其他对象已被删除。
以下已弃用的 API 已在 v1 中移除：

​
核心功能

  • TraceGroup - 使用 LangSmith 追踪替代
  • BaseDocumentLoader.loadAndSplit - 使用 .load() 后跟文本分割器
  • RemoteRunnable - 不再支持

​
提示词

  • BasePromptTemplate.serialize 和 .deserialize - 直接使用 JSON 序列化
  • ChatPromptTemplate.fromPromptMessages - 使用 ChatPromptTemplate.fromMessages

​
检索器

  • BaseRetrieverInterface.getRelevantDocuments - 使用 .invoke() 替代

​
Runnables

  • Runnable.bind - 使用 .bindTools() 或其他特定的绑定方法
  • Runnable.map - 使用 .batch() 替代
  • RunnableBatchOptions.maxConcurrency - 在配置对象中使用 maxConcurrency

​
聊天模型

  • BaseChatModel.predictMessages - 使用 .invoke() 替代
  • BaseChatModel.predict - 使用 .invoke() 替代
  • BaseChatModel.serialize - 直接使用 JSON 序列化
  • BaseChatModel.callPrompt - 使用 .invoke() 替代
  • BaseChatModel.call - 使用 .invoke() 替代

​
LLMs

  • BaseLLMParams.concurrency - 在配置对象中使用 maxConcurrency
  • BaseLLM.call - 使用 .invoke() 替代
  • BaseLLM.predict - 使用 .invoke() 替代
  • BaseLLM.predictMessages - 使用 .invoke() 替代
  • BaseLLM.serialize - 直接使用 JSON 序列化

​
流式传输

  • createChatMessageChunkEncoderStream - 直接使用 .stream() 方法

​
追踪

  • BaseTracer.runMap - 使用 LangSmith 追踪 API
  • getTracingCallbackHandler - 使用 LangSmith 追踪
  • getTracingV2CallbackHandler - 使用 LangSmith 追踪
  • LangChainTracerV1 - 使用 LangSmith 追踪

​
内存和存储

  • BaseListChatMessageHistory.addAIChatMessage - 使用 .addMessage() 并传入 AIMessage
  • BaseStoreInterface - 使用特定的存储实现

​
工具函数

  • getRuntimeEnvironmentSync - 使用异步的 getRuntimeEnvironment()
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.