xagent

一、项目概览

XAgent 是一个功能强大的 AI Agent 操作系统，具有良好的兼容性和扩展性。项目使用 Python 3.11+ 开发，支持多种 LLM 提供商（OpenAI、Claude、Gemini、Zhipu 等），集成了 RAG 知识库、工具系统、Web 界面等核心功能。

二、目录结构

src/xagent/
├── config.py              # 统一配置管理模块
├── core/                  # 核心组件
│   ├── agent/            # Agent 类和执行模式
│   ├── model/            # LLM 模型集成（chat/embedding/rerank/image/tts）
│   ├── tools/            # 工具系统 (core/ + adapters/)
│   ├── memory/           # 记忆存储
│   ├── storage/          # 存储管理
│   ├── observability/    # 可观测性 (Langfuse)
│   └── retry/            # 重试机制
├── web/                   # FastAPI Web 应用
│   ├── api/              # API 端点
│   ├── models/           # 数据库模型
│   ├── services/         # 业务服务
│   └── channels/        # 集成渠道 (Feishu/Telegram)
├── providers/             # 第三方 provider
│   ├── pdf_parser/      # PDF 解析
│   └── vector_store/     # 向量存储 (LanceDB/Chroma/Milvus)
├── db/                    # 数据库配置和迁移
├── migrations/            # Alembic 迁移脚本
├── skills/                # Skills 管理
├── templates/             # Agent 模板
└── sandbox/               # 沙箱环境

三、核心架构分析

3.1 Agent 系统 (agent.py)

• 支持嵌套子 Agent (add_sub_agent)
• 支持多种执行模式 (ReAct、DAG plan-execute)
• 集成 Memory Store 和 LLM
• 提供执行历史查询功能

3.2 工具系统 (tools/)

核心工具 (core/):

工具	功能
file_tool	文件操作
python_executor	Python 代码执行
javascript_executor	JS 代码执行 (pptxgenjs)
browser_use	浏览器自动化
document_parser	文档解析
excel	Excel 操作
web_search	Web 搜索
image_tool / vision_tool	图像处理
calculator	数学计算
sql_tool	SQL 查询

RAG 工具 (RAG_tools/):

• 文档分块 (chunk/)
• 向量存储 (vector_storage/)
• 混合检索 (retrieval/)
• 文档摄取管道 (pipelines/)

MCP 工具 (mcp/):

• Model Context Protocol 支持
• Docker 管理器

3.3 模型集成 (model/)

支持多种 LLM 提供商适配器：

• OpenAI (openai.py)
• Anthropic Claude (claude.py)
• Google Gemini (gemini.py)
• Zhipu (zhipu.py)
• XInference (xinference.py)

3.4 配置系统 (config.py)

统一配置管理，优先从环境变量读取：

• XAGENT_STORAGE_ROOT - 存储根目录
• XAGENT_UPLOADS_DIR - 上传目录
• XAGENT_WEB_DIR - Web 模块目录
• XAGENT_EXTERNAL_SKILLS_LIBRARY_DIRS - 扩展 skills 目录

四、Web 界面 (web/)

基于 FastAPI 构建，提供：

• REST API (api/)
• WebSocket 实时通信 (websocket.py)
• 认证系统 (auth_config.py, auth_dependencies.py)
• Channel 集成 (飞书、Telegram Bot)

前端 (frontend/)

• Next.js 14 App Router
• TypeScript
• Tailwind CSS
• shadcn/ui 组件库

五、依赖分析 (pyproject.toml)

核心依赖:

• langchain >= 0.3.26 - Agent 框架
• fastapi >= 0.35.0 - Web 框架
• lancedb >= 0.13.0 - 向量数据库
• sqlalchemy >= 2.0.0 - ORM
• mcp >= 1.12.4 - Model Context Protocol

可选依赖:

• document-processing - 文档处理
• ai-document - AI 文档处理 (docling)
• browser - 浏览器自动化 (playwright)
• chromadb / milvus - 替代向量存储

六、特点与亮点

1. 配置统一管理: 所有路径配置通过 config.py 集中管理，支持环境变量覆盖
2. 工具自动发现: 遵循 get_{tool_name}_tool() 命名规范
3. 多模型支持: 统一的适配器模式支持多种 LLM
4. RAG 完善: 完整的文档处理、分割、存储、检索流程
5. 沙箱安全: sandboxed_tool/ 提供安全的工具执行环境
6. 可观测性: Langfuse 集成追踪和监控
7. Skills 系统: 支持扩展的 Agent 技能库

七、待改进点

1. 配置管理: 文档建议使用 pydantic-settings 增强类型安全
2. 循环依赖: config.py 需确保无循环依赖
3. 文档: 部分核心模块文档可更完善