Spring AI Alibaba 项目源码学习（六）-Agent Framework 工作原理与使用

技术分享 4个月前 (11-15) 0 999+

Agent Framework 工作原理与使用

请关注微信公众号：阿呆-bot

概述

Spring AI Alibaba Agent Framework 是一个基于 ReAct（Reasoning + Acting）模式的智能 Agent 开发框架，为 Java 开发者提供了快速构建、编排和部署 AI Agent 的能力。该框架构建在 Graph Runtime 之上，支持多 Agent 编排、上下文工程等核心特性。

整体架构

Agent Framework 采用分层架构设计：

Agent 基类层：Agent 提供所有 Agent 的通用能力
BaseAgent 抽象层：BaseAgent 提供输入输出管理和节点转换能力
具体实现层：
- ReactAgent：实现 ReAct 模式的单 Agent
- FlowAgent 系列：实现多 Agent 编排（Sequential、Parallel、Loop、Routing）
- A2aRemoteAgent：实现 Agent-to-Agent 远程调用
扩展机制层：
- Hook：在 Agent 执行的关键点插入自定义逻辑
- Interceptor：拦截和修改模型调用、工具调用
- Tool：扩展 Agent 的能力

工作原理

ReAct 模式

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

Reasoning（推理）：LLM 节点分析当前状态，决定下一步行动
Acting（行动）：根据决策执行工具调用
Observing（观察）：收集工具执行结果，更新状态
循环：重复上述过程，直到达到终止条件

Graph 执行流程

Agent Framework 基于 Graph Runtime 执行：

public abstract class Agent {  	/** The agent's name. Must be a unique identifier within the graph. */ 	protected String name;  	/** 	 * One line description about the agent's capability. The system can use this for 	 * decision-making when delegating control to different agents. 	 */ 	protected String description;  	protected CompileConfig compileConfig;  	protected volatile CompiledGraph compiledGraph;  	protected volatile StateGraph graph;  	/** 	 * Protected constructor for initializing all base agent properties. 	 * @param name the unique name of the agent 	 * @param description the description of the agent's capability 	 */ 	protected Agent(String name, String description) throws GraphStateException { 		this.name = name; 		this.description = description; 	}  	/** 	 * Default protected constructor for subclasses that need to initialize properties 	 * differently. 	 */ 	protected Agent() { 		// Allow subclasses to initialize properties through other means 	}  	/** 	 * Gets the agent's unique name. 	 * @return the unique name of the agent. 	 */ 	public String name() { 		return name; 	}  	/** 	 * Gets the one-line description of the agent's capability. 	 * @return the description of the agent. 	 */ 	public String description() { 		return description; 	}  	public StateGraph getGraph() { 		if (this.graph == null) { 			try { 				this.graph = initGraph(); 			} 			catch (GraphStateException e) { 				throw new RuntimeException(e); 			} 		} 		return this.graph; 	}  	public synchronized CompiledGraph getAndCompileGraph() { 		if (compiledGraph != null) { 			return compiledGraph; 		}  		StateGraph graph = getGraph(); 		try { 			if (this.compileConfig == null) { 				this.compiledGraph = graph.compile(); 			} 			else { 				this.compiledGraph = graph.compile(this.compileConfig); 			} 		} catch (GraphStateException e) { 			throw new RuntimeException(e); 		} 		return this.compiledGraph; 	}

执行流程：

初始化 Graph：调用 initGraph() 创建状态图
编译 Graph：将状态图编译为可执行的 CompiledGraph
执行 Graph：通过 invoke() 或 stream() 方法执行
状态管理：使用 OverAllState 在节点间传递数据

使用示例

ReactAgent 基本使用

// 1. 创建 ReactAgent Builder ReactAgent agent = ReactAgent.builder()     .name("assistant")     .description("A helpful assistant")     .instruction("You are a helpful assistant.")     .chatModel(chatModel)  // 设置 LLM 模型     .tools(tools)          // 设置工具列表     .maxIterations(10)     // 设置最大迭代次数     .build();  // 2. 同步调用 AssistantMessage response = agent.call("What's the weather today?");  // 3. 流式调用 Flux<NodeOutput> stream = agent.stream("Tell me a story"); stream.subscribe(output -> {     // 处理流式输出 });

FlowAgent 使用示例

// 1. 创建 SequentialAgent（顺序执行） SequentialAgent sequentialAgent = SequentialAgent.builder()     .name("sequential")     .agents(agent1, agent2, agent3)     .build();  // 2. 创建 ParallelAgent（并行执行） ParallelAgent parallelAgent = ParallelAgent.builder()     .name("parallel")     .agents(agent1, agent2, agent3)     .build();  // 3. 创建 LoopAgent（循环执行） LoopAgent loopAgent = LoopAgent.builder()     .name("loop")     .agent(agent)     .loopStrategy(new CountLoopStrategy(5))     .build();  // 4. 创建 RoutingAgent（路由选择） LlmRoutingAgent routingAgent = LlmRoutingAgent.builder()     .name("routing")     .agents(agent1, agent2, agent3)     .chatModel(chatModel)     .build();

Hook 使用示例

// 创建 HumanInTheLoop Hook HumanInTheLoopHook hook = HumanInTheLoopHook.builder()     .name("human-feedback")     .interactionHandler(new ConsoleInteractionHandler())     .build();  // 添加到 ReactAgent ReactAgent agent = ReactAgent.builder()     .name("assistant")     .chatModel(chatModel)     .tools(tools)     .hooks(hook)  // 添加 Hook     .build();

Interceptor 使用示例

// 创建 Model Fallback Interceptor ModelFallbackInterceptor fallbackInterceptor = ModelFallbackInterceptor.builder()     .primaryModel(primaryModel)     .fallbackModel(fallbackModel)     .build();  // 创建 Tool Retry Interceptor ToolRetryInterceptor retryInterceptor = ToolRetryInterceptor.builder()     .maxRetries(3)     .build();  // 添加到 ReactAgent ReactAgent agent = ReactAgent.builder()     .name("assistant")     .chatModel(chatModel)     .tools(tools)     .modelInterceptors(fallbackInterceptor)  // 添加 Model Interceptor     .toolInterceptors(retryInterceptor)     // 添加 Tool Interceptor     .build();

Tool 扩展示例

// 1. 实现自定义 Tool @Bean public Function<String, String> weatherTool() {     return (location) -> {         // 调用天气 API         return "Sunny, 25°C";     }; }  // 2. 注册为 Spring AI Tool @Bean public Tool weatherToolBean() {     return Tool.builder()         .name("get_weather")         .description("Get weather for a location")         .function("weatherTool")         .build(); }  // 3. 在 ReactAgent 中使用 ReactAgent agent = ReactAgent.builder()     .name("assistant")     .chatModel(chatModel)     .tools(weatherToolBean)  // 使用自定义工具     .build();