Spring AI Alibaba

主题

Agent Framework 智能体框架 ​

Spring AI Alibaba Agent Framework 是构建生产级 AI Agent 的核心框架，内置 Context Engineering 最佳实践，支持从简单 ReactAgent 到复杂多 Agent 协作的全场景覆盖。

什么是 AI Agent？ ​

AI Agent 是能够感知环境、做出决策、执行行动的自主 AI 系统：

传统 AI 应用：用户输入 → LLM → 输出（单次交互）

AI Agent：
用户目标
    │
    ▼
┌─────────────────────────────────┐
│  Agent 循环（ReAct 模式）        │
│                                  │
│  思考（Thought）                 │
│    ↓                             │
│  行动（Action）→ 调用工具        │
│    ↓                             │
│  观察（Observation）← 工具结果   │
│    ↓                             │
│  重复，直到任务完成              │
└─────────────────────────────────┘
    │
    ▼
最终答案

依赖配置 ​

xml
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-agent-framework</artifactId>
    <version>1.1.2.0</version>
</dependency>

ReactAgent：最基础的 Agent ​

ReactAgent 实现了经典的 ReAct（Reasoning + Acting）模式：

java
@Configuration
public class AgentConfig {

    @Bean
    public ReactAgent researchAgent(
        ChatClient.Builder builder,
        SearchTools searchTools,
        CalculatorTools calcTools
    ) {
        return ReactAgent.builder()
            .chatClient(builder.build())
            .tools(searchTools, calcTools)
            .systemPrompt("""
                你是一个研究助手，可以使用搜索和计算工具。
                遇到问题时，先思考需要哪些信息，然后调用工具获取，
                最后综合信息给出完整回答。
                """)
            .maxIterations(10)  // 最大循环次数，防止无限循环
            .build();
    }
}

// 使用
@GetMapping("/research")
public String research(@RequestParam String topic) {
    return researchAgent.run(topic);
}

ReactAgent 执行流程 ​

用户："分析 Spring AI Alibaba 的 GitHub Star 增长趋势"

第 1 轮：
  思考：需要获取 GitHub 数据
  行动：searchGitHub("spring-ai-alibaba stars history")
  观察：返回 Star 历史数据

第 2 轮：
  思考：需要计算增长率
  行动：calculate("增长率 = (当前 - 初始) / 初始 * 100")
  观察：增长率 = 340%

第 3 轮：
  思考：信息足够，可以生成分析报告
  最终回答：Spring AI Alibaba 自发布以来 Star 增长 340%...

内置 Agent 类型 ​

SequentialAgent（顺序执行） ​

多个子 Agent 按顺序执行，前一个的输出作为后一个的输入：

java
@Bean
public SequentialAgent contentPipeline(
    ChatClient.Builder builder
) {
    return SequentialAgent.builder()
        .name("内容生产流水线")
        .addAgent("researcher", ReactAgent.builder()
            .chatClient(builder.build())
            .tools(searchTools)
            .systemPrompt("你是研究员，负责收集资料")
            .build()
        )
        .addAgent("writer", ReactAgent.builder()
            .chatClient(builder.build())
            .systemPrompt("你是写作专家，基于研究资料撰写文章")
            .build()
        )
        .addAgent("editor", ReactAgent.builder()
            .chatClient(builder.build())
            .systemPrompt("你是编辑，负责润色和校对文章")
            .build()
        )
        .build();
}

// 执行：研究 → 写作 → 编辑，自动传递上下文
String article = contentPipeline.run("写一篇关于 Spring AI 的技术博客");

ParallelAgent（并行执行） ​

多个子 Agent 并行执行，最后汇总结果：

java
@Bean
public ParallelAgent marketAnalysis(ChatClient.Builder builder) {
    return ParallelAgent.builder()
        .name("市场分析")
        .addAgent("techAnalyst", ReactAgent.builder()
            .systemPrompt("分析技术趋势和竞争格局")
            .tools(searchTools)
            .build()
        )
        .addAgent("marketAnalyst", ReactAgent.builder()
            .systemPrompt("分析市场规模和增长潜力")
            .tools(searchTools, dataTools)
            .build()
        )
        .addAgent("riskAnalyst", ReactAgent.builder()
            .systemPrompt("识别潜在风险和挑战")
            .tools(searchTools)
            .build()
        )
        // 汇总 Agent：整合三个分析结果
        .aggregator(ReactAgent.builder()
            .systemPrompt("整合以上分析，生成综合报告")
            .build()
        )
        .build();
}

// 三个分析并行执行，最后汇总
String report = marketAnalysis.run("分析 Java AI 框架市场");

RoutingAgent（路由分发） ​

根据输入内容智能路由到不同的专业 Agent：

java
@Bean
public RoutingAgent customerService(ChatClient.Builder builder) {
    return RoutingAgent.builder()
        .name("智能客服路由")
        .routerPrompt("""
            分析用户问题，路由到对应专业 Agent：
            - order_agent：订单相关（查询、退款、修改）
            - tech_agent：技术支持（使用问题、故障排查）
            - sales_agent：销售咨询（产品介绍、价格、促销）
            - general_agent：其他通用问题
            
            只输出 agent 名称，不要其他内容。
            """)
        .addRoute("order_agent", ReactAgent.builder()
            .systemPrompt("你是订单专家")
            .tools(orderTools)
            .build()
        )
        .addRoute("tech_agent", ReactAgent.builder()
            .systemPrompt("你是技术支持专家")
            .tools(techDocs, ticketTools)
            .build()
        )
        .addRoute("sales_agent", ReactAgent.builder()
            .systemPrompt("你是销售顾问")
            .tools(productCatalog, pricingTools)
            .build()
        )
        .addRoute("general_agent", ReactAgent.builder()
            .systemPrompt("你是通用客服")
            .build()
        )
        .build();
}

LoopAgent（循环执行） ​

持续循环执行直到满足终止条件：

java
@Bean
public LoopAgent codeRefactorAgent(ChatClient.Builder builder) {
    return LoopAgent.builder()
        .name("代码重构 Agent")
        .agent(ReactAgent.builder()
            .systemPrompt("分析代码质量，提出并执行一个改进")
            .tools(codeReadTools, codeWriteTools, testTools)
            .build()
        )
        // 终止条件：代码质量评分 >= 90 或循环 5 次
        .terminationCondition(state ->
            state.getQualityScore() >= 90 || state.getIterations() >= 5
        )
        .build();
}

Context Engineering ​

Context Engineering 是 Agent Framework 的核心特性，自动管理 Agent 的上下文质量：

Human-in-the-Loop（人工介入） ​

java
@Bean
public ReactAgent approvalAgent(ChatClient.Builder builder) {
    return ReactAgent.builder()
        .chatClient(builder.build())
        .tools(orderTools, paymentTools)
        .systemPrompt("你是订单处理 Agent")
        // 配置需要人工审批的工具
        .humanInTheLoop(HumanInTheLoopConfig.builder()
            .requireApprovalForTools("cancelOrder", "refundPayment")
            .approvalHandler(toolCall -> {
                // 发送审批通知（钉钉/邮件/企业微信）
                notificationService.sendApprovalRequest(
                    toolCall.getToolName(),
                    toolCall.getArguments()
                );
                // 等待人工审批（阻塞或异步）
                return approvalService.waitForApproval(toolCall.getId());
            })
            .build()
        )
        .build();
}

上下文压缩 ​

java
ReactAgent agent = ReactAgent.builder()
    .chatClient(builder.build())
    .tools(tools)
    // 自动压缩过长的上下文
    .contextCompaction(ContextCompactionConfig.builder()
        .maxTokens(8000)
        .compressionStrategy(CompressionStrategy.SUMMARIZE)
        .build()
    )
    .build();

动态工具选择 ​

java
ReactAgent agent = ReactAgent.builder()
    .chatClient(builder.build())
    .tools(allTools)  // 注册所有工具
    // 根据当前任务动态选择相关工具（减少 Token 消耗）
    .dynamicToolSelection(DynamicToolSelectionConfig.builder()
        .maxTools(5)  // 每次最多选 5 个工具
        .selectionStrategy(SelectionStrategy.SEMANTIC_SIMILARITY)
        .build()
    )
    .build();

A2A：Agent 间通信 ​

Spring AI Alibaba 支持 Agent-to-Agent（A2A）协议，实现分布式 Agent 协作：

xml
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-nacos-a2a</artifactId>
</dependency>
java
// Agent A：任务分发者
@Service
public class OrchestratorAgent {

    @Autowired
    private A2AClient a2aClient;

    public String orchestrate(String task) {
        // 发现并调用其他 Agent
        A2AResponse response = a2aClient.call(
            "data-analysis-agent",  // Nacos 中注册的 Agent 名称
            A2ARequest.builder()
                .task(task)
                .context(Map.of("format", "JSON"))
                .build()
        );
        return response.getResult();
    }
}

// Agent B：数据分析专家（独立部署的 Spring Boot 应用）
@SpringBootApplication
@EnableA2AServer(name = "data-analysis-agent")
public class DataAnalysisAgentApp {

    @A2AHandler
    public String handleTask(A2ARequest request) {
        return dataAnalysisAgent.run(request.getTask());
    }
}

实战：智能代码审查 Agent ​

java
@Service
public class CodeReviewAgent {

    @Autowired
    private ChatClient.Builder chatClientBuilder;

    @Autowired
    private GitTools gitTools;

    @Autowired
    private CodeAnalysisTools codeTools;

    @Autowired
    private NotificationTools notifyTools;

    public CodeReviewResult reviewPullRequest(String prUrl) {

        ReactAgent reviewer = ReactAgent.builder()
            .chatClient(chatClientBuilder.build())
            .tools(gitTools, codeTools, notifyTools)
            .systemPrompt("""
                你是一个资深代码审查专家，职责：
                1. 获取 PR 的代码变更
                2. 分析代码质量（规范、性能、安全）
                3. 运行静态分析工具
                4. 生成详细的审查报告
                5. 在 PR 上发表审查评论
                
                审查标准：
                - 代码规范：遵循 Google Java Style Guide
                - 性能：避免 N+1 查询、不必要的对象创建
                - 安全：SQL 注入、XSS、敏感信息泄露
                - 测试：关键逻辑必须有单元测试
                """)
            .maxIterations(15)
            .build();

        String result = reviewer.run("审查 PR：" + prUrl);
        return CodeReviewResult.parse(result);
    }
}

Agent 状态管理 ​

java
// Agent 执行状态
AgentExecution execution = agent.execute(task);

// 监控执行过程
execution.onStep(step -> {
    log.info("步骤 {}: {} → {}",
        step.getIndex(),
        step.getThought(),
        step.getAction()
    );
});

// 获取最终结果
String result = execution.getResult();

// 获取执行轨迹（用于调试和审计）
List<AgentStep> trace = execution.getTrace();
trace.forEach(step -> {
    System.out.printf("[%d] 思考：%s%n", step.getIndex(), step.getThought());
    System.out.printf("    行动：%s(%s)%n", step.getToolName(), step.getToolInput());
    System.out.printf("    结果：%s%n%n", step.getObservation());
});

最佳实践 ​

Agent 设计原则

  1. 单一职责：每个 Agent 专注一个领域，避免"万能 Agent"
  2. 工具精简：只给 Agent 它需要的工具，减少决策复杂度
  3. 提示词清晰：明确 Agent 的角色、能力边界和输出格式
  4. 设置上限：maxIterations 防止无限循环，生产环境必须设置
  5. 错误处理：工具调用失败时，Agent 应能优雅降级
  6. 可观测性：记录 Agent 的每一步决策，便于调试和审计

生产注意事项

  • Agent 循环调用 LLM，Token 消耗是普通对话的数倍，注意成本控制
  • Human-in-the-Loop 会阻塞执行，需要合理设置超时
  • 涉及写操作的工具（删除、支付）必须加人工审批
  • 多 Agent 并行时注意资源竞争和数据一致性

相关组件 ​

本站内容由 褚成志 整理编写，仅供学习参考

Copyright © 2024-present 褚成志 · All Rights Reserved