Content
# Xgent - Lightweight AI Agent Orchestration Framework
Xgent is a lightweight AI Agent orchestration framework developed based on Spring Boot and DDD (Domain-Driven Design) architecture. It integrates `google-adk` (Agent Development Kit) and aims to provide developers with a simple and efficient way to build and orchestrate Multi-Agent workflows, supporting Model Context Protocol (MCP), Agent Skills system, and multiple mainstream AI frameworks (Spring AI, LangChain4j).
## Business Architecture Diagram:
<img src="./docs/archtype/images/base_archtype.png">
## 🚀 Core Features
- **🧩 Modular Design**: Based on DDD architecture, clear responsibility division, easy to extend and maintain.
- **🤖 Multi-Agent Orchestration**: Built-in support for **Sequential**, **Parallel**, and **Loop** agent execution modes.
- **💬 Dialogue Service**: Provides complete session management, supporting non-streaming and streaming (SSE) agent dialogue APIs, with session context memory capabilities.
- **📱 Mobile Automation**: Supports controlling Android devices through agents (click, swipe, input, launch apps, etc.), achieving automated task execution for mobile apps.
- **🔌 MCP Support**: Deeply integrates Model Context Protocol, supporting external tool calls (such as Baidu search, Baidu maps, etc.) through SSE (Server-Sent Events).
- **🛠️ Skills System**: Supports defining agent skills through `SKILL.md` files, including scripts, reference documents, and instructions, realizing reusable agent capability packages.
- **🎨 Framework Abstraction**: Supports both `Spring AI` and `dev.langchain4j` through adaptation layers, seamlessly switching underlying AI capabilities.
- **📝 Configuration-Driven**: Agents and their workflows can be declaratively defined through YAML files, reducing code coupling.
- **🌐 Front-end Interface**: Built-in web front-end pages (login page, dialogue interface) based on Nginx, supporting direct connection to back-end APIs.
- **🐳 Production-Ready**: Includes complete log recording, multi-environment configuration, Docker support, and unit testing.
## 🛠️ Technology Stack
- **Core Framework**: Spring Boot 3.4.3
- **AI Enhancement**: google-adk 0.5.0 (Agent Development Kit), Spring AI 1.1.0-M3, LangChain4j 1.4.0
- **Persistence Layer**: MyBatis 3.0.4, MySQL 8.0.28
- **Architecture Pattern**: Domain-Driven Design (DDD)
- **Other Components**: Fastjson2, Guava, RxJava3, Lombok
- **Development Environment**: Java 17, Maven
## 📂 Project Structure
```text
xgent
├── xgent-api # API interface definition layer (DTOs, Responses)
├── xgent-app # Application configuration and startup layer (Config, Application, Tests)
│ └── src/main/resources/agent
│ ├── test-agent.yml # Agent YAML configuration
│ ├── only-one-agent.yml # Single agent configuration (learning plan)
│ ├── mobile-hermes-agent.yml # Mobile automation agent (JSON instruction mode)
│ ├── auto-phone-agent.yml # Mobile automation agent (AutoGLM operation mode)
│ └── skills # Agent skills directory
│ ├── battle-plan/SKILL.md # Computer performance optimization skill
│ └── pdf/SKILL.md # PDF processing skill
├── xgent-domain # Core business domain layer (Agent logic, business services, ChatService)
├── xgent-infrastructure # Infrastructure layer (MySQL, Redis, external adapters)
├── xgent-trigger # Trigger layer (HTTP interface, scheduled tasks, listeners)
├── xgent-types # Common type layer (Constants, Enums, Exceptions)
└── docs/dev-ops/nginx/html # Front-end static pages (index.html, login.html)
```
## 🚦 Quick Start
### 1. Environment Preparation
- JDK 17+
- Maven 3.6+
- MySQL 8.0+
### 2. Database Configuration
Execute the SQL script in `docs/dev-ops/mysql/sql/archetype.sql` to initialize the database.
### 3. Configure API Key
Configure your AI model API Key and MCP tool Key in `xgent-app/src/main/resources/agent/test-agent.yml`.
```yaml
ai:
agent:
config:
tables:
testAgent:
module:
ai-api:
api-key: your_api_key_here # Fill in your API Key
chat-model:
tool-mcp-list:
- sse:
name: baidu-search
sse-endpoint: sse?api_key=your_mcp_key_here # Fill in MCP tool Key
```
### 4. Run the Application
Start the `com.cool.Application` class under the `xgent-app` module.
The service default port is `8901`. After startup, you can access it through the following addresses:
- **API Root Path**: `http://localhost:8901/api/v1/`
- **Front-end Page** (with Nginx): `docs/dev-ops/nginx/html/index.html`
## 🔌 API Interface
| Interface | Method | Description |
|------|------|------|
| `/api/v1/query_ai_agent_config_list` | GET | Query agent configuration list |
| `/api/v1/create_session` | POST | Create dialogue session |
| `/api/v1/chat` | POST | Agent dialogue (non-streaming) |
| `/api/v1/chat_stream` | POST | Agent dialogue (streaming SSE) |
### curl Example
**Query Agent List**
```bash
curl -X GET 'http://localhost:8901/api/v1/query_ai_agent_config_list'
```
**Create Session**
```bash
curl -X POST 'http://localhost:8901/api/v1/create_session' \
-H 'Content-Type: application/json' \
-d '{"agentId":"100003","userId":"cool"}'
```
**Non-Streaming Dialogue**
```bash
curl -X POST 'http://localhost:8901/api/v1/chat' \
-H 'Content-Type: application/json' \
-d '{"agentId":"100003","userId":"cool","sessionId":"","message":"What can you do"}'
```
**Streaming Dialogue**
```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":"What can you do"}'
```
## 💡 Usage Example
### Workflow Orchestration
Define a simple code generation pipeline through YAML configuration:
```yaml
# test-agent.yml example fragment
agent-workflows:
- type: sequential
name: CodePipelineAgent
sub-agents:
- CodeWriterAgent # Responsible for writing code
- CodeReviewerAgent # Responsible for reviewing code
- CodeRefactorerAgent # Responsible for refactoring code
```
Call in test class:
```java
// See 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 System
Xgent supports mounting reusable skill packages for agents through `SKILL.md` files. The skill directory is located at `xgent-app/src/main/resources/agent/skills/`.
Each skill includes:
- `SKILL.md`: Skill definition and instructions
- `reference.md`: Reference documents and dialogue structures
- `scripts/`: Supporting scripts (Shell, Python, etc.)
For example, the `battle-plan` skill allows agents to execute system information collection and generate optimization suggestions; the `pdf` skill provides complete PDF processing capabilities (text extraction, merging and splitting, form filling, OCR, etc.).
### Mobile Automation
Xgent supports controlling Android devices through agents to complete automated tasks, providing two operation modes:
**Mode 1: JSON Instruction Mode (mobile-hermes-agent)**
Agents output standard JSON format operation instructions by analyzing screenshots:
```json
{
"type": "action",
"command": {
"action": "click",
"params": { "x": 500, "y": 800 }
},
"reason": "Click the search button to enter the search page"
}
```
Supported instructions: `click`, `swipe`, `input`, `open`, `back`, `home`, `screenshot`, etc.
**Mode 2: AutoGLM Operation Mode (auto-phone-agent)**
Based on the `autoglm-phone` model, output structured operation instructions:
```
<think>Need to open JD search product</think>
<answer>do(action="Launch", app="com.jingdong.app.mall")</answer>
```
Supported operations: `Launch`, `Tap`, `Type`, `Swipe`, `Long Press`, `Double Tap`, `Back`, `Home`, `Wait`, `finish`, etc.
**Applicable Scenarios**:
- Automatic food ordering, shopping, and ordering
- Social App automatic messaging
- App automation testing and information extraction
Thanks for your attention and support for Xgent! If you have any questions or suggestions, feel free to submit an issue.
