用 Spring AI Alibaba 写 Agent，开发体验还行。但上线之后呢？Prompt 怎么迭代不走发布流程？效果好不好怎么量化？线上出了问题 Trace 在哪看？这些问题，之前没有官方答案，大家各显神通。Spring AI Alibaba Admin 就是来补这个缺的。

一、它是什么

一句话概括：Spring AI Alibaba 负责开发 Agent，Admin 负责管理和运维 Agent。 类比 Spring Boot 和 Spring Boot Admin 的关系。

项目已经合并进 alibaba/spring-ai-alibaba 主仓库（10k+ Stars），作为官方生态长期维护。

技术栈：

组件	版本
Java	17+
Spring Boot	3.5.8
Spring AI	1.1.2
Spring AI Alibaba	1.1.2.2
Nacos	3.1
Vue3	3.x

二、核心能力全景

SAA Admin 的能力分两条线：开发侧和运维侧。

┌─────────────────────────────────────────────────────┐
│              Spring AI Alibaba Admin                 │
├──────────────────────┬──────────────────────────────┤
│      开发侧          │          运维侧              │
├──────────────────────┼──────────────────────────────┤
│  多智能体编排         │  Prompt 管理                 │
│  ┌─ Sequential ─┐    │  版本控制 → 在线调试          │
│  ├─ Parallel  ──┤    │       → Nacos 动态下发        │
│  ├─ Routing   ──┤    │                              │
│  └─ Loop      ──┘    │  效果评估                     │
│  上下文工程           │  数据集 → 评估器 → 实验管理   │
│  多模态 / 语音代理    │                              │
│  Graph 工作流         │  可观测性                     │
│  A2A 分布式协作       │  OpenTelemetry 全链路 Trace   │
└──────────────────────┴──────────────────────────────┘

2.1 开发侧：多智能体编排 + 上下文工程

多智能体编排

这是最核心的能力。四种内置模式覆盖大部分协作场景：

Sequential:   A → B → C

Parallel:     ┌→ A →┐
              ├→ B →┤ → 合并结果
              └→ C →┘

Routing:      条件判断 → Agent A / Agent B / Agent C

Loop:         A → 判断 → 不满足 → 回到 A（直到满足退出条件）

代码示例：

// 创建一个 Sequential Agent
SequentialAgent sequentialAgent = SequentialAgent.builder()
    .addAgent(researchAgent)    // 第一步：调研
    .addAgent(writeAgent)       // 第二步：撰写
    .addAgent(reviewAgent)      // 第三步：审核
    .build();

// 创建一个 Parallel Agent
ParallelAgent parallelAgent = ParallelAgent.builder()
    .addAgent(codeReviewAgent)  // 并行：代码审查
    .addAgent(testAgent)        // 并行：测试执行
    .addAgent(securityAgent)    // 并行：安全扫描
    .build();

比写一堆 if-else 清晰得多。特别是 ParallelAgent 配合上下文工程策略，能做出比较复杂的 Agent 系统。

上下文工程

这块比较实用，内置了一系列提升可靠性的策略：

• 人工介入（Human-in-the-loop）：关键决策点暂停，等待人工确认
• 上下文精简和编辑：自动管理上下文窗口，避免 token 溢出
• 模型与工具调用次数限制：防止无限循环
• 工具重试机制：网络抖动时自动重试
• 任务规划 + 动态工具选择：根据任务自动选择合适的工具

# application.yml 配置示例
spring:
  ai:
    alibaba:
      agent:
        context:
          max-tokens: 8000
          compaction-enabled: true
        tool-call:
          max-retries: 3
          retry-delay: 1000ms
        human-in-the-loop:
          enabled: true
          timeout: 30s

做 Agent 的人都知道，上下文管理是个大坑——太长模型会"忘事"，工具调用失控会死循环，没有重试遇到网络抖动就挂。SAA Admin 把这些最佳实践内置了，省得自己一个个踩坑。

多模态 + 语音代理

• 多模态：ReactAgent 支持文本与图像输入，还能基于工具生成图像或音频
• 语音代理：基于 WebSocket 实时交互，支持流式音频

基于图的工作流

条件路由、嵌套图、并行执行、状态管理，Java 原生的。和 LangGraph 思路类似，但对已经在用 Spring AI 的项目来说，不用为了用 Graph 去学一套 Python 的东西。

// Graph 工作流示例
Graph graph = Graph.builder()
    .addNode("analyze", analyzeNode)
    .addNode("route", routingNode)
    .addNode("execute", executeNode)
    .addEdge("analyze", "route")
    .addConditionalEdge("route", 
        condition -> condition.getCodeQuality() > 0.8 ? "approve" : "review",
        Map.of("approve", "execute", "review", "human-review"))
    .build();

A2A 分布式协作

通过 Nacos 集成，实现跨服务的分布式 Agent 协作：

┌──────────────┐     A2A 协议     ┌──────────────┐
│  Agent A     │ ←──────────────→ │  Agent B     │
│  (代码审查)   │     Nacos 发现    │  (Bug 分析)   │
└──────────────┘                  └──────────────┘
       ↕                                ↕
   独立部署                          独立部署
   独立扩缩容                        独立扩缩容

每个 Agent 可以独立部署、独立扩缩容、独立迭代，通过 A2A 协作而不是全挤在一个进程里。对微服务架构的团队来说，这个设计很友好。

// A2A 服务发现配置
spring:
  cloud:
    nacos:
      discovery:
        enabled: true
        server-addr: localhost:8848
  ai:
    alibaba:
      a2a:
        enabled: true
        agent-id: code-review-agent
        capabilities:
          - code-analysis
          - security-scan

2.2 运维侧：Prompt 管理 + 评估 + 可观测

Prompt 管理

Prompt 管理看起来简单，做起来坑很多。传统做法是硬编码在代码里或扔在 application.yml 里，改一个词就要重新编译部署。

SAA Admin 的做法形成了一条完整闭环：

Prompt 修改 → 版本自动记录 → 在线调试验证
                                    ↓
               业务应用 @RefreshScope ← Nacos 一键发布

核心能力：

1. 版本控制：每次修改自动记录版本，支持回滚
2. 在线调试：直接在界面上输入测试数据，实时看模型输出
3. Nacos 动态下发：优化后的 Prompt 一键发布到 Nacos，业务应用通过 @RefreshScope 自动热更新

// 业务应用中使用动态 Prompt
@RestController
@RefreshScope
public class AgentController {
    
    @Value("${agent.system-prompt:You are a helpful assistant.}")
    private String systemPrompt;
    
    @PostMapping("/chat")
    public String chat(@RequestBody ChatRequest request) {
        // systemPrompt 会自动从 Nacos 更新，无需重启
        return agent.run(systemPrompt, request.getMessage());
    }
}

这条链路打通之后，Prompt 的迭代效率会提升很多。产品经理或运营也可以直接参与调优，不用每次都提需求给开发。

效果评估

这是我觉得整个项目最有价值的部分。

SAA Admin 构建了一套完整的评估闭环：

生产环境 Trace 数据
        ↓ 一键筛选异常请求
   测试数据集（版本化）
        ↓
   评估器（准确性/相关性/合规性/自定义）
        ↓
   实验管理（批量跑 + 可视化对比）
        ↓
   量化结果：换 Prompt / 换模型 / 调参数

三个核心组件：

组件	功能	亮点
数据集管理	维护测试用例集，支持版本化	从生产 Trace 一键筛选异常请求
评估器管理	内置多维度评估器，支持自定义	检查 Agent 是否按预期调用正确工具
实验管理	批量实验，结果可视化对比	换 Prompt/模型/参数直接出量化结果

// 自定义评估器示例
@Component
public class ToolCallEvaluator implements Evaluator {
    
    @Override
    public EvaluationResult evaluate(Trace trace) {
        List<ToolCall> toolCalls = trace.getToolCalls();
        
        // 检查是否调用了正确的工具
        boolean correctToolCalled = toolCalls.stream()
            .anyMatch(tc -> "search_code".equals(tc.getToolName()));
        
        // 检查工具调用次数是否合理
        boolean reasonableCount = toolCalls.size() <= 5;
        
        return EvaluationResult.builder()
            .score(correctToolCalled && reasonableCount ? 1.0 : 0.0)
            .metrics(Map.of(
                "correct_tool", correctToolCalled,
                "reasonable_count", reasonableCount
            ))
            .build();
    }
}

换 Prompt 跑一次、换模型跑一次、调 temperature 跑一次——直接出量化结果。从"凭感觉"变成"看数据"，这是 Agent 工程化的关键一步。

可观测性

AI 应用天然黑盒——推理了几轮？调了哪些工具？每个步骤花了多久？Token 消耗了多少？为什么给出这个答案？

SAA Admin 集成了 OpenTelemetry，完整链路都有 Trace：

用户请求 → Agent 推理 → 工具调用 1 → 工具调用 2 → 模型输出
   │            │              │              │           │
   └────────────┴──────────────┴──────────────┴───────────┘
                    OpenTelemetry Span 链路
                            ↓
              ┌─────────────┼─────────────┐
              ↓             ↓             ↓
         服务监控       Trace 分析     Token 统计
        QPS/延迟/错误率  每步耗时+IO   按模型/Agent/时段

接入示例：

<!-- 添加依赖 -->
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-graph-observation</artifactId>
</dependency>

# 配置 OpenTelemetry
management:
  tracing:
    sampling:
      probability: 1.0
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces

• 服务监控概览：QPS、延迟、错误率一目了然
• Trace 深度分析：每个 Span 的耗时、输入输出都可以展开看
• Token 消耗统计：按模型、按 Agent、按时间段统计消耗和费用

一站式代理平台

支持可视化构建 Agent，无需编码即可部署，或者导出为独立 Java 项目。对非技术人员（产品经理、运营）很有价值——可以直接在平台上搭建简单的 Agent，不需要开发介入。

三、对 Java 开发者意味着什么

AI Agent 领域 Python 是主流，Java 开发者想做 Agent 经常要自己拼方案。SAA Admin 解决的是这个问题：让 Java 开发者在自己的技术栈里，完成 Agent 从开发到运维的完整闭环。

3.1 多智能体编排是杀手锏

SequentialAgent、ParallelAgent、RoutingAgent、LoopAgent 覆盖了大部分场景。之前要用 Java 实现这些，要么手写状态机，要么硬套设计模式，代码写出来又丑又难维护。现在有了官方支持的编排能力，代码可以写得很清晰。

3.2 A2A 解决了分布式 Agent 的痛点

之前做分布式 Agent，通信要自己搞——消息队列、HTTP 调用、共享数据库，每种都有坑。SAA Admin 通过 Nacos 集成提供标准协议通信，每个 Agent 独立部署、独立扩缩容、通过 A2A 协作。对微服务架构的团队来说，这个设计很自然。

3.3 上下文工程是实战经验的沉淀

人工介入、工具调用次数限制、重试机制……看着简单，但都是踩过坑才知道要做的事。特别是"人工介入"和"工具调用次数限制"，是生产环境里避免 Agent 失控的关键。没有这些，Agent 一旦进入死循环或调用失败不断重试，Token 消耗会飙升。

3.4 评估 + 可观测 + Nacos 是工程化基础设施

评估体系、OpenTelemetry 全链路 Trace、Nacos 配置中心，都是 Agent 项目做久了迟早要补的课。SAA Admin 都提供了，而且是 Java 生态里成熟的方案，接入成本不高。

我在 Dream-SaaS 里也验证了：Nacos 动态下发 Prompt 比改配置文件重启强太多，OpenTelemetry 的 Trace 在排查 Agent 问题时真的能救命。

3.5 企业级场景，Java 的运维优势更明显

Python 在研究和原型上更顺手，但企业级落地是另一回事——稳定性、可维护性、运维体系、人才储备，Java 都有优势。特别是 Agent 项目做半年以上、多人协作、线上运维的时候，Java 的工程化实践远比 Python 成熟。

四、快速开始

4.1 环境要求

• JDK 17+
• Maven 3.8+
• Nacos 3.1+（可选）

4.2 创建项目

git clone --depth=1 https://github.com/alibaba/spring-ai-alibaba.git
cd spring-ai-alibaba/examples/chatbot

4.3 添加依赖

<dependencies>
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-agent-framework</artifactId>
        <version>1.1.2.0</version>
    </dependency>
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
        <version>1.1.2.1</version>
    </dependency>
</dependencies>

4.4 配置 API Key

export AI_DASHSCOPE_API_KEY=your-api-key

4.5 启动应用

./mvnw spring-boot:run

访问 http://localhost:8080/chatui/index.html 即可体验。

五、写在最后

Spring AI Alibaba Admin 填补了 Java 生态里 AI Agent 全栈平台的空白。不管用不用这个项目，它代表的方向值得关注：

1. 多智能体编排 + 上下文工程 是 Agent 开发的核心能力，Java 生态终于有了官方支持
2. A2A 分布式协作 解决了多 Agent 系统的部署和通信问题，对微服务架构友好
3. Nacos + OpenTelemetry 正在成为 Java AI Agent 生态的事实标准
4. 评估体系 + 可观测性 是 Agent 工程化的关键，不能再"凭感觉"做 AI 应用

项目还在早期，有些功能还在完善，但方向是对的。对正在做 AI Agent 的 Java 开发者来说，现在值得关注，后续可以按需接入。

项目地址： https://github.com/alibaba/spring-ai-alibaba

---

Dream-SaaS 实战项目

我在 Dream-SaaS 项目里也做了类似的工程化实践，整个项目结构长这样：

Dream-SaaS/
├── dream-saas-core/              # 业务核心（user/order/product/case/workflow）
├── dream-saas-gateway/           # Spring Cloud Gateway
├── dream-saas-edge/              # 边缘层（business/platform/user）
├── dream-saas-common/            # SaaS 公共库
├── dream-saas-cache/             # Redis 缓存层
├── dream-saas-message/           # 消息（RocketMQ）
│
├── dream-ai/                     # AI 能力域（23 个 Java 模块）
│   ├── dream-ai-common/          # AI 共享库
│   ├── dream-ai-agent-core/      # 基础设施（RAG/Prompt/Security）
│   ├── dream-ai-graph/           # Graph 编排引擎（Supervisor + 4 子图）
│   ├── dream-ai-mcp/             # MCP 平台（5 个子模块）
│   ├── dream-ai-agent-chat/      # Agent 对话 + ReAct
│   ├── dream-ai-agent-runtime/   # 运行时（Recovery/Trace/Debug）
│   ├── dream-ai-agent-companion/ # 搭子 Java 数据层
│   ├── dream-ai-agent-study/     # 学习助手 Java 数据层
│   ├── dream-ai-agent-content/   # 内容操作系统
│   ├── dream-ai-agent-memory/    # 三层记忆（API/MCP/pgvector/Redis）
│   ├── dream-ai-agent-rag-service/ # RAG 服务层
│   ├── dream-ai-agent-bi/        # BI 数据分析
│   ├── dream-ai-agent-repo/      # 仓库分析 Agent
│   ├── dream-ai-agent-bug/       # Bug 分析 Agent
│   ├── dream-ai-agent-tech/      # 技术资讯 Agent
│   ├── dream-ai-code-review/     # 代码审查（:8095）
│   ├── dream-ai-rag/             # RAG 服务（:8096）
│   ├── dream-ai-gateway/         # 统一网关（:8090）
│   └── dream-ai-python/          # Python 编排层（:8092）
│
├── frontend/                     # 主站 Vue 3 SPA
├── dream-saas-study-admin/       # 学习助手 React SPA
└── dream-saas-content-admin/     # 内容管理 React SPA

Graph 编排、混合检索 RAG、MCP 平台层、三层记忆、OpenTelemetry 可观测，这些能力全部在这个 monorepo 里。

7 月初我会开始更新 Java 开发 AI Agent 的实战系列（到时候会全面上线并开放功能体验），从架构设计、代码解析到落地踩坑，23 个模块全部拆开讲，感兴趣的先关注占个位~

有问题评论区见，欢迎交流~