Agent-R1 文档

页面定位

Agent-R1 围绕 Getting Started、Core Concepts 和 Tutorials 三条主线组织内容。 这份页面优先聚焦最关键的阅读内容，方便第一次接触的人按顺序建立整体理解。

阅读路线

环境准备

第一次使用 Agent-R1，不建议直接把注意力放在复杂 Agent 任务上，先把当前主线的 AgentEnvLoop + ToolEnv 训练闭环跑通更重要。你真正需要确认的是四件事： 兼容的 verl 源码环境、模型路径、数据路径，以及 GPU/显存条件。

• 先按 verl 官方安装方式准备环境，但使用包含 AgentFlow、async rollout、reward-loop 与 verl.trainer.config package-data API 的近期源码版本。
• Agent-R1 本身不需要作为独立包额外安装；在同一个环境里 clone 仓库后，从仓库根目录直接运行脚本即可。
• 基础模型路径需要先能被训练脚本读到。默认示例使用 Qwen/Qwen3-4B-Instruct-2507，也可以通过 Hydra override 换成本地路径。
• 数据集路径、输出目录和缓存目录最好一开始就设成绝对路径，减少路径歧义。
• 如果你用的是已有环境，先跑 GSM8K-tool sanity check，而不是一上来跑 HotpotQA、ALFWorld 或 WebShop。

第一次跑通

Agent-R1 的第一次成功，不是指“最终模型效果很好”，而是指训练入口、模型路径、数据路径和 rollout 逻辑已经能形成完整闭环。一个常见做法是先跑最小任务，确认日志能正常前进、loss 有更新、输出目录生成。

# Stage 1: 准备工具增强 GSM8K 数据
python3 examples/data_preprocess/gsm8k_tool.py --local_save_dir ~/data/gsm8k_tool

# Stage 2: 跑通 AgentEnvLoop + ToolEnv 主线训练脚本
bash examples/run_qwen3-4b_gsm8k_tool.sh

# 可选：切换到 StepPO recipe
bash examples/run_qwen3-4b_gsm8k_tool_steppo.sh

examples/run_qwen3-4b_gsm8k_tool.sh 的入口是 python3 -m agent_r1.trainer.main_agent_ppo，默认设置 algorithm.adv_estimator=grpo、 actor_rollout_ref.rollout.agent.default_agent_flow=agent_env_loop、 actor_rollout_ref.rollout.agent.max_steps=5。 脚本末尾保留 $@，因此可以直接追加 Hydra overrides。

# 常见 override：换模型路径或 GPU 数
bash examples/run_qwen3-4b_gsm8k_tool.sh \
  actor_rollout_ref.model.path=/path/to/Qwen3-4B \
  trainer.n_gpus_per_node=4

排错建议

Agent-R1 初次失败时，大多数问题并不来自 Step-level MDP 本身，而是来自环境、路径或脚本参数。 建议把排查顺序固定下来，不要同时改很多东西。

Step-level MDP

Agent-R1 的核心判断是：多步 Agent 任务不应该只被看成“一个越来越长的 prompt”，而应该被视为真正的 step-level reinforcement learning 过程。每一轮交互都包含状态、动作、环境反馈和终止判断。

轨迹表示的演进路线

在 Step-level MDP 之下，轨迹表示不只是“怎么存历史”，更决定了 rollout 回放时训练信号是否仍然忠实于原始交互。 因此更准确的理解方式，是把它看成一条从 text-space 到 token-space， 再到 structured step-level 的演进路线。

1. Text-Space: 先有 messages

最早的多轮 Agent 系统通常把历史存成一组 messages。它的优点是直观、兼容 chat API， 但问题在于 rollout 实际是在 token 空间里生成的：如果先把原始 token 解码成文本，再在训练时重新 tokenize， 回放得到的 token 序列就可能和 rollout 时并不一致。

2. Flat Token-Space: 再到 token in, token out

引入 token in, token out 的核心目的，是避免这种 retokenization drift。 直接保存 token id 后，训练回放可以和 rollout 时的 token 边界、mask、log-prob 与 reward 对齐， 从而保证 replay 的数学一致性。

对 Agent-R1 来说，这个问题其实在比较早期就已经以 bug 的形式暴露出来了。最初大家并不是先从抽象概念出发讨论 token in, token out，而是在多轮轨迹拼接与回放过程中先碰到了 token 对齐错误，并优先把它修掉。 之后社区才逐渐把这类做法总结为更统一的 token in, token out 视角。相关讨论可见 Issue #30。

Flat Token-Space 为什么还不够

它虽然解决了“训练回放不忠实”的问题，但仍把整条多步交互看成一条 append-only 的扁平 token 序列。 一旦你想对中间上下文做截断、摘要、重组或插入环境反馈，就会破坏原始序列的一体性； 同时，这种严格的 token 控制也和真实部署里常见的 chat API 形态存在落差。

3. Structured Step-Level: 最终到 step-based sequence

Agent-R1 进一步把轨迹拆成按 step 组织的结构化转移。每一步都保留自己的状态 s_t、动作 a_t 和反馈 r_t，而环境返回则进入下一步 s_{t+1} 的构造。这样既保持了 step 内部的 token 一致性，也让上下文管理终于能在 step 边界上被显式控制。

这条演进路线的关键不是“表示越来越复杂”，而是先解决 replay fidelity，再进一步解决多步 Agent 场景里的上下文管理与训练部署错位问题。

一个值得记住的历史点

Agent-R1 对这类问题的识别并不是后见之明。早期实现里，团队已经在 Issue #30 中遇到并修复了由解码再编码带来的轨迹错位问题；后来，“直接在 token 空间里保持 rollout 与 replay 一致”才逐渐被更系统地抽象为 token in, token out。

这件事后续也对社区产生了实际影响。比如 veRL 的 Issue #2188 就把 Agent-R1 Issue #30 作为多轮 Agentic RL 调试问题的公开案例之一来引用。这也说明，Agent-R1 对这类轨迹一致性问题的发现与修复，确实较早为社区提供了可参考的经验。

分层抽象

Agent-R1 把任务组织拆成多层抽象，这样做的目的是让你在迁移新任务时，只替换真正需要替换的那一层， 而不是把整个训练流程重写一遍。

交互闭环

理解 Agent-R1 最稳的方法，是把它想成“模型 + 环境 + 工具”的闭环。模型每一步的输出不是终点， 而是下一轮环境更新的输入。

任务结构

在 Agent-R1 里，一个样本通常不只是 prompt。它还可以带上 agent_name、 env_kwargs 等字段，让环境在样本级别获得上下文与控制参数。GSM8K-tool 是最小完整例子： 每条样本指定 agent_env_loop，并通过 env_kwargs 创建一个带 calc_gsm8k_reward 工具的 ToolEnv。

{
  "data_source": "openai/gsm8k",
  "agent_name": "agent_env_loop",
  "prompt": [{"role": "system", "content": "..."}],
  "reward_model": {"style": "rule", "ground_truth": "..."},
  "env_kwargs": {
    "env_type": "tool",
    "tools": ["calc_gsm8k_reward"],
    "tool_format": "hermes",
    "tools_kwargs": {"ground_truth": "<answer>"}
  }
}

训练工作流

如果把 Agent-R1 的真实训练过程压缩成一条路径，可以概括为“样本准备 → 环境实例化 → 多步交互 → 奖励/终止 → 训练更新”。这个顺序在理解源码时很重要。

迁移新任务

把 Agent-R1 从现有案例迁移到你的新任务时，最有效的方法不是大范围改源码，而是沿着三层结构逐步改： 数据、环境/工具、训练脚本。

recipe/<task>/
  base.yaml
  prepare_<task>_agent_r1.py
  <task>_agent_flow.py
  reward_fn.py
  prompts.py
  utils.py

支持的数据集与算法

Agent-R1 不是绑定在单个 benchmark 上的训练脚本，而是一套可复用的 Agentic RL 训练框架。 当前本地仓库已经包含从数学推理、检索问答到具身环境和网页购物的多类任务 recipe； 同一个任务也可以通过不同 algorithm.adv_estimator 与 policy loss 组合切换算法。

支持的数据集 / 环境

支持的算法 / 优势估计

脚本与配置

实际使用中，脚本通常承担三类信息：模型与数据路径、训练资源参数、任务相关超参。 第一次修改脚本时，优先改“路径和资源”，最后再改“任务逻辑”。Agent-R1 的示例脚本都支持在命令末尾追加 Hydra overrides，因此常见实验不需要复制一份新脚本。

数据准备入口

# GSM8K Tool
python3 examples/data_preprocess/gsm8k_tool.py --local_save_dir ~/data/gsm8k_tool

# HotpotQA + retrieval corpus
python3 recipe/hotpotqa/prepare_hotpotqa_agent_r1.py \
  --output_dir data/corpus/hotpotqa \
  --corpus_output_path data/corpus/hotpotqa_corpus/hpqa_corpus.jsonl

# Paper Search
python3 recipe/paper_search/prepare_paper_search_agent_r1.py \
  --input_dir recipe/paper_search/inference/datasets/AutoScholarQuery \
  --output_dir data/pasa

# ALFWorld / WebShop
python3 recipe/alfworld/prepare_alfworld_agent_r1.py \
  --input_dir alfworld_data/json_2.1.1 \
  --output_dir data/alfworld
python3 recipe/webshop/prepare_webshop_agent_r1.py \
  --dataset_mode small \
  --input_dir webshop_data \
  --output_dir data/webshop

常用训练脚本

算法切换

Agent-R1 将 advantage estimator 与 policy loss 解耦。常用 algorithm.adv_estimator 包括 gae、token_gae、grpo、rloo、 reinforce_plus_plus、reinforce_plus_plus_baseline 和 gigpo。 StepPO 组合可理解为 step-level GAE 加 GSPO policy loss。

常见问题

补充资源

下面这些链接适合继续查看更完整的章节、源码和技术报告，作为延伸阅读入口使用。