https://github.com/xyctruth/x-agent
https://github.com/xyctruth/x-agent
Last synced: 29 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/xyctruth/x-agent
- Owner: xyctruth
- Created: 2026-05-22T09:18:45.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-24T12:20:51.000Z (about 1 month ago)
- Last Synced: 2026-05-24T14:16:49.461Z (about 1 month ago)
- Language: Python
- Size: 271 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# x-agent
`x-agent` 是一个用于学习并实践生产级 Python AI Agent 服务的项目。目标是构建一个高可用、可扩展、边界清晰的 Agent 服务。
这个项目从第一版开始就按照真实服务的方式组织：清晰分层、明确开发流程、类型化业务代码、测试、lint、类型检查，以及服务职责文档。
## 架构
初始架构包含以下层次：
- Client 层：SDK、CLI、Web 客户端和外部调用方。
- API 层：FastAPI 路由、请求校验、响应 Schema 和错误映射。
- Application 层：用例编排、事务边界和应用服务。
- Domain 层：不依赖框架或基础设施的业务概念。
- Agent 层：Agent 会话、规划、上下文管理和执行策略。
- Execution 层：工具运行时、重试、超时和后台执行。
- Persistence 层：repository 和持久化状态。
- Infrastructure 层：配置、日志、LLM Provider、数据库、队列和外部 API。
更多说明见 [docs/architecture.md](docs/architecture.md)。
## 开发
安装依赖：
```bash
uv sync --extra dev
```
也可以使用 Makefile：
```bash
make sync
```
启动服务：
```bash
uv run fastapi dev src/x_agent/main.py
```
也可以直接使用 `uvicorn`：
```bash
uv run uvicorn x_agent.main:create_app --factory --reload
```
运行检查：
```bash
uv run ruff format --check .
uv run ruff check .
uv run mypy src tests
uv run pytest
```
或：
```bash
make check
```
启动前端：
```bash
cd web
npm install
npm run dev
```
前端默认连接 `http://127.0.0.1:8000`，可以通过 `VITE_X_AGENT_API_BASE_URL` 覆盖。
### 接入千问
默认使用确定性的 SimpleAgent。接入千问时通过环境变量启用，不要把 API Key 写入代码或文档：
```bash
export X_AGENT_LLM_PROVIDER=qwen
export X_AGENT_QWEN_API_KEY="你的百炼 API Key"
export X_AGENT_QWEN_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export X_AGENT_QWEN_MODEL="qwen-plus"
uv run fastapi dev src/x_agent/main.py
```
也兼容官方环境变量：
```bash
export DASHSCOPE_API_KEY="你的百炼 API Key"
```
### 初始化 Mock MySQL 业务库
项目提供本地 MySQL 8.0 mock 业务库，用于测试自然语言转统计 SQL、后续只读 SQL 执行和数据分析能力：
```bash
make start-mysql
bash scripts/init_mock_mysql.sh
```
默认连接 `127.0.0.1:3306`，用户和密码均为 `root`，数据库名为 `x_agent_mock_biz`。MySQL Docker 数据挂载到 `.data/mysql`。可以通过 `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_USER`、`MYSQL_PASSWORD`、`MYSQL_DATABASE` 环境变量覆盖。
一条命令启动 MySQL、Qdrant 并初始化 mock 业务库：
```bash
make up
```
### 启用 NL2SQL MySQL metadata 检索
NL2SQL 默认从本地 mock MySQL 的 `information_schema` 读取真实表结构、字段注释、外键和索引信息：
```bash
export X_AGENT_NL2SQL_KNOWLEDGE_SOURCE=mysql
export X_AGENT_MYSQL_HOST=127.0.0.1
export X_AGENT_MYSQL_PORT=3306
export X_AGENT_MYSQL_USER=root
export X_AGENT_MYSQL_PASSWORD=root
export X_AGENT_MYSQL_DATABASE=x_agent_mock_biz
uv run fastapi dev src/x_agent/main.py
```
启用后，服务会组合使用 MySQL metadata 和静态业务知识。MySQL metadata 负责真实表结构，静态知识库继续提供指标定义、业务术语和历史 SQL 样例。
如果需要在无数据库环境下临时运行，可以切回进程内静态知识库：
```bash
export X_AGENT_NL2SQL_KNOWLEDGE_SOURCE=memory
```
### 启用 NL2SQL 向量知识库
向量模式使用 Qdrant 存储知识向量，使用千问 `text-embedding-v4` 生成 embedding：
```bash
make start-qdrant
export X_AGENT_QWEN_API_KEY="你的百炼 API Key"
export X_AGENT_NL2SQL_KNOWLEDGE_SOURCE=vector
export X_AGENT_EMBEDDING_PROVIDER=qwen
export X_AGENT_QWEN_EMBEDDING_MODEL=text-embedding-v4
export X_AGENT_EMBEDDING_DIMENSIONS=1024
export X_AGENT_QDRANT_URL=http://127.0.0.1:6333
export X_AGENT_QDRANT_COLLECTION=nl2sql_knowledge
export X_AGENT_NL2SQL_VECTOR_SCORE_THRESHOLD=0.5
make ingest-nl2sql
uv run fastapi dev src/x_agent/main.py
```
Qdrant Docker 数据挂载到 `.data/qdrant`。ingest 脚本会读取 MySQL metadata 和静态业务知识，生成向量后写入 Qdrant collection。服务运行时会对用户问题生成 query embedding，再按检索计划中的知识类型和相似度阈值从 Qdrant 召回相似知识。
## 当前 API
- `GET /healthz`：存活检查和基础服务元数据。
- `GET /readyz`：服务就绪检查。
- `GET /api/v1/service-info`：服务职责和支持的架构分层。
- `POST /api/v1/agent-sessions`：创建 Agent 会话。
- `GET /api/v1/agent-sessions/{session_id}`：查询 Agent 会话。
- `POST /api/v1/agent-sessions/{session_id}/messages`：在会话下发送用户消息，并返回本次新增的 user/assistant 消息。
- `POST /api/v1/agent-sessions/{session_id}/messages/stream`：在会话下发送用户消息，并通过 SSE 流式返回 assistant 生成过程和最终消息。
- `GET /api/v1/agent-sessions/{session_id}/messages`：查询会话消息列表。
- `POST /api/v1/nl2sql/generate`：基于 Agentic RAG 检索业务知识并生成只读统计 SQL，返回检索计划、上下文、SQL 和校验结果。