简介

    saa是java的ai agent框架，本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理，不仅可以指导agent的开发，更可以改造框架，增加新特性

系列内容：

系列(一) 架构  完成

系列(三) 调用

     I 工具  完成

     II MCP

     -1 MCP MCP能力，工具，资源，Prompts，sampling，。。。；springboot自动配置  完成

     -2 分布式 MCP 

     -3 MCP security

     III skills  完成

系列(四) RAG  完成

     I 知识库，文档读取，分块；嵌入，向量store

     II 检索，增强生成，模块化；混合检索，融合重排

系列(二) 模型 model模型 完成

         chat模型，消息，提示词，结构化输出，记忆

         chat client，advisor组件

系列(五) graph  图结构，节点和边；StateGraph

                         推理框架graph映射示例: ReAct，relection，CoT，Plan-And-Execute

CompiledGraph；图执行，状态和存储

系列(六) agent及组件 ReactAgent，钩子和拦截器，记忆，结构化输出，Human-in-the-loop

              分布式agent

系列(七) MAS

        I 多agent graph，flow agent; handoffs模式，toolcalling模式；

        II 分布式agent，graph检查点和容错

系列(八) I 观测：观测组件(micrometer-observation)，观测点：chatClient，chat模型，工具(tracing)

        II 模型评估

系列(九) agent管理平台(admin) agent发现(a2a)，agent列表，提示词管理，会话管理，skill管理，MCP管理；chat；评估；观测

本文分析状态graph，静态结构，图构建

based spring ai alibaba v1.1.2.2

关键词

缩写

spring ai 缩写sa

spring ai alibaba  本文缩写saa

参考资料

概览 | Spring AI Alibaba  spring ai alibaba官网文档

https://docs.spring.io/spring-ai/reference/index.html  spring ai官方文档

SAA概览

上图是saa原理源码分析场景视图，每个包对应着saa/sa组件或特性，是本文分析的目录

model  大模型的封装，模型包括Chat，嵌入，audio，image等类型，其中chat模型包括，advisor组件，提示词，记忆等

agent/graph  agent/多agent和图紧密相关，可以认为agent是一种既定的”图”形，开发人员可以使用graph底层api直接构建graph，使用agent获得既定的图形，简化agent的开发

外部调用(calling)  工具，MCP，skills

RAG  检索增强生成

MAS  A2A，FlowAgent，子agnet，agent Tool；agent 集群

studio 简易的agent管理工具，嵌入到agent，带有agent面板，列表agent；提供chat界面，用于调试agent，是开发agent的便利工具

admin 管理台， agent的发布，列表，管理，执行；提示词工程，评估和数据集，观测

graph

       graph-core是saa的图组件，以图的结构，节点，边构建处理流程，节点执行动作，边决定下一个节点，对应的，agentic是另一种模式，整个流程大模型自主编排，agentic省心省事，但同时agentic容易失控，纯粹看大模型心情，因此，目前比较好的方案，主体使用flowable，需要的时候使用agentic节点。

       spring ai alibaba，agent的推理框架映射成graph，多agent角色也映射成graph，以图的节点承载执行逻辑，边决定下一节点，支持检查点保存执行状态，实现执行的暂停和恢复应

状态图

本节分析状态图(StateGraph)的结构

上图是图结构类图，展示了一个用于构建复杂、有状态 AI 应用（如 Agent 或工作流）的框架结构。核心思想是通过定义节点（Nodes）、边（Edges）和状态（State）来编排执行流程。

StateGraph  C位，是整个系统的中枢，它负责管理和编排整个执行流程，标准的图结构，节点和边组成

节点 (Nodes)

• Node: 节点接口/类。
  • 动作工厂: 每个节点关联一个ActionFactory，该工厂负责创建具体的异步动作 AsyncNodeActionWithConfig，动作是节点执行逻辑。

AsyncNodeActionWithConfig是BiFunction ，若设置action类型是

NodeActionWithConfig，AsyncNodeAction等function类型，使用AsyncNodeActionWithConfig统一适配

• SubStateGraphNode: 一种特殊的节点，它本身也包含一个 subGraph (子状态图)。这允许创建嵌套的、模块化的复杂工作流。编译图(CompiledGraph )也可以作为子节点，实际是一样，从编译图获取状态图

边 (Edges)

• Edge: 图的一条边
  • 目标 (targets): 节点一个或多个出边， EdgeValue
• EdgeValue: 封装了边的信息，二选一
  • 字符串: 节点的id，简单路由，指向一个节点
  • EdgeCondition: 条件
• EdgeCondition: 条件，决定了在特定状态下，流程是否应该沿着这条边继续。
  • 动作 (acton): 条件的判断逻辑，支持单值和多值返回
    • action::AsyncCommandAction: 返回单个命令 (action::Command)。
    • action::AsyncMultiCommandAction: 返回多个命令 (action::MultiCommand)，实现并行或分支路由。
  • 映射关系 (mappings): 条件和节点的映射关系集，例如，X:_x_， EdgeCondition返回‘X’，边走’_x_’节点

      设计有点晦涩难懂，但提供灵活的边设计，节点可有多出边，出边可以简单的无条件激活，可以有条件的激活(Command)，也可以多个出边成一组，根据条件并行激活（MultiCommand）

OverAllState: 全局状态，节点的动作，边的动作都可使用

StateSerializer 负责OverAllState 的序列化，对象后可保存

AgentStateFactory<T>:  agent状态工程，Function类型，agent状态其实就是OverAllState，因此，T就是OverAllState类型， 其实现是OverAllState::new

KeyStrategyFactory  KeyStrategy工厂，可以理解位provider，提供KeyStrategy

KeyStrategy 定义了state的更改策略，覆盖、追加、合并等

推理框架

        推理框架是Agent 的 “认知架构” 或 “思维方式”。它定义了 Agent 如何思考、规划、决策以及适应环境，是一个结构化的流程，常用的 ReAct、CoT、Reflection、Plan-and-Execute。可以认为,

agent = 推理框架 + 上下文 + 工具

其中上下文，包括系统提示词，工具说明，对话记忆，用户提示词等，可以看到，agent的不可缺少是推理框架，其他可以根据用户任务设置，agent封装了特定框架，在saa，推理框架映射成特定”图”型。

上节分析了图模型，下面分析agent的推理框架映射成graph

Relection

Reflection（反思）是一种 AI 自我评估、优化自身输出的范式。Reflection 聚焦于内部自我批判和迭代改进——让模型扮演"生成者"和"评审者"双重角色，通过多轮自我优化提升输出质量

Reflection循环一般包含：

• 生成阶段 (Generation)：模型根据指令生成初始输出
• 反思阶段 (Reflection)：模型（或另一个模型实例）对输出进行批判性评估
• 优化阶段 (Refinement)：回到同生成阶段，基于反思结果改进输出
• 迭代控制：设置最大轮次，直到质量达标或达到上限

saa的示例包包括一个Reflection示例，看看怎样构建反思框架的图

上图ReflectAgent构建图

上图是对应的流程图，原来的generate节点名称是“graph”，改成“generate”,可以看到边的条件，前面的generateCount，”生成”的计数，超过最大迭代stop；后面的检查生成的质量，使用打分，给出评价，决定是否stop。

ReAct

ReAct（Reasoning + Acting）是一个“思考 → 行动 → 观察 → 再思考”的闭环流程。它让大语言模型（LLM）不再是只靠内部知识“空想”，而是能在需要时调用外部工具（Tool）获取信息，再基于这些新信息进行下一步推理，直到最终完成任务。

saa实现了react示例，用ReactAgent实现，带天气查询工具，回答天气相关的问题，如，查询天气并推荐活动

下面以saa graph包的react示例分析

上图ReactAgent生成的图，注意到没有观察节点，ReactAgent model节点和观察节点合并，工具返回到model节点，第二轮模型调用同时实现观察的职能，有3点要注意：

1 InstructionAgentHook节点是内置的hook节点，处理指令设置

2 model节点到工具节点的条件有返回model的选项，这个是留给afterModel hook，应该是设计人员给hook实现的一个后门

3 上图工具节点有到End的选项，但条件逻辑，下图

系列-工具介绍过，工具returnDirect设置，true直接返回应用，false 返回给大模型，这里显然要返回给大模型观察，代码有点纠结，无视了ReturnDirect，但破坏了工具的设置

上图，增加model节点，即，负责思考的节点，接着增加工具节点，执行思考节点需要执行的行动

上图两个关键边，model节点到工具节点，工具节点到model节点边条件设置，这里重点分析图构建，不深入分析里面的逻辑，在系列-agent深入分析

注意，条件与节点映射集，在没有hook节点的情况，loopExitNode，loopEntryNode都是model节点，exitNode是End节点

Cot

CoT 思维链（Chain of Though） 是一种提示工程（Prompt Engineering）技术，通过引导大语言模型（LLM）在给出最终答案之前，先生成一系列中间推理步骤，从而显著提升模型在复杂逻辑、数学计算和常识推理任务中的表现。

下面以示例分析Cot

上图Cot生成的图，带自我反思与修正

上图是Cot图构建

plan and execute

Plan-and-Execute（规划与执行） 是一种专为解决复杂、多步骤任务而设计的 AI Agent 架构范式，其核心思想是将“思考”与“行动”解耦，先由规划器制定全局路线图，再由执行器按步骤逐一落实，从而避免传统 ReAct 模式在长任务中容易出现的逻辑跑偏、无限循环和上下文爆炸等问题。

下面以示例分析Plan and Execute

上图Plan and Execute生成的图

上图是PE图构建

总结：

Reflection  适用做好一件事，如，写论文，反复打磨(论文)，直到达到要求

ReAct  适用做完一件事，思考确定下一步，动作，观察，再思考确定下一步，一步步完成事情

多agent图

单个agent推理框架以图结构支持，多agent的拓扑也是图支持，本节以flow agent的并行agent为例分析多agent图映射

首先，介绍一下flow agent的构建，作为分析图构建的前置知识

上图flow agent图构建类图，每个flow有自己的构建策略，抽象策略负责公用部分，START节点，END节点，还有hook节点，hook作为节点，本文分析聚焦多agent拓扑图结构，不涉及hook部分

ParallelAgent

并行执行模式，多个Agent同时处理相同的输入，结果被收集合并输出

流程：

1. 输入同时发送给所有Agent
2. 所有Agent并行处理
3. 结果被合并成单一输出

下面分析ParallelAgent的图构建

上图是并行agent的图构建逻辑1of2

1. 增加聚合节点，多个并行节点结果合并为一个结果
2. 并行start节点

上图是并行agent的图构建2of2

4  并行的子agent作为节点，子agent的内部graph作为子图，子agent的节点向前连接并行start节点，向后连接聚合节点
5/6 聚合节点连接END节点

上图是并行flow生成的图，内部是ReactAgent的图，flow的子图

总结：Spring AI Alibaba Graph 作为一个低级别的工作流和多智能体编排框架，其核心优势在于将“单智能体的深度推理”与“多智能体的宏观拓扑调度”进行了完美的融合。它既提供了支撑 Agent 思考与执行的微观节点能力，又构建了宏观的多 Agent 协作图结构。agentic模式下，图结构可以记录大模型决策，观测大模型整个决策，分布式agent，图也作为执行图共享，集群的agent一张图下协调工作。