Spring AI + 自研DSL设计Multi-Agent协作机制基础：架构全景与核心抽象

作者：资深Java架构师
版本基准：Spring AI 1.0.0 GA / Spring AI Alibaba 1.0.0
适用场景：企业级智能体编排、审批流自动化、合同智能审查

---

一、为什么需要Multi-Agent架构？

2024年，大模型从"聊天工具"走向"自主执行"。单个LLM能回答问题，但无法独立完成"合同审查→法律风险识别→修订建议→人工确认→电子签章"这类有状态、多步骤、需要外部工具的复杂任务。

Multi-Agent（多智能体）架构的核心价值在于：分治。把一个复杂目标拆解成多个职责清晰的子Agent，每个Agent聚焦自己的领域，通过协作完成人工智能无法单独驾驭的企业级任务。

但问题随之而来：Agent如何协调？任务如何编排？状态如何管理？这正是本系列文章要解决的工程问题。

---

二、Spring AI核心抽象全景

Spring AI的设计哲学是面向接口编程，屏蔽底层差异。无论底层是OpenAI、通义千问还是本地Ollama，上层代码保持一致。

2.1 三大核心客户端

+--------------------------------------------------+
|              Spring AI 核心抽象层                 |
+--------------------------------------------------+
|                                                  |
|  ChatClient          EmbeddingModel    ImageModel |
|  (对话交互)           (文本向量化)      (图像生成)  |
|      |                    |                |     |
|  ChatModel           VectorStore       SpeechModel|
|  (模型驱动层)         (向量存储)        (语音合成) |
|                                                  |
+------------------+--+----------------------------+
                   |  |
        +----------+  +----------+
        |                        |
  OpenAI/Anthropic           通义/文心/讯飞
  Gemini/Bedrock             Ollama本地模型

ChatClient 是日常开发中用得最多的入口，它是一个流式Builder API：

@Configuration
public class AgentConfig {

    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder
            // 全局系统提示词
            .defaultSystem("你是一位专业的企业法务助手，擅长合同风险识别与条款分析。")
            // 全局Advisor链（拦截器模式）
            .defaultAdvisors(
                new MessageChatMemoryAdvisor(new InMemoryChatMemory()),
                new SimpleLoggerAdvisor()
            )
            // 全局工具注册
            .defaultTools("contractAnalyzer", "riskScorer")
            .build();
    }
}

调用时非常简洁：

// 同步调用
String result = chatClient.prompt()
    .user("分析这份合同第7条款的违约责任是否合理")
    .call()
    .content();

// 流式调用（SSE推送场景）
Flux<String> stream = chatClient.prompt()
    .user(userMessage)
    .stream()
    .content();

// 结构化输出（直接映射到Java对象）
ContractRisk risk = chatClient.prompt()
    .user(analysisPrompt)
    .call()
    .entity(ContractRisk.class);

EmbeddingModel 负责将文本转换为向量，是RAG和语义搜索的基础：

@Service
public class ContractIndexService {
    
    private final EmbeddingModel embeddingModel;
    private final VectorStore vectorStore;
    
    public void indexContract(String contractText) {
        // 文档分块
        List<Document> docs = new TokenTextSplitter(512, 50)
            .split(List.of(new Document(contractText)));
        // 批量向量化并存储
        vectorStore.add(docs);
    }
    
    public List<Document> searchSimilar(String query) {
        return vectorStore.similaritySearch(
            SearchRequest.query(query).withTopK(5).withSimilarityThreshold(0.75)
        );
    }
}

2.2 Advisor拦截器链

Spring AI引入了AOP风格的Advisor机制，在请求发出前后执行横切逻辑。这是构建Multi-Agent记忆、RAG、日志等能力的基础：

用户输入
   |
   v
+---------------------------+
| Advisor Chain (有序执行)   |
+---------------------------+
| 1. SimpleLoggerAdvisor    |  <- 日志记录
| 2. QuestionAnswerAdvisor  |  <- RAG知识检索
| 3. MessageChatMemoryAdvisor| <- 对话历史注入
| 4. SafeGuardAdvisor       |  <- 内容安全检查
+---------------------------+
   |
   v
  LLM调用
   |
   v
+---------------------------+
| 响应后处理                 |
+---------------------------+
| 4. SafeGuardAdvisor       |  <- 输出过滤
| 3. MessageChatMemoryAdvisor| <- 历史存储
| 2. QuestionAnswerAdvisor  |  <- 引用追踪
| 1. SimpleLoggerAdvisor    |  <- 响应日志
+---------------------------+
   |
   v
 最终响应

2.3 VectorStore与文档ETL

Spring AI提供了完整的文档处理流水线：

原始文档（PDF/Word/HTML）
    |
    v
+-------------------+
| DocumentReader    |  PdfReader / TextReader / JsonReader
+-------------------+
    |
    v
+-------------------+
| DocumentTransformer|  TextSplitter / TokenTextSplitter
+-------------------+  MetadataEnricher / KeywordEnricher
    |
    v
+-------------------+
| VectorStore.add() |  Redis / PgVector / Milvus / Chroma
+-------------------+  Pinecone / Weaviate / Qdrant
    |
    v
+-------------------+
| 索引完成，可供检索  |
+-------------------+

---

三、Spring AI Alibaba Graph框架

Spring AI本身提供了ChatClient、Tool Calling等基础能力，但缺乏工作流编排能力。Spring AI Alibaba通过Graph框架填补了这一空白。

3.1 Graph框架核心概念

Graph框架基于有向无环图（DAG），将Agent的执行过程建模为图中的节点和边：

+--------+     +----------+     +---------+     +--------+
| START  | --> | 信息提取  | --> | 风险分析 | --> | 人工审核|
+--------+     | Agent    |     | Agent   |     | (HITL)  |
               +----------+     +---------+     +--------+
                                     |               |
                               [风险>0.7]       [拒绝修改]
                                     |               |
                               +----------+    +----------+
                               | 人工审核  |    | 修订Agent|
                               +----------+    +----------+
                                     |               |
                                     +-------+-------+
                                             |
                                        +--------+
                                        |  END   |
                                        +--------+

核心API设计：

// 定义图状态（贯穿整个执行流的共享数据）
public class ContractReviewState extends AgentState {
    
    public ContractReviewState(Map<String, Object> initData) {
        super(initData);
    }
    
    public String getContractText() {
        return (String) data().get("contractText");
    }
    
    public List<RiskItem> getRiskItems() {
        return (List<RiskItem>) data().getOrDefault("riskItems", new ArrayList<>());
    }
    
    public double getRiskScore() {
        return (double) data().getOrDefault("riskScore", 0.0);
    }
}

// 构建执行图
StateGraph<ContractReviewState> graph = new StateGraph<>(ContractReviewState::new)
    .addNode("extractor",    new ExtractorAgent())
    .addNode("riskAnalyzer", new RiskAnalyzerAgent())
    .addNode("humanReview",  new HumanReviewNode())
    .addNode("revisionAgent",new RevisionAgent())
    .addEdge(START,           "extractor")
    .addEdge("extractor",     "riskAnalyzer")
    .addConditionalEdges("riskAnalyzer",
        state -> state.getRiskScore() > 0.7 ? "humanReview" : "revisionAgent",
        Map.of("humanReview", "humanReview", "revisionAgent", "revisionAgent"))
    .addEdge("humanReview",   "revisionAgent")
    .addEdge("revisionAgent", END);

// 编译并执行
CompiledGraph<ContractReviewState> compiled = graph.compile();
ContractReviewState result = compiled.invoke(
    Map.of("contractText", contractContent)
);

3.2 Spring AI Alibaba的DSL转换器

Spring AI Alibaba提供了与Dify低代码平台兼容的DSL转换能力，将Dify导出的YAML格式工作流直接转换为Spring AI Graph执行图，实现"低代码设计、高代码运行"：

Dify可视化设计器
      |
      | 导出YAML DSL
      v
+------------------+
| DslConverter     |  解析Dify DSL规范
+------------------+
      |
      | 转换
      v
+------------------+
| StateGraph构建    |  映射为Spring AI Graph节点/边
+------------------+
      |
      | 编译
      v
+------------------+
| CompiledGraph    |  可直接执行的运行时图
+------------------+

---

四、Multi-Agent四大支柱

在工程实践中，一个成熟的Multi-Agent系统必须解决四个核心问题：

+---------------------------------------------------+
|           Multi-Agent 四大支柱                    |
+-------------------+-------------------------------+
|                   |                               |
|  规划（Planning） |  记忆（Memory）               |
|  ・预定义计划      |  ・短期：对话上下文窗口        |
|  ・动态ReAct生成   |  ・长期：向量数据库持久化      |
|  ・层次分解        |  ・工作记忆：当前任务状态      |
|                   |                               |
+-------------------+-------------------------------+
|                   |                               |
|  工具使用（Tools）|  推理（Reasoning）            |
|  ・Function Call  |  ・ReAct推理框架              |
|  ・MCP协议集成    |  ・思维链（CoT）              |
|  ・工具权限控制   |  ・自我反思（Reflection）     |
|                   |                               |
+-------------------+-------------------------------+

4.1 规划支柱

规划解决"任务怎么拆解、步骤如何排序"的问题。有三种核心规划模式：

规划模式	适用场景	实现方式	优缺点
预定义计划	审批流、固定流程	DSL静态定义DAG	可预测性强，无法应对异常
动态ReAct	开放式任务	LLM自主推理生成步骤	灵活，但结果不可预测
层次分解	大型复杂项目	主Agent拆解→子Agent执行	可扩展，协调成本高

4.2 记忆支柱

记忆解决"Agent如何记住过去，利用历史知识"的问题：

// 短期记忆：InMemory对话历史
ChatMemory shortTermMemory = new InMemoryChatMemory();

// 长期记忆：向量数据库持久化
VectorStoreChatMemoryAdvisor longTermAdvisor = 
    new VectorStoreChatMemoryAdvisor(
        vectorStore,
        "user-001",    // 用户级隔离
        20             // 最近20轮历史
    );

4.3 工具使用支柱

工具赋予Agent操纵真实世界的能力：

@Component
public class ContractTools {
    
    @Tool(description = "解析PDF合同文件，提取结构化条款数据")
    public ContractStructure parsePdf(
        @ToolParam(description = "PDF文件路径或URL") String filePath
    ) {
        // 调用PDF解析服务
        return pdfParserService.parse(filePath);
    }
    
    @Tool(description = "查询历史合同数据库，搜索相似案例")
    public List<ContractCase> searchHistoricalCases(
        @ToolParam(description = "搜索关键词") String keywords,
        @ToolParam(description = "最大返回数量，默认5") int topK
    ) {
        return contractRepository.searchByKeywords(keywords, topK);
    }
    
    @Tool(description = "发起电子签章请求")
    public SignatureResult requestESign(
        @ToolParam(description = "合同ID") String contractId,
        @ToolParam(description = "签署人列表，逗号分隔") String signers
    ) {
        return eSignService.initiate(contractId, signers.split(","));
    }
}

4.4 推理引擎支柱

ReAct（Reasoning + Acting）框架是Agent推理的核心范式：

用户问题
    |
    v
+----------+
| Thought   |  分析当前状态，决定下一步行动
+----------+
    |
    v
+----------+
| Action    |  调用工具或生成输出
+----------+
    |
    v
+----------+
| Observe   |  观察工具执行结果
+----------+
    |
    v
+----------+
| 达到目标? |
+----------+
  是 |  否 |
     |     +---> 返回Thought继续迭代
     v
  最终答案

---

五、九种多智能体设计模式

5.1 模式总览

+----------------------------------------------------------+
|              九种多智能体设计模式                         |
+----------------------+-----------------------------------+
| 协调器/分发器模式     | 一个主Agent统筹分配任务          |
| 并行扇出/聚合模式     | 多Agent并行处理，结果汇总        |
| 层次分解模式          | 多层Agent树，逐级分解执行        |
| 生成器与评判器模式    | 一个生成，一个审查，迭代提升     |
| 迭代精进模式          | 单Agent反复自我优化到满足条件    |
| 顺序流水线模式        | Agent串行处理，结果逐步精化      |
| 人工介入模式          | 关键节点暂停，人工审核后继续     |
| 语义路由模式          | 根据输入内容智能路由到专属Agent  |
| 复合模式              | 以上模式的组合应用              |
+----------------------+-----------------------------------+

5.2 协调器/分发器模式（Orchestrator）

这是最常用的企业级模式。一个"主控Agent"负责理解任务全局，将子任务分发给专业Agent执行：

@Component
public class OrchestratorAgent {
    
    private final ChatClient orchestratorClient;
    private final Map<String, Agent> agentRegistry;
    
    public String execute(String complexTask) {
        // 主控Agent分解任务
        TaskPlan plan = orchestratorClient.prompt()
            .system("""
                你是任务协调器，负责将复杂任务分解为子任务并分配给合适的Agent。
                可用Agent：extractor（提取）、analyzer（分析）、writer（撰写）、reviewer（审核）
                请以JSON格式返回执行计划。
                """)
            .user(complexTask)
            .call()
            .entity(TaskPlan.class);
        
        // 按计划调度子Agent执行
        Map<String, String> results = new LinkedHashMap<>();
        for (SubTask subTask : plan.getTasks()) {
            Agent agent = agentRegistry.get(subTask.getAgentType());
            String result = agent.execute(subTask.getInstruction(), results);
            results.put(subTask.getId(), result);
        }
        
        return aggregateResults(results);
    }
}

5.3 并行扇出/聚合模式（Parallel Fan-out）

多个Agent同时处理不同部分，最后汇总结果：

// 合同多维度并行审查
public ContractReport parallelReview(String contractText) {
    
    CompletableFuture<LegalRisk> legalFuture = CompletableFuture.supplyAsync(
        () -> legalAgent.analyze(contractText)
    );
    CompletableFuture<FinancialRisk> financialFuture = CompletableFuture.supplyAsync(
        () -> financialAgent.analyze(contractText)
    );
    CompletableFuture<ComplianceRisk> complianceFuture = CompletableFuture.supplyAsync(
        () -> complianceAgent.analyze(contractText)
    );
    
    // 等待所有Agent完成，汇总报告
    return CompletableFuture.allOf(legalFuture, financialFuture, complianceFuture)
        .thenApply(v -> ContractReport.builder()
            .legalRisk(legalFuture.join())
            .financialRisk(financialFuture.join())
            .complianceRisk(complianceFuture.join())
            .build())
        .join();
}

5.4 生成器与评判器模式（Generator & Critic）

这是提升输出质量的关键模式，在合同修订场景中极为实用：

public String generateWithCritic(String originalClause) {
    String draft = generatorAgent.generate(originalClause);
    
    for (int iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
        // 评判器审查草稿
        CriticFeedback feedback = criticAgent.review(draft);
        
        if (feedback.getScore() >= 90) {
            return draft;  // 达到质量标准
        }
        
        // 根据反馈优化
        draft = generatorAgent.revise(draft, feedback.getSuggestions());
    }
    
    return draft;
}

5.5 人工介入模式（Human-in-the-Loop）

企业合规场景必须支持人工干预，这在后续章节将深入展开：

Agent执行中
    |
    | 检测到高风险或关键决策点
    v
+----------------+
| 暂停执行        |
| 保存图状态快照  |
+----------------+
    |
    | 通知人工审核员
    v
+----------------+
| 人工审核界面    |
| - 查看Agent输出 |
| - 批准/拒绝/修改|
+----------------+
    |
    | 人工决策结果
    v
+----------------+
| 恢复执行        |
| 加载状态快照    |
| 从断点继续      |
+----------------+

---

六、自研DSL的定位与价值

6.1 现有方案的局限

Spring AI Graph框架功能强大，但纯Java编程方式对业务人员不友好。每次修改工作流都需要重新编译部署。Dify等低代码平台虽然提供可视化设计，但DSL格式专有，与Spring AI的绑定深度不足。

自研DSL的核心价值：

+----------------------------------+
| 业务人员                          |
|  - 通过可视化编辑器设计流程        |
|  - 导出/修改YAML DSL             |
+----------------------------------+
             |
             | YAML DSL
             v
+----------------------------------+
| DSL解析引擎（自研）               |
|  - 词法/语法解析                  |
|  - AST生成                       |
|  - 验证与优化                     |
+----------------------------------+
             |
             | StateGraph对象
             v
+----------------------------------+
| Spring AI Alibaba Graph运行时    |
|  - 节点调度                       |
|  - 状态管理                       |
|  - 分布式执行                     |
+----------------------------------+

6.2 DSL设计原则

经过多个企业项目实践，我们总结出自研DSL的六大设计原则：

原则	说明	反例（规避）
可读性优先	业务人员能读懂每行含义	引入过多技术符号
最小惊讶	行为与字面意思一致	隐式默认值导致混淆
渐进复杂度	简单场景写法简单	强制声明所有可选项
类型安全	编译期/解析期发现错误	运行时才暴露类型不匹配
可组合性	子流程可被主流程引用	每个流程都是孤立的
版本可控	支持Git管理，可回滚	仅支持数据库存储

6.3 与Dify DSL的兼容策略

Dify是目前国内最流行的低代码AI平台，其DSL格式已成为事实标准。我们的自研DSL在结构上与Dify保持兼容，同时扩展了Spring AI特有的能力：

# 自研DSL示例（兼容Dify格式，扩展Spring AI特性）
workflow:
  name: "合同审查标准流程"
  version: "1.2.0"
  description: "适用于B2B标准合同的智能审查流程"
  
  # Spring AI特有：全局变量注入
  environment:
    model: "${spring.ai.openai.model:gpt-4o}"
    vectorStore: "contractKnowledgeBase"
    
  agents:
    - id: "extractor"
      name: "合同信息提取Agent"
      type: "llm"
      model: "${environment.model}"
      system_prompt: |
        你是合同信息提取专家，负责从合同文本中提取结构化信息。
        输出格式严格按照ContractStructure JSON Schema。
      tools:
        - "pdfParser"
        - "ocrService"
      output_schema: "ContractStructure"
      
    - id: "riskAnalyzer"
      name: "风险分析Agent"
      type: "llm"
      model: "${environment.model}"
      memory:
        type: "vector_store"
        store: "${environment.vectorStore}"
        top_k: 5
      tools:
        - "legalKnowledgeSearch"
        - "riskScorer"
        
    - id: "humanReview"
      name: "法务经理审核"
      type: "human_in_the_loop"
      # 动态断点：风险评分超阈值触发
      trigger_condition: "riskScore > 0.7"
      timeout: "P2D"  # ISO 8601 duration: 2天
      escalation:
        after: "P1D"  # 1天后升级
        to: "legalDirector"
        
    - id: "revisionAgent"
      name: "合同修订Agent"
      type: "llm"
      model: "${environment.model}"
      
  edges:
    - from: "extractor"
      to: "riskAnalyzer"
    - from: "riskAnalyzer"
      to: "humanReview"
      condition: "state.riskScore > 0.7"
    - from: "riskAnalyzer"
      to: "revisionAgent"
      condition: "state.riskScore <= 0.7"
    - from: "humanReview"
      to: "revisionAgent"
      condition: "humanDecision == 'approved_with_changes'"
    - from: "humanReview"
      to: "__end__"
      condition: "humanDecision == 'rejected'"
    - from: "revisionAgent"
      to: "__end__"

---

七、整体技术架构

将上述所有组件整合，整体架构如下：

+--------------------------------------------------------------+
|                    客户端层（Client Tier）                    |
|   Web UI / 微信小程序 / REST API / WebSocket / 企业内网       |
+-------------------------------+------------------------------+
                                |
+-------------------------------v------------------------------+
|                   API网关层（Gateway Tier）                  |
|   Spring Cloud Gateway + JWT认证 + 限流熔断                  |
+-------------------------------+------------------------------+
                                |
+-------------------------------v------------------------------+
|                 Multi-Agent编排层（Orchestration Tier）      |
|                                                              |
|  +------------------+  +-------------------+               |
|  | DSL解析引擎       |  | StateGraph执行引擎 |               |
|  | YAML → AST       |  | 节点调度/状态管理  |               |
|  +------------------+  +-------------------+               |
|           |                      |                          |
|  +------------------+  +-------------------+               |
|  | Agent注册中心     |  | 工具注册与发现    |               |
|  | 动态实例化        |  | MCP协议客户端    |               |
|  +------------------+  +-------------------+               |
+-------------------------------+------------------------------+
                                |
+-------------------------------v------------------------------+
|                Spring AI基础设施层（AI Infra Tier）           |
|                                                              |
|  ChatClient   EmbeddingModel   VectorStore   ChatMemory      |
|  QuestionAnswerAdvisor   MessageChatMemoryAdvisor            |
|                                                              |
+-------------------------------+------------------------------+
                                |
+-------------------------------v------------------------------+
|                    基础设施层（Infrastructure Tier）          |
|                                                              |
|  +----------+  +----------+  +----------+  +----------+    |
|  | LLM服务  |  |向量数据库 |  |消息队列  |  | 关系数据库|    |
|  | OpenAI   |  | Milvus   |  | Kafka    |  | PostgreSQL|   |
|  | 通义千问  |  | Pinecone |  | RabbitMQ |  | MySQL     |   |
|  +----------+  +----------+  +----------+  +----------+    |
+--------------------------------------------------------------+

---

八、技术选型决策

在真实企业项目落地时，技术选型会面临几个关键抉择：

8.1 LLM选型矩阵

维度	OpenAI GPT-4o	通义千问Max	文心一言4.0	本地Ollama
推理能力	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
中文理解	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐
数据安全	需合规评估	国内合规	国内合规	完全私有
调用成本	较高	中等	中等	硬件成本
工具调用	完善	完善	完善	部分支持
推荐场景	国际化业务	国内企业首选	金融/政务	安全敏感

8.2 向量数据库选型

数据库	适用规模	部署方式	核心优势
Milvus	亿级以上	独立集群	高性能，生产级
PgVector	千万级	PostgreSQL插件	运维简单，事务支持
Chroma	百万级	嵌入式/独立	开发友好
Redis	百万级	内存优先	极低延迟
Pinecone	无上限	云服务	全托管，免运维

推荐方案：开发环境用Chroma，生产环境据数据量选Milvus（亿级）或PgVector（千万级）。

---

九、本系列文章路线图

本文建立了整体架构认知。后续文章将逐层深入：

本文（已读）：架构全景与核心抽象
      |
      +-- 第2篇：规划层 - 如何设计任务分解与DAG编排
      |
      +-- 第3篇：记忆层 - 短期上下文 + 长期向量记忆
      |
      +-- 第4篇：工具层 - Function Calling + MCP协议集成
      |
      +-- 第5篇：人机协同层 - HITL六大模式
      |
      +-- 第6篇：DSL层 - 完整语法规范与解析器实现
      |
      +-- 第7篇：运行时 - 执行引擎与分布式调度
      |
      +-- 第8篇：落地实战 - 审批流 + 合同审查完整案例

---

十、总结

Multi-Agent架构不是把大模型API包一层就算完。真正的企业级Multi-Agent系统需要解决：状态管理（每个Agent的执行结果如何传递）、协调机制（谁来调度谁）、记忆设计（历史知识如何复用）、工具安全（外部调用如何管控）、人机边界（何时交给人类决策）。

Spring AI提供了坚实的基础设施，Spring AI Alibaba的Graph框架提供了编排能力，而我们的自研DSL则在二者之上搭建了"低代码可视化设计、高代码精确执行"的桥梁。

理解了这套架构全景，后续每一层的设计决策都有了清晰的坐标系。

---

关注博主，持续更新Spring AI企业实战系列
如有问题欢迎评论区讨论，技术细节见后续章节深入解析