Tsukino Dev Notes

Spring-AI-Alibaba

7分钟阅读

Spring AI Alibaba 架构解析

学习仓库：alibaba/spring-ai-alibaba
克隆路径：_refs/repos/spring-ai-alibaba/
学习日期：2026-05-08

1. 定位与概述

Spring AI Alibaba 是阿里巴巴官方推出的 Agentic AI 框架，构建在 Spring AI（v1.1.2）和 Spring Boot（v3.5.8）之上。

它不是简单地包装 Spring AI，而是提供了一个全新的 Agent 抽象层、持久化层和分布式协调层，使 Java 开发者能像 Python 开发者用 LangGraph 一样构建复杂 Agent 应用。

核心定位：生产级的 Agent、Workflow 和多智能体应用框架。

2. 三层架构

┌─────────────────────────────────────────┐
│  Platform 层：Admin + Studio            │  ← 可视化 IDE、可观测性、MCP 管理
├─────────────────────────────────────────┤
│  Framework 层：Agent Framework          │  ← ReactAgent、多 Agent 编排、Hooks
├─────────────────────────────────────────┤
│  Runtime 层：Graph Core                 │  ← StateGraph、CompiledGraph、Checkpoint
└─────────────────────────────────────────┘
层级模块用途
Platformspring-ai-alibaba-admin一站式可视化 Agent 平台
Platformspring-ai-alibaba-studio嵌入式 Agent 调试 UI
Frameworkspring-ai-alibaba-agent-frameworkReAct Agent、多 Agent 编排、Context Engineering
Runtimespring-ai-alibaba-graph-core类 LangGraph 的图执行引擎

依赖流向：agent-framework → graph-core → spring-ai-*

3. 核心特性（相比 vanilla Spring AI 的新增）

特性说明源码位置
ReactAgentReAct 循环 Agent，内置工具调用agent-framework/.../agent/ReactAgent.java
多 Agent 编排Sequential / Parallel / Loop / Routingagent-framework/.../agent/flow/agent/
Context Engineering上下文压缩、编辑、调用限制、重试、动态工具选择agent-framework/.../agent/hook/
Human-in-the-Loop可中断动作、人工审核 Hookagent-framework/.../hip/HumanInLoopHook.java
图工作流引擎StateGraph API，条件边、并行执行、子图graph-core/.../graph/StateGraph.java
A2A 通信Agent-to-Agent，Nacos 服务发现agent-framework/.../a2a/A2aRemoteAgent.java
持久化/CheckpointMemory / File / PG / MySQL / Oracle / Mongo / Redisgraph-core/.../checkpoint/savers/
图表生成导出 Mermaid / PlantUMLgraph-core/.../diagram/MermaidGenerator.java
Skills Registry类路径/文件系统技能注册，Prompt 增强graph-core/.../skills/registry/
Voice AgentWebSocket 实时语音 Agentexamples/voice-agent/

4. Agent Framework 详解

4.1 核心抽象

Agent (抽象基类：invoke / stream / schedule / getGraph)
  └── BaseAgent (通用属性：name, description, outputKey)
        └── ReactAgent (ReAct 实现)

4.2 ReactAgent 内部结构

ReactAgent 内部把自己编译成一个 StateGraph，包含：

  • AGENT_MODEL_NAME 节点：LLM 调用（AgentLlmNode）
  • AGENT_TOOL_NAME 节点：工具执行（AgentToolNode）
  • 条件边：根据 AssistantMessage.hasToolCalls() 在 model → tool → model 之间路由
  • Hook 节点：在 BEFORE_AGENT、AFTER_AGENT、BEFORE_MODEL、AFTER_MODEL 处注入

4.3 Hook 机制

Hook 实现 Hook 接口，可以声明 JumpTo 目的地（model、tool、end）动态改变控制流。

内置 Hook 类型：

  • HumanInTheLoopHook — 人工介入
  • ModelCallLimitHook — 模型调用次数限制
  • SummarizationHook — 上下文摘要压缩
  • SkillsAgentHook — 技能注入

4.4 Flow Agents（内置编排模式）

Agent模式
SequentialAgent链式串行执行子 Agent
ParallelAgent并发扇出，可配置 MergeStrategy
LoopAgent迭代执行，LoopStrategy: COUNT / CONDITION / JSON_ARRAY
LlmRoutingAgentLLM 动态路由到子 Agent

均通过 FlowGraphBuilder 构建 StateGraph 实现。

4.5 Interceptor 层

在 Hook 之下还有一层拦截器：

  • ModelInterceptor / ToolInterceptor
  • ContextEditingInterceptor — 上下文编辑
  • ModelRetryInterceptor — 模型重试
  • ToolRetryInterceptor — 工具重试
  • ToolSelectionInterceptor — 动态工具选择

5. Graph Core 详解

这是 Java 版 LangGraph 的实现：

类角色
StateGraph定义节点、边、条件边、子图
CompiledGraphStateGraph.compile(CompileConfig) 生成的可执行形式
OverAllState中央可序列化状态对象；键有 KeyStrategy（Append / Replace / Merge）
NodeOutput每步输出包装器
RunnableConfig运行时配置：threadId、metadata、checkpoint config、executor
InterruptableActionHuman-in-the-Loop 接口：interrupt() / interruptAfter()

Graph 特性

  • 条件路由：addConditionalEdges(source, condition, mappings)
  • 并行条件边：addParallelConditionalEdges(source, multiCommand, mappings)
  • 子图：addNode(id, CompiledGraph) 或 addNode(id, StateGraph)
  • 持久化：CompileConfig + SaverConfig 支持 memory/file/DB/Redis/Mongo
  • 流式：CompiledGraph.stream() 返回 Flux<NodeOutput>
  • 调度：CompiledGraph.schedule(ScheduleConfig) 支持 cron-like 调度
  • 状态序列化：Jackson-based + Java ObjectStream

6. 关键源码目录速查

Agent Framework

spring-ai-alibaba-agent-framework/.../graph/agent/
├── Agent.java, BaseAgent.java, ReactAgent.java
├── Builder.java, DefaultBuilder.java
├── node/
│   ├── AgentLlmNode.java          # LLM 调用节点
│   └── AgentToolNode.java         # 工具执行节点
├── flow/
│   ├── agent/
│   │   ├── SequentialAgent.java
│   │   ├── ParallelAgent.java
│   │   ├── LoopAgent.java
│   │   └── LlmRoutingAgent.java
│   ├── builder/FlowGraphBuilder.java
│   └── strategy/                  # 各模式的图构建策略
├── hook/
│   ├── AgentHook.java, ModelHook.java
│   ├── hip/HumanInTheLoopHook.java
│   ├── modelcalllimit/ModelCallLimitHook.java
│   ├── summarization/SummarizationHook.java
│   └── skills/SkillsAgentHook.java
├── interceptor/
│   ├── ModelInterceptor.java, ToolInterceptor.java
│   ├── contextediting/ContextEditingInterceptor.java
│   ├── modelretry/ModelRetryInterceptor.java
│   ├── toolretry/ToolRetryInterceptor.java
│   └── toolselection/ToolSelectionInterceptor.java
├── tool/
│   ├── AsyncToolCallback.java
│   └── multimodal/                # 多模态工具结果支持
└── a2a/
    ├── A2aRemoteAgent.java
    └── A2aNodeActionWithConfig.java

Graph Core

spring-ai-alibaba-graph-core/.../graph/
├── StateGraph.java
├── CompiledGraph.java
├── OverAllState.java, OverAllStateBuilder.java
├── RunnableConfig.java
├── action/                          # Node/Edge action 接口
├── checkpoint/
│   ├── BaseCheckpointSaver.java
│   └── savers/                    # Memory, File, PG, MySQL, Oracle, Mongo, Redis
├── state/                           # Channel, Reducer, AppenderChannel
├── serializer/                      # Jackson & ObjectStream
├── observation/                     # Micrometer/OpenTelemetry
├── diagram/
│   ├── MermaidGenerator.java
│   └── PlantUMLGenerator.java
└── store/                           # Key-value store 抽象

7. 示例与 Starter

Examples（examples/）

示例说明
chatbot/基础聊天机器人 + 嵌入式 Studio UI
multiagent-patterns/丰富的多 Agent 模式：handoff、pipeline、routing、skills、subagent、supervisor、workflow
multimodal/图像/音频输入的 ReactAgent
voice-agent/WebSocket 实时语音 Agent
deepresearch/深度研究 Agent（图工作流）
agentscope/AgentScope handoff 集成

Spring Boot Starters

  • spring-ai-alibaba-starter-a2a-nacos — A2A + Nacos 服务发现
  • spring-ai-alibaba-starter-config-nacos — Nacos 动态配置
  • spring-ai-alibaba-starter-graph-observation — 图可观测性
  • spring-ai-alibaba-starter-builtin-nodes — 预置工作流节点
  • spring-ai-alibaba-starter-agentscope — AgentScope 集成

8. 与 Spring AI 的关系

维度Vanilla Spring AISpring AI Alibaba
Agent 抽象ChatClient、ChatModel、Advisors完整的 ReactAgent，ReAct 循环、Hooks、拦截器
多 Agent手动编排内置 SequentialAgent、ParallelAgent、LoopAgent、RoutingAgent
状态执行简单 Memory repositoriesStateGraph + OverAllState + Checkpoint + 子图
工作流引擎无原生支持类 LangGraph 的图 API
人工介入无内置InterruptableAction、HumanInTheLoopHook
上下文工程基础上下文压缩、编辑、调用限制、重试、PII 检测
A2A / 分布式无Nacos 集成的 A2A
可视化平台无Admin（全平台）+ Studio（嵌入式调试）
云原生通用DashScope/Tongyi 深度集成

一句话总结：Spring AI 提供原子能力（ChatModel、ToolCallback、Advisors、VectorStore），Spring AI Alibaba 在这些原子上构建了一个完整的 Agent 操作系统。

9. 学习路径建议

  1. 入门：跑通 examples/chatbot/，理解 ReactAgent 的基本用法
  2. 进阶：阅读 ReactAgent 源码，看它如何把自身编译成 StateGraph
  3. 深入：研究 multiagent-patterns/ 示例，理解各种编排模式
  4. 底层：看 graph-core 的 StateGraph 和 CompiledGraph，理解图引擎原理
  5. 对比：与 LangGraph Python 对比，理解设计差异

最近更新

关系图谱

反向链接