X-Agents

企业级智能体平台，支持多 Agent 协作、工具调用、知识库管理、文档解析等能力。

项目概述

X-Agents 是一个前后端分离的智能体平台，采用微服务架构设计，提供完整的 AI Agent 管理和执行能力。

核心功能

• 智能体管理：创建、配置和管理多个 AI Agent
• 工具调用：支持多种工具的注册、调用和沙盒执行
• 知识库管理：支持文档上传、解析、向量化存储和检索
• 文档解析：基于 gRPC 的高性能文档解析服务，支持多种格式
• 模型管理：支持多种 LLM 模型的配置和切换
• 安全机制：工具白名单、人工审批、审计日志等安全控制
• 数据库集成：支持 MySQL、Neo4j 等数据库连接和查询

技术栈

前端 (web/)

• Vue 3 - 渐进式 JavaScript 框架
• Vite - 下一代前端构建工具
• TypeScript - JavaScript 的超集
• Element Plus - Vue 3 组件库
• Tailwind CSS - 原子化 CSS 框架
• Pinia - Vue 状态管理
• Vue Router - 路由管理
• ECharts - 数据可视化

后端

Go API Gateway (server/)

• Gin - HTTP Web 框架
• GORM - ORM 库
• gRPC - 高性能 RPC 框架
• JWT - 身份认证

Python Agent Engine (agent/)

• FastAPI - 高性能 Web 框架
• LangChain - LLM 应用开发框架
• OpenAI SDK - OpenAI API 客户端
• Anthropic SDK - Claude API 客户端

AI-Core 文档解析服务 (ai-core/)

• gRPC - RPC 通信框架
• MarkItDown - 文档解析引擎
• Protocol Buffers - 数据序列化

数据存储

• MySQL 8.0 - 关系型数据库
• Redis - 缓存和消息队列
• Neo4j - 图数据库（可选）

项目结构

X-Agents/
├── server/                    # Go API Gateway
│   ├── cmd/api/              # 程序入口
│   ├── internal/
│   │   ├── config/           # 配置管理
│   │   ├── handler/          # HTTP 处理器
│   │   ├── service/          # 业务逻辑层
│   │   ├── repository/       # 数据访问层
│   │   ├── middleware/       # 中间件
│   │   └── model/            # 数据模型
│   ├── config/               # 配置文件
│   ├── Dockerfile
│   └── go.mod
│
├── agent/                     # Python Agent Engine
│   ├── app/
│   │   ├── agent/
│   │   │   ├── core/         # Agent 核心
│   │   │   ├── tools/        # 工具管理
│   │   │   └── memory/       # 记忆管理
│   │   ├── api/              # API 路由
│   │   ├── llm/              # LLM 适配器
│   │   └── security/         # 安全机制
│   ├── requirements.txt
│   └── Dockerfile
│
├── ai-core/                   # 文档解析服务
│   ├── parser/               # 文档解析器
│   ├── proto/                # gRPC 协议定义
│   ├── service/              # gRPC 服务实现
│   ├── requirements.txt
│   └── config.yaml
│
├── web/                      # 前端项目
│   ├── src/
│   │   ├── components/       # Vue 组件
│   │   ├── views/            # 页面视图
│   │   ├── router/           # 路由配置
│   │   └── utils/            # 工具函数
│   ├── package.json
│   ├── vite.config.ts
│   └── tailwind.config.js
│
├── docs/                     # 文档
│   └── ARCHITECTURE.md      # 架构设计文档
│
├── docker-compose.yml         # Docker 编排文件
├── docker-compose.dev.yml    # 开发环境配置
├── .env.example             # 环境变量模板
└── README.md               # 项目说明

快速开始

前置要求

• Docker 和 Docker Compose
• Node.js 18+
• Go 1.25+
• Python 3.9+

方式一：使用 Docker Compose（推荐）

1. 克隆项目

git clone <repository-url>
cd X-Agents

2. 配置环境变量

cp .env.example .env
# 根据需要修改 .env 文件中的配置

3. 启动所有服务

docker-compose up -d

服务将在以下端口启动：

• Go API: http://localhost:8080
• Python Agent: http://localhost:8081
• 前端: http://localhost:5173
• AI-Core: localhost:50051 (gRPC)
• MySQL: localhost:3306
• Redis: localhost:6379

方式二：本地开发

1. 启动基础服务（数据库）

docker-compose -f docker-compose.yml up -d

2. 启动 Go API 服务

cd server
go run ./cmd/api

服务将在 http://localhost:8082 启动

3. 启动 Python Agent 服务

cd agent
pip install -r requirements.txt
python -m app.main

服务将在 http://localhost:8081 启动

4. 启动 AI-Core 文档解析服务

cd ai-core
pip install -r requirements.txt
python generate_grpc.py
python main.py --port 50051

服务将在 localhost:50051 启动

5. 启动前端服务

cd web
npm install
npm run dev

前端将在 http://localhost:5173 启动

方式三：使用启动脚本（Windows）

.\start-local.ps1

此脚本会自动启动数据库、Go 服务和前端服务。

配置说明

Go 服务配置

编辑 server/config/config.yaml：

port: "8082"
jwt_secret: "your-secret-key"

database_host: "localhost"
database_port: "3306"
database_user: "root"
database_password: "root"
database_name: "x_agents"

python_service_url: "http://localhost:8081"
ai_core_service_addr: "localhost:50051"

upload_mode: "local"
upload_local_path: "resource/files"
server_base_url: "http://localhost:8082"

AI-Core 配置

编辑 ai-core/config.yaml：

server:
  host: "0.0.0.0"
  port: 50051

parser:
  default_engine: "builtin"
  supported_engines:
    - builtin
    - markitdown

logging:
  level: "INFO"

开发指南

前端开发

cd web
npm run dev          # 启动开发服务器
npm run build        # 构建生产版本
npm run preview      # 预览生产版本

后端开发

# Go 服务
cd server
go run ./cmd/api     # 启动开发服务器
go test ./...        # 运行测试

# Python 服务
cd agent
python -m app.main   # 启动开发服务器
pytest               # 运行测试

添加新工具

1. 在 agent/app/agent/tools/impl/ 目录下创建新工具
2. 在 agent/app/agent/tools/registry.py 中注册工具
3. 配置安全级别和权限

添加新文档解析器

1. 在 ai-core/parser/ 目录下实现解析器类
2. 继承 BaseParser 并实现 parse_into_text 方法
3. 在 ai-core/parser/registry.py 中注册

API 文档

详细 API 文档请参考 team-require/api/ 目录。

主要接口包括：

• 认证接口
• Agent 聊天接口
• 知识库管理接口
• 模型管理接口
• 数据库查询接口
• 文件上传接口

架构设计

详细的架构设计文档请参考 docs/ARCHITECTURE.md。

安全机制

• 工具白名单：所有工具必须在注册表中注册
• 安全分级：工具分为 SAFE、REVIEW、DANGER 三个等级
• 人工审批：危险操作需要人工审批
• 审计日志：记录所有操作历史
• 沙盒执行：代码在隔离环境中执行

常见问题

数据库连接失败

检查 MySQL 服务是否正常启动，配置文件中的数据库信息是否正确。

前端无法连接后端

检查后端服务是否正常启动，CORS 配置是否正确。

文档解析失败

检查 AI-Core 服务是否正常启动，gRPC 端口是否正确配置。

贡献指南

欢迎提交 Issue 和 Pull Request。

许可证

MIT License