RAGEN: 通过强化推理来训练智能体

诊断智能体故障模式，优化你的 RL（强化学习）训练。

RAGEN (Reasoning AGENT) 是一个用于训练推理智能体的灵活 RL 框架。 我们开发了诊断工具，旨在深入理解智能体 RL 训练的运作机制，并修复其中的隐藏问题。

正在寻找 V1 版本的 README？ 请查看这里。

新闻

• 2026.3.12. 我们非常激动地发布了 RAGEN-2！我们引入了关于智能体 RL 中推理崩溃（reasoning collapse）的系统性研究，以及用于稳定训练的轻量级干预措施。详见 v2 论文。
• 2025.4.20. RAGEN V1 论文 在 arXiv 上发表。
• 2025.1.27. RAGEN 首次发布。推文链接。

关于项目

RAGEN 基于 StarPO (State-Thinking-Actions-Reward Policy Optimization，状态-思考-行动-奖励策略优化) 构建，这是一个统一的 RL 框架，用于训练多轮、轨迹级（trajectory-level）智能体，并支持对推理过程、奖励分配机制和提示词 rollout（采样）结构的灵活控制。

RAGEN 的灵活性体现在：

• StarPO 框架。 支持多轮智能体的统一优化，同时支持轨迹级和轮次级（turn-wise）训练。
• 10 个内置环境。 涵盖 Sokoban, FrozenLake, WebShop, DeepCoder, SearchQA, Lean, Bandit, Countdown, MetaMathQA, Sudoku。
• 兼容 Gym 的接口。 轻松添加自定义环境。

RAGEN-2 额外引入了：

• SNR-Adaptive Filtering (V2)。 基于奖励方差的轻量级 rollout 过滤机制，以减轻噪声梯度更新的影响。
• 推理崩溃诊断 (V2)。 用于在训练期间检测和监控模板崩溃（template collapse）的互信息（Mutual Information）代理指标。

算法

StarPO：通过轨迹级优化强化推理

StarPO (State-Thinking-Action-Reward Policy Optimization) 框架包含两个交替阶段：rollout 阶段和更新阶段。LLM 生成推理引导的动作来与环境交互，收集轨迹级奖励以共同优化推理和行动策略。

MDP 公式化。 智能体与环境的交互被公式化为马尔可夫决策过程 (MDP)，其中状态和动作均为 Token 序列，使得 LLM 能够在环境动态中进行推理。目标是最大化多轮交互中的预期累积奖励。

Rollout 阶段。 给定初始状态，LLM 生成多条轨迹。在每一步，模型都会产生一个推理引导的动作：... action 。环境返回反馈（奖励和下一个状态）。

更新阶段。 StarPO 使用重要性采样（importance sampling）优化整个轨迹。它支持：

• PPO。 通过轨迹上的价值函数（value function）进行 Token 级的优势估计。
• GRPO。 将归一化奖励分配给完整轨迹。

V2：诊断模板崩溃

仅靠熵（Entropy）无法检测模板崩溃（即推理在单个输入内看起来多样，但在跨输入时却变得与输入无关）。RAGEN-2 将推理质量分解为两个维度：

• 输入内多样性： 条件熵 H(Z|X)
• 跨输入可区分性： 互信息 I(X;Z)

SNR-Adaptive Filtering 使用奖励方差作为轻量级代理指标，在每次迭代中选择高信号提示词，从而直接解决模板崩溃的根本原因。

更新日志

2026.3.12. RAGEN-2 发布！查看我们的 v2 论文。

历史更新：

• 2025.5.8. 官方 文档 发布。注意：该文档现已过时。
• 2025.5.2. 发布了用于记录小型代码库更新的 追踪文档。
• 2025.4.20. RAGEN V1 论文 发布。代码库重构：集成 veRL 作为子模块；架构拆分为三个模块——环境状态管理器（Environment State Manager）、上下文管理器（Context Manager）和智能体代理（Agent Proxy）。
• 2025.3.13. RAGEN 代码库正在重构中。详见 developing 分支。
• 2025.3.8. 修复了 veRL 中的 KL 项问题 链接。默认优势估计器改为 GAE (PPO) 以实现更稳定的训练。
• 2025.1.27. RAGEN 首次发布。推文链接。

开始使用

git clone https://github.com/mll-lab-nu/RAGEN.git
cd RAGEN
conda create -n ragen python=3.12 -y && conda activate ragen
bash scripts/setup_ragen.sh

使用 bash scripts/setup_ragen.sh --with-search 来包含搜索环境。有关 WebShop 的说明，请参阅 docs/experiment_webshop_release.md。

四种推理范式

RAGEN-2 在两个轴上诊断智能体行为——输入内多样性（条件熵）和...