跳到主要内容
本迁移指南概述了 LangChain v1 中的主要更改。要了解 v1 的新功能，请参阅介绍性文章。 要升级，
npm install langchain@latest @langchain/core@latest

​
createAgent

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

​
导入路径

react 代理预构建的导入路径已从 @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: "claude-sonnet-4-5-20250929",
  tools,
  middleware: [
    summarizationMiddleware({
      model: "claude-sonnet-4-5-20250929",
      maxTokensBeforeSummary: 1000,
    }),
  ],
});

​
模型后置钩子

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

const agent = createAgent({
  model: "claude-sonnet-4-5-20250929",
  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) => {
    // Access custom state properties
    const name = state.userName;
    // Optionally modify messages/system prompt based on state
    return;
  },
});

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

const agent = createAgent({
  model: "claude-sonnet-4-5-20250929",
  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: "gpt-5-nano",
  tools,
  middleware: [dynamicModel],
});

​
预绑定模型

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

// Use instead
const agent = createAgent({ model: "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: "claude-sonnet-4-5-20250929",
  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: "gpt-4o-mini",
  tools,
  // explicitly using tool strategy
  responseFormat: toolStrategy(OutputSchema), 
});

​
移除提示输出

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

​
流式节点名称重命名

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

​
运行时上下文

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

const agent = createAgent({
  model: "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("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 (new)
import { ... } from "@langchain/classic";
import { ... } from "@langchain/classic/chains";

// v0 (old)
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()

​
可运行对象

  • Runnable.bind - 改用 .bindTools() 或其他特定绑定方法
  • Runnable.map - 改用 .batch()
  • RunnableBatchOptions.maxConcurrency - 改用 config 对象中的 maxConcurrency

​
聊天模型

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

​
LLMs

  • BaseLLMParams.concurrency - 改用 config 对象中的 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()
在 GitHub 上编辑此页面源文件。
以编程方式连接这些文档到 Claude、VSCode 等，通过 MCP 获取实时答案。
© . This site is unofficial and not affiliated with LangChain, Inc.