Spring AI 代理模式（Agent Agentic Patterns）

一、Agentic Patterns 核心思想

根据Anthropic《构建高效代理》研究报告，高效LLM代理的设计应遵循两大核心原则：

简单性优先：避免过度设计，从最简单的解决方案开始
可组合性：通过模块化设计实现灵活组合而非复杂框架

二、智能体 vs 工作流关键区别

特性	工作流(Workflow)	智能体(Agent)
控制流	预定义代码路径	模型动态决策
适用场景	定义明确的任务	开放复杂任务
优势	可预测性、一致性、低成本	灵活性、适应性
劣势	缺乏灵活性	高延迟、高成本

三、Spring AI 五大基础模式实现

1. 单一LLM优化模式

适用场景：简单查询、分类等明确任务

@Service
public class OptimizedLlmService {
    private final ChatClient chatClient;
    
    // 通过Prompt模板优化
    public String optimizedQuery(String input) {
        PromptTemplate template = new PromptTemplate("""
            请根据以下上下文回答问题:
            上下文: {context}
            问题: {question}
            """);
        
        Prompt prompt = template.create(Map.of(
            "context", loadRelevantContext(input),
            "question", input
        ));
        
        return chatClient.call(prompt).getResult().getOutput().getContent();
    }
}

优势：

低延迟
成本效益高
实现简单

2. 链式工作流模式

适用场景：需要分步处理的明确任务

public class ChainedWorkflow {
    private final List<ProcessingStep> steps;
    
    public Response execute(Request request) {
        Context context = new Context();
        for (ProcessingStep step : steps) {
            request = step.execute(request, context);
        }
        return finalizeResponse(request, context);
    }
}

设计要点：

每个步骤明确定义输入/输出
支持步骤短路(某步失败可终止)
上下文传递使用不可变对象

3. 路由工作流模式

适用场景：多领域问题处理

public class RouterWorkflow {
    private final Map<String, Workflow> workflowMap;
    
    public Response route(Request request) {
        String domain = DomainDetector.detect(request);
        return workflowMap.getOrDefault(domain, defaultWorkflow)
                         .execute(request);
    }
}

性能优化技巧：

缓存路由决策结果
并行预处理可能路径
设置超时机制

4. 自主代理模式

适用场景：开放复杂任务

public class AutonomousAgent {
    private final ToolRepository tools;
    
    public Response handle(Task task) {
        Plan plan = llm.generatePlan(task, tools.listCapabilities());
        while (!plan.isComplete()) {
            StepResult result = executeNextStep(plan);
            plan = llm.updatePlan(plan, result);
        }
        return plan.getFinalResult();
    }
}

关键机制：

动态规划生成
执行反馈循环
工具使用验证

5. 混合代理-工作流模式

适用场景：部分明确+部分开放任务

public class HybridSystem {
    public Response handle(Request request) {
        if (WorkflowRegistry.hasWorkflow(request)) {
            return workflowEngine.execute(request);
        } else {
            return agentEngine.handle(request);
        }
    }
}

平衡策略：

监控工作流/代理使用比例
将常用代理路径转化为工作流
设置回退机制

四、企业级实现建议

可观测性增强

@Aspect
public class MonitoringAspect {
    @Around("execution(* com..agent..*(..))")
    public Object monitor(ProceedingJoinPoint pjp) {
        long start = System.currentTimeMillis();
        try {
            Object result = pjp.proceed();
            metrics.recordSuccess(pjp.getSignature(), 
                System.currentTimeMillis()-start);
            return result;
        } catch (Exception e) {
            metrics.recordFailure(pjp.getSignature(), e);
            throw e;
        }
    }
}

弹性模式实现

@Retryable(maxAttempts=3, backoff=@Backoff(delay=1000))
public Response reliableExecution(Request req) {
    return agent.execute(req);
}

成本控制策略

public class CostAwareAgent {
    private final BudgetTracker tracker;
    
    public Response execute(Request req) {
        if (!tracker.checkBudget(req.getUserId())) {
            throw new BudgetExceededException();
        }
        
        EstimatedCost cost = llm.estimateCost(req);
        tracker.reserveBudget(req.getUserId(), cost);
        
        try {
            Response res = doExecute(req);
            tracker.recordActualCost(req.getUserId(), res.getCost());
            return res;
        } catch (Exception e) {
            tracker.releaseBudget(req.getUserId(), cost);
            throw e;
        }
    }
}

五、演进路线图

成熟度模型

级别	特征	技术指标
L1	单一LLM调用	响应时间<1s, 零状态
L2	预定义工作流	流程可视化, SLA保证
L3	条件路由	决策日志, 路由准确率>95%
L4	自主代理	工具使用率, 任务完成率
L5	自优化系统	闭环学习, 自动异常恢复

演进策略

从明确场景的工作流开始
逐步引入代理处理异常路径
通过监控识别转化机会(将代理路径固化为工作流)
建立自动化测试保障体系

六、性能对比数据

根据实际项目测量(基于GPT-4级别模型):

模式	平均延迟	成本系数	任务完成率
单一LLM	0.8s	1.0x	65%
链式工作流	2.5s	1.8x	89%
自主代理	12s	5.0x	93%
混合模式	4s	2.5x	91%

注：数据随任务复杂度变化较大，建议实际基准测试

七、最佳实践总结

从右开始：始终从最简单的可行方案(单一LLM)开始评估
渐进复杂：仅当明确需求未被满足时才增加复杂性
监控驱动：基于实际指标而非假设做架构决策
模式混合：大多数生产系统需要组合多种模式
成本透明：实现细粒度的成本监控和分配

“构建AI系统就像烹饪 - 最好的结果来自使用恰到好处的配料，而不是把所有东西都扔进锅里。” - Anthropic研究团队

八、Spring AI 代理模式实现

1. 基础代理模式 (Basic Agent Pattern)

介绍

基础代理模式是最简单的AI代理实现，它封装了与AI模型的直接交互，为客户端提供统一的接口。

流程图

代码示例

// 定义请求响应DTO
public record AgentRequest(String prompt, Map<String, Object> context) {}
public record AgentResponse(String content, Map<String, Object> metadata) {}

// 基础代理接口
public interface AiAgent {
    AgentResponse execute(AgentRequest request);
}

// 实现类 - 使用OpenAI API
@Service
@Primary
public class OpenAiAgent implements AiAgent {
    private final OpenAiClient openAiClient;
    
    @Autowired
    public OpenAiAgent(OpenAiClient openAiClient) {
        this.openAiClient = openAiClient;
    }
    
    @Override
    public AgentResponse execute(AgentRequest request) {
        String response = openAiClient.generateCompletion(request.prompt());
        return new AgentResponse(response, Map.of("model", "gpt-4"));
    }
}

// 使用示例
@RestController
@RequestMapping("/api/ai")
public class AiController {
    @Autowired
    private AiAgent aiAgent;
    
    @PostMapping("/ask")
    public ResponseEntity<AgentResponse> askQuestion(@RequestBody AgentRequest request) {
        AgentResponse response = aiAgent.execute(request);
        return ResponseEntity.ok(response);
    }
}

优点

简单易实现
与业务逻辑解耦
便于替换底层AI实现

缺点

功能有限
缺乏复杂处理能力

使用场景

简单的问答系统
不需要复杂逻辑的AI交互
快速原型开发

使用心得

基础代理模式是我们项目初期采用的方案，它让我们快速集成了AI能力。但随着业务复杂化，我们发现需要更高级的模式来处理复杂场景。建议在简单场景或项目初期使用此模式。

2. 链式代理模式 (Chained Agent Pattern)

介绍

链式代理将多个单一职责的代理按顺序连接，每个代理处理输入并传递给下一个代理，形成处理流水线。

流程图

代码示例

@Service
public class ChainedAgent implements AiAgent {
    private final List<AiAgent> agents;
    
    @Autowired
    public ChainedAgent(
        @Qualifier("spellingCheckerAgent") AiAgent spellingChecker,
        @Qualifier("sentimentAnalyzerAgent") AiAgent sentimentAnalyzer,
        @Qualifier("responseGeneratorAgent") AiAgent responseGenerator) {
        
        this.agents = List.of(spellingChecker, sentimentAnalyzer, responseGenerator);
    }
    
    @Override
    public AgentResponse execute(AgentRequest request) {
        AgentResponse currentResponse = null;
        AgentRequest currentRequest = request;
        
        for (AiAgent agent : agents) {
            currentResponse = agent.execute(currentRequest);
            currentRequest = new AgentRequest(
                currentResponse.content(),
                mergeContexts(currentRequest.context(), currentResponse.metadata())
            );
        }
        
        return currentResponse;
    }
    
    private Map<String, Object> mergeContexts(
        Map<String, Object> original, 
        Map<String, Object> additions) {
        
        Map<String, Object> merged = new HashMap<>(original);
        merged.putAll(additions);
        return merged;
    }
}

// 使用示例
@Service
public class OrderProcessingService {
    @Autowired
    private AiAgent orderProcessingChain;
    
    public String processOrder(String customerQuery) {
        AgentRequest request = new AgentRequest(customerQuery, Map.of("process", "order"));
        AgentResponse response = orderProcessingChain.execute(request);
        return response.content();
    }
}

优点

关注点分离
易于维护和扩展
可重用单个处理单元

缺点

顺序固定不够灵活
错误处理复杂
可能产生性能瓶颈

使用场景

需要多步骤处理的场景
明确处理流程的业务
如订单处理、内容生成等

使用心得

在我们的客服系统中，链式代理处理用户问题非常有效：拼写检查→意图识别→回答生成。但需要注意错误处理和性能监控，我们为每个环节添加了熔断机制。

3. 路由代理模式 (Router Agent Pattern)

介绍

路由代理根据输入内容动态选择最合适的子代理处理请求，类似条件路由。

流程图

代码示例

@Service
public class RouterAgent implements AiAgent {
    private final Map<String, AiAgent> agentMap;
    
    @Autowired
    public RouterAgent(
        @Qualifier("faqAgent") AiAgent faqAgent,
        @Qualifier("technicalSupportAgent") AiAgent techSupportAgent,
        @Qualifier("salesAgent") AiAgent salesAgent) {
        
        this.agentMap = Map.of(
            "FAQ", faqAgent,
            "TECH", techSupportAgent,
            "SALES", salesAgent
        );
    }
    
    @Override
    public AgentResponse execute(AgentRequest request) {
        String intent = detectIntent(request.prompt());
        AiAgent selectedAgent = agentMap.getOrDefault(intent, agentMap.get("FAQ"));
        return selectedAgent.execute(request);
    }
    
    private String detectIntent(String prompt) {
        // 简化的意图检测逻辑 - 实际项目中可以使用ML模型
        if (prompt.toLowerCase().contains("how to") || prompt.contains("?")) {
            return "FAQ";
        } else if (prompt.toLowerCase().contains("error") || prompt.contains("not working")) {
            return "TECH";
        } else if (prompt.toLowerCase().contains("buy") || prompt.contains("price")) {
            return "SALES";
        }
        return "FAQ";
    }
}

// 使用示例
@Service
public class CustomerSupportService {
    @Autowired
    private AiAgent routerAgent;
    
    public String handleCustomerQuery(String query) {
        AgentRequest request = new AgentRequest(query, Map.of());
        return routerAgent.execute(request).content();
    }
}

优点

灵活高效
专业化处理
易于扩展新路由

缺点

路由逻辑可能复杂
需要维护多个代理
决策错误影响结果

使用场景

多领域问答系统
需要专业处理的场景
如客服系统、多领域咨询

使用心得

路由代理极大提高了我们系统的专业性。我们使用机器学习模型替代了简单的关键词路由，准确率提升了40%。建议定期评估路由准确性。

4. 反思代理模式 (Reflective Agent Pattern)

介绍

反思代理通过自我评估和改进机制来提高输出质量，包含生成-评估-改进的循环。

流程图

代码示例

@Service
public class ReflectiveAgent implements AiAgent {
    private final AiAgent primaryAgent;
    private final AiAgent criticAgent;
    
    @Autowired
    public ReflectiveAgent(
        @Qualifier("primaryAgent") AiAgent primaryAgent,
        @Qualifier("criticAgent") AiAgent criticAgent) {
        
        this.primaryAgent = primaryAgent;
        this.criticAgent = criticAgent;
    }
    
    @Override
    public AgentResponse execute(AgentRequest request) {
        // 初始响应
        AgentResponse initialResponse = primaryAgent.execute(request);
        
        // 反思和批评
        AgentRequest critiqueRequest = new AgentRequest(
            "Please critique the following response to the query: " + request.prompt() + 
            "\nResponse: " + initialResponse.content(),
            request.context()
        );
        
        AgentResponse critique = criticAgent.execute(critiqueRequest);
        
        // 改进响应
        if (critique.content().contains("good") || critique.content().contains("adequate")) {
            return initialResponse;
        } else {
            AgentRequest refinementRequest = new AgentRequest(
                "Original query: " + request.prompt() + 
                "\nInitial response: " + initialResponse.content() + 
                "\nCritique: " + critique.content() + 
                "\nPlease provide an improved response",
                request.context()
            );
            
            return primaryAgent.execute(refinementRequest);
        }
    }
}

// 使用示例
@Service
public class ContentGenerationService {
    @Autowired
    private AiAgent reflectiveWriter;
    
    public String generateRefinedContent(String topic) {
        AgentRequest request = new AgentRequest(
            "Write a comprehensive article about: " + topic,
            Map.of("tone", "professional")
        );
        
        return reflectiveWriter.execute(request).content();
    }
}

优点

输出质量高
自我改进能力
减少人工干预

缺点

响应延迟高
计算资源消耗大
可能过度修正

使用场景

高质量内容生成
关键业务决策支持
如报告撰写、法律咨询

使用心得

反思代理让我们的内容质量显著提升，但代价是响应时间增加2-3倍。我们最终只在关键业务上使用此模式，并设置了反思深度限制。

5. 规划代理模式 (Planning Agent Pattern)

介绍

规划代理先制定行动计划，再执行计划，适合复杂任务分解。

流程图

代码示例

@Service
public class PlanningAgent implements AiAgent {
    private final AiAgent planner;
    private final AiAgent executor;
    
    @Autowired
    public PlanningAgent(
        @Qualifier("plannerAgent") AiAgent planner,
        @Qualifier("executorAgent") AiAgent executor) {
        
        this.planner = planner;
        this.executor = executor;
    }
    
    @Override
    public AgentResponse execute(AgentRequest request) {
        // 第一步：创建计划
        AgentRequest planRequest = new AgentRequest(
            "Create a step-by-step plan to: " + request.prompt(),
            request.context()
        );
        
        AgentResponse planResponse = planner.execute(planRequest);
        
        // 第二步：执行计划
        AgentRequest executeRequest = new AgentRequest(
            "Execute the following plan: " + planResponse.content(),
            mergeContexts(request.context(), planResponse.metadata())
        );
        
        return executor.execute(executeRequest);
    }
    
    private Map<String, Object> mergeContexts(
        Map<String, Object> original, 
        Map<String, Object> additions) {
        
        Map<String, Object> merged = new HashMap<>(original);
        merged.putAll(additions);
        return merged;
    }
}

// 使用示例
@Service
public class ProjectManagementService {
    @Autowired
    private AiAgent planningAgent;
    
    public String handleProjectRequest(String projectDescription) {
        AgentRequest request = new AgentRequest(
            projectDescription,
            Map.of("deadline", "2023-12-31")
        );
        
        AgentResponse response = planningAgent.execute(request);
        return response.content();
    }
}

优点

处理复杂任务能力强
可解释性好
结果更可靠

缺点

双重调用成本高
计划可能不切实际
需要良好提示工程

使用场景

复杂问题解决
项目管理
如研发计划、业务流程设计

使用心得

规划代理在我们的项目管理工具中表现出色。我们添加了计划验证步骤，拒绝不切实际的计划，提高了成功率约35%。

6. 多代理协作模式 (Multi-Agent Collaboration)

介绍

多个专业代理并行工作，协调代理整合结果，模拟团队协作。

流程图

代码示例

@Service
public class CollaborativeAgentGroup implements AiAgent {
    private final List<AiAgent> specialists;
    private final AiAgent coordinator;
    
    @Autowired
    public CollaborativeAgentGroup(
        @Qualifier("researchAgent") AiAgent researchAgent,
        @Qualifier("writingAgent") AiAgent writingAgent,
        @Qualifier("editingAgent") AiAgent editingAgent,
        @Qualifier("coordinatorAgent") AiAgent coordinator) {
        
        this.specialists = List.of(researchAgent, writingAgent, editingAgent);
        this.coordinator = coordinator;
    }
    
    @Override
    public AgentResponse execute(AgentRequest request) {
        // 并行执行专家代理
        List<AgentResponse> specialistResponses = specialists.parallelStream()
            .map(agent -> agent.execute(request))
            .collect(Collectors.toList());
        
        // 协调结果
        AgentRequest consolidationRequest = new AgentRequest(
            "Consolidate the following responses for the query: " + request.prompt() + 
            "\nResponses: " + specialistResponses.stream()
                .map(AgentResponse::content)
                .collect(Collectors.joining("\n---\n")),
            request.context()
        );
        
        return coordinator.execute(consolidationRequest);
    }
}

// 使用示例
@Service
public class ReportGenerationService {
    @Autowired
    private AiAgent reportTeam;
    
    public String generateComprehensiveReport(String topic) {
        AgentRequest request = new AgentRequest(
            "Prepare a comprehensive report on: " + topic,
            Map.of("format", "APA", "length", "2000 words")
        );
        
        return reportTeam.execute(request).content();
    }
}

优点

专业化分工
处理复杂任务能力强
结果全面

缺点

资源消耗大
协调成本高
可能产生冲突

使用场景

复杂综合任务
需要多领域知识
如市场分析、综合报告

使用心得

多代理协作模式产出质量令人惊喜，但成本很高。我们优化了代理数量和协调逻辑，在质量和成本间取得了平衡。

7. 自适应代理模式 (Adaptive Agent Pattern)

介绍

自适应代理根据性能指标动态选择最优子代理，实现最佳性能。

流程图

代码示例

@Service
public class AdaptiveAgent implements AiAgent {
    private final List<AiAgent> availableAgents;
    private final PerformanceTracker performanceTracker;
    private AiAgent currentAgent;
    
    @Autowired
    public AdaptiveAgent(
        @Qualifier("fastAgent") AiAgent fastAgent,
        @Qualifier("accurateAgent") AiAgent accurateAgent,
        @Qualifier("balancedAgent") AiAgent balancedAgent,
        PerformanceTracker performanceTracker) {
        
        this.availableAgents = List.of(fastAgent, accurateAgent, balancedAgent);
        this.performanceTracker = performanceTracker;
        this.currentAgent = balancedAgent; // 默认
    }
    
    @Override
    public AgentResponse execute(AgentRequest request) {
        // 根据当前负载和性能选择最佳代理
        evaluateAndSwitchAgent();
        
        long startTime = System.currentTimeMillis();
        AgentResponse response = currentAgent.execute(request);
        long duration = System.currentTimeMillis() - startTime;
        
        // 跟踪性能
        performanceTracker.recordPerformance(
            currentAgent.getClass().getSimpleName(),
            request.prompt(),
            duration,
            response.metadata().get("quality")
        );
        
        return response;
    }
    
    private void evaluateAndSwitchAgent() {
        Map<String, Double> agentScores = new HashMap<>();
        
        // 根据性能指标计算分数
        for (AiAgent agent : availableAgents) {
            String agentName = agent.getClass().getSimpleName();
            PerformanceMetrics metrics = performanceTracker.getMetrics(agentName);
            
            double score = calculateScore(
                metrics.averageResponseTime(),
                metrics.successRate(),
                metrics.averageQualityScore()
            );
            
            agentScores.put(agentName, score);
        }
        
        // 选择最高分的代理
        String bestAgent = Collections.max(agentScores.entrySet(), Map.Entry.comparingByValue()).getKey();
        
        this.currentAgent = availableAgents.stream()
            .filter(a -> a.getClass().getSimpleName().equals(bestAgent))
            .findFirst()
            .orElse(currentAgent);
    }
    
    private double calculateScore(double responseTime, double successRate, double quality) {
        // 简化的评分算法 - 可根据业务需求调整
        return (0.4 * (1 - normalize(responseTime, 0, 5000))) + 
               (0.3 * successRate) + 
               (0.3 * quality);
    }
    
    private double normalize(double value, double min, double max) {
        return Math.min(1, Math.max(0, (value - min) / (max - min)));
    }
}

// 使用示例
@Service
public class AdaptiveChatService {
    @Autowired
    private AiAgent adaptiveAgent;
    
    public String handleUserMessage(String message) {
        AgentRequest request = new AgentRequest(message, Map.of("user", "current"));
        return adaptiveAgent.execute(request).content();
    }
}

优点

自动优化
资源利用率高
适应不同场景

缺点

实现复杂
需要性能监控
切换可能不稳定

使用场景

多变的工作负载
服务质量要求高
如实时系统、高流量服务

使用心得

自适应代理帮助我们应对流量高峰，响应时间降低了30%。关键是要设置合理的评估指标和切换阈值。

8. 状态感知代理模式 (Stateful Agent Pattern)

介绍

状态感知代理维护对话状态，提供上下文相关的连续交互体验。

流程图

代码示例

@Service
@Scope(value = WebApplicationContext.SCOPE_SESSION, proxyMode = ScopedProxyMode.TARGET_CLASS)
public class StatefulAgent implements AiAgent {
    private final AiAgent delegate;
    private AgentState state;
    
    @Autowired
    public StatefulAgent(
        @Qualifier("delegateAgent") AiAgent delegate) {
        
        this.delegate = delegate;
        this.state = new AgentState();
    }
    
    @Override
    public AgentResponse execute(AgentRequest request) {
        // 更新状态
        updateState(request);
        
        // 丰富请求
        AgentRequest enrichedRequest = enrichRequest(request);
        
        // 执行
        AgentResponse response = delegate.execute(enrichedRequest);
        
        // 更新状态
        updateState(response);
        
        return response;
    }
    
    private void updateState(AgentRequest request) {
        state.setLastUserInput(request.prompt());
        state.incrementInteractionCount();
        
        // 分析情绪
        if (request.prompt().contains("!")) {
            state.setUserMood("excited");
        }
    }
    
    private void updateState(AgentResponse response) {
        state.setLastResponse(response.content());
    }
    
    private AgentRequest enrichRequest(AgentRequest original) {
        Map<String, Object> enrichedContext = new HashMap<>(original.context());
        enrichedContext.put("state", Map.of(
            "interactionCount", state.getInteractionCount(),
            "userMood", state.getUserMood(),
            "lastTopics", state.getLastTopics()
        ));
        
        return new AgentRequest(original.prompt(), enrichedContext);
    }
}

// 状态类
public class AgentState {
    private int interactionCount = 0;
    private String lastUserInput;
    private String lastResponse;
    private String userMood = "neutral";
    private List<String> lastTopics = new ArrayList<>();
    
    // getters and setters
}

// 使用示例
@RestController
@RequestMapping("/api/chat")
public class ChatController {
    @Autowired
    private StatefulAgent chatAgent;
    
    @PostMapping
    public ResponseEntity<String> chat(@RequestBody String message) {
        AgentRequest request = new AgentRequest(message, Map.of());
        AgentResponse response = chatAgent.execute(request);
        return ResponseEntity.ok(response.content());
    }
}

优点

上下文感知
对话连贯
个性化体验

缺点

状态管理复杂
内存消耗大
可能状态混乱

使用场景

对话系统
个性化服务
如聊天机器人、个人助理

使用心得

状态感知代理极大提升了用户体验评分。我们实现了状态压缩和定期清理机制，解决了内存增长问题。

综合比较表

模式	复杂度	响应时间	适用场景	资源需求
基础代理	低	快	简单任务	低
链式代理	中	中	流程化处理	中
路由代理	中	中	多领域任务	中
反思代理	高	慢	高质量输出	高
规划代理	高	慢	复杂问题	高
多代理协作	很高	很慢	综合任务	很高
自适应代理	高	快	动态环境	中-高
状态感知代理	中	中	连续交互	中