一种具有可扩展工具集的通用推理智能体

如果您喜欢我们的项目，请在 GitHub 上为我们点亮一颗星 ⭐，以获取最新更新。

📣 最新消息

• [2026年1月14日]：🎉 DeepAgent 已被 WWW 2026 接收！
• [2025年10月28日]：🔥 我们很荣幸成为 Hugging Face 每日论文 #1 的亮点。
• [2025年10月27日]：📄 我们的论文现已发布在 arXiv 和 Hugging Face 上。
• [2025年10月27日]：🚀 我们的代码库已发布。现在您可以使用像 QwQ、Qwen3 这样的推理模型以及您自己的工具集来部署 DeepAgent。

🎬 演示

1. 带有16,000多种RapidAPIs的通用智能体任务

DeepAgent 是一种具有可扩展工具集的推理智能体，能够在端到端的智能体推理过程中，从超过16,000个RapidAPI中搜索并使用合适的工具来完成通用任务。(注：由于ToolBench中的部分API无法使用，本演示中API响应由LLM模拟，以展示系统的正常功能。)

2. ALFWorld环境中的具身AI智能体任务

DeepAgent 还擅长导航类任务（如网页浏览、操作系统交互和具身AI），它使用一系列多功能的可插拔动作，例如移动、观察和拾取。

3. 带有专用工具的深度研究任务

DeepAgent 也可以作为强大的科研助手，配备用于网络搜索、浏览、代码执行、视觉问答和文件处理的专用工具。

💡 概述

DeepAgent 是一种端到端的深度推理智能体，它在一个连贯的推理过程中完成自主思考、工具发现和动作执行。这种范式摆脱了传统的预定义工作流程（如ReAct的“思考-行动-观察”循环），使智能体能够保持对整个任务的全局视角，并根据需要动态发现工具。

为了应对长期交互并防止陷入错误的探索路径，我们引入了 自主记忆折叠 机制。这使得DeepAgent可以通过将交互历史压缩成一种结构化的、受大脑启发的记忆模式来“喘口气”，从而重新考虑其策略并高效推进。

此外，我们提出了 ToolPO，这是一种专为通用工具使用设计的端到端强化学习训练方法，可以提升智能体掌握这些复杂机制的能力。

📊 总体性能

我们在广泛的基准测试上进行了大量实验：

• (1) 通用工具使用任务： 我们在ToolBench、API-Bank、TMDB、Spotify和ToolHop上评估了DeepAgent，这些基准涵盖了从几十种到一万多种不同工具的工具集。
• (2) 下游应用： 我们测试了它在ALFWorld、WebShop、GAIA和人类终极考试（HLE）中的表现，这些任务需要使用特定领域的工具集。图中的总体结果显示，DeepAgent在所有场景中都表现出色。

✨ DeepAgent框架

关键特性：

• 统一的智能体推理： DeepAgent摒弃了僵化的预定义工作流程。它在一个单一的思想流中运行，自主地对任务进行推理、动态地发现所需的工具并执行动作。这使得LRM能够保持全局视角，并充分发挥其自主潜力。

• 自主记忆折叠与受大脑启发的记忆： 面对复杂问题时，DeepAgent可以自主触发记忆折叠。这一过程将交互历史整合为一种结构化的记忆，使智能体能够以精简但全面的理解重新开始推理。该记忆架构受大脑启发，包括：

  • 情景记忆： 对关键事件、决策和子任务完成情况的高层次记录。
  • 工作记忆： 包含最近的信息，包括当前的子目标和近期计划。
  • 工具记忆： 整合与工具相关的交互，使智能体能够从经验中学习并优化其策略。

• 基于ToolPO的端到端强化学习训练： 为了有效训练智能体，我们引入了ToolPO，这是一种策略优化方法，具有以下特点：

  • 基于LLM的工具模拟器，可模拟真实世界的API，确保训练稳定高效。
  • 工具调用优势归因，可为正确的工具调用标记分配细粒度的奖励，从而提供更精确的学习信号。

🔧 安装

环境设置

# 创建 conda 环境
conda create -n deepagent python=3.10
conda activate deepagent

# 安装依赖
cd DeepAgent-main
pip install -r requirements.txt

📊 基准测试

我们使用的基准测试可分为几类：

• 通用工具使用基准：
  • ToolBench：包含 16,000 多个需要多步、多工具推理的真实 RapidAPI。
  • API-Bank：通过 314 个由人类标注的对话，评估规划、检索和调用 73 个 API 的能力。
  • RestBench：模拟 REST API 应用程序，场景包括 TMDB（54 个工具）和 Spotify（40 个工具）。
  • ToolHop：测试跨 3,912 个本地可执行工具的多跳推理，需进行 3–7 次连续调用。
• 具身智能体基准：
  • ALFWorld：基于文本的具身 AI 环境，智能体通过 9 种基本动作完成家务任务。
• 网页导航基准：
  • WebShop：在线购物模拟，要求智能体搜索和导航商品以满足用户需求。
• 深度研究基准：
  • GAIA：复杂的资讯检索任务，涉及网络搜索、浏览、VQA、代码执行和文件处理。
  • 人类终极考试 (HLE)：极具挑战性的推理问题，测试代码、搜索和 VQA 工具等高级能力。为高效测试，我们从包含 2,500 道题的完整数据集中抽取了 500 道题。

所有预处理好的数据都位于 ./data/ 目录中，除了 ToolBench 数据需要从 ToolBench 官方仓库 下载，因为其体积过大，无法放入我们的仓库。

🤖 模型服务

在运行 DeepAgent 之前，请确保您的推理模型和辅助模型已使用 vLLM 提供服务。DeepAgent 旨在与强大的推理模型作为主代理协同工作，并可利用辅助模型执行记忆生成和工具选择等任务。更多详情请参阅 [vLLM](https://github.com/vllm-project/vllm)。

对于主推理模型，我们推荐以下几种模型。性能从上到下逐渐提升，但计算成本也随之增加。您可以根据自身需求选择性价比合适的模型：

模型	参数量	类型	链接
Qwen3-4B-Thinking	40亿	思考型	🤗 HuggingFace
Qwen3-8B	80亿	混合型	🤗 HuggingFace
Qwen3-30B-A3B-Thinking	300亿	思考型	🤗 HuggingFace
QwQ-32B	320亿	思考型	🤗 HuggingFace
DeepAgent-QwQ-32B	320亿	思考型	🤗 HuggingFace
Qwen3-235B-A22B-Thinking	2350亿	思考型	🤗 HuggingFace

对于辅助模型，我们建议使用与主推理模型参数相近的 Qwen2.5-Instruct 或 Qwen3-Instruct 系列模型，但无需思考能力，以加快推理速度。

⚙️ 配置

所有配置均位于 ./config/base_config.yaml 文件中，包括 API 密钥、服务 URL 和路径。您需要将其修改为实际配置：

1. API 配置

根据您的任务选择并配置相应的 API：

• ToolBench (RapidAPI)：
  • toolbench_api：用于 ToolBench 的 RapidAPI 密钥。您可以从 ToolBench 官方仓库 获取。
  • toolbench_service_url：ToolBench 服务 URL。保持默认即可使用 ToolBench 的官方服务。
• 深度研究：
  • google_serper_api：用于网络搜索的 Google Serper API 密钥。您可在此申请：serper.dev。
  • use_jina：是否使用 Jina Reader 来稳定地获取 URL 内容。
  • jina_api_key：Jina API 密钥。您可在此申请：jina.ai/api-dashboard/reader。
• RestBench (TMDB 和 Spotify)：
  • tmdb_access_token：TMDB 访问令牌。您可在此获取 TMDB API 密钥：developer.themoviedb.org/docs/getting-started。
  • spotify_client_id：Spotify 客户端 ID。您可在此获取 Spotify API 密钥：developer.spotify.com/documentation/web-api。
  • spotify_client_secret：Spotify 客户端密钥。
  • spotify_redirect_uri：Spotify 重定向 URI。
• WebShop：
  • webshop_service_url：WebShop 服务 URL。您可根据 WebShop 官方仓库 中的说明创建新环境并在本地提供服务。

2. 模型配置

在配置文件中设置您的模型端点：

• 主推理 LLM：

  • model_name：您部署的推理模型名称（如 QwQ-32B）。
  • base_url：推理模型服务的 API 端点（如 http://0.0.0.0:8080/v1）。
  • api_key：访问推理模型服务的 API 密钥。如果您使用 vLLM，则设为 empty。
  • tokenizer_path：推理模型分词器文件的本地路径。

• 辅助 LLM：

  • aux_model_name：您部署的辅助模型名称（如 Qwen2.5-32B-Instruct）。
  • aux_base_url：辅助模型服务的 API 端点。
  • aux_api_key：辅助模型的 API 密钥。如果您使用 vLLM，则设为 empty。
  • aux_tokenizer_path：辅助模型分词器文件的本地路径。

• VQA 模型（用于 GAIA 和 HLE 中的图像输入）：

  • vqa_model_name：您部署的视觉语言模型名称（如 Qwen2.5-VL-32B-Instruct）。模型服务方法见 [模型服务]。
  • vqa_base_url：VQA 模型服务的 API 端点。
  • vqa_api_key：VQA 模型的 API 密钥。如果您使用 vLLM，则设为 empty。

• 工具检索器：

  • tool_retriever_model_path：工具检索器模型的本地路径（例如 ./models/bge-large-en-v1.5）。
  • tool_retriever_api_base：工具检索器服务的 API 端点。预先部署可以避免每次运行系统时都重新加载检索器模型。你可以使用以下命令进行部署：

  python src/run_tool_search_server.py \
      --base_config_path ./config/base_config.yaml \
      --datasets toolbench,toolhop,tmdb,spotify,api_bank \
      --host 0.0.0.0 \
      --port 8001
  

3. 数据路径配置

所有基准数据集都存储在 ./data/ 目录下。如有需要，你可以修改这些路径。

🚀 运行 DeepAgent

要在启用工具搜索的情况下对某个基准数据集进行运行，可使用以下命令：

python src/run_deep_agent.py \
    --config_path ./config/base_config.yaml \
    --dataset_name toolbench \
    --enable_tool_search \
    --eval

若要在闭集模式下对某个基准数据集进行运行，则使用以下命令：

python src/run_deep_agent.py \
    --config_path ./config/base_config.yaml \
    --dataset_name gaia \
    --eval

参数说明：

• --config_path：主配置文件的路径。
• --dataset_name：要使用的数据集名称（例如 toolbench、api_bank、tmdb、spotify、toolhop、gaia、hle、alfworld、webshop）。
• --subset_num：从数据集中运行的样本数量。
• --concurrent_limit：最大并发请求数。默认值为 32。
• --enable_tool_search：允许智能体搜索工具。如果禁用，则仅使用任务提供的工具（闭集模式）。
• --enable_thought_folding：允许智能体使用思维折叠机制。
• --max_action_limit：每道题目的最大动作数（包括工具搜索和工具调用）。
• --max_fold_limit：每道题目的最大思维折叠次数。
• --top_k：返回的搜索工具的最大数量。
• --eval：生成结果后对结果进行评估。

多工具失败问题排查

如果 DeepAgent 在运行 ToolBench 或其他多工具基准测试时出现卡住、不断选择奇怪工具或忽略工具输出的情况，请参阅 docs/multi_tool_agent_failure_modes.md 中的逐步检查清单。

评估

我们的模型推理脚本可以自动保存模型的输入和输出以便进行评估。要运行评估，在执行 ./src/run_deep_agent.py 时添加 --eval 标志即可。各数据集的评估脚本位于 ./src/evaluate/ 目录下。

🔥 深度研究智能体家族

欢迎试用我们的深度研究智能体系列：

DeepAgent：具有可扩展工具集的通用推理智能体（WWW 2026）
简述： 一个端到端的深度推理智能体，通过受大脑启发的记忆折叠机制，实现自主思考、工具发现和动作执行。

代理式熵平衡策略优化（WWW 2026）
简述： 一种代理式的强化学习算法，旨在在回放和策略更新阶段平衡熵。

代理式强化策略优化（ICLR 2026）
简述： 一种代理式的强化学习算法，鼓励策略模型在高熵的工具调用回合中自适应地进行分支采样，

解耦规划与执行：面向深度搜索的层次化推理框架
简述： 该框架通过专门的智能体，将深度搜索分层解耦为战略规划和领域特定的执行。

Tool-Star：通过强化学习赋能大模型脑的多工具推理器
简述： 一个端到端的TIR后训练框架，通过自我批评强化学习设计，使大模型能够自主地与多工具环境交互。

WebThinker：赋予大型推理模型深度研究能力（NeurIPS 2025）
简述： 一个深度研究智能体，赋予大型推理模型自主搜索、网页浏览和撰写研究报告的能力。

Search-o1：代理式搜索增强型大型推理模型（EMNLP 2025）
简述： 一个代理式搜索增强框架，通过代理式RAG和文档内推理模块，将自主知识检索与大型推理模型相结合。

📄 引用

如果您觉得这项工作对您有帮助，请引用我们的论文：

@misc{deepagent,
      title={DeepAgent: 一个具有可扩展工具集的通用推理智能体}, 
      author={李晓溪、焦文翔、金嘉睿、董冠廷、金家杰、王一诺、王浩、朱宇涛、文继荣、陆元、窦志成},
      year={2025},
      eprint={2510.21618},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2510.21618}, 
}

📄 许可证

本项目采用 MIT 许可证 开源。

📞 联系方式

如有任何问题或反馈，请通过 xiaoxi_li@ruc.edu.cn 与我们联系。

星标历史

DeepAgent 快速上手指南

DeepAgent 是一个具备可扩展工具集的通用推理智能体（General Reasoning Agent）。它能够在端到端的推理过程中自主思考、动态发现工具并执行动作，适用于通用工具调用、具身智能（Embodied AI）及深度研究等多种场景。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux 或 macOS (Windows 用户建议使用 WSL2)
• Python 版本: 3.9 或更高 (推荐 3.10)
• 包管理器: Conda (推荐) 或 pip
• 模型服务: 需部署 vLLM 服务以运行推理模型和辅助模型

前置依赖

您需要预先准备好以下 API Key（根据具体任务选择配置）：

• 通用工具任务: RapidAPI Key (ToolBench)
• 深度研究任务: Google Serper API Key, Jina API Key
• 特定基准测试: TMDB Token, Spotify Client ID/Secret 等

2. 安装步骤

2.1 创建虚拟环境

推荐使用 Conda 创建独立的 Python 环境：

conda create -n deepagent python=3.10
conda activate deepagent

2.2 克隆代码与安装依赖

下载项目代码并安装所需依赖包：

git clone https://github.com/your-repo/DeepAgent.git
cd DeepAgent-main
pip install -r requirements.txt

提示: 国内用户若下载依赖较慢，可添加清华源加速： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 基本使用

3.1 启动模型服务

DeepAgent 依赖 vLLM 部署主推理模型（Reasoning Model）和辅助模型（Auxiliary Model）。

推荐模型组合：

• 主模型: QwQ-32B, Qwen3-30B-A3B-Thinking 或微调版 DeepAgent-QwQ-32B
• 辅助模型: Qwen2.5-Instruct 或 Qwen3-Instruct (同参数量级，无思考模式以加速推理)

请使用 vLLM 启动服务（示例）：

python -m vllm.entrypoints.api_server --model Qwen/QwQ-32B --port 8000

3.2 配置文件修改

编辑 ./config/base_config.yaml 文件，填入您的 API Key 和服务地址。

关键配置项示例：

# ToolBench 任务配置
toolbench_api: "YOUR_RAPIDAPI_KEY"
toolbench_service_url: "http://default-toolbench-service"

# 深度研究任务配置
google_serper_api: "YOUR_SERPER_API_KEY"
use_jina: true
jina_api_key: "YOUR_JINA_API_KEY"

# 模型服务地址
reasoning_model_url: "http://localhost:8000/v1"
auxiliary_model_url: "http://localhost:8001/v1"

3.3 运行智能体

配置完成后，即可运行 DeepAgent 执行任务。以下是一个通用的运行命令示例（具体脚本名称请参考项目 scripts 目录）：

python run_agent.py \
    --config ./config/base_config.yaml \
    --task_type "general_tool_use" \
    --query "帮我查找北京明天的天气并推荐附近的餐厅"

运行说明：

• --task_type: 指定任务类型，如 general_tool_use (通用工具), embodied_ai (具身智能), deep_research (深度研究)。
• --query: 输入您的自然语言指令。
• 系统将自动进行“自主记忆折叠”（Autonomous Memory Folding），动态调用工具并输出最终结果。

---

更多详细基准测试数据集请查看 ./data/ 目录，或访问 HuggingFace 数据集页面获取。