# 第 26 课：Tool Use 与 Agentic RL

这一课讲 `trainer/train_agent.py`：MiniMind 如何把工具调用从“会输出一段 `<tool_call>` 文本”推进到“多轮 rollout 中调用工具、观察结果、继续生成，并用延迟 reward 做 GRPO/CISPO 更新”。

本节不覆盖完整 Agent 系统设计。这里的 Agentic RL 是 MiniMind 项目里的狭义版本：固定工具集、mock 工具环境、有限多轮交互、规则/GT/reward model 组合打分。

## 目录

- [0. 本节主线](#l26-mainline)
- [1. 本节要懂的 7 个原理](#l26-principles)
- [2. 完整原理：从 tool call 到 trajectory reward](#l26-complete-principle)
- [3. 源码阅读顺序图](#l26-reading-order)
- [4. MiniMind 源码走读](#l26-source-walkthrough)
- [5. 本节必须会写 / 暂时不要求](#l26-must-write)
- [6. 手写与实验模块](#l26-handwrite)
- [7. 实验验证](#l26-experiment)
- [8. 阶段组装](#l26-stage-assembly)
- [9. 本节检查](#l26-check)
- [10. 下一课](#l26-next)

<a id="l26-mainline"></a>
## 0. 本节主线

MiniMind 的 Tool Use / Agentic RL 链路是：

```text
样本提供 messages + tools + gt
-> chat_template 把 tools 渲染到 system prompt
-> policy 生成 assistant response
-> 从 response 中解析 <tool_call>{json}</tool_call>
-> 执行 mock tool，得到 tool observation
-> 把 tool observation 作为 tool message 拼回 messages
-> 继续下一轮生成，直到没有 tool_call 或达到 max_turns
-> 对整条 trajectory 计算 reward
-> 同 prompt 多条 trajectory 做 group-relative advantage
-> 用 GRPO/CISPO + reference KL 更新 policy
-> eval/API 把模型文本中的 <tool_call> 转成 OpenAI 风格 tool_calls
```

一句话：

```text
Tool calling 是模型生成结构化动作；
Agentic RL 是把动作执行后的观察接回上下文，再用整条轨迹的结果训练模型。
```

本节最容易混的三个对象：

```text
tool schema:
  告诉模型有哪些工具、每个工具需要哪些参数。

tool_call:
  模型生成的动作，格式是 <tool_call>{"name": "...", "arguments": {...}}</tool_call>。

tool_response:
  环境执行动作后的观察，格式是 <tool_response>{...}</tool_response>。
```

第 25 课的 `reward / logprob / KL` 在这里没有换概念，只是 reward 从“单条回答分数”变成“多轮工具轨迹分数”。

<a id="l26-principles"></a>
## 1. 本节要懂的 7 个原理

| 原理 | 要理解什么 | 源码位置 |
|---|---|---|
| 工具协议先由 tokenizer/template 固化 | `<tool_call>`、`<tool_response>` 是模型要学习和解析的文本协议 | `trainer/train_tokenizer.py:35-38`, `model/tokenizer_config.json:333` |
| Agent RL 数据不是 labels 数据 | `AgentRLDataset` 返回 `messages/tools/gt`，训练时在线 rollout，不直接返回 `input_ids/labels` | `dataset/lm_dataset.py:226-252` |
| rollout 是环境循环 | 每轮生成 response，解析 tool_call，执行工具，把 tool observation 拼回上下文 | `trainer/train_agent.py:98-157` |
| 工具调用只是 JSON 文本动作 | 训练端用正则找 `<tool_call>...</tool_call>`，再 `json.loads` 成动作 | `trainer/train_agent.py:76-95`, `scripts/eval_toolcall.py:70-78` |
| reward 是 trajectory 级信号 | 工具合法性、GT 命中、格式闭合、未完成、多余重复、RM 分数共同决定 reward | `trainer/train_agent.py:188-239` |
| policy update 沿用 GRPO/CISPO | Agent 训练仍然使用 group reward、old/current/ref logprob、reference KL 和 mask | `trainer/train_agent.py:242-333` |
| eval/API 要把文本协议转成 tool_calls 字段 | 本地评测和 OpenAI API 服务端都要解析模型输出中的 tool_call | `scripts/eval_toolcall.py:177-199`, `scripts/serve_openai_api.py:83-102` |

学完本节，你应该能解释这些变量：

```text
messages_batch:
  batch 内每条样本的多轮消息前缀，来自 AgentRLDataset。

tools_batch:
  每条样本可用的工具 schema。

gt_batch:
  最终答案校验目标，用来给工具轨迹打规则 reward。

turn_outputs_batch:
  一条 trajectory 中每轮 assistant 生成的文本。

response_ids:
  policy 生成的 response token，加上后续 tool observation delta。

response_mask:
  1 表示 policy 生成 token 参与 loss，0 表示 tool observation / prompt 部分不参与 loss。

response_old_logps:
  rollout 时生成 token 的 old logprob；tool observation token 对应 0.0。

rewards:
  每条 trajectory 的最终标量 reward，shape 是 `[B * num_generations]`。
```

<a id="l26-complete-principle"></a>
## 2. 完整原理：从 tool call 到 trajectory reward

### 2.1 Tool calling 是结构化动作，不是普通文本答案

没有工具时，模型只要生成自然语言答案：

```text
user -> assistant answer
```

有工具时，模型要先生成一个动作：

```text
assistant -> <tool_call>{"name":"calculate_math","arguments":{"expression":"256 * 37"}}</tool_call>
```

这个动作不会直接结束对话。训练脚本会解析它，调用环境里的 mock 工具，拿到观察：

```text
tool -> {"result": "9472"}
```

然后把观察重新放进上下文，让模型继续生成最终答案：

```text
assistant -> 256 乘以 37 等于 9472。
```

所以 Agentic RL 训练的对象不是单个 response，而是一条 trajectory：

```text
prompt
-> assistant action_1
-> tool observation_1
-> assistant action_2
-> tool observation_2
-> ...
-> assistant final_answer
```

### 2.2 为什么需要 response_mask

在一条 trajectory 里，不是所有 token 都是模型生成的。

```text
policy 生成的 assistant token:
  应该参与 policy loss。

tool observation token:
  是环境返回，不是 policy 动作，不应该参与 policy loss。

prompt / system / user token:
  是条件上下文，也不应该参与 policy loss。
```

因此 `train_agent.py` 在 rollout 中维护：

```text
response_ids:
  训练用的 token 序列后半部分。

response_mask:
  哪些 response_ids 是 policy 生成动作。

response_old_logps:
  policy 生成动作对应 rollout logprob；非 policy token 用 0.0 占位。
```

这就是本节比普通 GRPO 多出来的关键点：同一段 `response_ids` 中混有 policy 动作和环境观察，必须用 mask 区分。

### 2.3 Reward 是延迟的

工具调用本身不一定立刻知道好坏。比如：

```text
<tool_call>{"name":"calculate_math","arguments":{"expression":"256 * 37"}}</tool_call>
```

这个动作可能是合法的，但最终答案仍然可能错。

MiniMind 的 Agent reward 因此按整条轨迹打分：

```text
R(trajectory)
= tool call 对齐分
+ final answer GT 命中分
+ thinking / 长度 / 格式分
+ reward model score
- 标签不闭合惩罚
- 未完成惩罚
- 重复惩罚
```

然后 GRPO/CISPO 把同一个 prompt 的多条 trajectory reward 做组内标准化：

```text
advantage = (reward - group_mean) / (group_std + 1e-4)
```

也就是说，模型不是学习“某个 token 本身是否好”，而是学习：

```text
在这个上下文中，生成这些动作 token 后，整条轨迹是否比同题其他轨迹更好。
```

### 2.4 Agentic RL 和 SFT Tool Calling 的区别

SFT Tool Calling 学的是数据里的参考轨迹：

```text
给定已有 messages/tools/tool_calls/tool_response/final answer
-> 让模型拟合 assistant 部分 token
```

Agentic RL 学的是在线采样轨迹：

```text
给定 messages/tools/gt
-> 让模型自己采样 tool_call / final answer
-> 环境执行工具
-> 根据最终轨迹打 reward
-> 用 RL 更新模型
```

所以 `AgentRLDataset` 不需要提前给出完整 assistant labels。它只提供起始状态和校验目标。

<a id="l26-reading-order"></a>
## 3. 源码阅读顺序图

建议按这个顺序读：

```text
1. trainer/train_tokenizer.py:35-38
   先看 tool/reasoning 标签如何进入 tokenizer 训练。

2. model/tokenizer_config.json:333
   看 chat_template 如何把 tools/tool_calls/tool role 渲染成文本协议。

3. dataset/lm_dataset.py:226-252
   看 AgentRLDataset 返回 messages/tools/gt，而不是 labels。

4. trainer/train_agent.py:40-95
   看工具定义、mock 执行、参数校验、tool_call 解析。

5. trainer/train_agent.py:98-180
   看多轮 rollout 如何执行工具并拼回 observation。

6. trainer/train_agent.py:188-239
   看 trajectory reward 的规则项。

7. trainer/train_agent.py:242-333
   看 reward 如何进入 GRPO/CISPO 更新。

8. scripts/eval_toolcall.py:177-199
   看推理侧如何反复 generate -> tool call -> tool result。

9. scripts/serve_openai_api.py:83-102
   看服务端如何把文本中的 <tool_call> 转成 OpenAI 风格 tool_calls 字段。
```

<a id="l26-source-walkthrough"></a>
## 4. MiniMind 源码走读

### 4.1 工具标签进入 tokenizer/template

#### 源码证据 A：工具标签作为额外 token

文件：`trainer/train_tokenizer.py:35-38`

看它是为了理解：MiniMind 在训练 tokenizer 时显式加入工具调用和思考标签。

代码摘录：

```python
additional_tokens_list = [
    "<tool_call>", "</tool_call>",
    "<tool_response>", "</tool_response>",
    "<think>", "</think>"
]
```

这段代码说明：

- 工具协议不是临时字符串，它被纳入 tokenizer 训练配置。
- `<tool_call>` 和 `<tool_response>` 都是模型需要稳定生成/识别的结构标签。
- `<think>` 与 tool calling 在同一套 chat template 里共存。

#### 源码证据 B：chat template 描述工具协议

文件：`model/tokenizer_config.json:333`

看它是为了理解：当 `tools` 存在时，template 会把工具 schema 放入 system prompt，并告诉模型按 `<tool_call>` 包裹 JSON。

代码摘录：

```jinja
{%- if tools %}
    {{- '<|im_start|>system\n' }}
    {{- "# Tools\n\nYou may call one or more functions ..." }}
    {{- "function signatures within <tools></tools> XML tags:\n<tools>" }}
    ...
    {{- "For each function call, return a json object ... within <tool_call></tool_call> XML tags:" }}
{%- endif %}
```

这段代码说明：

- 工具 schema 是 prompt 的一部分，不是模型内部结构。
- 模型输出 tool call 的约束来自 template 提示和 SFT/RL 训练。
- 后续解析器依赖 `<tool_call>...</tool_call>` 标签边界。

### 4.2 数据集只提供起始状态和 GT

#### 源码证据：`AgentRLDataset`

文件：`dataset/lm_dataset.py:226-252`

看它是为了理解：Agent RL 样本不是普通 SFT 的 `input_ids/labels`，而是用于在线 rollout 的环境初始状态。

代码摘录：

```python
class AgentRLDataset(Dataset):
    def __init__(self, jsonl_path, tokenizer, max_length=1024):
        ...
        with open(jsonl_path, 'r', encoding='utf-8') as f:
            for line in f:
                self.samples.append(json.loads(line.strip()))

    def parse_conversations(self, conversations):
        messages = []
        tools = None
        for message in conversations:
            message = dict(message)
            if message.get("role") == "system" and message.get("tools"):
                tools = json.loads(message["tools"]) if isinstance(message["tools"], str) else message["tools"]
            messages.append(message)
        return messages[:-1], tools

    def __getitem__(self, index):
        sample = self.samples[index]
        messages, tools = self.parse_conversations(sample['conversations'])
        return {'messages': messages, 'tools': tools, 'gt': sample['gt']}
```

这段代码说明：

- `messages[:-1]` 会去掉最后一轮，留下模型要开始 rollout 的上下文。
- `tools` 从 system message 里解析出来。
- `gt` 是最终校验目标，用于 reward，不是 labels。
- `__getitem__` 不返回 `input_ids`，因为 tokenization 会在 rollout 时根据多轮上下文动态发生。

README 里的数据格式也说明了这个约定。

文件：`README.md:824-838`

看它是为了理解：SFT/Agent 数据使用 OpenAI 风格消息，`tools` 挂在 system，`tool_calls` 挂在 assistant。

代码摘录：

```json
{"role": "system", "content": "# Tools ...", "tools": "[...]"}
{"role": "user", "content": "帮我算一下 256 乘以 37 等于多少"}
{"role": "assistant", "content": "", "tool_calls": "[{\"name\":\"calculate_math\",\"arguments\":{\"expression\":\"256 * 37\"}}]"}
{"role": "tool", "content": "{\"result\":\"9472\"}"}
{"role": "assistant", "content": "256 乘以 37 等于 9472。"}
```

这段代码说明：

- 监督数据里可以有完整 tool trajectory。
- Agent RL 数据会额外使用 `gt` 作为最终校验目标。
- 当前工作区没有实际 `dataset/agent_rl.jsonl` 文件；训练命令需要你另外准备数据。

### 4.3 工具定义、解析和执行

#### 源码证据 A：固定工具 schema

文件：`trainer/train_agent.py:40-47`

看它是为了理解：训练脚本里的工具集是固定的 function schema 列表。

代码摘录：

```python
TOOLS = [
    {"type": "function", "function": {"name": "calculate_math", ...}},
    {"type": "function", "function": {"name": "unit_converter", ...}},
    {"type": "function", "function": {"name": "get_current_weather", ...}},
    {"type": "function", "function": {"name": "get_current_time", ...}},
    {"type": "function", "function": {"name": "get_exchange_rate", ...}},
    {"type": "function", "function": {"name": "translate_text", ...}},
]
```

这段代码说明：

- Agentic RL 训练不是开放世界工具系统。
- 每个工具都有 `name`、`description`、`parameters`、`required`。
- reward 校验会用这些 schema 判断 tool call 是否有效。

#### 源码证据 B：mock 工具执行和参数校验

文件：`trainer/train_agent.py:56-74`

看它是为了理解：工具环境是训练脚本内置的 mock executor，不是外部真实服务。

代码摘录：

```python
MOCK_RESULTS = {
    "calculate_math": lambda args: {"result": str(eval(...))},
    "unit_converter": lambda args: {"result": round(...)},
    "get_current_weather": lambda args: ...,
    "get_current_time": lambda args: ...,
    "get_exchange_rate": lambda args: ...,
    "translate_text": lambda args: ...,
}

CHECK_ARGS = {
    "calculate_math": lambda a: bool(a.get("expression")),
    "unit_converter": lambda a: a.get("value") is not None and a.get("from_unit") and a.get("to_unit"),
    ...
}
```

这段代码说明：

- `MOCK_RESULTS` 决定动作执行后能拿到什么 observation。
- `CHECK_ARGS` 决定 reward 里的“有效工具调用”。
- 学这节时不要把 mock executor 当成生产级工具沙箱。

#### 源码证据 C：解析 `<tool_call>` 文本

文件：`trainer/train_agent.py:76-95`

看它是为了理解：模型输出先是文本，训练脚本再用正则和 JSON 解析成动作。

代码摘录：

```python
def parse_tool_calls(text):
    calls = []
    for m in re.findall(r'<tool_call>(.*?)</tool_call>', text, re.DOTALL):
        try: calls.append(json.loads(m.strip()))
        except: pass
    return calls

def execute_tool(name, args):
    fn = MOCK_RESULTS.get(name)
    if not fn: return None
    try:
        signal.signal(signal.SIGALRM, ...)
        signal.alarm(1)
        return fn(args)
    except:
        return None
    finally:
        try: signal.alarm(0)
        except: pass
```

这段代码说明：

- 标签不闭合或 JSON 非法时，解析不到有效 tool call。
- 未知工具返回 `None`。
- 执行被 1 秒 alarm 限制，避免简单 mock 函数卡死。
- 解析失败被吞掉，reward 侧再通过格式/GT/工具数量扣分。

### 4.4 多轮 rollout：动作、观察、再生成

#### 源码证据：`rollout_single`

文件：`trainer/train_agent.py:98-157`

看它是为了理解：Agent rollout 不只是 `model.generate` 一次，而是最多多轮“生成 -> 执行工具 -> 拼回上下文”。

代码摘录：

```python
for turn in range(max_turns):
    context = tokenizer.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True,
        tools=tools,
        open_thinking=open_thinking
    )
    inputs = tokenizer(context, return_tensors="pt", add_special_tokens=False).to(device)
    ...
    rollout_result = rollout_engine.rollout(...)
    new_ids = rollout_result.completion_ids[0].tolist()
    new_logps = rollout_result.per_token_logps[0].tolist()
    ...
    calls = parse_tool_calls(new_text)
    if not calls:
        break
    messages.append({"role": "assistant", "content": new_text})
    for call in calls:
        ...
        result = execute_tool(name, raw)
        result_str = (json.dumps(result, ensure_ascii=False) if result else '{"error": "tool not found"}')[:2048]
        messages.append({"role": "tool", "content": result_str})
```

这段代码说明：

- 每一轮都会重新把 `messages` 渲染成 prompt。
- 只有模型生成的 `new_ids/new_logps` 才是 policy action。
- 如果这一轮没有 tool call，trajectory 结束。
- 如果有 tool call，就把 assistant 文本和 tool result 追加到 `messages`，下一轮继续。
- `result_str[:2048]` 防止工具结果太长撑爆后续 tokenizer。

#### 源码证据：tool observation 不参与 policy loss

文件：`trainer/train_agent.py:146-153`

看它是为了理解：工具返回内容会进入训练序列，但 mask 为 0。

代码摘录：

```python
observe_context = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=not unfinished, tools=tools, open_thinking=open_thinking)
observe_ids = tokenizer(observe_context, return_tensors="pt", add_special_tokens=False)["input_ids"][0].tolist()
current_len = len(prompt_ids) + len(response_ids)
obs_delta = observe_ids[current_len:]
response_ids.extend(obs_delta)
response_mask.extend([0] * len(obs_delta))
response_old_logps.extend([0.0] * len(obs_delta))
```

这段代码说明：

- `obs_delta` 是本轮工具观察造成的新增上下文 token。
- 它们会进入 `response_ids`，因为下一轮生成需要看到这些上下文。
- 它们的 `response_mask` 是 0，因此不参与 policy loss。
- 它们没有 rollout logprob，所以 `response_old_logps` 用 0.0 占位。

### 4.5 trajectory reward

#### 源码证据 A：reward 输入

文件：`trainer/train_agent.py:188-200`

看它是为了理解：reward 函数拿到的是 prompt、completion、GT、tools 和多轮输出。

代码摘录：

```python
def calculate_rewards(prompts, completions, gt_batch, tools_batch, num_gen, reward_model=None, device="cuda", turn_outputs_batch=None, unfinished_batch=None):
    rewards = torch.zeros(len(completions), device=device)
    for idx, response in enumerate(completions):
        reward, answer = 0.0, response
        sample_idx = idx // num_gen
        tools = tools_batch[sample_idx]
        turn_outputs = turn_outputs_batch[idx] if turn_outputs_batch is not None else [response]
        unfinished = unfinished_batch[idx] if unfinished_batch is not None else False
        turn_answers = [turn.split('</think>', 1)[-1].strip() if '</think>' in turn else turn.strip() for turn in turn_outputs]
        answer = turn_answers[-1] if turn_answers else response.strip()
        valid_names = {t['function']['name'] for t in tools} if tools else set()
        tool_calls = []
        for turn_answer in turn_answers: tool_calls.extend(parse_tool_calls(turn_answer))
```

这段代码说明：

- `idx // num_gen` 把 flat trajectory 映射回原始样本。
- reward 会看一条 trajectory 的所有 turn，不只看最后一段 completion。
- `valid_names` 来自当前样本可用工具，不是全局工具全集。

#### 源码证据 B：没有 tool call 时走普通回答 reward

文件：`trainer/train_agent.py:201-218`

看它是为了理解：Agent 训练仍然允许不用工具的回答。

代码摘录：

```python
reward -= 0.5 * sum(abs(turn.count('<tool_call>') - turn.count('</tool_call>')) for turn in turn_answers)
if not tool_calls:
    reward += 0.5 if 5 <= len(response.strip()) <= 800 else -0.5
    if '</think>' in response:
        think, answer = response.split('</think>', 1)
        reward += 1.0 if 20 <= len(think.strip()) <= 300 else -0.5
        reward += 0.25 if response.count('</think>') == 1 else -0.25
        answer = answer.strip()
    if reward_model is not None:
        ...
        score = reward_model.get_score(messages, answer)
        reward += score
    reward -= rep_penalty(answer)
    rewards[idx] = max(min(reward, 3.0), -3.0)
```

这段代码说明：

- 标签开闭数量不一致会扣分。
- 没有工具调用时，reward 类似 SFT/RLAIF 的普通回答打分。
- reward model 是可选叠加项。
- 分数最终 clip 到 `[-3.0, 3.0]`。

#### 源码证据 C：有 tool call 时看工具合法性和 GT 命中

文件：`trainer/train_agent.py:219-239`

看它是为了理解：工具轨迹的主要 reward 来自“调用是否对齐”和“最终答案是否命中 GT”。

代码摘录：

```python
else:
    gt = gt_batch[sample_idx]
    valid_call_count = 0
    for tool_call in tool_calls:
        name, raw = tool_call.get("name", ""), tool_call.get("arguments", {})
        if isinstance(raw, str):
            try: raw = json.loads(raw)
            except: raw = {}
        check = CHECK_ARGS.get(name)
        valid_call_count += int(bool(name in valid_names and check and check(raw)))
    tool_gap = abs(valid_call_count - len(gt)) + max(0, len(tool_calls) - valid_call_count)
    reward += 0.5 if tool_gap == 0 else -0.5 * tool_gap

    final_text = "" if unfinished else (answer.split('</tool_call>')[-1] if '</tool_call>' in answer else answer)
    verified = validate_gt_in_text(final_text, gt) if gt else set()
    if gt: reward += 2.5 * len(verified) / len(gt)
    if unfinished: reward -= 0.5
    reward -= rep_penalty(final_text if final_text else answer)
    rewards[idx] = max(min(reward, 3.0), -3.0)
```

这段代码说明：

- 工具名必须在当前样本可用工具里。
- 参数必须通过 `CHECK_ARGS`。
- `tool_gap` 同时惩罚工具数量不匹配和无效调用。
- `validate_gt_in_text` 只检查最终文本，不检查 tool observation 本身。
- 如果达到 `max_turns` 仍未完成，会扣 `unfinished` 分。

### 4.6 Agent RL 更新：GRPO/CISPO 没换

#### 源码证据 A：rollout 后打包 token、mask、old logprob

文件：`trainer/train_agent.py:242-273`

看它是为了理解：多轮 trajectory 最后会被整理成训练张量。

代码摘录：

```python
messages_batch = batch['messages']
tools_batch = batch['tools']
gt_batch = batch['gt']
...
completions, contexts, prompt_ids_batch, response_ids_batch, response_masks_batch, response_old_logps_batch, turn_outputs_batch, unfinished_batch = rollout_batch(...)
...
for p, r, m, old_lp in zip(prompt_ids_batch, response_ids_batch, response_masks_batch, response_old_logps_batch):
    ids = p + r
    mask = [0] * len(p) + m
    old_logps = [0.0] * max(len(p) - 1, 0) + old_lp
    ...
input_ids = torch.tensor(...)
full_response_masks = torch.tensor(...)
old_per_token_logps = torch.tensor(...)
...
rewards = calculate_rewards(...)
```

这段代码说明：

- `ids = prompt + response` 是完整模型输入。
- `mask = prompt_mask_0 + response_mask` 决定哪些 token 是 policy action。
- `old_logps` 要和 `input_ids[:, 1:]` 对齐，所以 prompt 部分长度是 `len(p)-1`。
- reward 在打包后才计算，仍然是每条 trajectory 一个标量。

#### 源码证据 B：current/ref logprob、EOS mask、group advantage

文件：`trainer/train_agent.py:275-318`

看它是为了理解：Agent 训练复用第 24-25 课的 GRPO/CISPO 张量逻辑。

代码摘录：

```python
res = model_unwrapped(input_ids, attention_mask=full_mask)
logits = res.logits[:, :-1, :]
per_token_logps = F.log_softmax(logits, dim=-1).gather(2, input_ids[:, 1:].unsqueeze(-1)).squeeze(-1)

with torch.no_grad():
    ref_per_token_logps = compute_per_token_logps(ref_model, input_ids, input_ids.size(1) - 1, attention_mask=full_mask)

completion_mask = full_response_masks[:, 1:]
...
completion_mask = completion_mask * (pos <= eos_idx.unsqueeze(1)).float()
token_counts = completion_mask.sum(dim=1)
...
grouped_rewards = rewards.view(-1, args.num_generations)
mean_r = grouped_rewards.mean(dim=1).repeat_interleave(args.num_generations)
std_r = grouped_rewards.std(dim=1, unbiased=False).repeat_interleave(args.num_generations)
advantages = (rewards - mean_r) / (std_r + 1e-4)
```

这段代码说明：

- `per_token_logps` 是 current policy 对每个 next token 的 logprob。
- `ref_per_token_logps` 来自冻结 reference model。
- `completion_mask` 从 `full_response_masks[:, 1:]` 来，是为了和 next-token logprob 对齐。
- group advantage 的 shape 仍然是 `[B * num_generations]`。

#### 源码证据 C：GRPO/CISPO loss 和 rollout policy 同步

文件：`trainer/train_agent.py:319-364`

看它是为了理解：Agentic RL 的策略更新公式与第 24 课一致，只是 reward 和 mask 来自多轮工具轨迹。

代码摘录：

```python
kl_div = ref_per_token_logps - per_token_logps
per_token_kl = torch.exp(kl_div) - kl_div - 1
ratio = torch.exp(per_token_logps - old_per_token_logps)
if args.loss_type == "cispo":
    clamped_ratio = torch.clamp(ratio, max=args.epsilon_high).detach()
    per_token_loss = -(clamped_ratio * advantages.unsqueeze(1) * per_token_logps - args.beta * per_token_kl)
else:
    clipped_ratio = torch.clamp(ratio, 1 - args.epsilon, 1 + args.epsilon)
    per_token_loss1 = ratio * advantages.unsqueeze(1)
    per_token_loss2 = clipped_ratio * advantages.unsqueeze(1)
    per_token_loss = -(torch.min(per_token_loss1, per_token_loss2) - args.beta * per_token_kl)
policy_loss = ...
loss.backward()
...
if step % args.save_interval == 0 or step == iters: rollout_engine.update_policy(model)
```

这段代码说明：

- `ratio` 比较 current policy 和 rollout old policy。
- `per_token_kl` 比较 current policy 和 frozen reference model。
- `completion_mask` 保证只有 policy 生成 token 参与 loss。
- 更新/保存后要同步 rollout engine，否则后续采样还会使用旧 policy。

### 4.7 推理侧：eval 和 API 都要解析 tool_call

#### 源码证据 A：本地/API 评测循环

文件：`scripts/eval_toolcall.py:177-199`

看它是为了理解：推理时也要循环“模型输出 -> 执行工具 -> 添加 tool message”。

代码摘录：

```python
def run_case(prompt, tools, args, model=None, tokenizer=None, client=None):
    messages = [{"role": "user", "content": prompt}]
    while True:
        if args.backend == 'local':
            content = generate(model, tokenizer, messages, tools, args)
            tool_calls = parse_tool_calls(content)
        else:
            content, tool_calls = chat_api(client, messages, tools, args, stream=bool(args.stream))
        if not tool_calls:
            break
        ...
        messages.append(...)
        for tc in tool_calls:
            result = execute_tool(...)
            messages.append({"role": "tool", "content": json.dumps(result, ensure_ascii=False)} ...)
```

这段代码说明：

- eval 不是只看第一轮输出。
- 只要模型继续生成 tool call，脚本就继续执行工具并扩展 messages。
- 本地后端使用文本解析；API 后端使用 OpenAI 风格 `tool_calls` 字段。

#### 源码证据 B：OpenAI API 服务端解析 tool_calls

文件：`scripts/serve_openai_api.py:83-102`

看它是为了理解：服务端把 MiniMind 原生文本协议转换成 OpenAI 兼容响应字段。

代码摘录：

```python
def parse_response(text):
    reasoning_content = None
    think_match = re.search(r'<think>(.*?)</think>', text, re.DOTALL)
    ...
    tool_calls = []
    for i, m in enumerate(re.findall(r'<tool_call>(.*?)</tool_call>', text, re.DOTALL)):
        try:
            call = json.loads(m.strip())
            tool_calls.append({"id": f"call_{int(time.time())}_{i}", "type": "function", "function": {"name": call.get("name", ""), "arguments": json.dumps(call.get("arguments", {}), ensure_ascii=False)}})
        except Exception:
            pass
    if tool_calls:
        text = re.sub(r'<tool_call>.*?</tool_call>', '', text, flags=re.DOTALL)
    return text.strip(), reasoning_content, tool_calls or None
```

这段代码说明：

- MiniMind 内部仍然生成 `<tool_call>` 文本。
- API 层把它转成 `message.tool_calls`。
- 如果有 tool call，正文里会移除 `<tool_call>...</tool_call>` 片段。
- 这是部署兼容层，不是训练 loss 的一部分。

<a id="l26-must-write"></a>
## 5. 本节必须会写 / 暂时不要求

必须会写：

```text
1. 从一段模型输出中解析 <tool_call>...</tool_call>。
2. 判断 tool name 是否在当前样本可用工具列表里。
3. 判断 arguments 是否满足 CHECK_ARGS。
4. 执行一个 mock tool，得到 JSON observation。
5. 把 tool observation 作为 tool message 加回 messages。
6. 区分 policy token mask 和 tool observation mask。
7. 根据 tool_gap、GT 命中、unfinished、格式闭合计算 trajectory reward。
```

暂时不要求：

```text
1. 实现生产级工具沙箱。
2. 接入真实天气、汇率、搜索 API。
3. 训练长期记忆、多任务规划、浏览器控制等完整 Agent 系统。
4. 手写 SGLang rollout server。
5. 重新实现 OpenAI API 服务端。
6. 在没有 agent_rl 数据和 reward model 的情况下跑完整 train_agent.py。
```

当前工作区缺少 `dataset/agent_rl.jsonl` 和默认 `reward_model_path` 指向的 reward model。第 26 课的验收实验因此选择验证解析和 reward 逻辑，不把完整训练作为本地必跑项。

<a id="l26-handwrite"></a>
## 6. 手写与实验模块

本节不新增 `course/impl/core/` 下的核心 RL loss。第 24-25 课已经把 `GRPO/CISPO`、`reward/logprob/KL` 的核心张量逻辑放进了手写复现路线。

本节新增一个源码观察实验：

```text
course/labs/trace_agent_tool_reward.py
```

它对齐的源码函数：

```text
trainer/train_agent.py:76-82      parse_tool_calls
trainer/train_agent.py:84-95      execute_tool
trainer/train_agent.py:183-186    validate_gt_in_text
trainer/train_agent.py:188-239    calculate_rewards
trainer/train_agent.py:314-318    group reward normalization
```

实验检查的行为：

```text
1. 合法 tool_call 能被解析。
2. 合法工具和参数能被 mock executor 执行。
3. 错误参数、未知工具、标签不闭合会改变 reward。
4. 最终答案命中 gt 会增加 reward。
5. 同 prompt 多条 completion 的 reward 可以转成 GRPO-style advantage。
```

刻意简化：

```text
1. 不加载 tokenizer。
2. 不加载 MiniMind 模型。
3. 不采样真实 rollout。
4. 不初始化 reward model。
5. 不做反向传播。
```

这样做是为了单独验证 Agent reward 逻辑，避免被模型权重、数据下载、GPU、reward model 路径干扰。

<a id="l26-experiment"></a>
## 7. 实验验证

### 实验：解析 tool_call 并计算 trajectory reward

这个实验验证：

```text
模型输出文本
-> parse_tool_calls
-> execute_tool
-> validate_gt_in_text
-> calculate_rewards
-> group advantage
```

命令：

```bash
cd /home/sun/minimind
python course/labs/trace_agent_tool_reward.py
```

需要记录：

```text
available_tools =
case=0 parsed_calls =
case=0 executed =
case=0 verified_gt =
case=0 reward =
case=1 reward =
case=2 reward =
case=3 reward =
advantages =
adv_mean =
```

输出怎么看：

```text
case=0:
  合法 calculate_math 调用，最终文本命中 9472，reward 应该最高。

case=1:
  工具名合法，但 arguments 缺少 expression，CHECK_ARGS 不通过。

case=2:
  工具名不在当前可用工具里，即使最终文本包含 9472，也会有工具调用惩罚。

case=3:
  <tool_call> 没有闭合标签，parse_tool_calls 解析不到有效调用，格式惩罚会出现。

advantages:
  同一 prompt 的多条候选 completion 被放进一个 group。
  reward 高于组均值的 completion advantage > 0。
  reward 低于组均值的 completion advantage < 0。
```

可选观察：如果你已经准备好了 `agent_rl.jsonl`、reward model 和模型权重，可以再跑真实训练入口。

命令：

```bash
cd /home/sun/minimind/trainer
python train_agent.py --data_path ../dataset/agent_rl.jsonl --num_workers 0 --debug_mode --debug_interval 1
```

这个命令不是当前课程的默认验收命令，因为当前工作区没有 `dataset/agent_rl.jsonl`。

<a id="l26-stage-assembly"></a>
## 8. 阶段组装

到第 26 课为止，RL/Agent 阶段可以这样组合：

```text
第 21-22 课：
  DPO 数据、chosen/rejected logprob、偏好 loss。

第 23 课：
  PPO rollout、old logprob、critic/value、GAE、policy update。

第 24 课：
  GRPO group advantage、CISPO loss 分支。

第 25 课：
  reward / old logprob / current logprob / ref logprob / KL penalty 的统一地图。

第 26 课：
  tool schema、tool_call、tool_response、多轮 rollout、trajectory reward。
```

教学版实现建议：

```text
course/impl/core/grpo.py:
  继续作为 GRPO/CISPO loss 的核心实现。

course/labs/trace_agent_tool_reward.py:
  作为 Agent reward 和工具协议的观察实验。

原项目 trainer/train_agent.py:
  继续承担真实多轮工具环境、reward model、rollout engine、checkpoint、分布式训练。
```

为什么不急着手写完整 Agent 训练脚本：

```text
Agentic RL 的难点不只在 loss，而在环境循环、工具执行、安全边界、数据准备、rollout engine 同步、reward 设计。
课程的核心目标是看懂 MiniMind 源码中这些边界如何连接，而不是复制所有工程外围。
```

阶段验收命令：

```bash
cd /home/sun/minimind
python course/labs/trace_grpo_cispo_loss.py
python course/labs/trace_reward_logprob_kl.py
python course/labs/trace_agent_tool_reward.py
```

Portfolio 记录可以写：

```text
读懂并复现实验验证了 MiniMind Agentic RL 的工具调用链路：
tool schema -> <tool_call> JSON -> mock tool execution -> <tool_response> observation -> trajectory reward -> GRPO/CISPO update。
能够解释 policy token 与 tool observation token 的 mask 区别，以及为什么 Agent reward 是延迟的 trajectory-level signal。
```

<a id="l26-check"></a>
## 9. 本节检查

1. `tool schema`、`tool_call`、`tool_response` 分别是什么？
2. 为什么 `AgentRLDataset.__getitem__` 返回 `messages/tools/gt`，而不是 `input_ids/labels`？
3. `rollout_single` 为什么在 tool observation 之后要重新 `apply_chat_template`？
4. 为什么 `obs_delta` 要进入 `response_ids`，但 `response_mask` 是 0？
5. `tool_gap` 同时惩罚了哪两类错误？
6. `validate_gt_in_text` 检查的是 tool observation 还是最终文本？
7. Agentic RL 里的 `rewards.view(-1, num_generations)` 为什么仍然要求同 prompt 的多条轨迹连续排列？

<a id="l26-next"></a>
## 10. 下一课

第 27 课进入模型转换、OpenAI API 与 WebUI。

下一课要解决：

```text
convert_model.py 如何把原生 MiniMind 权重转换成 transformers 格式；
serve_openai_api.py 如何包装成 OpenAI 兼容接口；
web_demo.py 如何把 tokenizer/template/generate 接成可交互 UI；
tool_calls / reasoning_content / open_thinking 如何在部署侧流转；
部署脚本复用了哪些训练时已经学过的模型与 tokenizer 约定。
```