RAGEN（Reasoning AGENt）是一个用于训练推理型 LLM 智能体的灵活强化学习框架，基于 StarPO 算法构建，支持多轮强化学习。项目同时开发了诊断工具，用于理解智能体强化学习训练的工作机制，并修复 Echo Trap（RAGEN）和推理崩溃（RAGEN-2）等隐藏的失败模式。
用途：训练具备推理能力的 LLM 智能体，通过多轮强化学习优化其在环境中的推理与行动策略，并对训练过程进行诊断和稳定性改进。
主要能力：
- StarPO 框架：面向多轮智能体的统一优化，支持轨迹级与轮次级训练。
- 10 个内置环境：Sokoban、FrozenLake、WebShop、DeepCoder、SearchQA、Lean、Bandit、Countdown、MetaMathQA、Sudoku。
- Gym 兼容接口：便于添加自定义环境。
- RAGEN-2 额外引入：
- SNR 自适应过滤（V2）：基于奖励方差的轻量级 rollout 过滤，用于缓解噪声梯度更新。
- 推理崩溃诊断（V2）：通过互信息代理指标检测和监控训练中的模板坍缩。
StarPO 原理：StarPO（State-Thinking-Action-Reward Policy Optimization）包含两个交错阶段：rollout 阶段和 update 阶段。LLM 生成推理引导的动作与环境交互，收集轨迹级奖励，联合优化推理与行动策略。
- MDP 建模：智能体与环境的交互被建模为马尔可夫决策过程，状态和动作均为 token 序列，使 LLM 能够对环境动态进行推理，目标是最大化多轮交互的期望累计奖励。
- Rollout 阶段：给定初始状态，LLM 生成多条轨迹。每一步模型产生推理引导的动作：<think>...</think><ans> action </ans>，环境返回反馈（奖励与下一状态）。
- Update 阶段：StarPO 使用重要性采样优化整条轨迹，支持 PPO（通过价值函数进行 token 级优势估计）和 GRPO（将归一化奖励分配给整条轨迹）。
V2 模板坍缩诊断：仅凭熵无法检测模板坍缩（推理在单个输入内看似多样，但跨输入时变得与输入无关）。RAGEN-2 将推理质量分解为两个维度：
- 输入内多样性：条件熵 H(Z|X)
- 跨输入可区分性：互信息 I(X;Z) SNR 自适应过滤使用奖励方差作为轻量级代理，在每次迭代中选择高信号 prompt，直接针对模板坍缩的根因。
四种推理模式：RAGEN-2 沿两个轴诊断智能体行为——输入内多样性（条件熵）和跨输入可区分性（互信息）——得到四种不同的推理模式。输入驱动的推理会适应当前状态；模板化推理则在不同输入下产生几乎相同的响应。模板坍缩（高熵、低互信息）对现有基于熵的指标不可见。
使用方式： 运行 bash scripts/setup_ragen.sh --with-search 可包含搜索环境。WebShop 相关配置参见 docs/experiment_webshop_release.md。训练时可不使用过滤（默认），或使用 SNR 自适应过滤（V2，Top-p）。更多过滤策略（Top-k、线性模式等）参见 Rollout Filtering Guide。
适用场景：需要训练多轮推理型 LLM 智能体的研究或工程场景，例如在 Sokoban、FrozenLake、WebShop、DeepCoder、SearchQA 等环境中进行智能体强化学习，并需要诊断训练质量、识别模板坍缩或推理崩溃等问题。
限制：官方文档说明部分文档已过时，更新版本将后续发布；当前未提供收费、价格等信息。
