# x-deepagents **Repository Path**: chain-engine/x-deepagents ## Basic Information - **Project Name**: x-deepagents - **Description**: 一个完整的 DeepAgents（处理复杂、多步骤任务的智能体） 学习与实践项目 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-22 - **Last Updated**: 2026-03-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # X-DeepAgents
**一个完整的 DeepAgents 学习与实践项目** [![Python 3.11](https://img.shields.io/badge/Python-3.11-blue.svg)](https://www.python.org/) [![LangChain](https://img.shields.io/badge/LangChain-0.3+-green.svg)](https://github.com/langchain-ai/langchain) [![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-teal.svg)](https://fastapi.tiangolo.com/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
--- ## 📖 项目介绍 X-DeepAgents 是一个可直接运行、可二次开发、可服务化部署的 DeepAgents 学习与实践项目。 它围绕“市场研究报告自动生成”这一真实场景，完整覆盖了以下链路： - 任务输入（CLI 或 API） - 主代理规划与分解（`write_todos`） - 多子代理协作执行（研究员 / 分析师 / 撰写员） - 工具调用（搜索、分析、落盘） - 结果输出（报告文件 + API 返回） ### 项目定位 - **学习者视角**：看懂 DeepAgents 在真实项目中的落地方式 - **开发者视角**：复用现有框架，快速扩展子代理/工具 - **应用者视角**：通过 CLI 或 HTTP API 快速接入业务系统 ### 功能特性 | 功能 | 说明 | |------|------| | **多代理协作** | 研究员、分析师、撰写员协作完成复杂研究任务 | | **任务自动分解** | 主代理使用 `write_todos` 自动规划执行路径 | | **双入口接入** | 同时支持 `CLI` 和 `HTTP API` | | **异步任务与流式进度** | API 支持 `job_id` 异步任务与 SSE 流式反馈 | | **报告自动落盘** | 研究结果默认保存至 `reports/` 目录 | | **多模型支持** | 支持 DeepSeek / kimi2.5 / glm4.7 / 阿里云 / 豆包 | ### 配置说明 #### 1) 环境变量（`.env`） 复制 `.env.example` 为 `.env`，至少配置一个可用 LLM 的 `API_KEY`： | 提供者 | 关键环境变量 | 默认模型变量 | |--------|--------------|--------------| | DeepSeek | `DEEPSEEK_API_KEY` | `DEEPSEEK_MODEL_NAME` | | kimi2.5 | `KIMI_API_KEY` | `KIMI_MODEL_NAME` | | glm4.7 | `GLM_API_KEY` | `GLM_MODEL_NAME` | | 阿里云 | `ALIYUN_API_KEY` | `ALIYUN_MODEL_NAME` | | 豆包 | `DOUBAO_API_KEY` | `DOUBAO_MODEL_NAME` | 另外，搜索能力依赖： - `TAVILY_API_KEY` #### 2) 应用配置（`config.yaml`） 项目默认配置包括： - 服务端口（`server.port`，默认 `8000`） - 日志级别与轮转策略（`logging`） - 代理执行参数（`agent.*`） - 报告输出目录与信息源上限（`research.*`） --- ## 🏗️ 系统图示 ### 1) 整体结构图 ```text +------------------------------------------------------------------------+ | X-DeepAgents 系统架构 | +------------------------------------------------------------------------+ | v +------------------------------------------------------------------------+ | 用户交互层 (CLI / HTTP API) | | src/cli.py + src/api.py | +------------------------------------------------------------------------+ | v +------------------------------------------------------------------------+ | 主代理协调器 (Coordinator) | | src/agents/coordinator.py | | +------------------------------------------------------------------+ | | | DeepAgents 核心引擎 | | | | - write_todos (任务规划) - filesystem (文件操作) | | | | - task (子代理生成) - store (长期记忆) | | | +------------------------------------------------------------------+ | +------------------------------------------------------------------------+ | +-----------------------+-----------------------+ | | | v v v +---------------------+ +---------------------+ +---------------------+ | 研究员代理 | | 分析师代理 | | 撰写员代理 | | Researcher | | Analyst | | Writer | +---------------------+ +---------------------+ +---------------------+ | v +------------------------------------------------------------------------+ | 工具层 / 模型层 / 基础设施层 | | tools + llm providers + core(config/logger) | +------------------------------------------------------------------------+ ``` ### 2) 工作流程图 ```text 用户输入研究主题 | v 主代理规划任务（write_todos） | v 分发给子代理（researcher / analyst / writer） | v 并行/串行执行 + 工具调用（搜索、分析、写作） | v 汇总结果 + 质量检查 | v 输出报告（API返回 + reports/*.md） ``` ### 3) DeepAgents 生态架构图 ```text +------------------------------------------------------------------------+ | DeepAgents 生态架构 | +------------------------------------------------------------------------+ | v +------------------------------------------------------------------------+ | Agent Harness: DeepAgents / Claude Agent SDK | | （内置工具、预设提示、子代理能力） | +------------------------------------------------------------------------+ ^ | +------------------------------------------------------------------------+ | Agent Framework: LangChain / CrewAI / LlamaIndex | | （抽象层、组件化、工具接口） | +------------------------------------------------------------------------+ ^ | +------------------------------------------------------------------------+ | Agent Runtime: LangGraph / Temporal | | （状态管理、持久化、流式传输） | +------------------------------------------------------------------------+ ``` --- ## 📁 项目结构 ```text x-deepagents/ ├── src/ │ ├── agents/ │ │ └── coordinator.py # 主代理协调器（多代理编排核心） │ ├── core/ │ │ ├── config.py # 配置加载（.env + config.yaml） │ │ └── logger.py # 日志管理 │ ├── llm/ │ │ └── providers.py # 多 LLM 提供者适配 │ ├── tools/ │ │ └── __init__.py # 搜索/分析/报告保存工具 │ ├── api.py # FastAPI 服务入口（同步+异步+SSE） │ └── cli.py # 命令行入口（交互式/单次查询） ├── examples/ │ └── multi_agent.py ├── reports/ # 报告输出目录 ├── logs/ # 日志目录 ├── config.yaml # 应用配置 ├── .env.example # 环境变量模板 ├── Dockerfile ├── docker-compose.yml ├── pyproject.toml # 依赖与脚本（market-research） └── README.md ``` --- ## ⚡ 快速开始 本章节提供运行方式总览与本地开发启动步骤，便于快速完成环境验证与功能跑通。 ### 1) 环境要求 - Python `3.11+` - [uv](https://github.com/astral-sh/uv) - Docker（可选） ### 2) 初始化项目 ```bash git clone https://github.com/chain-engine/x-deepagents.git cd x-deepagents ``` 安装依赖： ```bash uv sync ``` 配置环境变量： ```bash # Linux / macOS / Git Bash cp .env.example .env # Windows PowerShell # copy .env.example .env ``` 然后编辑 `.env`，至少填写一个 LLM 的 `API_KEY`。 ### 3) 运行方式总览 | 入口类型 | 本地运行 | Docker 运行 | 推荐场景 | |---------|---------|------------|---------| | **CLI** | `uv run market-research ...` | `docker compose run --rm x-deepagents python /app/src/cli.py ...` | 一次性任务、调试、人工操作 | | **HTTP API** | `uv run python -m src.api` | `docker compose up --build -d` | 系统集成、前后端联调、服务化部署 | > 说明：Docker 是运行环境，不是 API 本身。 > 同一套核心能力可通过 CLI 和 HTTP API 两种入口使用。 ### 4) 本地运行（推荐开发调试） #### A. CLI（最快） ```bash # 交互模式 uv run market-research # 单次查询 uv run market-research "中国新能源汽车市场分析报告" # 简单模式（单代理） uv run market-research -s "人工智能行业投资机会" ``` #### B. HTTP API ```bash uv run python -m src.api ``` 本地验证： ```bash curl http://localhost:8000/health ``` 同步调用： ```bash curl -X POST http://localhost:8000/research \ -H "Content-Type: application/json" \ -d "{\"query\":\"中国新能源汽车市场分析报告\",\"simple\":false,\"verbose\":false}" ``` 异步调用（推荐长任务）： ```bash # 1) 启动任务，获取 job_id curl -s -X POST http://localhost:8000/research/start \ -H "Content-Type: application/json" \ -d "{\"query\":\"中国新能源汽车市场分析报告\",\"simple\":false,\"verbose\":false}" # 2) 流式查看进度 curl -N http://localhost:8000/jobs/JOB_ID/stream # 3) 查询最终结果 curl http://localhost:8000/jobs/JOB_ID ``` 接口文档： - Swagger UI: `http://localhost:8000/docs` - ReDoc: `http://localhost:8000/redoc` ### 5) Docker 运行（部署/隔离环境） #### A. 启动 HTTP API（推荐） ```bash docker compose up --build -d curl http://localhost:8000/health ``` #### B. Docker 内执行 CLI（可选） ```bash docker compose run --rm x-deepagents python /app/src/cli.py "中国新能源汽车市场分析报告" docker compose run --rm x-deepagents python /app/src/cli.py -s "人工智能行业投资机会" ``` --- ## 🔌 API 一览 | 方法 | 路径 | 说明 | |------|------|------| | `GET` | `/health` | 健康检查 | | `POST` | `/research` | 同步执行研究，返回最终结果 | | `POST` | `/research/start` | 异步创建任务，返回 `job_id` | | `GET` | `/jobs/{job_id}` | 查询任务状态和结果 | | `GET` | `/jobs/{job_id}/stream` | SSE 流式获取任务进度 | --- ## 🧩 扩展开发 ### 添加新的子代理 在 `src/agents/` 中新增代理并接入 `coordinator.py` 编排流程。 ### 添加新的工具 在 `src/tools/` 中实现工具函数，并在代理执行链路中按需调用。 ### 调整模型/日志/执行策略 - 模型与密钥：`.env` - 端口、日志、研究参数：`config.yaml` --- ## ❓ 常见问题 ### 1) 运行时报“未检测到 API 密钥” 请检查 `.env` 是否存在且至少包含一个可用密钥（如 `DEEPSEEK_API_KEY`）。 ### 2) API 能启动但研究失败 通常是外部模型或搜索服务配置问题，建议先： - 调用 `/health` 确认服务存活 - 使用 `simple=true` 测试最小链路 - 检查 `logs/` 下日志文件 ### 3) 报告保存在哪里？ 默认输出目录是 `reports/`（可在 `config.yaml` 中修改）。 --- ## 📖 参考资料 - [DeepAgents 官方文档](https://python.langchain.com/docs/deepagents/) - [LangChain 文档](https://python.langchain.com/) - [LangGraph 文档](https://langchain-ai.github.io/langgraph/) --- ## 📄 许可证 本项目采用 MIT 许可证，详见 [LICENSE](LICENSE)。