Agent-R1

Agent-R1：使用端到端强化学习训练强大的 LLM 智能体。

一、用途 Agent-R1 是一个统一、模块化的智能体强化学习（Agentic RL）框架，用于训练多步 LLM 智能体。它通过步骤级（step-native）RL 循环训练模型：模型观察环境、生成动作、接收工具或环境反馈，并持续执行直到任务完成或终止。不同于将交互视为单一不断增长的提示-响应对的单轮 RL 流水线，Agent-R1 将每个回合建模为步骤级 MDP 转移，使工具使用、环境状态、上下文管理、奖励分配和策略优化成为同一训练基础中显式的组成部分。

二、背景与设计目标 现代 LLM 基础设施已有 vLLM、SGLang 等强大服务系统，以及 DeepSpeed、FSDP、Megatron-LM 等强大分布式训练系统。智能体 RL 需要将两侧重新连接为 rollout -> reward -> replay -> update 循环，使模型在多回合中与工具和环境交互。

Agent-R1 围绕三个设计目标构建：

1. 步骤级轨迹表示：每次转移存储观察、动作、环境反馈、奖励、终止状态和下一观察，同时保留动作边界，避免脆弱的 Token -> Text -> Token 重建。
2. 灵活的上下文管理：由环境决定模型接下来看到什么，因此历史可以被追加、截断、摘要、重写或增强。
3. 算法-系统解耦：任务工作流、环境、rollout、奖励、优势估计器和策略目标可以独立演进。

三、核心思想：步骤级 MDP 在多回合智能体训练中，模型不只是延续 token 序列。每次模型输出都可能调用工具、改变环境状态、接收外部反馈并塑造下一观察。因此 Agent-R1 将智能体步骤作为基本交互单元：一个步骤记录模型看到了什么、产生了什么动作、环境返回了什么反馈和奖励，以及下一步应暴露什么观察。这种步骤级轨迹表示使 rollout、replay、上下文构建和信用分配与真实智能体决策保持一致，同时仍允许在每个生成动作内部进行 token 级策略损失。Agent-R1 使用分层抽象，使新任务可以复用同一训练器而无需重写整个 RL 栈。

四、主要能力

• 步骤级 MDP 训练基础与分层抽象。
• 在线策略蒸馏（OPD）支持（opd 分支提供通用 OPD 训练支持）。
• StepPO 集成与训练支持。
• 面向 HotpotQA、ALFWorld、WebShop、学术论文搜索的 recipe 集成。
• 多模态支持，用于视觉语言模型智能体。
• 过程奖励（process rewards），用于每次工具调用反馈。
• 推理脚本与交互式聊天界面。
• 重新设计的工具环境，支持更灵活的智能体-工具交互模式。
• 修复了由 NaN 值引起的 GRPO 和 REINFORCE 训练崩溃问题。

五、使用方式 Agent-R1 使用与 verl 相同的环境设置，当前版本要求 verl==0.7.0。只需克隆本仓库，没有单独的 Agent-R1 安装步骤。

主循环为：

1. 加载包含 prompt、agent_name、reward_model 和可选 env_kwargs 的样本。
2. 创建配置好的 AgentFlow 和环境。
3. 从当前观察生成动作。
4. 解析动作，执行工具或更新环境，并返回反馈。
5. 记录步骤并继续，直到 done=True 或达到 max_steps。
6. 将结构化轨迹转换为奖励、优势、掩码和策略更新。

推荐入门路径：

• 阅读 Getting Started 页面以获取最小设置流程。
• 从 ModelScope 下载处理后的数据发布版，然后将每个任务的文件放置或软链接到对应 recipe 期望的路径。
• 使用 examples/gsm8k/run_steppo.sh 作为环境是否正确接线的完整性检查。
• 转到 Agent Task Tutorial 查看基于 ToolEnv + BaseTool 的最小 GSM8K + Tool 示例。
• 阅读 Recipes and Algorithms 了解当前任务集成和启动脚本布局。

可通过 ModelScope CLI 或 git 下载处理后的数据。

阶段 1：基础训练栈完整性检查 使用数据发布版中处理后的 GSM8K 文件，或在本地重新生成最小 GSM8K 数据集，然后运行单步脚本。此阶段仅是设置检查，用于确认环境、模型路径、数据集路径和训练栈是否正确接线。

阶段 2：尝试最小工具调用示例 GSM8K + Tool 是最简单的 ToolEnv + BaseTool 示例。使用数据发布版中处理后的 GSM8K 工具文件，或在本地重新生成工具增强数据集，然后启动多步工具调用脚本。此路径使用通用 AgentEnvLoop 与内置 ToolEnv 和 recipe 本地的 calc_gsm8k_reward 工具。纯 GSM8K 脚本仍是单轮环境完整性检查。

六、构建新智能体任务 对于新任务，保持训练器不变并实现任务特定层。典型迁移检查清单：

• 数据：输出包含 prompt、reward_model、agent_name 和 env_kwargs 的 parquet 行。
• 环境/工具：定义状态更新、工具观察、奖励和终止如何工作。
• 智能体流：将模型动作连接到环境循环并暴露步骤记录。
• 训练脚本：通过 Hydra 覆盖设置路径、rollout 步数、批大小、估计器和策略损失。

七、分支说明

• main 包含当前 v0.1.0 架构，基于 Step-level MDP 和分层抽象。
• legacy 保留先前实现以供参考。 需使用包含本仓库所需 AgentFlow / 异步 rollout 栈的较新 verl 源码检出。

八、使用 Agent-R1 的项目

• TableMind：用于工具增强表格推理的自主程序化智能体。
• PaperScout：使用 Agent-R1 和 Proximal Sequence Policy Optimization 训练的自主学术论文搜索智能体。
• Cast-R1：将时间序列预测重新表述为顺序决策的智能体框架。
• StepPO：面向智能体强化学习的步骤对齐策略优化，一种步骤级 Agentic RL 方法，将智能体步骤视为动作单元并使信用分配与多回合智能体决策对齐。

九、版本与发布记录

• [2026.07.21] 支持在线策略蒸馏（OPD），通用 OPD 训练支持在 opd 分支提供。
• [2026.05.30] 发布大幅修订的 Agent-R1 技术报告，介绍步骤级轨迹表示、灵活上下文管理和智能体强化学习的分层抽象。
• [2026.05.29] 集成 StepPO，扩展 recipe 覆盖范围，发布处理后的数据；包含 HotpotQA、ALFWorld、WebShop 和学术论文搜索的 recipe 集成；处理后数据集在 ModelScope 提供。
• [2026.03.23] Agent-R1 v0.1.0 是重构架构的第一个官方版本，引入 Step-level MDP 基础和新的分层抽象；先前实现归档在 legacy 分支。
• [2026.03.04] 发布 Claw-R1，通过中间件式设计将 Agentic RL 扩展到 OpenClaw 等通用智能体。
• [2026.01.10] 发布 PaperScout。
• [2025.11.18] Agent-R1 技术报告在 arXiv 发布。
• [2025.05.06] 工具环境重新设计；修复 GRPO 和 REINFORCE 训练中 NaN 导致的崩溃。
• [2025.04.01] 添加基础推理脚本和交互式聊天界面。
• [2025.03.18] 添加多模态支持；verl 移至 git 子模块。
• [2025.03.16] 支持过程奖励，用于每次工具调用反馈。

十、致谢 本工作在中国科学技术大学认知智能全国重点实验室完成，感谢 DeepSeek-R1、veRL 和 RAGEN 的思路与基础设施，以及 Qi Liu 教授和 Mingyue Cheng 教授的指导与支持。

项目主页：https://agentr1.github.io/agent-r1 文档：https://agentr1.github.io/agent-r1/docs/ 仓库：https://github.com/0russwest0/Agent-R1

实验快照：Agent-R1 报告在代表性智能体场景中评估了 Qwen3-4B；实验设置、任务覆盖、优化器比较和上下文管理分析见 Experiments 部分。