Agent-R1

最新消息

• [2026年3月23日] Agent-R1 v0.1.0 标志着该项目的第一个正式版本。 它引入了完全重构的代码库、步骤级MDP 基础架构以及新的分层抽象。之前的版本已被归档至 legacy 分支。

• [2026年3月4日] 我们推出了 Claw-R1，这是一个更先进的框架，旨在通过中间件设计，利用代理式强化学习赋能通用智能体（如 OpenClaw 等）。请访问 AgentR1/Claw-R1 了解详情。

概述

Agent-R1 是一个开源框架，用于通过端到端强化学习训练强大的语言智能体。它专为多步智能体任务而设计，在这些任务中，模型会与环境和工具进行多轮交互，而不是仅生成单一的最终答案。

Agent-R1 的核心理念是步骤级MDP：每一步交互都被视为一个完整的强化学习转换，包含由环境定义的状态、LLM的动作以及环境产生的下一次观测。这取代了传统上将所有内容拼接成不断增长的标记序列的做法，提供了一种更为规范且灵活的训练抽象。

借助 Agent-R1，您可以构建自定义的智能体工作流，定义交互式环境和工具，并在统一的强化学习流水线中训练多步智能体。

同时请查看 Awesome-Agent-RL：我们精心整理的关于如何通过强化学习释放智能体潜力的论文和资源合集。

为什么选择 Agent-R1 v0.1.0

Agent-R1 v0.1.0 是新架构的首个正式发布版本。它旨在解决 LLM 智能体强化学习训练中的两种常见问题：

• 基于文本的流水线中的重新标记漂移：如果回放缓冲区的数据以文本形式收集，随后再被重新标记化用于训练，那么“标记 → 文本 → 标记”的转换过程是不可逆的。
• 僵化的纯标记轨迹构建：如果整个交互过程被表示为一个不断增长的标记列表，上下文管理就会被硬编码为简单的追加逻辑。

Agent-R1 通过步骤级轨迹表示解决了这些问题：

• 每个步骤都存储自己的提示和响应
• 下一步的观测由环境而非原始标记拼接来控制
• 上下文可以在步骤之间被截断、摘要化、重写或增强
• 标准的强化学习循环，如 obs -> action -> step -> next_obs，可以自然地映射到智能体训练中

这使得 Agent-R1 更适合处理涉及工具使用、环境反馈和灵活上下文管理的真实多步智能体任务。

版本指南

• 默认的 main 分支包含了基于步骤级MDP和分层抽象的新v0.1.0架构。
• 之前的实现保留在 legacy 分支中，供参考。
• 当前版本使用与 verl 相同的运行时环境，需要 verl==0.7.0。

开始使用

Agent-R1 使用与 verl 相同的环境设置，当前版本要求 verl==0.7.0。您只需克隆此仓库即可，无需单独安装 Agent-R1。

推荐的流程如下：

1. 阅读 入门指南 以了解最小化设置流程。
2. 使用 examples/data_preprocess/gsm8k.py 和 examples/run_qwen2.5-3b.sh 作为 sanity check，确认环境配置正确。
3. 转到 智能体任务教程，了解基于多步交互和工具使用的 Agent-R1 主要工作流。

第一阶段：检查基础训练堆栈是否正常

准备一个最小化的 GSM8K 数据集并运行单步脚本：

python3 examples/data_preprocess/gsm8k.py --local_save_dir ~/data/gsm8k
bash examples/run_qwen2.5-3b.sh

这一阶段仅用于设置检查，帮助确认您的环境、模型路径、数据集路径和训练堆栈配置无误。

第二阶段：运行主要的 Agent-R1 工作流

准备工具增强型数据集并启动多步智能体训练脚本：

python3 examples/data_preprocess/gsm8k_tool.py --local_save_dir ~/data/gsm8k_tool
bash examples/run_qwen3-4b_gsm8k_tool.sh

这是 Agent-R1 的主要路径，其中 AgentEnvLoop 负责驱动多步回放缓冲区的生成，而 ToolEnv 则处理工具调用和环境反馈。

核心概念：

• 步骤级MDP
• 分层抽象

使用 Agent-R1 的优秀项目

以下是一些基于 Agent-R1 构建的代表性项目：

• TableMind：一种用于工具增强型表格推理的自主程序化智能体。TableMind 基于 Agent-R1 框架，利用其端到端强化学习流水线，训练出专门用于结构化表格理解的智能体。
• PaperScout：一款基于 Agent-R1 构建的学术论文搜索自主智能体。它引入了近端序列策略优化（PSPO），这是一种考虑流程的方法，用于将标记级别的优化与序列级别的智能体交互对齐。

致谢

本工作在中国科学技术大学认知智能国家重点实验室开展。我们衷心感谢DeepSeek-R1、veRL和RAGEN提供的启发性思路与早期见解，这些都对Agent-R1的开发产生了重要影响。同时，我们也真诚地感谢刘琪教授和程明月教授的指导与支持。

引用

如果您在研究中使用了Agent-R1，请引用以下文献：

@misc{cheng2025agentr1trainingpowerfulllm,
  title={Agent-R1: Training Powerful LLM Agents with End-to-End Reinforcement Learning},
  author={Mingyue Cheng and Jie Ouyang and Shuo Yu and Ruiran Yan and Yucong Luo and Zirui Liu and Daoyu Wang and Qi Liu and Enhong Chen},
  year={2025},
  eprint={2511.14460},
  archivePrefix={arXiv},
  primaryClass={cs.CL},
  url={https://arxiv.org/abs/2511.14460}
}

星标历史

Agent-R1 快速上手指南

Agent-R1 是一个基于端到端强化学习（End-to-End RL）训练强大 LLM Agent 的开源框架。其核心创新在于**步级 MDP（Step-level MDP）**架构，将每一步交互视为独立的 RL 转换，有效解决了传统文本流水线中的重分词漂移和上下文管理僵化问题，特别适用于多步工具调用和环境交互任务。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• Python: 3.8+
• GPU: 支持 CUDA 的 NVIDIA GPU（建议显存 24GB+ 以运行较大模型）

前置依赖

Agent-R1 v0.1.0 复用 veRL 的运行时环境，无需单独安装 Agent-R1 包，但必须严格匹配 veRL 版本。

• 核心依赖: verl==0.7.0
• 其他依赖: PyTorch, Transformers, Ray 等（由 veRL 统一管理）

国内加速建议： 在安装 Python 依赖时，推荐使用清华或阿里镜像源以提升下载速度：

export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# 或
export PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

安装步骤

Agent-R1 采用源码运行模式，只需克隆仓库并配置好 veRL 环境即可。

1. 克隆仓库

   git clone https://github.com/AgentR1/Agent-R1.git
   cd Agent-R1
   

2. 安装 veRL 运行时环境 请确保安装指定版本 verl==0.7.0。如果尚未安装 veRL，请参考 veRL 官方安装文档 进行基础环境搭建，然后执行：

   pip install verl==0.7.0
   

   (注：若使用国内镜像，请在命令前确保已设置上述 PIP_INDEX_URL 环境变量)

3. 验证环境 确保 python3 -c "import verl; print(verl.__version__)" 输出 0.7.0。

基本使用

Agent-R1 的使用分为两个阶段：首先是基础训练栈的连通性测试（单步），然后是核心的多步 Agent 工作流。

阶段一：基础环境连通性测试 (Sanity Check)

此步骤用于验证数据集处理、模型路径及训练栈是否配置正确。我们使用 GSM8K 数据集进行单步测试。

1. 准备数据

   python3 examples/data_preprocess/gsm8k.py --local_save_dir ~/data/gsm8k
   

2. 运行单步训练脚本

   bash examples/run_qwen2.5-3b.sh
   

   说明：该脚本默认加载 Qwen2.5-3B 模型。若需更换模型，请编辑脚本中的模型路径参数。

阶段二：运行多步 Agent 工作流

这是 Agent-R1 的核心功能，展示如何利用 AgentEnvLoop 进行多步滚动（rollout）以及通过 ToolEnv 处理工具调用和环境反馈。

1. 准备工具增强型数据

   python3 examples/data_preprocess/gsm8k_tool.py --local_save_dir ~/data/gsm8k_tool
   

2. 启动多步 Agent 训练

   bash examples/run_qwen3-4b_gsm8k_tool.sh
   

   说明：此流程将启动完整的强化学习循环，模型将在多轮交互中学习使用工具解决问题。

进阶学习

完成上述步骤后，建议阅读以下核心概念文档以自定义 Agent 工作流：

• 步级 MDP 核心概念
• 分层抽象架构
• Agent 任务完整教程