Spring AI Alibaba 学习（二）：Agent 智能体架构深度解析

📌 系列文章

• Spring AI Alibaba学习（一）------ RAG
• Spring AI Alibaba 学习（二）：Agent 智能体架构深度解析（本文）

---

目录

前言

[一、什么是 Agent？](#一、什么是 Agent？)

[1.1 Agent vs 传统 AI 应用](#1.1 Agent vs 传统 AI 应用)

[1.2 Agent 的核心特征](#1.2 Agent 的核心特征)

[二、ReAct 模式：Agent 的核心思想（响应式Agent）](#二、ReAct 模式：Agent 的核心思想（响应式Agent）)

[2.1 什么是 ReAct？](#2.1 什么是 ReAct？)

[2.2 ReAct 工作流程](#2.2 ReAct 工作流程)

[三、ReactAgent 快速入门与上手](#三、ReactAgent 快速入门与上手)

[3.1 最简单的 ReactAgent](#3.1 最简单的 ReactAgent)

[3.2 带工具的 ReactAgent](#3.2 带工具的 ReactAgent)

[四、生命周期管理：Hook 和 Interceptor](#四、生命周期管理：Hook 和 Interceptor)

[4.1 为什么需要生命周期管理？](#4.1 为什么需要生命周期管理？)

[4.2 ReactAgent 的完整生命周期](#4.2 ReactAgent 的完整生命周期)

[4.3 Hook：生命周期管理](#4.3 Hook：生命周期管理)

[4.4 Interceptor：调用拦截](#4.4 Interceptor：调用拦截)

[4.5 Hook vs Interceptor 对比](#4.5 Hook vs Interceptor 对比)

五、多智能体编排

[5.1 为什么需要多智能体？](#5.1 为什么需要多智能体？)

[5.2 五种编排模式](#5.2 五种编排模式)

[1️⃣ SequentialAgent（顺序执行）](#1️⃣ SequentialAgent（顺序执行）)

[2️⃣ ParallelAgent（并行执行）](#2️⃣ ParallelAgent（并行执行）)

[3️⃣ RoutingAgent（路由选择）](#3️⃣ RoutingAgent（路由选择）)

[4️⃣ LoopAgent（循环执行）](#4️⃣ LoopAgent（循环执行）)

[5️⃣ SupervisorAgent（监督者）](#5️⃣ SupervisorAgent（监督者）)

六、实战案例：完整的内容创作系统

七、其它功能实践与原则

[7.1 Hook 设计原则](#7.1 Hook 设计原则)

[7.2 合理设置 instruction](#7.2 合理设置 instruction)

[7.3 使用状态持久化](#7.3 使用状态持久化)

八、性能优化建议

[8.1 并发控制](#8.1 并发控制)

[8.2 循环限制](#8.2 循环限制)

[8.3 成本控制](#8.3 成本控制)

九、总结

核心要点回顾

[Agent Framework vs RAG](#Agent Framework vs RAG)

参考资源

---

前言

前景提要一手，在前一篇博文中，我们深入学习了 Spring AI Alibaba 的 RAG（检索增强生成）架构。现在，我们将探索另一个核心模块：Agent Framework（智能体编排框架）。

如果说 RAG 让 AI 能够访问知识库，那么 Agent 就是让 AI 能够自主思考和行动。通过 Agent Framework，我们可以构建能够自主决策、调用工具、协作完成复杂任务的智能体系统。

本文将涵盖：

• ✅ Agent 的核心概念和 ReAct 模式
• ✅ ReactAgent 的架构和使用方法
• ✅ Hook 和 Interceptor 的生命周期管理
• ✅ 多智能体编排的 5 种模式
• ✅ 完整的实战示例

---

一、什么是 Agent？

1.1 Agent vs 传统 AI 应用

传统的 AI 应用（如 "古老的 ChatGPT 3.0 时代"）是"一问一答"模式：

而 Agent 是一个能够自主感知、决策和执 行的基于大模型为核心core的 AI 系统：

1.2 Agent 的核心特征

特性	Agent	传统应用
决策能力	✅ 自主决策	❌ 固定逻辑
工具调用	✅ 动态选择工具	❌ 硬编码调用
上下文理解	✅ 理解自然语言	❌ 需要精确指令
适应性	✅ 灵活适应	❌ 需要修改代码

---

二、ReAct 模式：Agent 的核心思想（响应式Agent）

2.1 什么是 ReAct？

ReAct = Reasoning (推理) + Acting (行动)

这是一个让 LLM 能够自主思考和行动的循环模式。

2.2 ReAct 工作流程

让我们通过一个实际例子来理解：

用户提 问：北京今天天气怎么样？

---

三、ReactAgent 快速入门与上手

3.1 最简单的 ReactAgent

// 1. 创建 ChatModel
ChatModel chatModel = DashScopeChatModel.builder()
    .apiKey(System.getenv("AI_DASHSCOPE_API_KEY"))
    .build();

// 2. 创建 ReactAgent
ReactAgent agent = ReactAgent.builder()
    .name("simple_agent")
    .model(chatModel)
    .instruction("你是一个智能助手")
    .build();

// 3. 调用
AssistantMessage response = agent.call("你好，请介绍一下自己");
System.out.println(response.getText());

3.2 带工具的 ReactAgent

// 1. 定义工具
public class WeatherTools {
    @Tool(
        name = "get_weather",
        description = "查询指定城市的天气信息"
    )
    public String getWeather(
        @ToolParam(description = "城市名称") String city
    ) {
        // 实际应该调用天气 API
        return city + "今天晴天，温度 15°C";
    }
}

// 2. 创建带工具的 Agent
ReactAgent weatherAgent = ReactAgent.builder()
    .name("weather_agent")
    .model(chatModel)
    .instruction("你是天气助手，帮助用户查询天气")
    .methodTools(new WeatherTools())  // 👈 注册工具
    .build();

// 3. 使用
AssistantMessage response = weatherAgent.call("北京今天天气怎么样？");
System.out.println(response.getText());
// 输出: "根据查询结果，北京今天晴天，温度 15°C"

---

四、生命周期管理：Hook 和 Interceptor

4.1 为什么需要生命周期管理？

ReactAgent 的执行过程有明确的生命周期，我们需要在不同阶段插入自定义逻辑。举一个最简单的🌰，比如我们需要在Agent进行了一次完整全链路的响应回复之后。需要计算当前轮次回复消耗了多少Token，同时对本次推理的Token费用进行计算。

💡 重要概念 ：++Hook 不是前端专属概念，而是通用的软件设计模式，类似于 Spring 的 @PostConstruct、Servlet 的 Filter、AOP 的 @Before/@After。++

4.2 ReactAgent 的完整生命周期

4.3 Hook：生命周期管理

Hook 的 4 个位置：

public enum HookPosition {
    BEFORE_AGENT,   // Agent 开始前（生命周期开始）
    AFTER_AGENT,    // Agent 结束后（生命周期结束）
    BEFORE_MODEL,   // 调用 LLM 前（每次循环前）
    AFTER_MODEL     // 调用 LLM 后（每次循环后）
}

自定义 Hook 示例：

// 性能监控 Hook
public class PerformanceHook extends AgentHook {
    
    @Override
    public String getName() {
        return "performance_monitoring";
    }
    
    @Override
    public CompletableFuture<Map<String, Object>> beforeAgent(
        OverAllState state, 
        RunnableConfig config
    ) {
        // 记录开始时间
        System.out.println("Agent 开始执行");
        return CompletableFuture.completedFuture(
            Map.of("start_time", System.currentTimeMillis())
        );
    }
    
    @Override
    public CompletableFuture<Map<String, Object>> afterAgent(
        OverAllState state, 
        RunnableConfig config
    ) {
        // 计算耗时
        long startTime = (long) state.value("start_time").orElse(0L);
        long duration = System.currentTimeMillis() - startTime;
        System.out.println("Agent 执行完成，耗时: " + duration + "ms");
        return CompletableFuture.completedFuture(Map.of());
    }
    
    @Override
    public HookPosition[] getHookPositions() {
        return new HookPosition[]{
            HookPosition.BEFORE_AGENT, 
            HookPosition.AFTER_AGENT
        };
    }
}

// 使用 Hook
ReactAgent agent = ReactAgent.builder()
    .name("monitored_agent")
    .model(chatModel)
    .hooks(List.of(new PerformanceHook()))
    .build();

4.4 Interceptor：调用拦截

Interceptor 用于拦截每次具体的调用：

// 模型重试拦截器
ModelRetryInterceptor retryInterceptor = 
    ModelRetryInterceptor.builder()
        .maxRetries(3)  // 失败时重试 3 次
        .build();

// 工具重试拦截器
ToolRetryInterceptor toolRetry = 
    ToolRetryInterceptor.builder()
        .maxRetries(3)
        .build();

// 使用 Interceptor
ReactAgent agent = ReactAgent.builder()
    .name("resilient_agent")
    .model(chatModel)
    .modelInterceptors(List.of(retryInterceptor))
    .toolInterceptors(List.of(toolRetry))
    .build();

4.5 Hook vs Interceptor 对比

也许你会感到困惑，那么Hook和拦截器有什么区别？最重要的在于他们的作用域、作用粒度、对象以及运用的场景不同。下表展示了两者的区分：

特性	Hook	Interceptor
作用对象	Agent 和 Model 的生命周期	Tool 和 Model 的调用
粒度	节点级别（粗粒度）	调用级别（细粒度）
触发时机	4 个固定的生命周期阶段	每次调用的前后
主要用途	生命周期管理、状态修改	调用拦截、结果修改
典型场景	日志、监控、人工确认	重试、降级、错误处理

它们两者的关系就像是：

• Hook 是"人生的重要节点"（出生、上学、工作、退休）
• Interceptor 则是"每次行动的检查"（每次出门前检查钥匙）

---

五、多智能体编排

5.1 为什么需要多智能体？

单个 Agent 虽然强大，但面对复杂任务时会遇到瓶颈：

单 Agent 的局限：
❌ 任务过于复杂，单个 Agent 难以处理
❌ 需要多个专业领域的知识
❌ 需要并行处理多个子任务

多 Agent 的优势：
✅ 分工明确，每个 Agent 专注特定任务
✅ 并行执行，提高效率
✅ 模块化，易于维护和扩展

5.2 五种编排模式

Spring AI Alibaba 提供了 5 种内置的编排模式：

1️⃣ SequentialAgent（顺序执行）

适用场景：流水线式任务，后续任务依赖前面的结果

// 示例：写作流程
ReactAgent researchAgent = ReactAgent.builder()
    .name("researcher")
    .instruction("你是研究专家，负责收集信息")
    .model(chatModel)
    .tools(searchTools)
    .build();

ReactAgent writerAgent = ReactAgent.builder()
    .name("writer")
    .instruction("你是写作专家，负责撰写文章")
    .model(chatModel)
    .build();

ReactAgent editorAgent = ReactAgent.builder()
    .name("editor")
    .instruction("你是编辑，负责校对和润色")
    .model(chatModel)
    .build();

// 顺序编排
SequentialAgent workflow = SequentialAgent.builder()
    .name("writing_workflow")
    .description("研究-撰写-编辑流程")
    .subAgents(List.of(researchAgent, writerAgent, editorAgent))
    .build();

// 执行
AssistantMessage result = workflow.call("写一篇关于 AI 的文章");

2️⃣ ParallelAgent（并行执行）

模式：

适用场景：多角度分析、独立子任务并行处理

// 示例：多角度产品分析
ReactAgent techAgent = ReactAgent.builder()
    .name("tech_analyst")
    .instruction("从技术角度分析产品")
    .model(chatModel)
    .outputKey("tech_analysis")
    .build();

ReactAgent marketAgent = ReactAgent.builder()
    .name("market_analyst")
    .instruction("从市场角度分析产品")
    .model(chatModel)
    .outputKey("market_analysis")
    .build();

// 并行编排
ParallelAgent parallelAnalysis = ParallelAgent.builder()
    .name("product_analysis")
    .description("产品多维度分析")
    .subAgents(List.of(techAgent, marketAgent))
    .mergeStrategy(new ParallelAgent.DefaultMergeStrategy())
    .maxConcurrency(2)  // 最多 2 个并发
    .build();

// 执行
AssistantMessage result = parallelAnalysis.call("分析 iPhone 15");

3️⃣ RoutingAgent（路由选择）

模式：根据输入类型路由到不同的专家 Agent

// 示例：智能客服
ReactAgent techSupportAgent = ReactAgent.builder()
    .name("tech_support")
    .description("处理技术问题，如软件故障、配置问题等")
    .instruction("你是技术支持专家")
    .model(chatModel)
    .build();

ReactAgent salesAgent = ReactAgent.builder()
    .name("sales")
    .description("处理产品咨询、价格、购买等问题")
    .instruction("你是销售顾问")
    .model(chatModel)
    .build();

// 路由编排
LlmRoutingAgent customerService = LlmRoutingAgent.builder()
    .name("customer_service")
    .description("智能客服系统")
    .model(chatModel)  // 用于路由决策的 LLM
    .subAgents(List.of(techSupportAgent, salesAgent))
    .build();

// 执行
customerService.call("软件无法启动怎么办？");  // → 路由到 techSupportAgent
customerService.call("这个产品多少钱？");      // → 路由到 salesAgent

4️⃣ LoopAgent（循环执行）

模式：循环迭代直到满足条件

// 示例：代码生成与测试
ReactAgent codeGeneratorAgent = ReactAgent.builder()
    .name("code_generator")
    .instruction("生成 Python 代码")
    .model(chatModel)
    .outputKey("code")
    .build();

ReactAgent codeTesterAgent = ReactAgent.builder()
    .name("code_tester")
    .instruction("测试代码并返回测试结果")
    .model(chatModel)
    .tools(List.of(runCodeTool))
    .outputKey("test_result")
    .build();

// 循环编排
LoopAgent codeWorkflow = LoopAgent.builder()
    .name("code_generation_loop")
    .description("生成并测试代码，直到通过")
    .subAgents(List.of(codeGeneratorAgent, codeTesterAgent))
    .loopCondition((state) -> {
        String testResult = (String) state.value("test_result").orElse("");
        return !testResult.contains("PASS");  // 未通过则继续循环
    })
    .maxIterations(5)  // 最多循环 5 次
    .build();

5️⃣ SupervisorAgent（监督者）

模式：监督者动态分配任务给多个子 Agent

// 示例：项目开发
ReactAgent developerAgent = ReactAgent.builder()
    .name("developer")
    .description("负责编写代码")
    .instruction("你是开发工程师")
    .model(chatModel)
    .build();

ReactAgent testerAgent = ReactAgent.builder()
    .name("tester")
    .description("负责测试代码")
    .instruction("你是测试工程师")
    .model(chatModel)
    .build();

// 监督者编排
SupervisorAgent projectManager = SupervisorAgent.builder()
    .name("project_manager")
    .description("项目经理，负责任务分配和协调")
    .model(chatModel)
    .subAgents(List.of(developerAgent, testerAgent))
    .build();

// 执行
AssistantMessage result = projectManager.call("开发一个用户登录功能");

---

六、实战案例：完整的内容创作系统

让我们构建一个完整的内容创作系统，结合多种编排模式：

// 1. 研究 Agent
ReactAgent researchAgent = ReactAgent.builder()
    .name("researcher")
    .instruction("收集相关资料和数据")
    .model(chatModel)
    .tools(List.of(searchTool, webScraperTool))
    .outputKey("research_data")
    .build();

// 2. 大纲 Agent
ReactAgent outlineAgent = ReactAgent.builder()
    .name("outliner")
    .instruction("根据研究资料创建文章大纲")
    .model(chatModel)
    .outputKey("outline")
    .build();

// 3. 写作团队（并行）
ReactAgent introAgent = ReactAgent.builder()
    .name("intro_writer")
    .instruction("撰写引言部分")
    .model(chatModel)
    .outputKey("intro")
    .build();

ReactAgent bodyAgent = ReactAgent.builder()
    .name("body_writer")
    .instruction("撰写正文部分")
    .model(chatModel)
    .outputKey("body")
    .build();

ReactAgent conclusionAgent = ReactAgent.builder()
    .name("conclusion_writer")
    .instruction("撰写结论部分")
    .model(chatModel)
    .outputKey("conclusion")
    .build();

ParallelAgent writingTeam = ParallelAgent.builder()
    .name("writing_team")
    .subAgents(List.of(introAgent, bodyAgent, conclusionAgent))
    .mergeStrategy(new ParallelAgent.ConcatenationMergeStrategy("\n\n"))
    .build();

// 4. 编辑 Agent
ReactAgent editorAgent = ReactAgent.builder()
    .name("editor")
    .instruction("校对和润色文章")
    .model(chatModel)
    .outputKey("final_article")
    .build();

// 5. 组合成完整流程
SequentialAgent contentCreationSystem = SequentialAgent.builder()
    .name("content_creation_system")
    .description("完整的内容创作系统")
    .subAgents(List.of(
        researchAgent,
        outlineAgent,
        writingTeam,
        editorAgent
    ))
    .build();

// 使用
AssistantMessage article = contentCreationSystem.call(
    "写一篇关于人工智能发展趋势的文章"
);
System.out.println(article.getText());

---

七、其它功能实践与原则

7.1 Hook 设计原则

// ✅ 好的 Hook 设计
public class GoodHook extends ModelHook {
    @Override
    public CompletableFuture<Map<String, Object>> beforeModel(...) {
        try {
            // 1. 快速执行，不阻塞
            // 2. 异常处理完善
            // 3. 返回有意义的状态
            return CompletableFuture.completedFuture(Map.of("key", "value"));
        } catch (Exception e) {
            logger.error("Hook 执行失败", e);
            return CompletableFuture.completedFuture(Map.of());
        }
    }
}

// ❌ 不好的 Hook 设计
public class BadHook extends ModelHook {
    @Override
    public CompletableFuture<Map<String, Object>> beforeModel(...) {
        Thread.sleep(5000);  // ❌ 阻塞执行
        int result = 1 / 0;  // ❌ 没有异常处理
        return null;         // ❌ 返回 null
    }
}

7.2 合理设置 instruction

// ✅ 好的 instruction
.instruction("你是专业的技术支持，擅长解决软件问题。" +
             "回答要简洁明了，重点突出。" +
             "如果不确定，请明确告知用户。")

// ❌ 不好的 instruction
.instruction("你是 AI")

7.3 使用状态持久化

// ✅ 多轮对话场景必须使用
ReactAgent agent = ReactAgent.builder()
    .name("chatbot")
    .model(chatModel)
    .saver(new MemorySaver())  // 👈 必需
    .build();

// 使用 threadId 区分不同用户
RunnableConfig config = RunnableConfig.builder()
    .threadId("user_" + userId)
    .build();

---

八、性能优化建议

8.1 并发控制

// 控制并发数量，避免资源耗尽
ParallelAgent parallel = ParallelAgent.builder()
    .subAgents(agents)
    .maxConcurrency(5)  // 👈 最多 5 个并发
    .build();

8.2 循环限制

// 防止无限循环
LoopAgent loop = LoopAgent.builder()
    .subAgents(agents)
    .maxIterations(10)  // 👈 最多循环 10 次
    .build();

8.3 成本控制

// 使用 Hook 控制成本
CostControlHook costHook = new CostControlHook();
costHook.setMaxCostPerRequest(0.1);  // 单次请求最大成本 $0.1

ReactAgent agent = ReactAgent.builder()
    .name("cost_controlled_agent")
    .model(chatModel)
    .hooks(List.of(costHook))
    .build();

---

九、总结

通过本文，我们深入学习了 Spring AI Alibaba 的 Agent Framework：

核心要点回顾

1. Agent 的本质：能够自主思考、决策和执行的 AI 系统
2. ReAct 模式：Reasoning + Acting 的循环
3. 生命周期管理：通过 Hook 和 Interceptor 管理执行流程
4. 多智能体编排：5 种模式应对不同场景
5. 最佳实践：设计原则、性能优化、成本控制

Agent Framework vs RAG

特性	Agent Framework	RAG
核心能力	自主决策和行动	知识检索增强
适用场景	复杂任务、工具调用	知识问答
可组合性	✅ 可以结合 RAG	✅ 可以被 Agent 使用

---

📚 参考资源

• 官方文档 ：https://java2ai.com
• GitHub ：https://github.com/alibaba/spring-ai-alibaba
• 系列文章 ：
  *
  • Spring AI Alibaba学习（一）------ RAG
  • Spring AI Alibaba 学习（二）：Agent 智能体架构深度解析（本文）