AgentX - 智能对话 Agent 构建平台

基于大模型 (LLM) 与 MCP 协议的智能 Agent 构建平台。无需复杂的流程编排或拖拽设计,通过自然语言对话与工具集成即可创建、发布和管理个性化智能 Agent。

本项目参考开源项目 lucky-aeon/AgentX 进行学习改造,在此基础上补充了架构文档与测试说明。

📂 二开证据文档(供验证):REFACTOR-NOTES.md — 原项目提供什么 / 我改了什么 / 为什么改 · EVIDENCE.md — 核心模块源码路径索引(753 个 Java 类可逐文件核对)

✨ 核心功能

Agent 管理(创建/发布/编辑)
LLM 上下文管理(滑动窗口、摘要算法、token 溢出策略)
MCP 工具接入与工具市场
大模型服务商管理(OpenAI 协议兼容,如 SiliconFlow)
模型高可用网关(API 自动切换)
RAG 知识库(文档切分、向量检索)
定时任务(Agent 定时触发、延迟队列)
计费与用量统计(Product → Rule → Strategy 计费链路)
Agent 监控与调用追踪 (Traces)
长期记忆(基于向量库)
嵌入网站组件 (Widget)

🛠 技术栈

端	技术
后端	Java 17 · Spring Boot 3 · MyBatis-Plus · langchain4j · PostgreSQL · RabbitMQ · JWT · WebSocket
前端	Next.js 15 · TypeScript · Tailwind CSS · Radix UI / shadcn-ui · @xterm · axios
部署	Docker · Docker Compose · GitHub Actions(格式检查 / Docker 构建)

🏗 项目架构

总体架构

flowchart TB
    subgraph Frontend["前端 agentx-frontend-plus (Next.js 15)"]
        UI[页面层: studio / tools-market / knowledge / traces / admin ...]
        API_CLIENT[API 客户端 axios]
    end

    subgraph Backend["后端 AgentX (Spring Boot 3)"]
        direction TB
        IF["interfaces 层<br/>REST API / WebSocket / DTO"]
        APP["application 层<br/>应用服务: agent / billing / rag / task ..."]
        DOM["domain 层<br/>领域模型与领域服务"]
        INFRA["infrastructure 层<br/>Repository / LLM / MCP / MQ / 存储 / 支付"]
    end

    subgraph External["外部依赖"]
        PG[(PostgreSQL)]
        MQ[(RabbitMQ)]
        LLM_API[LLM 服务商<br/>SiliconFlow / OpenAI ...]
        MCP_SRV[MCP Server 集群]
        OSS[(对象存储 S3/OSS)]
        GW[模型高可用网关]
    end

    UI -->|HTTP / WebSocket :8088| IF
    IF --> APP --> DOM --> INFRA
    INFRA --> PG
    INFRA --> MQ
    INFRA --> LLM_API
    INFRA --> MCP_SRV
    INFRA --> OSS
    INFRA --> GW

后端分层设计(DDD)

后端采用 DDD 四层架构,包名以 org.xhy.* 开头,职责严格分层:

层	包路径	职责
interfaces	`org.xhy.interfaces`	HTTP 接口、WebSocket、请求/响应 DTO,不包含业务逻辑
application	`org.xhy.application`	应用服务,编排用例,事务边界
domain	`org.xhy.domain`	领域模型(Entity)、领域服务、领域常量,核心业务规则
infrastructure	`org.xhy.infrastructure`	Repository 实现、LLM/MCP 接入、MQ、存储、支付、邮箱等基础设施

核心领域模块:agent(Agent 管理)、token(上下文/token 策略)、rag(知识库)、scheduledtask(定时任务)、billing/product/rule(计费)、conversation(会话)、tool(工具)、memory(记忆)、container(容器运行时)。

📁 目录结构

AgentX/
├── AgentX/                      # 后端服务 (Spring Boot / Java 17)
│   ├── src/main/java/org/xhy/   # 主代码(interfaces/application/domain/infrastructure)
│   ├── src/main/resources/      # 配置、数据库脚本
│   ├── src/test/                # 测试(单元 / 集成 / 手动)
│   └── pom.xml                  # Maven 构建配置
├── agentx-frontend-plus/        # 前端服务 (Next.js 15 + TypeScript)
│   ├── app/                     # App Router 页面((auth)/(main)/widget)
│   ├── components/              # 通用组件
│   ├── hooks/ lib/ types/       # 自定义 Hook / 工具库 / 类型定义
│   └── package.json
├── deploy/                      # 一键部署脚本 + docker-compose
├── docker/                      # 前后端 Dockerfile
├── production/                  # 生产环境配置
├── docs/                        # 设计文档 / SQL / 监控 / 计费说明
├── .github/workflows/           # CI(code-format-check / docker-build)
├── .env.example                 # 环境变量模板
├── Dockerfile                   # 根级镜像构建
└── AGENTS.md / CLAUDE.md        # AI 协作指南

🚀 快速开始

环境要求

JDK 17+
Node.js 18+
PostgreSQL(可通过 docker-compose 自动拉起)
RabbitMQ(可通过 docker-compose 自动拉起)

方式一:开发环境启动(前后端分离)

# 1. 准备环境变量
cp .env.example .env   # 按需修改数据库/密钥等配置

# 2. 启动基础设施(PostgreSQL + RabbitMQ)
cd deploy && docker compose up -d

# 3. 启动后端(http://localhost:8088)
cd AgentX
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

# 4. 启动前端(http://localhost:3000)
cd agentx-frontend-plus
npm install
npm run dev

方式二:Docker 一键部署

cd deploy
./start.sh        # Linux/macOS
start.bat         # Windows

默认账号:管理员 admin@agentx.ai / admin123;测试用户 test@agentx.ai / test123(生产环境务必修改)。

详细部署与故障排查见 docs/ 与 deploy/README.md。

⚙️ 环境变量

核心配置项(完整列表见 .env.example):

配置项	说明	默认值
`SERVER_PORT`	后端 API 端口	`8088`
`DB_PASSWORD`	数据库密码	`agentx_pass`
`RABBITMQ_PASSWORD`	消息队列密码	`guest`
`JWT_SECRET`	JWT 密钥(生产必须修改,≥32 字符)	-
`AGENTX_ADMIN_PASSWORD`	管理员密码	`admin123`
`SILICONFLOW_API_KEY`	LLM 服务商 API Key	-
`EXTERNAL_DB_HOST` / `EXTERNAL_RABBITMQ_HOST`	外部数据库/队列地址	空(内置)

🧪 测试说明

后端测试(`AgentX/src/test`)

使用 JUnit 5 + Spring Boot Test,运行命令:

cd AgentX
./mvnw test                          # 运行全部测试
./mvnw test -Dtest=BillingIntegrationTest   # 运行单个测试类
./mvnw -DskipTests package           # 跳过测试打包

测试分三类:

① 单元测试(domain / infrastructure 层)

测试类	覆盖内容
`NoTokenOverflowStrategyTest`	无溢出 token 策略
`SlidingWindowTokenOverflowStrategyTest`	滑动窗口上下文策略
`SummarizeTokenOverflowStrategyTest`	摘要式上下文策略
`DelayedTaskQueueTest`	延迟任务队列
`MarkdownSplitterTest`	RAG 文档切分
`UserDomainServiceTest`	用户领域服务
`ToolTest`	工具注册与调用

② 集成测试(application 层,@SpringBootTest + @Transactional)

测试类	覆盖内容
`BillingIntegrationTest`	计费全链路:Product → Rule → Strategy
`AgentAppServiceBillingTest`	Agent 应用服务 + 计费联动
`ContainerAppServiceIntegrationTest`	容器应用服务
`ScheduledTaskAppServiceTest` / `DelayedTaskExecutionTest`	定时任务调度与延迟执行

集成测试需本地具备 PostgreSQL / RabbitMQ(或通过 deploy/docker-compose.yml 拉起),测试配置见 src/test/resources/application-test.yml。

③ 手动测试(main 方法,需真实环境或 API Key)

以下文件以 main() 方式运行,用于联调外部依赖,不参与 mvn test:

ChatTest / AgentStreamTest / MCPStandTest / MCPStreamTest / AgentStandTest — LLM 对话、流式响应与 MCP 工具调用联调
OssUploadTest / XFileStorageTest — 对象存储上传联调
ConversationAppServiceTest / Main.java — 应用服务手工验证

前端测试

前端未配置自动化测试框架,当前采用手动验证,仓库内提供以下联调文件:

文件	用途
`test-markdown.tsx`	Markdown 渲染组件验证(反引号、列表等)
`test-scheduled-task.js`	定时任务 API 联调脚本
`test-websocket.html`	WebSocket 实时推送联调页面

代码质量检查:

cd agentx-frontend-plus
npm run lint        # ESLint
npm run build       # 类型检查 + 生产构建

CI 检查

.github/workflows/ 内置两个流水线:

code-format-check.yml — 后端 Spotless 代码格式校验(./mvnw spotless:apply 可自动修复)
docker-build.yml — 前后端 Docker 镜像构建校验

📄 License

本项目基于 MIT License 开源,详见 LICENSE。参考项目:lucky-aeon/AgentX。

Navigation Menu

Repository navigation

About

Repository files navigation

AgentX - 智能对话 Agent 构建平台

✨ 核心功能

🛠 技术栈

🏗 项目架构

总体架构

后端分层设计(DDD)

📁 目录结构

🚀 快速开始

环境要求

方式一:开发环境启动(前后端分离)

方式二:Docker 一键部署

⚙️ 环境变量

🧪 测试说明

后端测试(`AgentX/src/test`)

前端测试

CI 检查

📄 License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.claude		.claude
.github		.github
AgentX		AgentX
agentx-frontend-plus		agentx-frontend-plus
deploy		deploy
docker		docker
docs		docs
production		production
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
TODO.md		TODO.md
promax.plan.md		promax.plan.md
启动教程.md		启动教程.md
学习计划.plan.md		学习计划.plan.md
项目概括.plan.md		项目概括.plan.md

Latest commit

History

Folders and files

Repository files navigation

AgentX - 智能对话 Agent 构建平台

✨ 核心功能

🛠 技术栈

🏗 项目架构

总体架构

后端分层设计(DDD)

📁 目录结构

🚀 快速开始

环境要求

方式一:开发环境启动(前后端分离)

方式二:Docker 一键部署

⚙️ 环境变量

🧪 测试说明

后端测试(AgentX/src/test)

前端测试

CI 检查

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

后端测试(`AgentX/src/test`)