No GPU, no LLM calls, no PyTorch — agentic RL training from scratch, in pure Python notebooks that run in seconds on a laptop.
听过 RLHF / DPO / GRPO / RLVR，但始终拼不出一张完整图景？这个仓库把 Agentic RL 的训练闭环拆成可以亲手验算的最小教学对象，在你的笔记本上几秒钟跑通这条主线：
agent loop -> trajectory -> reward -> advantage -> policy update
- 不需要 GPU，不调用任何 LLM，连 PyTorch 都不用装：核心三章只用 Python 标准库，把 token 级 policy 降维成离散动作的 softmax 策略——概念一个不少， 每个中间产物（trajectory、reward breakdown、loss mask、group advantage、 logit 更新）都打印出来给你看。
- 所有 notebook 自带运行输出（seed 固定、逐字可复现）：不装环境， 在 GitHub 上点开就能读完全程。
- 学完直接对接真实框架：最后两章桥接 TRL
GRPOTrainer和 verl 的 tool / reward 扩展点。
适合这些读者：
- 会写基本 LLM agent / tool-use workflow。
- 听过 RLHF、DPO、GRPO、RLVR，但容易混在一起。
- 想知道多轮 agent 为什么要记录 trajectory，为什么 tool observation 要 mask。
- 想先用小代码看懂概念，再接 TRL / verl / OpenRLHF 这类真实框架。
主线按站点顺序走：00 -> 01 -> 02 是必修（纯 stdlib，CPU 秒级跑完），
03 -> 04 是选修的真实框架桥接。每个站点先读配套 docs，再跑 notebook。
| 学习站点 | Notebook | 配套 docs 章 | 你会看到什么 | 必修/选修 |
|---|---|---|---|---|
| 起点：分清四个词 | —（纯阅读） | docs/01 | RLHF / DPO / RLVR / Agentic RL 到底差在哪 | 必修 |
| 00 Toy MDP | 00_toy_mdp.ipynb | docs/02；跑完 notebook 后选读附录推导 | reward -> advantage -> policy update 的最小数学过程 |
必修 |
| 01 Tool-Math Agent | 01_tool_math_agent.ipynb | docs/03、docs/04、docs/06 | 多轮 agent 的 trajectory、reward breakdown、loss mask、group advantage | 必修 |
| 02 GRPO Tool Agent | 02_grpo_tool_agent.ipynb | docs/05 | 完整 GRPO 闭环：训练信号让 agent 从乱用工具变成正确用工具 | 必修 |
| 03 GRPO Single-Turn | 03_grpo_single_turn.ipynb | docs/05 | reward / group advantage 接到 TRL GRPOTrainer 的接口形状 |
选修 |
| 04 verl Minimal | 04_verl_minimal.ipynb | —（notebook 与 README 自含） | 教学对象映射到 verl 的 tool / reward 扩展点 | 选修 |
docs/
README.md
01_rlhf_dpo_rlvr_agentic_rl.md
02_agent_loop_as_mdp.md
03_trajectory_and_mask.md
04_reward_design.md
05_grpo_ppo_intuition.md
06_tool_math_walkthrough.md
appendix_softmax_policy_gradient.md
examples/
00_toy_mdp/ # Notebook + pure Python script, teaches policy update
01_tool_math_agent/ # Notebook + Tool-Math trajectory/mask/reward demo
02_grpo_tool_agent/ # Notebook + GRPO closed loop on the Tool-Math env
03_grpo_single_turn/ # Notebook + optional TRL warm-up
04_verl_minimal/ # Notebook + optional verl bridge
scripts/
build_notebooks.py # Single source for all notebooks; do not edit .ipynb by hand.
# Build executes every notebook and commits the outputs
# (seed-fixed, reproducible); --no-execute skips execution.
tests/
test_toy_mdp.py
test_tool_math_agent.py
test_grpo_tool_agent.py
test_grpo_single_turn.py
requirements.txt # Jupyter tooling; core scripts are stdlib-only
requirements-optional.txt # torch / TRL for the optional bridges
Requires Python 3.10+ (the code uses zip(strict=...)).
Recommended path: use notebooks for learning, and keep scripts for smoke tests.
git clone https://github.com/ManagerYu10/agentic-rl-from-scratch.git
cd agentic-rl-from-scratch
python3 --version # 需要 3.10+；低于 3.10（如 macOS 自带的 3.9）请先升级，例如 brew install python@3.12
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python -m ipykernel install --user --name agentic-rl-from-scratch --display-name "Python (agentic-rl-from-scratch)"
jupyter notebook装好环境后，按上面的学习地图走：第一站先读
docs/01 分清几个容易混淆的词，
再打开 examples/00_toy_mdp/00_toy_mdp.ipynb。
If you use VS Code instead of the Jupyter web UI, open the notebook, click
Select Kernel, and choose Python (agentic-rl-from-scratch).
The core scripts use only the Python standard library, so they also run without installing anything:
python3 examples/00_toy_mdp/toy_policy_update.py
python3 examples/01_tool_math_agent/tool_math_agent.py
python3 examples/02_grpo_tool_agent/grpo_tool_agent.py
python3 -m unittest discover -s testsOptional training backends:
python3 -m pip install -r requirements-optional.txt
python3 examples/03_grpo_single_turn/train_grpo_single_turn.py注意版本口径：仓库本体只需要 Python 3.10+；这组可选依赖（torch / TRL）建议放在 单独的 Python 3.11/3.12 venv 里安装——预编译包对解释器版本有支持范围，太新或太旧 的版本经常装不上（详见 03 章 notebook 的可选一节）。
The optional scripts are intentionally secondary. Read and run the pure Python examples first.
This repo uses one simple trajectory schema throughout:
messages user / assistant / tool messages
actions assistant actions, such as tool_call or final_answer
observations tool or environment outputs
reward scalar reward plus breakdown
loss_mask 1 for assistant-generated tokens, 0 for user/tool tokens
这不是生产级 schema，而是教学 schema。真实框架会把这些内容进一步 tokenized、 batched、distributed，但概念不变。
- 不重新实现生产级 PPO / GRPO。
- 不替代 TRL、verl、OpenRLHF、Agent Lightning。
- 不追求大模型分数。
- 不把普通 agent workflow 包装成已经训练过的 Agentic RL。
The value here is clarity: small code, printed intermediate artifacts, and chapter-by-chapter concept alignment.