{"id":50568829,"url":"https://github.com/xyctruth/x-agent","last_synced_at":"2026-06-04T17:01:56.789Z","repository":{"id":359986454,"uuid":"1246520393","full_name":"xyctruth/x-agent","owner":"xyctruth","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-24T12:20:51.000Z","size":277,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T14:16:49.461Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xyctruth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-22T09:18:45.000Z","updated_at":"2026-05-24T12:20:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xyctruth/x-agent","commit_stats":null,"previous_names":["xyctruth/x-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/xyctruth/x-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xyctruth%2Fx-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xyctruth%2Fx-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xyctruth%2Fx-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xyctruth%2Fx-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xyctruth","download_url":"https://codeload.github.com/xyctruth/x-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xyctruth%2Fx-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33914548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-04T17:01:55.839Z","updated_at":"2026-06-04T17:01:56.778Z","avatar_url":"https://github.com/xyctruth.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# x-agent\n\n`x-agent` 是一个用于学习并实践生产级 Python AI Agent 服务的项目。目标是构建一个高可用、可扩展、边界清晰的 Agent 服务。\n\n这个项目从第一版开始就按照真实服务的方式组织：清晰分层、明确开发流程、类型化业务代码、测试、lint、类型检查，以及服务职责文档。\n\n## 架构\n\n初始架构包含以下层次：\n\n- Client 层：SDK、CLI、Web 客户端和外部调用方。\n- API 层：FastAPI 路由、请求校验、响应 Schema 和错误映射。\n- Application 层：用例编排、事务边界和应用服务。\n- Domain 层：不依赖框架或基础设施的业务概念。\n- Agent 层：Agent 会话、规划、上下文管理和执行策略。\n- Execution 层：工具运行时、重试、超时和后台执行。\n- Persistence 层：repository 和持久化状态。\n- Infrastructure 层：配置、日志、LLM Provider、数据库、队列和外部 API。\n\n更多说明见 [docs/architecture.md](docs/architecture.md)。\n\n## 开发\n\n安装依赖：\n\n```bash\nuv sync --extra dev\n```\n\n也可以使用 Makefile：\n\n```bash\nmake sync\n```\n\n启动服务：\n\n```bash\nuv run fastapi dev src/x_agent/main.py\n```\n\n也可以直接使用 `uvicorn`：\n\n```bash\nuv run uvicorn x_agent.main:create_app --factory --reload\n```\n\n运行检查：\n\n```bash\nuv run ruff format --check .\nuv run ruff check .\nuv run mypy src tests\nuv run pytest\n```\n\n或：\n\n```bash\nmake check\n```\n\n启动前端：\n\n```bash\ncd web\nnpm install\nnpm run dev\n```\n\n前端默认连接 `http://127.0.0.1:8000`，可以通过 `VITE_X_AGENT_API_BASE_URL` 覆盖。\n\n### 接入千问\n\n默认使用确定性的 SimpleAgent。接入千问时通过环境变量启用，不要把 API Key 写入代码或文档：\n\n```bash\nexport X_AGENT_LLM_PROVIDER=qwen\nexport X_AGENT_QWEN_API_KEY=\"你的百炼 API Key\"\nexport X_AGENT_QWEN_BASE_URL=\"https://dashscope.aliyuncs.com/compatible-mode/v1\"\nexport X_AGENT_QWEN_MODEL=\"qwen-plus\"\nuv run fastapi dev src/x_agent/main.py\n```\n\n也兼容官方环境变量：\n\n```bash\nexport DASHSCOPE_API_KEY=\"你的百炼 API Key\"\n```\n\n### 初始化 Mock MySQL 业务库\n\n项目提供本地 MySQL 8.0 mock 业务库，用于测试自然语言转统计 SQL、后续只读 SQL 执行和数据分析能力：\n\n```bash\nmake start-mysql\nbash scripts/init_mock_mysql.sh\n```\n\n默认连接 `127.0.0.1:3306`，用户和密码均为 `root`，数据库名为 `x_agent_mock_biz`。MySQL Docker 数据挂载到 `.data/mysql`。可以通过 `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_USER`、`MYSQL_PASSWORD`、`MYSQL_DATABASE` 环境变量覆盖。\n\n一条命令启动 MySQL、Qdrant 并初始化 mock 业务库：\n\n```bash\nmake up\n```\n\n### 启用 NL2SQL MySQL metadata 检索\n\nNL2SQL 默认从本地 mock MySQL 的 `information_schema` 读取真实表结构、字段注释、外键和索引信息：\n\n```bash\nexport X_AGENT_NL2SQL_KNOWLEDGE_SOURCE=mysql\nexport X_AGENT_MYSQL_HOST=127.0.0.1\nexport X_AGENT_MYSQL_PORT=3306\nexport X_AGENT_MYSQL_USER=root\nexport X_AGENT_MYSQL_PASSWORD=root\nexport X_AGENT_MYSQL_DATABASE=x_agent_mock_biz\nuv run fastapi dev src/x_agent/main.py\n```\n\n启用后，服务会组合使用 MySQL metadata 和静态业务知识。MySQL metadata 负责真实表结构，静态知识库继续提供指标定义、业务术语和历史 SQL 样例。\n\n如果需要在无数据库环境下临时运行，可以切回进程内静态知识库：\n\n```bash\nexport X_AGENT_NL2SQL_KNOWLEDGE_SOURCE=memory\n```\n\n### 启用 NL2SQL 向量知识库\n\n向量模式使用 Qdrant 存储知识向量，使用千问 `text-embedding-v4` 生成 embedding：\n\n```bash\nmake start-qdrant\n\nexport X_AGENT_QWEN_API_KEY=\"你的百炼 API Key\"\nexport X_AGENT_NL2SQL_KNOWLEDGE_SOURCE=vector\nexport X_AGENT_EMBEDDING_PROVIDER=qwen\nexport X_AGENT_QWEN_EMBEDDING_MODEL=text-embedding-v4\nexport X_AGENT_EMBEDDING_DIMENSIONS=1024\nexport X_AGENT_QDRANT_URL=http://127.0.0.1:6333\nexport X_AGENT_QDRANT_COLLECTION=nl2sql_knowledge\nexport X_AGENT_NL2SQL_VECTOR_SCORE_THRESHOLD=0.5\n\nmake ingest-nl2sql\nuv run fastapi dev src/x_agent/main.py\n```\n\nQdrant Docker 数据挂载到 `.data/qdrant`。ingest 脚本会读取 MySQL metadata 和静态业务知识，生成向量后写入 Qdrant collection。服务运行时会对用户问题生成 query embedding，再按检索计划中的知识类型和相似度阈值从 Qdrant 召回相似知识。\n\n## 当前 API\n\n- `GET /healthz`：存活检查和基础服务元数据。\n- `GET /readyz`：服务就绪检查。\n- `GET /api/v1/service-info`：服务职责和支持的架构分层。\n- `POST /api/v1/agent-sessions`：创建 Agent 会话。\n- `GET /api/v1/agent-sessions/{session_id}`：查询 Agent 会话。\n- `POST /api/v1/agent-sessions/{session_id}/messages`：在会话下发送用户消息，并返回本次新增的 user/assistant 消息。\n- `POST /api/v1/agent-sessions/{session_id}/messages/stream`：在会话下发送用户消息，并通过 SSE 流式返回 assistant 生成过程和最终消息。\n- `GET /api/v1/agent-sessions/{session_id}/messages`：查询会话消息列表。\n- `POST /api/v1/nl2sql/generate`：基于 Agentic RAG 检索业务知识并生成只读统计 SQL，返回检索计划、上下文、SQL 和校验结果。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxyctruth%2Fx-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxyctruth%2Fx-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxyctruth%2Fx-agent/lists"}