一、本章介绍

对 AI Agent 智能体脚手架开展系统性的技术选型与整体工程架构设计。

该阶段本质上类似于新项目立项时的前期技术论证过程：首先对目标能力进行拆解，梳理实现路径与关键实现流程，明确各环节所依赖的核心技术组件与支撑能力；同时针对存在不确定性的技术点开展 PoC（概念验证）与样例测试，以验证可行性与性能边界。在完成技术能力盘点与风险评估后，形成完整的技术架构蓝图，并输出结构化、可落地的详细实施方案，为后续工程建设提供明确的设计依据与实施指引。

学编程别只停留在“跟着视频照抄代码”，要尽快转到“理解业务与功能、看代码改动（git diff）自己实现、做项目沉淀”，最后再用 AI 工具结合项目和简历做高强度面试训练，从而真正提升能力并拿到 offer。

二、架构设计

如图，整体简要架构设计；

智能体架构设计.drawio

1. 基础基础

• jdk 17+
• Maven 3.8.x
• SpringBoot 3.4.3
• Google ADK 0.4.0 ~ 0.5.0
• Spring AI 1.1.0-M3 ~ 2.0.0-M2（配和 SpringBoot 要升级到 4.1.0-M1）

2. 脚手架

我们所建设的项目本质上是一套脚手架工程，目标是让用户通过命令行或配置化方式，快速生成同类型的智能体项目工程。可以将其理解为“模板化复制”，但由于实际落地时工程中的项目名称、包名、模块标识等都会随用户需求发生变化，若完全依赖人工复制粘贴并逐项替换，不仅工作量大、效率低，还容易引入遗漏与错误。

因此，需要提供一套标准化脚手架能力，使用户能够通过一键初始化（或一次命令执行）完成智能体项目的自动创建与关键变量替换，快速获得可运行、可扩展、符合规范的项目骨架，从而显著降低项目启动成本并提升交付效率。


• 这里我们会选择 maven-archetype-plugin 插件方案，构建 AI Agent 智能体脚手架。

3. AI + AI Agent 框架

开发 AI 的实现路径多种多样，AI Agent 智能体的落地方案也并不唯一。例如在 AI 能力接口对接层面，既可以自研 SDK 来完成模型调用与能力封装，也可以直接采用 Spring AI、LangChain4j 等成熟框架，以获得更标准化的模型接入与组件化能力。

在 AI Agent 的流程与工作流编排层面，同样既可以选择自研实现以满足个性化需求，也可以基于现成的智能体框架与组件快速落地，例如采用 Google ADK 来承载智能体的工作流组织、能力编排与运行机制，从而降低工程复杂度并提升交付效率。

4. 模块编排

在整个 AI Agent 的实现过程中，往往存在一条完整且连续的装配与运行链路，包括：完成 AI 接口接入、实例化并管理所选模型、挂载/注册 MCP 工具能力、以及进一步进行智能体工作流的编排与执行。为了让这条链路具备更强的可治理性与可扩展性，我们不能把流程控制堆砌成大量的 if ··· else 分支，而应通过设计模式将“行为逻辑”拆分并沉淀到各个独立实现类中，再通过类与类之间的调度机制进行有序衔接，从而实现低耦合、可插拔、可演进的流程编排体系。

基于上述诉求，这里需要引入决策树/规则树模型，其核心思想可对应到设计模式中的组合模式（Composite Pattern），以树状结构表达复杂决策路径，并支持节点级别的复用、扩展与替换。之所以采用该类框架，是因为本场景并不一定需要引入更重型的规则引擎（如 Drools、Easy Rules 等——可按需检索与评估），而更适合使用一种轻量、易编码、可嵌入工程的决策树模型，在保证表达能力的同时显著降低引入成本与使用复杂度。

5. 工程框架

采用 DDD 领域驱动设计 + 六边形架构进行系统开发。

因为 DDD 架构中的四色建模方法能够更高效地梳理业务场景、识别核心概念与边界，从而更准确地抽象出贴合需求的领域模型。同时，DDD 常配套的六边形架构（Ports & Adapters）在工程层面能够对微服务能力单元进行更清晰、合理的拆分与隔离。例如：HTTP、Redis、MySQL 等外部依赖都可以通过适配器形式纳入各自明确的分层规划；并且通过端口接口实现对领域层的依赖倒置（类似思想在 Spring 源码中大量体现），使领域服务不直接依赖具体实现。这样，当我们在领域模块中编写服务时，可以更专注于模块内的高内聚业务能力构建，减少基础设施细节对领域逻辑的干扰。

基于该架构，我们既可以沉淀一套面向 AI Agent 智能体模型的构建与使用的领域服务（例如：智能体装配、运行编排、工具接入、配置解析等），也可以预留清晰的扩展领域边界，让使用者在独立的业务领域中实现自身诉求，并以最小成本与智能体能力进行组合与集成。

三、详细设计

1. 流程设计

智能体设计-详细流程设计.drawio

• 首先，从用户操作视角来看，用户通过 AI Agent 智能体脚手架一键初始化项目工程；随后在工程内通过 **YML 配置文件（支持多个）**声明并装配自己的智能体服务。同时，用户也可以在约定的业务模块中编写与场景相关的业务逻辑，实现“配置装配 + 业务扩展”并行推进的开发方式。

• 之后，当项目进入启动阶段，系统会在启动过程中自动扫描并加载对应的 YML 配置，完成智能体实例的解析、装配与初始化，最终生成可运行的 AI Agent 智能体对象。随后将智能体以 Bean 形式注册并注入到 Spring 容器中，确保后续调用具备统一的生命周期管理、依赖注入与治理能力。

• 然后，用户即可进入对话交互阶段。在对话请求到来时，系统会根据请求上下文（如场景标识、路由策略、会话绑定等）选择匹配的目标智能体，并将对话输入路由至对应的 AI Agent 执行，从而完成面向特定场景的智能体服务调用与响应输出。

2. YML 设计

ai:
  agent:
    config:
      tables:
        parallel_research_app:
          app-name: ResearchAndSynthesisPipeline
          agent:
            agent-id: 100002
            agent-name: 测试智能体02
            agent-desc: 并行研究并汇总的智能体管道
          module:
            ai-api:
              base-url: https://api1.oaipro.com
              api-key: sk-Sp2jx3yeq7x7HJ663bDc9bF0D34b4f609f8******
              completions-path: v1/chat/completions
              embeddings-path: v1/embeddings
            chat-model:
              model: gpt-4.1
              tool-mcp-list:
                - sse:
                    name: baidu-search
                    base-uri: https://appbuilder.baidu.com/v2/ai_search/mcp/
                    sse-endpoint: sse?api_key=bce-v3/ALTAK-3zODLb9qHozIftQlGwez5/2696e92781f5bf1ba1870e***申请key；https://console.bce.baidu.com/iam/?_=1753597622044#/iam/apikey/list
                    request-timeout: 5000
            agents:
              - name: RenewableEnergyResearcher
                description: Researches renewable energy sources.
                instruction: |
                  You are an AI Research Assistant specializing in energy.
                  Research the latest advancements in 'renewable energy sources'.
                  Use the Google Search tool provided.
                  Summarize your key findings concisely (1-2 sentences).
                  Output *only* the summary.
                output-key: renewable_energy_result
              - name: EVResearcher
                description: Researches electric vehicle technology.
                instruction: |
                  You are an AI Research Assistant specializing in transportation.
                  Research the latest developments in 'electric vehicle technology'.
                  Use the Google Search tool provided.
                  Summarize your key findings concisely (1-2 sentences).
                  Output *only* the summary.
                output-key: ev_technology_result
              - name: CarbonCaptureResearcher
                description: Researches carbon capture methods.
                instruction: |
                  You are an AI Research Assistant specializing in climate solutions.
                  Research the current state of 'carbon capture methods'.
                  Use the Google Search tool provided.
                  Summarize your key findings concisely (1-2 sentences).
                  Output *only* the summary.
                output-key: carbon_capture_result
              - name: SynthesisAgent
                description: Combines research findings into a structured report.
                instruction: |
                  You are an AI Assistant responsible for combining research findings into a structured report.
                  Your primary task is to synthesize the following research summaries, clearly attributing findings to their source areas. Structure your response using headings for each topic. Ensure the report is coherent and integrates the key points smoothly.
                  **Crucially: Your entire response MUST be grounded *exclusively* on the information provided in the 'Input Summaries' below. Do NOT add any external knowledge, facts, or details not present in these specific summaries.**** Input Summaries:**

                  *   **RenewableEnergy:** 
                      {renewable_energy_result}

                  *   **ElectricVehicles:** 
                      {ev_technology_result}

                  *   **CarbonCapture:** 
                      {carbon_capture_result}

                  **OutputFormat:** 

                  ## Summary of Recent Sustainable Technology Advancements

                  ### Renewable Energy Findings
                  (Based on RenewableEnergyResearcher's findings)
                  [Synthesize and elaborate *only* on the renewable energy input summary provided above.]

                  ### Electric Vehicle Findings
                  (Based on EVResearcher's findings)
                  [Synthesize and elaborate *only* on the EV input summary provided above.]

                  ### Carbon Capture Findings
                  (Based on CarbonCaptureResearcher's findings)
                  [Synthesize and elaborate *only* on the carbon capture input summary provided above.]

                  ### Overall Conclusion
                  [Provide a brief (1-2 sentence) concluding statement that connects *only* the findings presented above.]

                  Output *only* the structured report following this format. Do not include introductory or concluding phrases outside this structure, and strictly adhere to using only the provided input summary content.
            agent-workflows:
              - type: parallel
                name: ParallelWebResearchAgent
                description: Runs multiple research agents in parallel to gather information.
                sub-agents:
                  - RenewableEnergyResearcher
                  - EVResearcher
                  - CarbonCaptureResearcher
              - type: sequential
                name: ResearchAndSynthesisPipeline
                description: Coordinates parallel research and synthesizes the results.
                sub-agents:
                  - ParallelWebResearchAgent
                  - SynthesisAgent

• 以上内容展示的是一个智能体在构建过程中所涉及的核心配置项，包括 ai-api、chat-model、agents、agent-workflows 等配置的使用方式。当前阶段无需对每一项配置细节展开深入分析，只需先理解：我们可以通过这类 YML 文件 对一个智能体的整体配置进行统一管理。换句话说，上述整套配置信息，本质上是将基于 Spring AI + Google ADK 构建智能体时原本分散在代码中的硬编码实现，重构为一种可声明、可维护、可扩展的动态化配置方式。

• 那么，这样设计的核心目的，是将业务智能体开发过程中那些复杂、重复且高度通用的实现环节进行抽象与沉淀，形成一套可复用的标准化构建流程，从而帮助用户更高效地完成智能体服务的开发与落地。至于为什么这里不直接封装为一个通用组件包，是因为当用户将智能体能力与具体业务深度结合后，往往会不断提出更细粒度的定制化诉求；同时，在智能体编排过程中也可能持续引入新的机制与扩展能力。在这种情况下，相比于封闭式组件包，以脚手架工程的方式交付给用户，更能兼顾可扩展性、可调整性与业务适配能力，因此也更符合实际使用场景。

3. 执行节点

智能体设计-执行节点.drawio

• 首先，这是一张用于描述智能体装配过程的详细流程节点编排图。其中，AiApiNode 与 ChatModelNode 由 Spring AI 负责构建，主要承担模型接入与基础能力初始化；在此基础之上，后续的 AgentNode、LoopAgentNode、ParallelAgentNode、SequentialNode、RunnerNode 等节点，则由 Google ADK 提供实现，用于承载智能体执行流程的编排与调度能力。

• 需要特别说明的是，AgentWorkflowNode 属于一个流程流转节点，其作用是承接并组织不同类型的智能体编排结构。由于一个 AI Agent 智能体的执行过程并非固定单一路径，因此在配置层面可以支持多种装配组合形式，例如：

  • Sequential + Agent 01 + Agent 02 + Agent 03：该形式表示按照顺序依次执行多个 Agent 节点，前一个节点的输出作为后续节点的处理输入，适用于链式处理场景。

  • Sequential + LoopAgent（Agent 01、Agent 02）+ Agent 03：该形式表示在顺序执行链路中嵌入一个 LoopAgent 循环节点。可以将其理解为：Agent 01 与 Agent 02 会围绕某个任务持续执行“分析—决策—再分析”的迭代过程，直到满足终止条件或达到预设的最大执行步数，随后再将结果交由 Agent 03 继续处理。

  • Sequential + ParallelAgentNode（Agent 01、Agent 02）+ Agent 03：该形式表示在顺序执行流程中嵌入一个 ParallelAgentNode 并行节点。可以理解为：Agent 01 与 Agent 02 会围绕同一任务或同一类数据并发执行各自处理逻辑，在完成并行计算、信息获取或结果生成后，再将汇总结果统一交由 Agent 03 做进一步处理。

  • Sequential + Agent 02 + LoopAgent（Agent 03、Agent 04）+ ParallelAgentNode（Agent 07、Agent 05） + Agent 06 + Agent 01：这类形式则属于更复杂的 Agent 装配流程，体现了智能体编排过程中的多层次组合能力。它既包含串行执行节点，也包含循环推理节点与并行处理节点，能够支持复杂业务场景下的任务拆解、阶段性推演、并发处理与结果汇总，最终形成完整的智能体执行链路。