AI Agent Scaffold 智能体脚手架

Cactus li...大约 8 分钟

AI Agent Scaffold 智能体脚手架

📖 项目简介

AI Agent Scaffold 是一套基于 Google ADK 构建，并兼容 Spring AI / LangChain4j 的企业级 AI Agent 智能体应用开发框架。该脚手架以模块化与标准化为核心，通过 YML 声明式配置完成智能体能力的编排与装配，支持顺序、循环、并行等多种工作流执行模式，并提供 MCP 工具调用、Skills 技能书、多模态交互、Plugin 插件扩展等完整能力。

本目录为配套教程文档，涵盖从需求分析、架构设计、核心节点实现到脚手架发布部署的完整开发链路，帮助开发者从零构建一套可复用的 AI Agent 工程化框架。

🏗️ 项目架构

ai-agent-scaffold-lite/
├── ai-agent-scaffold-lite-api/       # API 接口定义与 DTO
├── ai-agent-scaffold-lite-app/       # 主应用模块（启动入口、YML 配置）
├── ai-agent-scaffold-lite-domain/    # 领域层（agent 装配、会话服务）
│   └── agent/
│       ├── armory/                   # 智能体装配节点
│       │   ├── node/                 # 装配流程节点
│       │   └── matter/               # 物料模块（MCP、Plugin）
│       └── service/                  # 领域服务（IArmoryService、IChatService）
├── ai-agent-scaffold-lite-trigger/   # 触发器层（HTTP 接口、定时任务）
├── ai-agent-scaffold-lite-case/      # 业务编排层（复杂流程调度）
├── docs/                             # 项目文档与部署配置
│   └── dev-ops/nginx/                # 前端 UI 与 Nginx 配置
├── ai-agent-scaffold-lite-archetype/ # Maven Archetype 脚手架模板
└── pom.xml                           # Maven 父项目配置

🚀 核心功能

1. 声明式智能体装配

基于 YML 配置文件定义智能体配置表（API、Model、Tool、Workflow）
应用启动时自动扫描加载，完成智能体实例化与 Spring Bean 注册
支持多智能体配置、多工作流并行管理

2. 规则树装配引擎

基于责任链模式与组合模式构建装配流程
节点化拆分：AiApiNode → ChatModelNode → AgentNode → AgentWorkflowNode → RunnerNode
支持 Loop（循环）、Parallel（并行）、Sequential（顺序）工作流编排

3. MCP 工具与 Skills 技能

支持 SSE、STDIO、Local 三种 MCP 接入方式
工厂模式 + 策略模式实现 MCP 类型扩展
Skills 技能书能力注入，缩短执行链路、降低 Token 消耗

4. 会话服务能力

智能体列表查询、会话创建、同步/流式消息处理
支持文本、文件、内联数据等多模态输入
Trigger 层 HTTP 接口 + 前端 UI 可视化对话

5. 运行时可观测性

InMemoryRunner 插件机制，支持生命周期 Hook 回调
日志记录、性能监控、请求拦截与治理扩展
自定义 Plugin 插件埋点

6. Maven 脚手架工程化

基于 maven-archetype-plugin 一键生成标准化项目
支持本地仓库、企业私服、Catalog 远程索引三种分发方式
Nginx / GitHub Pages 部署脚手架目录网页

🛠️ 技术栈

框架: Spring Boot 3.4.3, Google ADK 0.4.0 ~ 1.0.0
AI 集成: Spring AI 1.1.0-M3 ~ 2.0.0-M2, LangChain4j
语言: Java 17
架构: DDD 领域驱动设计 + 六边形架构
设计模式: 责任链、组合模式、工厂模式、策略模式
构建工具: Maven 3.8.x + maven-archetype-plugin
工具协议: MCP（Model Context Protocol）、Skills
部署: Docker, Docker Compose, Nginx
其他: Lombok, YAML 配置

📋 环境要求

JDK 17+
Maven 3.8.x
IntelliJ IDEA（社区版即可）
Git
Docker & Docker Compose（可选，用于 UI 与 Nginx 部署）
大模型 API Key（OpenAI 兼容接口）

🔧 快速开始

1. 技术预研验证

在正式开发脚手架前，建议先完成各框架的 PoC 验证：

# 参考教程第 3 章，分别验证 Spring AI、LangChain4j、Google ADK 的接入效果

2. 使用脚手架创建项目

命令行方式

# 在空目录下执行，选择本地 Archetype
mvn archetype:generate -X -DarchetypeCatalog=local

按提示输入 groupId、artifactId 等信息，即可生成完整的智能体项目工程。

IntelliJ IDEA 方式

在 IDEA 中配置 Maven Archetype 模板（参考教程第 22 章）
通过 File → New → Project → Maven Archetype 创建项目
打开项目，删除 .idea 后重新导入（如未识别为 Maven 工程）

3. 配置智能体

编辑 ai-agent-scaffold-lite-app/src/main/resources/application-ai-agent.yml：

ai:
  agent:
    config:
      tables:
        my_agent_app:
          app-name: MyAgentApp
          agent:
            agent-id: 100001
            agent-name: 我的智能体
            agent-desc: 示例智能体配置
          module:
            ai-api:
              base-url: https://api.openai.com
              api-key: sk-xxx
            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=your-api-key
            agents:
              - name: MyAgent
                description: 示例子智能体
                instruction: |
                  你是一个 AI 助手，请根据用户问题提供帮助。
            agent-workflows:
              - type: sequential
                sub-agents:
                  - MyAgent
            runner:
              agent-name: MyAgent

4. 启动应用

mvn clean install
cd ai-agent-scaffold-lite-app
mvn spring-boot:run

5. 访问对话 UI

# 启动 Nginx 前端（可选）
docker-compose -f docker-compose-app.yml up -d

浏览器访问对话页面，选择智能体、创建会话并发起对话。

⚙️ 配置说明

主要配置项

配置项	说明	示例
`ai.agent.config.tables`	智能体配置表（支持多个）	`my_agent_app`
`module.ai-api.base-url`	大模型 API 地址	`https://api.openai.com`
`module.ai-api.api-key`	API 密钥	`sk-xxx`
`module.chat-model.model`	模型名称	`gpt-4.1`
`module.chat-model.tool-mcp-list`	MCP 工具列表	SSE / STDIO / Local
`module.chat-model.tool-skills-list`	Skills 技能书列表	`battle-plan`
`module.agents`	子智能体定义	名称、指令、描述
`module.agent-workflows`	工作流编排	sequential / loop / parallel
`module.runner.agent-name`	Runner 关联的智能体	`MyAgent`

Maven Archetype Catalog 配置

在 ~/.m2/settings.xml 或 IDEA Maven 设置中添加远程 Catalog：

<archetypeCatalogs>
  <archetypeCatalog>
    <id>custom</id>
    <url>https://your-domain.com/archetype-catalog.xml</url>
  </archetypeCatalog>
</archetypeCatalogs>

📚 教程目录

第一阶段：需求分析与架构设计

章节	文档	内容
01	需求分析	项目背景、产品方案、智能体设计模型
02	系统架构设计	技术选型、模块编排、YML 配置设计
03	API 功能测试	Spring AI / LangChain4j / Google ADK PoC 验证

第二阶段：智能体装配核心实现

章节	文档	内容
04	配置表设计	YML 智能体配置表结构与值对象
05	装配域结构定义	IArmoryService、规则树节点框架
06	AiApiNode	AI 接口对接与 OpenAiApi 构建
07	ChatModelNode	对话模型创建与 MCP 集成
08	AgentNode	单一智能体实例构建
09	AgentWorkflowNode	工作流节点编排
10	Loop / Parallel / Sequential	循环、并行、顺序执行节点
11	RunnerNode	InMemoryRunner 构建与注册
12	加载与验证	启动加载智能体与功能测试

第三阶段：增强装配能力

章节	文档	内容
13	增强 RunnerNode	动态 Agent 注入 Runner
14	增强 AgentWorkflowNode	统一流转调度中心
15	本地 MCP	自定义 MCP 服务扩展
16	回调 Plugin	Runner 插件钩子机制
17	多模态能力	图片识别等多模态交互
21	Skills 技能	技能书配置与能力注入

第四阶段：会话服务与 UI 对接

章节	文档	内容
18	会话服务 Service	IChatService 领域服务实现
19	会话服务 Trigger	HTTP 接口层封装
20	UI 对接	前端对话页面集成

第五阶段：脚手架工程化与部署

章节	文档	内容
22	Maven 脚手架配置	archetype-plugin 模板生成
23	发布到 Maven 仓库	阿里云私服 Jar 发布
24	部署脚手架网页	Nginx / GitHub Pages Catalog 部署

🐳 部署指南

1. 脚手架 Jar 发布到私服

# 配置阿里云 Maven 私服 settings.xml 后执行
mvn clean install org.apache.maven.plugins:maven-deploy-plugin:2.8:deploy -DskipTests

2. 部署 Archetype Catalog 网页

# 本地 Docker 部署
docker-compose -f docker-compose-app.yml up -d

# 确保 archetype-catalog.xml 中的版本与发布的 Jar 版本一致

3. 云服务器 / GitHub Pages

云服务器：上传 archetype-catalog.xml 到 Nginx 静态目录
GitHub Pages：Fork lixuanfengs.github.io 模板，上传脚手架文件到 root 目录

📊 学习路径建议

需求分析 → 架构设计 → PoC 验证
    ↓
配置表设计 → 装配域结构 → 逐节点实现（06-11）
    ↓
启动加载验证 → 增强能力扩展（13-17, 21）
    ↓
会话服务 → Trigger 接口 → UI 对接
    ↓
Maven 脚手架 → 私服发布 → Catalog 网页部署