手敲重构学透 Multi-Agent 代码（下）：从 AgentScope 1.0.8 升级到 2.0，API 变了什么、踩了哪些坑

手敲重构学透 Multi-Agent 代码（下）：从 AgentScope 1.0.8 升级到 2.0，API 变了什么、踩了哪些坑

上篇把 AgentScope 1.0.8 的代码逐行手敲重构了一遍，每一行都搞懂了。这一篇接着记录升级到 2.0 的全过程------先是借助 AI 工具（Qoder、OpenCode）把 2.0 跑了一遍，踩了一堆坑；再手动重构，搞懂每一个 API 变化。哪些 API 变了、哪些坑踩了、虎头蛇尾又怎么收的场，都记在这里了。

1.0.8 版本全部搞懂之后，开始升级到 AgentScope 2.0。2.0 相比 1.x 有不少变化，这里先列一个总览，后面逐个展开：

变化点	1.0.8 写法	2.0 写法
任务分解	PlanNotebook + .enablePlan()	.enableTaskList()
Skills 加载	JarSkillRepositoryAdapter	ClasspathSkillRepository
DashScope 模型包路径	io.agentscope.core.model	io.agentscope.extensions.model
结构化输出	需 StructuredOutputReminder	call(msg, Class) 原生支持
核心依赖	agentscope-spring-boot-starter	agentscope + 独立扩展包
Nacos A2A	打包在 starter 中	拆为 agentscope-extensions-nacos-a2a

看起来变化不少，但实际改起来，大部分是「删掉旧写法、换成新方法名」的体力活。真正费时间的是那些文档没写清楚、只能靠报错一步步摸索的细节。

不过在手动重构之前，其实已经借助 AI 工具把 2.0 版本先跑了一遍。这个过程一波三折------先用 Qoder，免费额度用完了；改用 OpenCode，又踩了一堆坑。但正是这个「先让 AI 跑一遍」的过程，给后面的手动重构打下了基础：至少知道了 2.0 大概要改哪些东西，哪些地方是坑。

一、借助 AI 初探 2.0：从 Qoder 到 OpenCode

1.1 Qoder 试水

前面用 Qoder 学习代码的效果不错，这次升级 2.0 也先让它试试：

在AiTripPlan-V2中，将前面108的功能升级到2.0。

这些功能，文档都可以提取在readme.md中

Qoder 确实能做，但免费版本用不了------额度又用完了。

1.2 改用 OpenCode 迁移

Qoder 免费额度用完之后，改用 OpenCode 来做迁移。OpenCode 的优势在于免费，虽然能力上比 Qoder 差了不少，但免费就是最大的优势。

AiTripPlan-v108 -> 多agent功能已完成
将同样的功能迁移到AiTripPlan-V2
目录已创建，同样的功能都要迁移，且生成文档放在AiTripPlan-V2中的doc中。
ai-trip-plan-frontend 是v108的前端，要保证v2的所有接口都一样，直接访问，端口也一样吧。

1.3 运行踩坑：logback 冲突与 Nacos 连接

代码迁移完之后，启动就报错了。

logback 版本冲突

运行 ManagerAgentApplication 时，直接启动失败------logback-classic 1.4.14 和 logback-core 1.5.34 版本不兼容，LoggerContext.initCollisionMaps() 方法在 1.4.x 中不存在：

Logging system failed to initialize using configuration from 'null'
java.lang.NoSuchMethodError: 'void ch.qos.logback.classic.LoggerContext.initCollisionMaps()'
	at ch.qos.logback.classic.LoggerContext.reset(LoggerContext.java:362)
	at ch.qos.logback.classic.LoggerContext.stop(LoggerContext.java:343)
	at org.springframework.boot.logging.logback.LogbackLoggingSystem.stopAndReset(LogbackLoggingSystem.java:309)
	...
17:52:09.510 [main] ERROR org.springframework.boot.diagnostics.LoggingFailureAnalysisReporter -- 

***************************
APPLICATION FAILED TO START
***************************

Description:

An attempt was made to call a method that does not exist. The attempt was made from the following location:

    ch.qos.logback.classic.LoggerContext.reset(LoggerContext.java:362)

The following method did not exist:

    'void ch.qos.logback.classic.LoggerContext.initCollisionMaps()'

The calling method's class, ch.qos.logback.classic.LoggerContext, was loaded from the following locations:

    jar:file:/F:/maven/repository/ch/qos/logback/logback-classic/1.4.14/logback-classic-1.4.14.jar

The called method's class hierarchy was loaded from the following locations:

    ch.qos.logback.classic.LoggerContext: logback-classic-1.4.14.jar
    ch.qos.logback.core.ContextBase: logback-core-1.5.34.jar

Action:

Correct the classpath of your application so that it contains a single, compatible version of ch.qos.logback.classic.LoggerContext

问题根因：AgentScope 2.0 的依赖树拉入了 logback-core 1.5.34，但 Spring Boot 管理的 logback-classic 还停留在 1.4.14，两个版本跨大版本不兼容。这也是为什么后面 ai-core 的 pom 里显式指定了 logback-classic 的版本------统一版本才能解决冲突。

Nacos 连不上

logback 解决之后，又遇到了 Nacos 连接问题。OpenCode 生成的配置里，Agent Card 的 URL 写成了本地 IP，而不是走 Nacos 注册中心：

  a2a:
    server:
      enabled: true
      card:
        name: RouteMakingAgent
        url: ${ROUTE_AGENT_CARD_URL:http://192.168.55.1:8120}
        description: 路线规划专家，提供驾车/铁路/飞机路线、距离、耗时、交通方式对比 为什么不是192.168.55.140:8848

没看到连接到nacos啊

太慢了，取消了前面的回答，重新提问：

自己注册到nacos也不用自己配置啊，这多笨啊。 108版本不是有注册到nacos吗？你有没有看代码 。

OpenCode 又开始「试一下那个试一下」了，不得不提醒它：

我不希望你是这样试一下那样试一下，而是要就这种方法，一定要搞好，不然就会同一堆bug不停的出现，不停的出现。 一次只改一个地方，一个bug，不要动不动就换思路，只要是开始认为的思路就一直走下去。将这个写进opencode目录下的skills里面去。还有java，maven，这种常用的工具地址也写进skills里面去，不要每次查找下载。

1.4 关于 AI 工具的体会

真正来说，OpenCode 的优势在于免费，Qoder 比 OpenCode 强的不是一点点。但 OpenCode 免费啊，这也算是大优势了。少说一句都不行，还自作主张，说是没调通 Nacos，所以就自己注册了------妈呀，这都不是幻觉了。

更多的时候，我不希望 AI 工具这样试一下那样试一下，而是要就这种方法，一定要搞好，不然就会同一堆 bug 不停地出现、不停地出现。

正是有了这次 AI 辅助的初探，才让后面的手动重构更有方向感------至少知道了 2.0 的坑大概在哪些地方：logback 版本冲突、Nacos 连接配置、依赖包结构变化。下面就开始逐模块手动重构。

二、初始环境准备

为了避免和 1.0.8 的模块混淆，将 ai-common 改名为 ai-core。名字虽然只改了几个字母，但意义不同：ai-common 是 1.0.8 的公共模块，ai-core 是 2.0 的公共模块，两边依赖的 AgentScope 版本不同，混在一起容易出问题。新开一个项目 AITripPlan-V2，结构上和 1.0.8 保持一致：ai-core（公共模块）、manager-agent、routeMaking-agent、tripPlanner-agent。

粗糙地将 2.0 版本运行了出来，其他代码变化不大，主要是配置和 pom 依赖的调整。

2.1 ai-core

Properties 只是做了常规调整，包名从 vip.wayhua.ivy.ai.common.conf 改为 vip.wayhua.ivy.ai.conf。字段和 1.0.8 一致，没有什么新增。

package vip.wayhua.ivy.ai.conf;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;

/**
 *
 * @Author:黄卫华（wayhua@126.com）
 * @Description:
 * @date： 2026-08-06 08:58
 * @modifiedBy：
 * @version: 1.0
 */
@Configuration
public class Properties {

    // 大模型名称
    @Value("${ivy.agent.model_name}")
    private String modelName;

    // 阿里云DashScope Key
    @Value("${ivy.agent.dashscope_key}")
    private String dashscopeKey;

    @Value("${ivy.agent.dashscope_openai_base_url}")
    private String dashscopeOpenAiBaseUrl;


    // 百度地图MCP Key
    @Value("${ivy.mcp.baidu_map_addr}")
    private String baiduMapAddr;

    public String getModelName() {
        return modelName;
    }

    public void setModelName(String modelName) {
        this.modelName = modelName;
    }

    public String getDashscopeKey() {
        return dashscopeKey;
    }

    public void setDashscopeKey(String dashscopeKey) {
        this.dashscopeKey = dashscopeKey;
    }

    public String getDashscopeOpenAiBaseUrl() {
        return dashscopeOpenAiBaseUrl;
    }

    public void setDashscopeOpenAiBaseUrl(String dashscopeOpenAiBaseUrl) {
        this.dashscopeOpenAiBaseUrl = dashscopeOpenAiBaseUrl;
    }

    public String getBaiduMapAddr() {
        return baiduMapAddr;
    }

    public void setBaiduMapAddr(String baiduMapAddr) {
        this.baiduMapAddr = baiduMapAddr;
    }
}

AgentCallLogHook 改动不大，主要是包名调整。

package vip.wayhua.ivy.ai.hook;


import io.agentscope.core.hook.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import reactor.core.publisher.Mono;

/**
 * Agent 调用日志 Hook
 * <p>
 * 监听 Agent 的推理和工具调用事件，在 Agent 被调用时输出明确的日志，
 * 用于确认 Agent 确实被调用过。
 * <p>
 * 事件说明：
 * - PreReasoningEvent:  Agent 收到请求，开始推理（证明 Agent 被调用）
 * - PostReasoningEvent: Agent 推理完成
 * - PostActingEvent:    Agent 工具调用完成
 *
 * @Author:黄卫华（wayhua@126.com）
 * @Description:
 * @date： 2026-08-06 09:18
 * @modifiedBy：
 * @version: 1.0
 */
public class AgentCallLogHook implements Hook {

    private static final Logger log = LoggerFactory.getLogger(AgentCallLogHook.class);
    private final String agentName;

    public AgentCallLogHook(String agentName) {
        this.agentName = agentName;
    }

    @Override
    public <T extends HookEvent> Mono<T> onEvent(T event) {
        if (event instanceof PreReasoningEvent e) {
            // Agent 收到请求，开始推理 ------ 这证明 Agent 确实被调用了
            String input = "";
            if (e.getInputMessages() != null && !e.getInputMessages().isEmpty()) {
                input = e.getInputMessages().get(0).getTextContent();
                if (input != null && input.length() > 300) {
                    input = input.substring(0, 300) + "...";
                }
            }
            log.info("======================================================");
            log.info(">>> [{}] Agent 被调用! 开始处理请求", agentName);
            log.info(">>> [{}] 输入内容: {}", agentName, input);
            log.info("======================================================");

        } else if (event instanceof PostReasoningEvent e) {
            // Agent 推理完成
            String reasoning = e.getReasoningMessage() != null
                    ? e.getReasoningMessage().getTextContent()
                    : "";
            int length = reasoning != null ? reasoning.length() : 0;
            log.info(">>> [{}] 推理完成 (思考内容长度: {} 字符)", agentName, length);

        } else if (event instanceof PostActingEvent e) {
            // Agent 工具调用完成
            String toolName = e.getToolUse() != null ? e.getToolUse().getName() : "unknown";
            log.info(">>> [{}] 工具调用完成: {}", agentName, toolName);
        }

        // 返回原事件，不修改
        return Mono.just(event);
    }
}

修改比较多的是 pom。2.0 版本的依赖结构有变化，agentscope-spring-boot-starter 换成了核心包 agentscope，Nacos A2A 相关功能拆成了独立扩展包。这个变化其实反映了 2.0 的设计思路：核心功能和扩展功能分离，你只引入你需要的部分，而不是一股脑全塞进来。好处是依赖更轻量，坏处是你得搞清楚自己到底需要哪些包------以前一个 starter 搞定的事，现在要手动拼。

<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>
    <parent>
        <groupId>vip.wayhua.ivy.ai</groupId>
        <artifactId>AITripPlan-V2</artifactId>
        <version>1.0.1</version>
    </parent>

    <artifactId>ai-core</artifactId>
    <packaging>jar</packaging>

    <name>ai-core</name>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

    </properties>

    <dependencies>
        <dependency>
            <groupId>io.agentscope</groupId>
            <artifactId>agentscope</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webflux</artifactId>
        </dependency>
        <!--   实现slf4j接口，不然日志打印不出来    -->
        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-classic</artifactId>
            <version>${logback.version}</version>
        </dependency>
        <dependency>
            <groupId>io.agentscope</groupId>
            <artifactId>agentscope-extensions-nacos-a2a</artifactId>
        </dependency>
        <dependency>
            <groupId>io.agentscope</groupId>
            <artifactId>agentscope-extensions-a2a-client</artifactId>
        </dependency>

        <dependency>
            <groupId>com.alibaba.nacos</groupId>
            <artifactId>nacos-client</artifactId>
        </dependency>
    </dependencies>
</project>

1.0.8 的大部分功能还是能用的，主要是修改一些配置和 pom 依赖。2.0 把一些功能拆成了独立的扩展包，比如 agentscope-extensions-nacos-a2a（Nacos A2A 扩展）和 agentscope-extensions-a2a-client（A2A 客户端扩展），需要单独引入。

AgentUtils 的核心逻辑没变，但 DashScopeChatModel 的包路径从 io.agentscope.core.model 移到了 io.agentscope.extensions.model。这个变化说明 DashScope 支持从核心包剥离成了扩展------毕竟不是所有人都用阿里云的模型，放到 extensions 里更合理。

package vip.wayhua.ivy.ai.utils;

import io.agentscope.core.ReActAgent;

import jakarta.annotation.Resource;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import io.agentscope.extensions.model.dashscope.DashScopeChatModel;
import vip.wayhua.ivy.ai.conf.Properties;
import vip.wayhua.ivy.ai.hook.AgentCallLogHook;

/**
 *
 * @Author:黄卫华（wayhua@126.com）
 * @Description:
 * @date： 2026-08-06 09:24
 * @modifiedBy：
 * @version: 1.0
 */
@Component
public class AgentUtils {
    private static final Logger log = LoggerFactory.getLogger(AgentUtils.class);
    @Resource
    Properties properties;

    public ReActAgent.Builder getReActAgentBuilder(String name, String description) {
        String host = properties.getDashscopeOpenAiBaseUrl();
        log.error("==========================");
        log.error("openAiBaseUrl:" + host);
        log.error("==========================");
        String aliApiKey = properties.getDashscopeKey();


        String modelName = properties.getModelName();
        log.error("==========================");
        log.error("主管Agent使用的大模型:" + modelName);
        log.error("==========================");


        return ReActAgent.builder()
                .name(name)
                .description(description)
                .model(DashScopeChatModel.builder()
                        //请求语言大模型的apikey
                        .apiKey(aliApiKey)
                        //所使用的语言大模型
                        .modelName(modelName)
                        .stream(true)
                        //开启思考模式
                        .enableThinking(true)
                        .build())
                //直接在这添加全局日志
                .hook(new AgentCallLogHook(name))
                ;

    }

}

三、manager-agent 模块

3.1 ManagerAgent

2.0 版本的 ManagerAgent 主要变化在任务分解和结构化输出：PlanNotebook 被移除，改用 .enableTaskList()；StructuredOutputReminder 不再需要，call(msg, Class) 原生支持结构化输出。

说具体一点：

• 任务分解 ：1.0.8 里要手动创建 PlanNotebook，通过 .enablePlan() 和 .planNotebook(planNotebook) 来开启任务分解。2.0 简化成一个链式调用 .enableTaskList()，Agent 能自主分解复杂任务、生成执行步骤、跟踪状态并动态调整。代码量少了，但功能反而更强了。
• 结构化输出 ：1.0.8 里需要额外传一个 StructuredOutputReminder 来告诉 Agent「请按这个 schema 返回」。2.0 直接在 call() 方法里传 Class 参数就行，框架自动处理序列化。少了一层间接性，代码更直观。

代码中的注释块详细记录了这些 API 变化，方便对照。

package vip.wayhua.ivy.ai.manager.agent;

import com.alibaba.nacos.api.ai.AiService;
import com.alibaba.nacos.api.exception.NacosException;
import com.fasterxml.jackson.databind.ObjectMapper;
import io.agentscope.core.ReActAgent;
import io.agentscope.core.a2a.agent.A2aAgent;
import io.agentscope.core.agent.Event;
import io.agentscope.core.agent.EventType;
import io.agentscope.core.event.AgentEventType;
import io.agentscope.core.event.ThinkingBlockDeltaEvent;
import io.agentscope.core.message.Msg;
import io.agentscope.core.nacos.a2a.discovery.NacosAgentCardResolver;
import io.agentscope.core.tool.Toolkit;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import vip.wayhua.ivy.ai.data.ResponseSchema;
import vip.wayhua.ivy.ai.manager.hook.PlanHook;
import vip.wayhua.ivy.ai.manager.tool.RemoteAgentTool;
import vip.wayhua.ivy.ai.utils.AgentUtils;
import vip.wayhua.ivy.ai.utils.NacosUtils;
import vip.wayhua.ivy.ai.utils.PromptUtils;
import vip.wayhua.ivy.ai.utils.ToolUtils;

import java.util.HashMap;
import java.util.Map;

/**
 *
 * @Author:黄卫华（wayhua@126.com）
 * @Description:
 * @date： 2026-08-06 16:42
 * @modifiedBy：
 * @version: 1.0
 */
@Component
public class ManagerAgent {
    private static final Logger log = LoggerFactory.getLogger(ManagerAgent.class);
    private final ObjectMapper objectMapper = new ObjectMapper();
    private final ReActAgent agent;

    AgentUtils agentUtils;

    public ReActAgent getManagerAgent() {
        return this.agent;
    }


    public ManagerAgent(AgentUtils agentUtils, NacosUtils nacosUtils) throws NacosException {
        this.agentUtils = agentUtils;
        //Toolkit
        ToolUtils toolUtils = new ToolUtils();

        log.info("--------------------------");
        AiService nacosClient = nacosUtils.getNacosClient();
        log.info("--------------------------");

        A2aAgent routeMakingAgent = A2aAgent.builder()
                .name("RouteMakingAgent")
                .agentCardResolver(
                        //创建 Nacos 的 AgentCardResolver
                        new NacosAgentCardResolver(nacosClient))
                .build();

        A2aAgent tripPlannerAgent = A2aAgent.builder()
                .name("TripPlannerAgent")
                .agentCardResolver(
                        //创建 Nacos 的 AgentCardResolver
                        new NacosAgentCardResolver(nacosClient))
                .build();
        //将远程Agent封装为工具的封装注册到工具包
     Toolkit toolkit = toolUtils.getToolkit(new RemoteAgentTool(routeMakingAgent,tripPlannerAgent));

        agent = agentUtils.getReActAgentBuilder(
                        "ManagerAgent",
                        "主管Agent"
                )
                /* **********************
                 *
                 * AgentScope 2.0 的任务分解能力：
                 *
                 * 1.x 版本通过 PlanNotebook (PlanAct + ReAct) 实现任务分解与步骤执行：
                 * .enablePlan()  /  .planNotebook(planNotebook)
                 *
                 * 2.0 版本 PlanNotebook 已移除，改为 .enableTaskList()：
                 * 开启后 ReActAgent 能自主分解复杂任务、生成执行步骤、状态跟踪、动态调整。
                 *
                 * *********************/
                .enableTaskList()
                .hook(new PlanHook())
                //工具包
                 .toolkit(toolkit)
                //结构化输出：2.0 由 call(msg, Class) 原生支持，无需 StructuredOutputReminder
                .build();
    }


    public ResponseSchema run(String prompt) {

        Msg response = agent.call(PromptUtils.getUserMsg(prompt)).block();

        ResponseSchema data = new ResponseSchema();
        data.response = response != null ? response.getTextContent() : "";
        return data;
    }

    public Flux<String> stream(String prompt) {
        return agent.stream(PromptUtils.getUserMsg(prompt))
//                .filter(event -> {
//                    // 2.0 枚举：AgentStreamEvent.Type.REASONING
//                    boolean isReasoning = AgentStreamEvent.Type.REASONING.equals(event.type());
//                    if (isReasoning) {
//                        log.debug("已过滤 REASONING 事件，不推送到前端");
//                    }
//                    return !isReasoning;
//                })

//                .filter(event -> {
//                    // 过滤思考推理事件，不推前端
////                    boolean isReasoning = event instanceof ThinkingBlockDeltaEvent;
//                    boolean isReasoning = AgentEventType.R.REASONING.equals(event.getType());
//                    if (isReasoning) {
//                        log.debug("已过滤 REASONING(ThinkingBlockDeltaEvent) 事件，不推送到前端");
//                    }
//                    return !isReasoning;
//                })
                .map(this::eventToJson)
                .onErrorResume(e -> {
                    log.warn("Agent 流式执行异常", e);
                    Map<String, Object> err = new HashMap<>();
                    err.put("type", "ERROR");
                    err.put("text", "执行出错：" + e.getMessage());
                    return Mono.just(toJsonString(err));
                })
                .concatWith(Mono.just("{\"type\":\"DONE\",\"text\":\"\",\"isLast\":true}"));

//
//                .map(this::eventToJson)
//                .onErrorResume(e -> {
//                    log.warn("Agent 流式执行异常", e);
//                    Map<String, Object> err = new HashMap<>();
//                    err.put("type", "ERROR");
//                    err.put("text", "执行出错：" + e.getMessage());
//                    return Mono.just(toJsonString(err));
//                })
//                .concatWith(Mono.just("{\"type\":\"DONE\",\"text\":\"\",\"isLast\":true}"));
    }

    private String eventToJson(Event event) {
        Map<String, Object> map = new HashMap<>();
        EventType type = event.getType();
        String text = event.getMessage() != null ? event.getMessage().getTextContent() : "";

        if (type == EventType.REASONING) {
            map.put("type", "REASONING");
            map.put("text", text != null ? text : "");
        } else if (type == EventType.TOOL_RESULT) {
            map.put("type", "TOOL_RESULT");
            map.put("text", text != null ? text : "");
        } else {
            map.put("type", "TEXT");
            map.put("text", text != null ? text : "");
        }
        map.put("isLast", event.isLast());

        return toJsonString(map);
    }

    private String toJsonString(Map<String, Object> map) {
        try {
            return objectMapper.writeValueAsString(map);
        } catch (Exception e) {
            return "{\"type\":\"ERROR\",\"text\":\"JSON序列化失败\"}";
        }
    }
}

3.2 RemoteAgentTool

RemoteAgentTool 和 1.0.8 版本基本一致，主要是包名调整。流式调用的逻辑没有变化------还是通过 A2aAgent.stream(userMsg) 发起流式请求，用 reduce 拼接结果，加上超时和错误处理。

值得一提的是，2.0 里 A2aAgent 的构建方式没变，还是通过 NacosAgentCardResolver 从 Nacos 注册中心获取 Agent Card。上篇里花了不少时间把 Trae 硬编码的 127.0.0.1:8120 改成 Nacos 服务发现，这次升级到 2.0 这部分代码倒是省心了，直接搬过来就行。

package vip.wayhua.ivy.ai.manager.tool;

import com.alibaba.nacos.api.exception.NacosException;
import io.agentscope.core.a2a.agent.A2aAgent;
import io.agentscope.core.message.Msg;
import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import reactor.core.publisher.Mono;
import vip.wayhua.ivy.ai.utils.PromptUtils;

import java.time.Duration;

/**
 *
 * @Author:黄卫华（wayhua@126.com）
 * @Description:
 * @date： 2026-08-06 20:24
 * @modifiedBy：
 * @version: 1.0
 */
public class RemoteAgentTool {
    private static final Logger log = LoggerFactory.getLogger(RemoteAgentTool.class);


    // 流式调用超时时间
    private static final Duration STREAM_TIMEOUT = Duration.ofSeconds(180);
    // ========= 不在这里注入，外部把A2aAgent实例传入 =========
    private final A2aAgent routeMakingAgent;
    private final A2aAgent tripPlannerAgent;

    /**
     * 构造函数：由业务侧（ManagerAgent）传入已经构建好的A2aAgent实例
     * @param routeMakingAgent 路线agent
     * @param tripPlannerAgent 行程agent
     */
    public RemoteAgentTool(A2aAgent routeMakingAgent, A2aAgent tripPlannerAgent) {
        this.routeMakingAgent = routeMakingAgent;
        this.tripPlannerAgent = tripPlannerAgent;
    }

    //    @Tool(description = "从Nacos注册中心获取路线制定Agent")
    @Tool(description = "路线规划专家，提供：驾车/铁路/飞机路线、距离、耗时、交通方式对比。必须调用此工具获取任何交通路线信息，严禁自行编造车次和航班或路线")
    public Mono<String> callRouteMakingAgent(
            @ToolParam(name = "prompt", description = "路线查询需求，包含起点、终点、出行方式（铁路/自驾/飞机等）")
            String prompt) throws NacosException {
        final String PREFIX = "【callRouteMakingAgent 返回】\n";

        if (prompt == null || prompt.isBlank()) {
            log.warn("callRouteMakingAgent 收到空 prompt，跳过调用");
            return Mono.just(PREFIX + "无法制定路线：未收到有效的起终点信息");
        }
        log.info("callRouteMakingAgent -> 正在通过流式调用路线规划Agent");
        log.info("参数：" + prompt);
//        A2aAgent agent = A2aAgent.builder()
//                .name("RouteMakingAgent")
//                .agentCardResolver(
//                        //创建 Nacos 的 AgentCardResolver
//                        new NacosAgentCardResolver(nacosUtils.getNacosClient()))
//                .build();


        log.error("==========================");
        log.error("获取到的远程Agent描述：" + routeMakingAgent.getDescription());
        log.error("==========================");

        log.error("============");
        log.error("这个工具方法传入的参数：" + prompt);
        log.error("============");
//        Flux<Event> stream = agentUtils.streamResponse(agent, "调用百度地图MCP");
//
//        stream
//                .doOnNext(msg -> System.out.println(msg.getMessage().getTextContent()))
//                //阻塞直到结束
//                .blockLast();

        //远程Agent运行
//        agent.call().block();

        Msg userMsg = PromptUtils.getUserMsg(prompt);
        //远程Agent运行
        // 使用 stream() 流式调用，避免 call().block() 导致的 SSE 缓冲区溢出
        return routeMakingAgent.stream(userMsg)
                .doOnNext(event -> log.debug("[RouteMakingAgent] 收到流式事件: type={}, isLast={}",
                        event.getType(), event.isLast()))
                .map(event -> {
                    if (event.getMessage() != null) {
                        String text = event.getMessage().getTextContent();

                        return text != null ? text : "";
                    }
                    return "";
                })
                .filter(text -> !text.isEmpty())
                .reduce("", String::concat)
                .map(result -> result.isEmpty() ? PREFIX + "远程Agent未返回内容" : PREFIX + result)
                .timeout(STREAM_TIMEOUT)
                .doOnSuccess(result -> log.info("callRouteMakingAgent 流式调用完成, 结果长度: {} 字符",
                        result != null ? result.length() : 0))
                .onErrorResume(e -> {
                    log.error("callRouteMakingAgent 流式调用失败", e);
                    return Mono.just(PREFIX + "路线规划Agent调用失败: " + e.getMessage());
                });
    }


    @Tool(description = "行程规划专家，提供：每日景点安排、美食推荐、住宿建议、天气参考。获取路线后必须调用此工具完成行程细节规划")
    public Mono<String> callTripPlannerAgent(
            @ToolParam(name = "prompt", description = "行程规划需求，包含目的地、天数、偏好、路线信息等")
            String prompt) throws NacosException {
        // 工具名前缀，用于前端识别工具归属（与 mock 数据格式一致）
        final String PREFIX = "【callTripPlannerAgent 返回】\n";

        if (prompt == null || prompt.isBlank()) {
            log.warn("callTripPlannerAgent 收到空 prompt，跳过调用");
            return Mono.just(PREFIX + "无法规划行程：未收到有效的行程需求信息");
        }

        log.info("callTripPlannerAgent -> 正在通过流式调用行程规划Agent");
        log.info("参数：" + prompt);

//        A2aAgent agent = A2aAgent.builder()
//                .name("TripPlannerAgent")
//                .agentCardResolver(
//                        //创建 Nacos 的 AgentCardResolver
//                        new NacosAgentCardResolver(nacosUtils.getNacosClient()))
//                .build();
        log.error("==========================");
        log.error("获取到的远程Agent描述：" + tripPlannerAgent.getDescription());
        log.error("==========================");

        //远程Agent运行
//        agent.call().block();
        log.info("============");
        log.info("这个工具方法传入的参数：" + prompt);
        log.info("============");


        Msg userMsg = PromptUtils.getUserMsg(prompt);


        // 使用 stream() 流式调用，避免 call().block() 导致的 SSE 缓冲区溢出
        return tripPlannerAgent.stream(userMsg)
                .doOnNext(event -> log.debug("[TripPlannerAgent] 收到流式事件: type={}, isLast={}",
                        event.getType(), event.isLast()))
                .map(event -> {
                    if (event.getMessage() != null) {
                        String text = event.getMessage().getTextContent();

                        log.info("callTripPlannerAgent---->>" + text);
                        return text != null ? text : "";
                    }
                    return "";
                })
                .filter(text -> !text.isEmpty())
                .reduce("", String::concat)
                .map(result -> result.isEmpty() ? PREFIX + "远程Agent未返回内容" : PREFIX + result)
                .timeout(STREAM_TIMEOUT)
                .doOnSuccess(result -> log.info("callTripPlannerAgent 流式调用完成, 结果长度: {} 字符",
                        result != null ? result.length() : 0))
                .onErrorResume(e -> {
                    log.error("callTripPlannerAgent 流式调用失败", e);
                    return Mono.just(PREFIX + "行程规划Agent调用失败: " + e.getMessage());
                });
    }
}

四、routeMaking-agent 模块

4.1 pom.xml

routeMaking-agent 模块引入 ai-core 作为公共依赖，加上 A2A 和 Nacos 的 Spring Boot Starter。

<?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>
    <parent>
        <groupId>vip.wayhua.ivy.ai</groupId>
        <artifactId>AITripPlan-V2</artifactId>
        <version>1.0.1</version>
    </parent>

    <artifactId>routeMaking-agent</artifactId>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
<dependencies>
    <dependency>
        <groupId>vip.wayhua.ivy.ai</groupId>
        <artifactId>ai-core</artifactId>
        <version>1.0.1</version>
    </dependency>
    <dependency>
        <groupId>io.agentscope</groupId>
        <artifactId>agentscope-a2a-spring-boot-starter</artifactId>
    </dependency>

    <dependency>
        <groupId>io.agentscope</groupId>
        <artifactId>agentscope-nacos-spring-boot-starter</artifactId>
    </dependency>
</dependencies>
</project>

4.2 RouteMakingAgent

先将百度 MCP 去掉了，因为要用户确认，不知道是因为用量用完了还是什么原因，暂时注释掉。MCP（Model Context Protocol）是 Anthropic 提出的标准协议，让大模型能调用外部工具。百度地图的 MCP Server 提供了路线查询、POI 搜索、地理编码等能力，但在实际使用中发现每次调用都要用户确认，体验不太顺畅。这个问题先搁置，后面再研究是 MCP 客户端的配置问题还是百度地图的限制。

其余代码和 1.0.8 基本一致，只是注释掉了 MCP 相关的部分。

package vip.wayhua.ivy.ai.route.agent;

import io.agentscope.core.ReActAgent;
import io.agentscope.core.tool.Toolkit;
import io.agentscope.core.tool.mcp.McpClientWrapper;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import vip.wayhua.ivy.ai.conf.Properties;
import vip.wayhua.ivy.ai.route.mcp.BaiduMapMcp;
import vip.wayhua.ivy.ai.utils.AgentUtils;
import vip.wayhua.ivy.ai.utils.ToolUtils;


import java.util.Set;

@Component
public class RouteMakingAgent {
    private static final Logger log= LoggerFactory.getLogger(RouteMakingAgent.class);
    AgentUtils agentUtils;

    @Bean
    public ReActAgent  getRouteMakingAgent(  AgentUtils agentUtils, Properties properties){

        this.agentUtils=agentUtils;
//        BaiduMapMcp mcp = new BaiduMapMcp(properties);
//        mcp.initBaiduMapMCP();
//        //创建百度地图MCP客户端
//        mcp.getBaiduMapMCP();
//        //初始化百度地图MCP客户端
//        McpClientWrapper mcpClient = mcp.initBaiduMapMCP();
//
//        ToolUtils toolUtils = new ToolUtils();
//        //将百度地图MCP的工具注册到工具包
//        Toolkit toolkit = toolUtils.getToolkit(mcpClient);

        //打印挂载的工具
//        Set<String> toolNames = toolkit.getToolNames();
//        log.info("=============");
//        toolNames.stream().forEach(
//                value -> log.info("挂载的工具名称："+value)
//        );
//        log.info("=============");

       // log.info(">>> [RouteMakingAgent] Agent 初始化完成，已挂载 {} 个百度地图MCP工具", toolNames.size());
        log.info(">>> [RouteMakingAgent] 已添加调用日志 Hook，被调用时将输出日志");

        return agentUtils.getReActAgentBuilder(
                "RouteMakingAgent",
                        "路线规划专家，可使用百度地图工具查询：驾车/铁路/公交/步行/骑行路线、距离耗时、地理编码、POI搜索、天气、IP定位。你有实时地图数据，必须提供具体的路线信息"
                )
//                .toolkit(toolkit)

                .build();
    }
}

4.3 特别注意：Nacos 连接配置

一直连不上 Nacos，升级到 3.2.0 也连不上，查了资料才发现要修改配置------多个 enabled 属性需要显式设置为 true。这个问题在前面借助 OpenCode 升级时也遇到过（见 1.3 节），当时 OpenCode 没有搞清楚原因，直接硬编码了 Agent Card 的 URL 来绕过问题。手动重构时终于找到了根因：2.0 把功能拆成了扩展包，配置项也跟着多了。到底是哪一个生效我也还是没有完全搞明白，可能是 agentscope.a2a.nacos.enabled，这些细节还要在不断使用中去探索、积累。

这个问题挺典型的：2.0 把功能拆成了扩展包，灵活度上来了，但配置项也多了。1.0.8 里一个 starter 搞定的事，现在要手动开三个开关：agentscope.a2a.enabled、agentscope.a2a.server.enabled、agentscope.a2a.nacos.enabled。文档里没写清楚哪些是必须的，只能靠报错反推。这种「不报错就不知道少了什么」的体验，是升级过程中最耗时间的部分。

server:
  port:  9991


ivy:
  agent:
    model_name: ${MODEL_NAME}
    dashscope_key: ${DASHCOPE_KEY}
    dashscope_openai_base_url: ${DASHSCOPE_OPENAI_BASE_URL}
  mcp:
    baidu_map_addr: ${BAIDU_MAP_ADDR}

#  要使用.env 就必须添加上
spring:
  config:
    import: optional:file:.env[.properties]


agentscope:
  a2a:
    enabled : true
    server:
      enabled: true

    nacos:
      enabled: true
      server-addr: 192.168.55.140:8848
      username:  nacos
      password:  nacos

五、TripPlanner-agent

5.1 SuggestSightAgent

2.0 版本最大的改动在于加载 Skills 的方式：JarSkillRepositoryAdapter 改成了 ClasspathSkillRepository，从 classpath 路径读取 Skill 定义文件。

这个变化的影响其实不小。1.0.8 用 JarSkillRepositoryAdapter 加载 Skills，需要把 Skill 文件打包成 jar，然后通过 jar 路径加载------开发时改一次 Skill 文件就得重新打包，调试体验很差。2.0 改成 ClasspathSkillRepository，直接从 classpath 读取，开发时放在 resources/skills/ 目录下就行，改完刷新就生效。一个小改动，开发体验好了不少。

package vip.wayhua.ivy.ai.trip.agent;

import io.agentscope.core.ReActAgent;
import io.agentscope.core.skill.AgentSkill;
import io.agentscope.core.skill.SkillBox;

import io.agentscope.core.skill.repository.ClasspathSkillRepository;
import io.agentscope.core.tool.Toolkit;
import vip.wayhua.ivy.ai.utils.AgentUtils;

import java.io.IOException;

/**
 *
 * @Author:黄卫华（wayhua@126.com）
 * @Description:
 * @date： 2026-08-06 11:34
 * @modifiedBy：
 * @version: 1.0
 */
public class SuggestSightAgent {
    AgentUtils agentUtils;


    public SuggestSightAgent(AgentUtils agentUtils){
        this.agentUtils=agentUtils;
    }
    //创建景点推荐Agent
    public ReActAgent getSuggestSightAgent(  ) {

        Toolkit toolkit = new Toolkit();

        //构建Skill，并将工具包和Skill结合
        SkillBox skillBox = new SkillBox(toolkit);

        //以文件形式读取Skill.md

        ClasspathSkillRepository repo = null;
        try {
            repo = new ClasspathSkillRepository("skills");
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
        //景点推荐技能
        AgentSkill SuggestSightsSkill = repo.getSkill("Suggest-Sights");

        skillBox.registerSkill(SuggestSightsSkill);

//        //注册工具
//        skillBox.registration().tool(new Calculate());

        ReActAgent.Builder builder = agentUtils.getReActAgentBuilder
                        ("SuggestSightAgent",
                                "擅长景点推荐"
                        )
                //挂载工具包
                .toolkit(toolkit)
                //挂载Skills
                .skillBox(skillBox);


        return builder.build();
    }
}

5.2 TripPlannerAgent

TripPlannerAgent 的代码和 1.0.8 基本一致，只是从构造函数初始化改成了 @Bean 方式注入。它通过 toolkit.registration().subAgent() 把 SuggestSightAgent 注册为子 Agent 工具，实现 Agent 的嵌套调度。

这个 subAgent 的设计思路值得多说一句：TripPlannerAgent 是行程规划专家，但它不一定擅长景点推荐。与其把景点推荐的逻辑塞进 TripPlannerAgent 里，不如把 SuggestSightAgent 作为一个「工具」挂上去，需要的时候调用。这其实就是 Multi-Agent 的核心价值------每个 Agent 只做自己擅长的事，通过工具调用的方式组合起来。1.0.8 和 2.0 在这一点上没有变化，说明这个设计是经得住考验的。

package vip.wayhua.ivy.ai.trip.agent;

import io.agentscope.core.ReActAgent;
import io.agentscope.core.tool.Toolkit;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import vip.wayhua.ivy.ai.utils.AgentUtils;

import java.io.IOException;

/**
 *
 * @Author:黄卫华（wayhua@126.com）
 * @Description:
 * @date： 2026-08-06 11:35
 * @modifiedBy：
 * @version: 1.0
 */

@Component
public class TripPlannerAgent {

    AgentUtils agentUtils;
//    ReActAgent agent;
//
//    public TripPlannerAgent(AgentUtils agentUtils) {
//        this.agentUtils = agentUtils;
//        Toolkit toolkit = new Toolkit();
//
//        SuggestSightAgent SuggestSightAgent = new SuggestSightAgent(agentUtils);
//
//
//        //将智能体(子Agent)作为工具
//        toolkit.registration().subAgent(
//                () -> SuggestSightAgent.getSuggestSightAgent()
//        ).apply();
//
//
//        //行程规划Agent Builder
//        ReActAgent.Builder builder = agentUtils.getReActAgentBuilder(
//                        "TripPlannerAgent",
//                        "你是行程规划专家。规划前必须先用 weather_check 脚本查目的地天气，所有数据整理后用 recalc 脚本生成表格。严禁编造天气和景点信息。"
//                )
//                .toolkit(toolkit);
//
//        agent = builder.build();
//    }
//
//    public ReActAgent getTripPlannerAgent() {
//        return this.agent;
//    }

    @Bean
    public ReActAgent getTripPlannerAgent(AgentUtils agentUtils) throws IOException {
        this.agentUtils = agentUtils;
        Toolkit toolkit = new Toolkit();

        SuggestSightAgent SuggestSightAgent = new SuggestSightAgent(agentUtils);


        //将智能体(子Agent)作为工具
        toolkit.registration().subAgent(
                () -> SuggestSightAgent.getSuggestSightAgent()
        ).apply();


        //行程规划Agent Builder
        ReActAgent.Builder builder = agentUtils.getReActAgentBuilder(
                        "TripPlannerAgent",
                        "你是行程规划专家。规划前必须先用 weather_check 脚本查目的地天气，所有数据整理后用 recalc 脚本生成表格。严禁编造天气和景点信息。"
                )
                .toolkit(toolkit);

        return builder.build();
    }
}

5.3 pom.xml

配置文件和 routeMaking-agent 是一样的，这个就不用多介绍了。

六、虎头蛇尾

总感觉升级到 2.0 有点虎头蛇尾，有点将就。怎么说呢？

仔细想想，「虎头」在于前面手动重构 1.0.8 时下了大功夫，每个模块逐行拆解，每个 API 都查了文档，信心满满地开始升级 2.0。结果到了 2.0，发现大部分代码直接搬过来就能用，真正要改的就是那几个 API 名字和 pom 依赖。心理预期是「大干一场」，实际是「搬砖+改名字」，落差感自然就来了。

「蛇尾」还体现在一些功能暂时搁置了。百度地图 MCP 因为用户确认的问题注释掉了，Nacos 连接的 enabled 配置到底哪个生效也没完全搞明白。这些问题不是不能解决，而是时间有限，先把主干跑通，细节后面再补。

但我认为这也不算什么大问题------代码最重要的是先运行起来，再在能运行的基础上不断探索、不断改进。能跑了之后，再研究文档、其他用法。如果连基础框架都搭建不起来，所有优化、高性能都是扯淡。先有再优，这是工程上的基本逻辑。

七、测试结果

2.0 版本调通后，发送「帮我制定10号从合肥到岳西的6日行程」的请求，下面是 Agent 返回的完整行程规划：

为您定制了这份10号合肥出发前往岳西的3日深度游攻略。这份行程结合了岳西的特色自然风光（明堂山/鹞落坪）与大别山红色文化底蕴，兼顾了休闲康养。

🗓️ 概览：10号-12日 · 大别山清凉避暑之旅
主题：高山康养 + 峡谷徒步 + 红色寻踪
最佳方式：自驾（最灵活，约2.5小时直达）
核心亮点：明堂山玻璃栈道、鹞落坪原始森林、禅溪温泉、岳西吊锅
🚗 第一部分：交通出行指南（合肥 ↔ 岳西）
出行方式	路线/班次详情	耗时参考	费用参考	💡 专家建议
🚙 自驾
(强烈推荐)	路线：合肥 → G4212合六叶高速 → S32铜黄高速 → 岳西出口
路况：全程高速，出高速后走X098县道至县城，路况良好。	单程约2~2.5小时	油费+过路费约60-80元/车	✅ 首选。岳西景点分散（如明堂山、鹞落坪距县城有一段距离），自驾最方便携带行李和土特产。
🚌 城际大巴	站点：合肥客运南站 → 岳西汽车站
频次：每日约8-10班（首班06:30，末班17:00）	约2.5~3小时	票价约 55-65 元/人	⚠️ 若需乘车，请提前在"皖美出行"小程序查票。到达后有公交或打车去景区。
🚄 高铁+接驳	步骤：合肥南→安庆站(40min) → 换乘汽车 → 岳西	全程约3.5小时	高铁70元 + 大巴60元	❌ 不推荐。需要在安庆中转，折腾且总耗时较长，除非无车且想体验高铁。
🗺️ 第二部分：3日详细行程安排
▶ Day 1 (10号)：抵达岳西 · 温泉洗尘
上午：轻松启程
建议 07:30 前 从合肥出发，避开出城早高峰。
约 10:00 抵达岳西县城，办理入住或寄存行李。
中午：舌尖上的岳西
前往老地方土菜馆或当地口碑好的农家菜馆。
🔥 必点菜单：岳西吊锅（灵魂菜品，集多种食材于一锅煮制）、黑猪汤、豆腐圆子、清炒高山野菜。
下午：入住与休整
方案A（度假风）：入住县城的禅溪温泉度假村，稍作休息后直接在酒店泡温泉，消除路途疲劳。
方案B（山林风）：入住明堂山景区附近民宿，感受山区清凉空气。
晚上：星空与夜色
如果不住景区，可在县城散步，品尝凉皮米豆腐、烤饼等宵夜。岳西光污染少，适合观星。
▶ Day 2 (11号)：探秘大别山 · 核心自然景观
此日有两个热门选项，请根据同行人员体力二选一：

✅ 选项A：明堂山（震撼景观，适合大多数游客）
08:30 抵达明堂山风景区，乘坐索道上山（省时省力）。
10:00-13:00 游览玻璃栈道（刺激打卡）、天梯（登高望远）、探幽谷。全程游览约3-4小时。
14:00 下山后返回县城或住宿地午餐。
15:30 如果喜欢户外，可去周边的天堂湖散步；或者回酒店做SPA按摩。
🌿 选项B：鹞落坪（原始秘境，适合摄影/喜静/轻徒步者）
09:00 前往鹞落坪自然保护区（车程约1小时）。
10:00-13:00 漫步原始次生林步道，这里是华东地区保存最完好的天然氧吧之一。主要看点是竹林、溪流和珍稀植物。
特色：这里更原生态，没有太多人工开发，适合深呼吸吸氧。中午可在保护区附近的农家乐吃地道的"笋宴"。
▶ Day 3 (12号)：红色记忆 · 满载而归
上午：文化与怀古
睡个懒觉，09:30 起床。
参观刘邓大军千里跃进大别山指挥部旧址（位于省立中学旧址内），免费参观，接受爱国主义教育，了解那段峥嵘岁月。
或者前往程长庚故居（徽剧奠基人故里），欣赏徽派建筑风格。
中午：伴手礼采购
在县城集市购买岳西翠兰茶叶（绿茶名品）、高山云雾茶、野生蜂蜜、干笋干、腊肉。
享用最后一顿午餐：荞面糊糊、石耳炖鸡。
下午：愉快返程
14:30 启程返回合肥。
预计 17:00前 抵达合肥，结束愉快的假期。
🎒 第三部分：行前贴士 & 避坑指南
👕 穿衣指南：
山区气温比县城低3-5度，昼夜温差大。即使是夏季，也建议带一件薄冲锋衣或长袖外套。
鞋子必须是防滑运动鞋，严禁穿高跟鞋爬山。
☔ 天气应对：
山区气候多变，建议随身携带雨衣（登山时雨伞不便）和驱蚊水。
如果遇到雨天，Day 2 的自然景点可能会因安全原因临时关闭，此时可改为"茶文化体验（河图镇龙井冲茶园）+ 游泳/水上项目"。
⚠️ 驾驶注意：
进入岳西境内后，国道和省道弯道较多，特别是雨雾天气，务必控制车速，鸣笛示警。
💰 消费预警：
景区内餐饮较贵，建议自备一些干粮和水。
购买茶叶时，不懂行的建议在正规专卖店购买，不要轻信路边拉客推销的散装茶。
祝您10号的旅程一路顺风，在大别山享受美好的时光！

八、1.0.8 vs 2.0 升级要点回顾

整个升级过程，真正要改的地方其实不多。下面按模块汇总一下，方便后面再升级时参考：

依赖变化

依赖项	1.0.8	2.0
核心包	agentscope-spring-boot-starter	agentscope
Nacos A2A	打包在 starter 中	agentscope-extensions-nacos-a2a
A2A 客户端	打包在 starter 中	agentscope-extensions-a2a-client
Spring Web	spring-boot-starter-web	spring-boot-starter-webflux
Nacos 客户端	通过 starter 间接引入	显式引入 nacos-client

API 变化

API	1.0.8	2.0
任务分解	.enablePlan() + PlanNotebook	.enableTaskList()
Skills 加载	JarSkillRepositoryAdapter	ClasspathSkillRepository
DashScope 模型	io.agentscope.core.model	io.agentscope.extensions.model
结构化输出	StructuredOutputReminder	call(msg, Class) 原生支持
流式输出	call().block() 或 stream()	stream()（推荐）

配置变化

# 1.0.8 --- 不需要显式开启
agentscope:
  a2a:
    server-addr: 192.168.55.140:8848

# 2.0 --- 三个 enabled 都要手动设为 true
agentscope:
  a2a:
    enabled: true
    server:
      enabled: true
    nacos:
      enabled: true
      server-addr: 192.168.55.140:8848

没变的部分

好消息是，以下内容在 1.0.8 和 2.0 之间完全兼容，直接搬过来就行：

• ReActAgent.builder() 链式构建方式
• A2aAgent + NacosAgentCardResolver 的远程 Agent 调用
• Toolkit + @Tool + @ToolParam 的工具注册
• toolkit.registration().subAgent() 的子 Agent 嵌套
• SkillBox + registerSkill() 的技能加载
• Hook 的事件监听机制
• Msg 消息对象和 PromptUtils 工具类

小结

升级 2.0 的感受

升级 2.0 的过程，比预想的要顺利，也比预想的要平淡。1.0.8 手动重构时那种「每行代码都要想半天」的紧张感没有了，大部分时间花在改包名、改依赖、改 API 名字上。真正需要动脑子的，只有 Nacos 连接配置那三个 enabled 开关。

这也说明 1.0.8 的手动重构没有白费。正因为每一行代码都搞懂了，升级时才能快速判断「这个要不要改」「那个改了会不会影响别的」。如果跳过手动重构直接升级，大概率会被各种报错淹没------你不知道哪个报错是新版本的问题，哪个是你原来就没理解的。

关于 AgentScope 框架的演进

从 1.0.8 到 2.0，能看出 AgentScope 的演进方向：核心更精简，扩展更灵活。核心包只保留 ReActAgent、Toolkit、SkillBox、Hook 这些最基础的能力，DashScope 模型、Nacos A2A、A2A 客户端都拆成了独立扩展包。这种思路和 Spring Boot 的 starter 生态很像------你只引入你需要的，而不是一个庞大的全家桶。

PlanNotebook 到 enableTaskList() 的简化，JarSkillRepositoryAdapter 到 ClasspathSkillRepository 的改进，StructuredOutputReminder 的移除------这些变化的方向是一致的：让 API 更简洁、让开发体验更好。框架在往「少写配置、多写业务」的方向走，这是好事。

关于 AI 辅助编程的边界

这次升级 2.0 经历了两个阶段：先借助 AI 工具（Qoder → OpenCode）跑通，再手动重构搞懂。两个阶段的对比很能说明问题。

Qoder 能力强，但免费额度用完了；OpenCode 免费，但能力差一截，还自作主张------说是没调通 Nacos，就直接硬编码了 Agent Card 的 URL 来绕过。这不叫幻觉，这叫「偷懒式解决」：任务确实完成了，但问题没解决，只是绕过去了。127.0.0.1:8120 硬编码能跑通，但换一台机器就废了。

AI 能帮你跑通代码，但跑通≠正确。它能解决眼前的问题，但不会考虑架构的合理性、代码的可维护性。这就是 AI 辅助编程的边界：它是很好的执行者，但不是好的架构师。你需要自己判断什么是对的，什么是将就的。

先有再优

升级 2.0 有点虎头蛇尾，但我不觉得这是什么大问题。百度 MCP 暂时注释掉了，Nacos 的 enabled 配置还没完全搞明白，流式输出的 filter 逻辑还有一些注释掉的试验代码------这些都不完美，但代码跑起来了，Agent 能正常协作了，行程规划能正常返回了。先有再优，在能运行的基础上不断打磨，比追求一步到位然后卡在环境配置上强得多。

一句话总结：手动重构 1.0.8 让我搞懂了每一行代码，升级 2.0 让我看到了框架的演进方向。先有再优，代码能跑起来，才有资格谈优化。

---

本文是 AiTripPlan 系列的第三篇（下篇）。上篇记录了 AgentScope 1.0.8 的手动重构过程，本篇记录了从 1.0.8 升级到 2.0 的完整过程------先是借助 Qoder 和 OpenCode 跑通 2.0，再手动重构逐行搞懂。从「抄出来了」到「跑通了」再到「真懂了」，再到「升级了」，这段教程代码才算真正变成了自己的。如果你也有「能跑但没懂」的教程项目，不妨试试这个学法。感谢阅读！