LangChain4j 1.11.0 升级实录：从 0.x 到 1.11 的 6 个Breaking Change

2026年2月刚发布的1.11.0，我花了3天升级，踩了这些坑

说实话，我之前的项目用的是 LangChain4j 0.35.0。

看到1.11.0发布的消息，想着"升级应该挺简单的吧，就是个版本号的事"。

结果 pom.xml 一改，编译报错一大堆。

这篇文章记录我从 0.x 升级到 1.11.0 的真实踩坑过程。

坑一：包结构大改，import 全红

报错现场：

java: 程序包 dev.langchain4j.agent.agentic 不存在
java: 找不到符号: 类 AiServices
java: 找不到符号: 类 ChatMemory

当时我的 pom.xml：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>0.35.0</version>
</dependency>

改成 1.11.0 后：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>1.11.0</version>
</dependency>

问题在哪：

1.11.0 重构了包结构，很多东西都换了地方：

旧位置 (0.x) 新位置 (1.11.0)
dev.langchain4j.service.AiServices dev.langchain4j.agentic.AiServices
dev.langchain4j.memory.ChatMemory dev.langchain4j.memory.chat.ChatMemory
dev.langchain4j.agent.Agent dev.langchain4j.agentic.Agent
dev.langchain4j.mcp.McpClient dev.langchain4j.mcp.client.McpClient

我是怎么解决的：

IDEA 全局替换：

查找：import dev.langchain4j.service.AiServices
替换：import dev.langchain4j.agentic.AiServices

但 Agent 相关的改动比较大，不只是包名变了，API 也变了…

坑二：Agentic API 完全重写，旧代码全废

报错现场：

java: 找不到符号: 类 Agent
java: 找不到符号: 方法 builder()
java: 方法 does not override or implement a method from a supertype

0.x 时代的代码（现在全废了）：

// 0.x 时代的写法，1.11.0 已完全不兼容
Agent agent = Agent.builder()
    .chatLanguageModel(model)
    .tools(List.of(tool1, tool2))
    .build();

String response = agent.execute("查询北京天气");

1.11.0 的新写法：

// 1.11.0 全新的 Agentic API
import dev.langchain4j.agentic.Agent;
import dev.langchain4j.agentic.Supervisor;

Agent agent = Agent.builder()
    .id("weather-agent")
    .chatModel(model)
    .toolProvider(toolProvider)  // 注意：不是 tools()
    .build();

// 执行方式也变了
AgentResult result = agent.execute(
    AgentInvocation.builder()
        .input("查询北京天气")
        .build()
);

我花了多久： 大概2小时看文档 + 重构代码。

核心变化：

  1. Agent 变成声明式配置：以前的编程式配置被废弃
  2. Supervisor 模式：多 Agent 协调有新 API
  3. AgentResult 取代 String：返回值封装了更多信息

迁移建议：

官方有个迁移指南，但还没写全。我主要靠看 langchain4j-agentic 模块的测试用例来学习新 API。

坑三：ChatMemory 的 set() 方法，想当然地用了

报错现场：

java.lang.UnsupportedOperationException: 
ChatMemoryWindow does not support set()

我当时在干嘛：

看到 Release Note 说 1.11.0 给 ChatMemory 加了 set() 方法，兴奋地想用来手动修改对话历史。

ChatMemory chatMemory = MessageWindowChatMemory.builder()
    .maxMessages(10)
    .build();

// 想手动修改某条消息
chatMemory.set(0, new UserMessage("修改后的内容"));

结果报错。

问题在哪：

只有 ChatMemoryWindow 的某些实现支持 set()，我之前用的 MessageWindowChatMemory 不支持。

1.11.0 的 ChatMemory 新类图：

ChatMemory (接口)
├── ChatMemoryWindow
│   ├── MessageWindowChatMemory  ❌ 不支持 set()
│   └── TokenWindowChatMemory     ❌ 不支持 set()
├── ChatMemoryStore
│   └── InMemoryChatMemoryStore   ✅ 支持 set()
└── PersistentChatMemory
    └── JdbcChatMemoryStore       ✅ 支持 set()

我是怎么解决的：

如果要支持 set()，需要换实现：

// 换成支持 set() 的实现
ChatMemoryStore store = InMemoryChatMemoryStore.builder().build();

ChatMemory chatMemory = ChatMemory.builder()
    .store(store)
    .maxMessages(10)
    .build();

// 现在可以用 set() 了
chatMemory.set(0, new UserMessage("修改后的内容"));

但注意： 这个 set() 是实验性功能，文档说未来可能改动。

坑四：MCP 的 Context 注入，Headers 变了

报错现场：

MCP Client error: Header 'X-Custom-Context' not allowed

0.x 的 MCP Client 配置：

McpClient client = McpClient.builder()
    .transport(new StdioMcpTransport())
    .customHeader("X-Custom-Context", "my-value")  // 1.11.0 已废弃
    .build();

1.11.0 的新写法：

import dev.langchain4j.mcp.client.McpClient;
import dev.langchain4j.mcp.client.transport.McpTransport;

McpClient client = McpClient.builder()
    .transport(McpTransport.STDIO)
    .headerProvider(() -> Map.of(
        "X-Custom-Context", "my-value"
    ))  // 新的 HeaderProvider API
    .listener(new McpClientListener() {
        @Override
        public void onConnect() {
            System.out.println("MCP 连接成功");
        }
        
        @Override
        public void onDisconnect() {
            System.out.println("MCP 断开连接");
        }
    })
    .build();

1.11.0 MCP 的重要变化：

  1. HeaderProvider: 动态提供 headers，支持 Supplier
  2. Listeners: 可以监听连接状态
  3. Context 注入: 支持在 headers 里注入上下文

我花了多久： 30分钟，主要是重新理解新 API 的设计思路。

坑五：Streaming 的取消机制，以前没这功能

场景：

用户发送了一个长问题，Agent 开始流式输出，但用户突然想中断。

0.x 时代的无奈：

// 0.x 只能等输出完，没法取消
streamingChatModel.generate("很长的提示词...", handler);
// 只能干等着...

1.11.0 的新功能：

import dev.langchain4j.model.chat.response.ChatResponse;
import java.util.concurrent.CancellationException;

// 1.11.0 支持取消
CancellationToken cancellationToken = new CancellationToken();

streamingChatModel.generate(
    "很长的提示词...",
    new StreamingChatResponseHandler() {
        @Override
        public void onNext(String token) {
            System.out.print(token);
        }
        
        @Override
        public void onError(Throwable error) {
            if (error instanceof CancellationException) {
                System.out.println("用户取消了请求");
            }
        }
    },
    cancellationToken  // 传入取消令牌
);

// 用户点击取消按钮时
cancellationToken.cancel();

但这是坑吗？

严格来说不是坑，是个惊喜。只是我需要重构之前的代码来支持这个功能。

坑六：Observability 监听器的线程安全问题

报错现场：

java.util.ConcurrentModificationException
    at java.util.ArrayList.forEach(ArrayList.java:1541)

我当时在干嘛：

1.11.0 新增了监听工具执行的功能，我想用来记录日志：

AiServices.builder(Assistant.class)
    .chatLanguageModel(model)
    .toolExecutionListener((tool, result) -> {
        // 记录工具执行
        logs.add(new ToolLog(tool.name(), result));  // ❌ 线程不安全
    })
    .build();

问题在哪：

Listener 可能在多线程环境下被调用，我用普通的 ArrayList 会有并发问题。

我是怎么解决的：

import java.util.concurrent.CopyOnWriteArrayList;

List<ToolLog> logs = new CopyOnWriteArrayList<>();

AiServices.builder(Assistant.class)
    .chatLanguageModel(model)
    .toolExecutionListener((tool, result) -> {
        logs.add(new ToolLog(tool.name(), result));  // ✅ 线程安全
    })
    .build();

1.11.0 新增的 Observability 功能：

  • ToolExecutionListener: 监听工具执行
  • EmbeddingModelListener: 监听 Embedding 调用
  • ContentRetrieverListener: 监听 RAG 检索

全部都要注意线程安全。

升级后的 pom.xml（完整版）

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>com.example</groupId>
    <artifactId>langchain4j-1.11-demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    
    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <langchain4j.version>1.11.0</langchain4j.version>
    </properties>
    
    <dependencies>
        <!-- 核心库 -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j</artifactId>
            <version>${langchain4j.version}</version>
        </dependency>
        
        <!-- Agentic 模块（1.11.0 新增） -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-agentic</artifactId>
            <version>${langchain4j.version}</version>
        </dependency>
        
        <!-- OpenAI 集成 -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-open-ai</artifactId>
            <version>${langchain4j.version}</version>
        </dependency>
        
        <!-- MCP 集成 -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-mcp</artifactId>
            <version>${langchain4j.version}</version>
        </dependency>
        
        <!-- 嵌入式模型（本地运行） -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-embeddings-all-minilm-l6-v2-q</artifactId>
            <version>1.0.0-beta1</version>
        </dependency>
    </dependencies>
</project>

一点总结

从 0.x 升级到 1.11.0，不是简单的改版本号。

主要的变化：

  1. 包结构重构：import 要全改
  2. Agentic API 重写：旧 Agent 代码要重写
  3. MCP 增强：新的 HeaderProvider 和 Listeners
  4. ChatMemory 新功能：set() 方法注意实现类
  5. Streaming 取消：新功能，需要重构代码
  6. Observability：注意线程安全

但升级是值得的。1.11.0 的 API 更统一，Agentic 模块的设计也更合理。

只是 migration guide 还没写全，很多要靠看源码和测试用例来学。

如果你也在升级，希望这篇能帮你省点时间。

GitHub 仓库： https://github.com/YaBoom/langchain4j-1.11-zyt

（包含完整的升级示例代码）

写作风格：踩坑实录型

  • 记录从 0.x 升级到 1.11.0 的真实过程
  • 对比新旧 API 的差异
  • 包含完整的代码迁移示例
# java # 人工智能
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

我测试了一个0.9B模型，它竟然能自动区分多人讲话）

avatar AI Agent技术社区
cover

从一张商品图到正式上架：实测店匠 Shoplazza Athena，AI Agent 不只是聊天框

avatar AI Agent技术社区
cover

【AI Agent】《2026年9月 AI Agent全栈开发技术选型专项面试宝典》

avatar AI Agent技术社区