内容
# Xgent - 轻量级 AI Agent 编排框架
Xgent 是一款基于 Spring Boot 和 DDD（领域驱动设计）架构开发的轻量级 AI Agent 编排框架。它集成了 `google-adk`（Agent Development Kit），旨在为开发者提供一种简单、高效的方式来构建和编排多智能体（Multi-Agent）工作流，支持模型上下文协议（MCP）、智能体技能（Skills）系统和多种主流 AI 框架（Spring AI, LangChain4j）。
---
## 业务架构图：
<img src="./docs/archtype/images/base_archtype.png">
---
## 🚀 核心特性
- **🧩 模块化设计**：基于 DDD 架构，清晰的职责划分，易于扩展和维护。
- **🤖 多智能体编排**：内置支持 **串行（Sequential）**、**并行（Parallel）** 和 **循环（Loop）** 智能体执行模式。
- **💬 对话服务**：提供完整的会话管理，支持非流式与流式（SSE）智能体对话 API，具备会话上下文记忆能力。
- **📱 移动端自动化**：支持通过智能体控制 Android 设备（点击、滑动、输入、启动应用等），实现移动 App 的自动化任务执行。
- **🔌 MCP 支持**：深度集成 Model Context Protocol，支持通过 SSE (Server-Sent Events) 调用外部工具（如百度搜索、百度地图等）。
- **🛠️ 技能系统（Skills）**：支持通过 `SKILL.md` 文件定义智能体技能，包含脚本、参考文档和指令，实现可复用的 agent 能力包。
- **🎨 框架抽象**：通过适配层同时支持 `Spring AI` 和 `dev.langchain4j`，无缝切换底层 AI 能力。
- **📝 配置驱动**：智能体及其工作流可以通过 YAML 文件进行声明式定义，降低代码耦合度。
- **🌐 前端界面**：内置基于 Nginx 的 Web 前端页面（登录页、对话界面），支持直连后端 API。
- **🐳 生产就绪**：包含完善的日志记录、多环境配置、Docker 支持及单元测试。
---
## 🛠️ 技术栈
- **核心框架**：Spring Boot 3.4.3
- **AI 增强**：google-adk 0.5.0 (Agent Development Kit), Spring AI 1.1.0-M3, LangChain4j 1.4.0
- **持久层**：MyBatis 3.0.4, MySQL 8.0.28
- **架构模式**：Domain-Driven Design (DDD)
- **其他组件**：Fastjson2, Guava, RxJava3, Lombok
- **开发环境**：Java 17, Maven
---
## 📂 项目结构
```text
xgent
├── xgent-api # API 接口定义层 (DTOs, Responses)
├── xgent-app # 应用配置与启动层 (Config, Application, Tests)
│ └── src/main/resources/agent
│ ├── test-agent.yml # 智能体 YAML 配置
│ ├── only-one-agent.yml # 单一智能体配置（学习计划）
│ ├── mobile-hermes-agent.yml # 移动端自动化智能体（JSON 指令模式）
│ ├── auto-phone-agent.yml # 移动端自动化智能体（AutoGLM 操作模式）
│ └── skills # 智能体技能目录
│ ├── battle-plan/SKILL.md # 电脑性能优化技能
│ └── pdf/SKILL.md # PDF 处理技能
├── xgent-domain # 核心业务领域层 (Agent 逻辑, 业务服务, ChatService)
├── xgent-infrastructure # 基础设施层 (MySQL, Redis, 外部适配器)
├── xgent-trigger # 触发器层 (HTTP 接口, 定时任务, 监听器)
├── xgent-types # 通用类型层 (Constants, Enums, Exceptions)
└── docs/dev-ops/nginx/html # 前端静态页面 (index.html, login.html)
```
---
## 🚦 快速开始
### 1. 环境准备
- JDK 17+
- Maven 3.6+
- MySQL 8.0+
### 2. 数据库配置
执行 `docs/dev-ops/mysql/sql/archetype.sql` 中的 SQL 脚本以初始化数据库。
### 3. 配置 API Key
在 `xgent-app/src/main/resources/agent/test-agent.yml` 中配置你的 AI 模型 API Key 以及 MCP 工具的 Key。
```yaml
ai:
agent:
config:
tables:
testAgent:
module:
ai-api:
api-key: your_api_key_here # 填入你的 API Key
chat-model:
tool-mcp-list:
- sse:
name: baidu-search
sse-endpoint: sse?api_key=your_mcp_key_here # 填入 MCP 工具 Key
```
### 4. 运行应用
启动 `xgent-app` 模块下的 `com.cool.Application` 类。
服务默认端口为 `8901`，启动后可通过以下地址访问：
- **API 根路径**：`http://localhost:8901/api/v1/`
- **前端页面**（需配合 Nginx）：`docs/dev-ops/nginx/html/index.html`
---
## 🔌 API 接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/v1/query_ai_agent_config_list` | GET | 查询智能体配置列表 |
| `/api/v1/create_session` | POST | 创建对话会话 |
| `/api/v1/chat` | POST | 智能体对话（非流式）|
| `/api/v1/chat_stream` | POST | 智能体对话（流式 SSE）|
### curl 示例
**查询智能体列表**
```bash
curl -X GET 'http://localhost:8901/api/v1/query_ai_agent_config_list'
```
**创建会话**
```bash
curl -X POST 'http://localhost:8901/api/v1/create_session' \
-H 'Content-Type: application/json' \
-d '{"agentId":"100003","userId":"cool"}'
```
**非流式对话**
```bash
curl -X POST 'http://localhost:8901/api/v1/chat' \
-H 'Content-Type: application/json' \
-d '{"agentId":"100003","userId":"cool","sessionId":"","message":"你可以做什么"}'
```
**流式对话**
```bash
curl -N -X POST 'http://localhost:8901/api/v1/chat_stream' \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-d '{"agentId":"100003","userId":"cool","sessionId":"...","message":"你可以做什么"}'
```
---
## 💡 使用示例
### 工作流编排
通过 YAML 配置定义一个简单的代码生成管道：
```yaml
# test-agent.yml 示例片段
agent-workflows:
- type: sequential
name: CodePipelineAgent
sub-agents:
- CodeWriterAgent # 负责编写代码
- CodeReviewerAgent # 负责评审代码
- CodeRefactorerAgent # 负责重构代码
```
在测试类中调用：
```java
// 详见 SequentialAgentTest.java
SequentialAgent codePipelineAgent = SequentialAgent.builder()
.name("CodePipelineAgent")
.subAgents(codeWriterAgent, codeReviewerAgent, codeRefactorerAgent)
.build();
InMemoryRunner runner = new InMemoryRunner(codePipelineAgent, "CodePipelineAgent");
Flowable<Event> eventStream = runner.runAsync(userId, sessionId, userMessage);
```
### 技能系统（Skills）
Xgent 支持通过 `SKILL.md` 文件为智能体挂载可复用的技能包。技能目录位于 `xgent-app/src/main/resources/agent/skills/`。
每个技能包含：
- `SKILL.md`：技能定义与指令
- `reference.md`：参考文档与话术结构
- `scripts/`：配套脚本（Shell、Python 等）
例如 `battle-plan` 技能可让智能体执行系统信息收集并生成优化建议；`pdf` 技能提供完整的 PDF 处理能力（提取文本、合并拆分、表单填写、OCR 等）。
### 移动端自动化
Xgent 支持通过智能体控制 Android 设备完成自动化任务，提供两种操作模式：
**模式一：JSON 指令模式（mobile-hermes-agent）**
智能体通过分析屏幕截图，输出标准 JSON 格式的操作指令：
```json
{
"type": "action",
"command": {
"action": "click",
"params": { "x": 500, "y": 800 }
},
"reason": "点击搜索按钮以进入搜索页面"
}
```
支持的指令：`click`、`swipe`、`input`、`open`、`back`、`home`、`screenshot` 等。
**模式二：AutoGLM 操作模式（auto-phone-agent）**
基于 `autoglm-phone` 模型，输出结构化操作指令：
```
<think>需要打开京东搜索商品</think>
<answer>do(action="Launch", app="com.jingdong.app.mall")</answer>
```
支持的操作：`Launch`、`Tap`、`Type`、`Swipe`、`Long Press`、`Double Tap`、`Back`、`Home`、`Wait`、`finish` 等。
**适用场景**：
- 自动点外卖、购物下单
- 社交 App 自动发消息
- App 自动化测试与信息提取
---
感谢对 Xgent 的关注与支持！如果你有任何问题或建议，欢迎提交 Issue。
