目录

Agent介绍

在 Spring AI Alibaba 的框架中，Agent 是将大语言模型与工具结合，创建具备任务推理、工具使用决策、工具调用的自动化系统。这个系统具备持续推理、工具调用的循环迭代能力，直至问题解决。

简单来说，Agent 不仅仅是一个聊天机器人了，还是一个能够自主思考、调用工具、完成任务的智能实体。Spring AI Alibaba 中提供了基于 ReactAgent 的生产级 Agent 实现。

大模型呢？

大语言模型的核心能力是给定一段输入，模型能够输出一段有意义的文本。这个能力本身已经非常强大，但大模型有一个根本性的局限，它只能“说”，不能“做”。

Agent架构设计

ReAct架构

最经典的是 ReAct，一边推理一边行动，来回交替，适合搜索、问答、工具调用这类相对短平快的任务。
核心是推理与行动的交替循环。每一步先“思考”当前状态并规划下一步，再调用工具执行，最后将执行结果作为“观察”融入下一步推理。它强调动态决策，适合需要灵活应变的开放任务，但需注意控制循环深度，避免陷入无限推理死循环。

ReAct 的核心思想是让 Agent 在一个循环中交替进行“推理”和“行动”：

  1. 思考（Reasoning） ：分析当前情况，决定下一步该做什么
  2. 行动（Acting） ：执行工具调用或生成最终答案
  3. 观察（Observation） ：接收工具执行的结果
  4. 迭代：基于观察结果继续思考和行动，直到完成任务

这个循环赋予 Agent 几个关键能力：

  • 将复杂问题分解为多个步骤
  • 基于中间结果动态调整策略
  • 处理需要多次工具调用的任务
  • 在不确定的环境中做出决策

Plan-and-Execute

采用先全局规划、再逐步执行的两阶段模式。首先生成一份包含步骤顺序与依赖关系的完整计划清单，再按清单调用工具执行。它强调统筹可控，适合写报告、做调研等长周期任务，但规划质量高度依赖模型能力，且对执行中的突发变化应变较慢。

在这里插入图片描述

RAG Agent

专门优化知识密集型检索生成。它先根据问题从向量库召回相关文档，经过重排筛选出最精准片段，再将这些片段作为上下文输入LLM。核心在于“先搜后答”，能有效解决私有数据和实时知识更新问题，是企业知识库问答的首选。

Reflection / Reflexion

通过自我批评实现迭代优化。模型先输出初稿，再扮演“评论员”找缺陷，根据反馈生成改进版，反复循环直至达标。核心是内置的自省与重试机制，无需外部标注，特别适合写作润色、代码调试等可自评任务。

Router / Handoff

作为任务分发的中枢神经。先进行意图识别分类，然后根据映射规则，将请求完整“转交”给对应的垂直领域专家Agent处理。核心是实现职责分离与负载分流，确保“专业的人做专业的事”，降低单个Agent的复杂度。

Multi-Agent

由多个扮演不同角色的Agent协同作战。每个Agent拥有独立的提示词和工具集（如研究、写作、代码），通过消息传递协作攻克超长文本或复杂项目。核心是发挥群体智能，解决单个模型上下文窗口无法容纳的复杂系统工程。

Supervisor

在Multi-Agent之上增设管理岗进行集中管控。主管Agent不干活，只负责全局拆解、调度专家、跟踪进度和最终验收。它决定“谁来做、先做谁”，确保所有子任务朝最终目标收敛，是高严谨度、强流程感项目的必备架构。

核心组件

Model（模型）

Model 是 Agent 的推理引擎，负责理解用户输入、制定计划、决定调用哪些工具。Spring AI Alibaba 支持多种模型配置方式。

基础配置：直接使用 ChatModel 实例：

DashScopeApi dashScopeApi = DashScopeApi.builder()
.apiKey(System.getenv("AI_DASHSCOPE_API_KEY"))
.build();

ChatModel chatModel = DashScopeChatModel.builder()
.dashScopeApi(dashScopeApi)
.build();

高级配置：通过 ChatOptions 精细控制模型行为：

ChatModel chatModel = DashScopeChatModel.builder()
.dashScopeApi(dashScopeApi)
.defaultOptions(DashScopeChatOptions.builder()
                .withModel(DashScopeChatModel.DEFAULT_MODEL_NAME)
                .withTemperature(0.7)      // 控制随机性，越高越有创造性
                .withMaxToken(2000)        // 最大输出长度
                .withTopP(0.9)             // 核采样参数
                .build())
.build();

常用参数：

  • temperature：控制输出的随机性（0.0-1.0），值越高越有创造性
  • maxTokens：限制单次响应的最大 token 数
  • topP：核采样，控制输出的多样性

Tools（工具）

Tools 就相当于 Agent 的手脚，有了它，Agent才具有执行操作的能力，扩展自己的能力边界，而不是只是一个会说的大模型了。

在 Spring AI Alibaba 中，工具可以通过 ToolCallback 来定义：、

import org.springframework.ai.tool.ToolCallback;
import org.springframework.ai.tool.function.FunctionToolCallback;

// 定义工具（示例：搜索工具）
public class SearchTool implements BiFunction<String, ToolContext, String> {
    @Override
    public String apply(String query, ToolContext context) {
        // 实现搜索逻辑
        return "搜索结果: " + query;
    }
}

// 创建工具回调
ToolCallback searchTool = FunctionToolCallback.builder("search", new SearchTool())
    .description("搜索工具")
    .build();

Agent是 可以注册多个工具的，他自己会根据需要自主选择调用哪个工具。

System Prompt（系统提示）

System Prompt 它定义了 Agent 的角色、行为准则和回答风格，决定了塑Agent 处理任务的方式。

基础用法：通过 systemPrompt 提供字符串：

ReactAgent agent = ReactAgent.builder()
    .name("my_agent")
    .model(chatModel)
    .systemPrompt("你是一个专业的技术助手。请准确、简洁地回答问题。")
    .build();

详细指令：使用 instruction 提供更复杂的指引：

String instruction = """
    你是一个经验丰富的软件架构师。
    在回答问题时，请：
    1. 首先理解用户的核心需求
    2. 分析可能的技术方案
    3. 提供清晰的建议和理由
    4. 如果需要更多信息，主动询问
    保持专业、友好的语气。
    """;

ReactAgent agent = ReactAgent.builder()
    .name("architect_agent")
    .model(chatModel)
    .instruction(instruction)
    .build();

Memory（记忆）

Memory 让 Agent 具备上下文感知能力，即记住之前的对话内容，在多轮对话中保持连贯性。

Spring AI Alibaba 提供了 MemorySaver、RedisSaver 等多种记忆存储实现，支持短期记忆（Session 级）和长期记忆（跨 Session）。

关于 Memory 的详细内容，后面专门的章节再讲。

Agent调用

基础调用：使用 call 方法获取最终响应：

import org.springframework.ai.chat.messages.AssistantMessage;

// 字符串输入
AssistantMessage response = agent.call("杭州的天气怎么样？");
System.out.println(response.getText());

// UserMessage 输入
UserMessage userMessage = new UserMessage("帮我分析这个问题");
AssistantMessage response = agent.call(userMessage);

// 多个消息
List<Message> messages = List.of(
  new UserMessage("我想了解 Java 多线程"),
  new UserMessage("特别是线程池的使用")
);
AssistantMessage response = agent.call(messages);

使用 invoke 方法获取完整的执行状态：

import com.alibaba.cloud.ai.graph.OverAllState;
import java.util.Optional;

Optional<OverAllState> result = agent.invoke("帮我写一首诗");

if (result.isPresent()) {
  OverAllState state = result.get();

  // 访问消息历史
  Optional<Object> messages = state.value("messages");
  List<Message> messageList = (List<Message>) messages.get();

  // 访问自定义状态
  Optional<Object> customData = state.value("custom_key");

  System.out.println("完整状态：" + state);
}

通过 RunnableConfig 传递运行时配置：

import com.alibaba.cloud.ai.graph.RunnableConfig;

String threadId = "thread_123";
RunnableConfig runnableConfig = RunnableConfig.builder()
  .threadId(threadId)
  .addMetadata("key", "value")
  .build();

AssistantMessage response = agent.call("你的问题", runnableConfig);

使用 Spring AI Alibaba 搭建一个 ReAct Agent

现在让lai 真正动手，搭建一个完整的 ReactAgent 应用。

需求就是构建一个天气查询助手 Agent，它有以下能力：

  1. 理解用户关于天气的问题
  2. 自主决定调用天气查询工具
  3. 根据查询结果生成友好的回答

添加依赖

在 pom.xml 中添加必要的依赖：

<dependencies>
  <!-- Lombok -->
  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
  </dependency>

  <!-- DashScope ChatModel 支持（如果使用其他模型，请跳转 Spring AI 文档选择对应的 starter） -->
  <dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.1.2.0</version>
  </dependency>

  <!-- Spring AI Alibaba Agent Framework -->
  <dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-agent-framework</artifactId>
    <version>1.1.2.0</version>
  </dependency>

  <!-- Spring AI Alibaba Graph Core -->
  <dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-graph-core</artifactId>
    <version>1.1.2.0</version> <!-- 请使用最新版本 -->
  </dependency>

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>

  <!-- Redisson (Redis 客户端，与 RedisSaver 匹配) -->
  <dependency>
    <groupId>org.redisson</groupId>
    <artifactId>redisson-spring-boot-starter</artifactId>
    <version>3.27.2</version>
  </dependency>
</dependencies>

配置文件

在 application.yml 中配置 API Key 和模型参数：

spring:
  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen3.7-max-preview
          temperature: 0.7
          max-tokens: 2048

定义工具：WeatherTool

首先创建一个天气查询工具。Agent 将通过这个工具获取实时天气信息。

package com.cys.saa.chapter04.tools;


import org.springframework.ai.chat.model.ToolContext;
import org.springframework.stereotype.Component;
import java.util.function.BiFunction;
import java.util.Map;
import java.util.HashMap;

/**
 * 天气查询工具
 * 模拟调用外部天气 API 获取天气信息
 */
@Component
public class WeatherTool implements BiFunction<String, ToolContext, String> {

    // 模拟天气数据
    private static final Map<String, String> WEATHER_DATA = new HashMap<>();

    static {
        WEATHER_DATA.put("上海", "晴，25°C，东南风 3-4 级，适合户外活动");
        WEATHER_DATA.put("北京", "多云，18°C，北风 2-3 级，空气质量良好");
        WEATHER_DATA.put("深圳", "阵雨，28°C，南风 2 级，建议携带雨具");
        WEATHER_DATA.put("杭州", "晴，22°C，微风，西湖游览好天气");
        WEATHER_DATA.put("成都", "阴，20°C，无持续风向，适合室内活动");
    }

    @Override
    public String apply(String city, ToolContext context) {
        // 模拟 API 调用延迟
        try {
            Thread.sleep(500);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }

        // 查询天气
        String weather = WEATHER_DATA.getOrDefault(
            city,
            city + "：天气数据暂不可用，请稍后重试"
        );

        return weather;
    }
}

配置类：AgentConfig

创建配置类，负责构建 ChatModel 和 ReactAgent：

package com.cys.saa.chapter04.config;

import com.alibaba.cloud.ai.dashscope.api.DashScopeApi;
import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatModel;
import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatOptions;
import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import com.cys.saa.chapter04.tools.WeatherTool;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.tool.ToolCallback;
import org.springframework.ai.tool.function.FunctionToolCallback;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AgentConfig {

    @Value("${spring.ai.dashscope.api-key}")
    private String apiKey;

    @Bean
    public DashScopeApi dashScopeApi() {
        return DashScopeApi.builder()
                .apiKey(apiKey)
                .build();
    }

    @Bean
    public ChatModel chatModel(DashScopeApi dashScopeApi) {
        return DashScopeChatModel.builder()
                .dashScopeApi(dashScopeApi)
                .defaultOptions(DashScopeChatOptions.builder()
                        .withModel(DashScopeChatModel.DEFAULT_MODEL_NAME)
                        .withTemperature(0.7)
                        .withMaxToken(2048)
                        .withTopP(0.9)
                        .build())
                .build();
    }

    @Bean
    public ToolCallback weatherToolCallback(WeatherTool weatherTool) {
        return FunctionToolCallback.builder("get_weather", weatherTool)
                .description("获取指定城市的实时天气信息，返回天气状况、温度和活动建议")
                .build();
    }

    @Bean
    public ReactAgent weatherAgent(ChatModel chatModel, ToolCallback weatherToolCallback) {
        String instruction = """
                你是一个专业的天气助手。
                
                你的职责是：
                1. 理解用户关于天气的查询意图
                2. 如果用户询问某个城市的天气，调用 get_weather 工具获取实时天气
                3. 根据工具返回的天气信息，生成友好、详细的回答
                4. 回答应包含天气状况、温度和活动建议
                
                注意：
                - 如果用户没有指定城市，请主动询问
                - 如果工具返回数据不可用，请告知用户并建议稍后重试
                - 保持热情、专业的语气
                """;

        return ReactAgent.builder()
                .name("weather_agent")
                .model(chatModel)
                .instruction(instruction)
                .tools(weatherToolCallback)
                .build();
    }
}

主要代码：

  • ReactAgent.builder() 是构建 Agent 的标准入口
  • .name() 设置 Agent 的名称，便于识别和日志追踪
  • .model() 绑定推理引擎
  • .instruction() 设置系统指令，定义 Agent 的行为准则
  • .tools() 注册工具，Agent 可以调用这些工具完成任务

DTO 定义

定义请求和响应的数据传输对象：

package com.cys.saa.chapter04.dto;


import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
public class ChatRequest {
    private String message;

}

响应

package com.cys.saa.chapter04.dto;


import lombok.Data;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
public class ChatResponse {
    private String answer;
    private boolean success;
    private String errorMessage;

    // 构造方法、getter 和 setter
    public ChatResponse() {}

    public ChatResponse(String answer, boolean success) {
        this.answer = answer;
        this.success = success;
    }

    public ChatResponse(String answer, boolean success, String errorMessage) {
        this.answer = answer;
        this.success = success;
        this.errorMessage = errorMessage;
    }

}

Service 层：AgentService

Service 层封装 Agent 的调用逻辑：

package com.cys.saa.chapter04.service;


import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import com.alibaba.cloud.ai.graph.exception.GraphRunnerException;
import org.springframework.ai.chat.messages.AssistantMessage;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.stereotype.Service;


@Service
public class AgentService {

    private final ReactAgent weatherAgent;

    public AgentService(ReactAgent weatherAgent) {
        this.weatherAgent = weatherAgent;
    }

    /**
     * 调用 Agent 处理用户消息
     * @param userMessage 用户输入
     * @return Agent 的回复
     */
    public String chat(String userMessage) throws GraphRunnerException {
        // 将用户消息封装为 UserMessage
        UserMessage userMsg = new UserMessage(userMessage);

        // 调用 Agent，返回 AssistantMessage
        AssistantMessage response = weatherAgent.call(userMsg);

        // 提取回复内容
        return response.getText();
    }
}

ReactAgent.call() 方法是 Agent 的核心调用入口，它接收 UserMessage 作为输入，返回 AssistantMessage 作为输出。在这个过程中，Agent 会自动执行 ReAct 循环——推理、调用工具、观察结果、继续推理，直到生成最终答案。

Controller 层

Controller 层暴露 REST API：

package com.cys.saa.chapter04.controller;


import com.cys.saa.chapter04.dto.ChatRequest;
import com.cys.saa.chapter04.dto.ChatResponse;
import com.cys.saa.chapter04.service.AgentService;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/agent")
public class AgentController {

    private final AgentService agentService;

    public AgentController(AgentService agentService) {
        this.agentService = agentService;
    }

    @PostMapping("/chat")
    public ChatResponse chat(@RequestBody ChatRequest request) {
        try {
            String answer = agentService.chat(request.getMessage());
            return new ChatResponse(answer, true);
        } catch (Exception e) {
            return new ChatResponse(null, false, e.getMessage());
        }
    }
}

启动类

package com.cys.saa.chapter04;

import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Chapter04Application {
    public static void main(String[] args) {
        org.springframework.boot.SpringApplication.run(Chapter04Application.class, args);
    }
}

运行与测试

启动应用后，通过 REST API 调用 Agent：

curl -X POST http://localhost:8080/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "上海今天天气怎么样？"}'

预期返回：

{
  "answer": "上海今天天气晴朗，气温25°C，东南风3-4级，非常适合户外活动。建议您可以安排一些户外活动，比如去外滩散步或者去公园游玩。",
  "success": true
}

Agent 的执行过程（后台日志） ：

  1. 推理：Agent 理解到用户想查询上海的天气
  2. 行动：Agent 调用 get_weather("上海") 工具
  3. 观察：工具返回“晴，25°C，东南风 3-4 级，适合户外活动”
  4. 迭代：Agent 根据天气信息生成友好的回答

这就是一个完整的 ReAct 循环。

小结：本章学习了Agent的概念和常见的架构设计、核心组件及ReAct Agent示例。下一章学习消息类型Messages和结构化输出。

# spring # 人工智能 # java
Logo
DAMO开发者矩阵

DAMO开发者矩阵，由阿里巴巴达摩院和中国互联网协会联合发起，致力于探讨最前沿的技术趋势与应用成果，搭建高质量的交流与分享平台，推动技术创新与产业应用链接，围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐

cover

RoboTTT：机器人策略的上下文规模化

avatar DAMO开发者矩阵

开题季实测：AI能帮你写报告，但大模型别直接交

开题季自救指南：测了十几款AI工具后，我劝你别再拿通用大模型硬写论文了 开学没几天，后台问"开题报告怎么写"的消息又炸了。 说个真事：我同门上周用某知名大模型生成开题报告，参考文献列了12篇，导师随手一查——7篇搜不到，剩下5篇里有3篇年份和作者对不上。当场被打回，还落了个"学术态度不端"的印象。 这两年AI工具爆发，通用大模型、垂直写作平台、AI智能体满天飞，个个都说自己能写论文。但开题报告这东

avatar DAMO开发者矩阵
cover

EgoEngine：从以自我为中心人类视频到高保真灵巧机器人演示

avatar DAMO开发者矩阵