# PR #6048 完整报告

- 仓库：`verl-project/verl`
- 标题：[rollout] chore: single turn agent loop also enable rollout trace as tool loop
- 合并时间：2026-04-20 11:45
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6048

---

# 执行摘要

- 一句话：为单轮对话 Agent Loop 启用 rollout 追踪装饰器，支持 Vexact 演示精确 rollout。
- 推荐动作：该 PR 变更简单，适合快速了解如何为 Agent Loop 添加追踪功能。值得关注的设计决策是使用装饰器模式非侵入式增强功能，但需注意 review 中提到的设计一致性疑虑。

# 功能与动机

根据 PR 描述“Single turn agent loop also enable rollout trace as tool agent loop, so that vexact can demo traced exact rollout”，目的是让单轮对话 Agent Loop 也能像工具 Agent Loop 一样支持 rollout 追踪，从而支持 Vexact 演示精确 rollout。

# 实现拆解

1. **导入 rollout_trace_op 装饰器**：在 `verl/experimental/agent_loop/single_turn_agent_loop.py` 中，从 `verl.utils.rollout_trace` 导入 `rollout_trace_op` 装饰器，为后续装饰器应用做准备。
2. **应用装饰器到 run 方法**：在 `SingleTurnAgentLoop` 类的 `run` 方法上添加 `@rollout_trace_op` 装饰器，使其在执行时启用 rollout 追踪功能。
3. **无测试或配置配套改动**：本次变更仅涉及源码级别的装饰器应用，没有新增或修改测试文件、配置文件或部署脚本。

关键文件：
- `verl/experimental/agent_loop/single_turn_agent_loop.py`（模块 Agent 循环；类别 source；类型 core-logic；符号 SingleTurnAgentLoop.run）: 这是唯一变更的文件，为单轮对话 Agent Loop 启用 rollout 追踪功能。

关键符号：SingleTurnAgentLoop.run

## 关键源码片段

### `verl/experimental/agent_loop/single_turn_agent_loop.py`

这是唯一变更的文件，为单轮对话 Agent Loop 启用 rollout 追踪功能。

```python
from verl.utils.rollout_trace import rollout_trace_op  # 新增导入：用于启用 rollout 追踪的装饰器

@register("single_turn_agent")
class SingleTurnAgentLoop(AgentLoopBase):
    """Naive agent loop that only do single turn chat completion."""

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.prompt_length = self.rollout_config.prompt_length
        self.response_length = self.rollout_config.response_length

    @rollout_trace_op  # 新增装饰器：为此方法启用 rollout 追踪，支持 Vexact 演示精确 rollout
    async def run(self, sampling_params: dict[str, Any], **kwargs) -> AgentLoopOutput:
        messages = list(kwargs["raw_prompt"])
        # ... 后续生成逻辑保持不变

```

# 评论区精华

reviewer gemini-code-assist[bot] 指出：
> “`rollout_trace_op` 装饰器已导入但仅应用于 `SingleTurnAgentLoop.run`。为保持一致性并完全支持 PR 目标（为单轮对话 Agent 启用 rollout 追踪），也应将其应用于 `DiffusionSingleTurnAgentLoop.run`（第 143 行）。”

讨论焦点是设计一致性：是否应将装饰器也应用于同文件中的 `DiffusionSingleTurnAgentLoop` 类。但 PR 作者未回应此评论，且 PR 已合并，表明当前决策是仅装饰 `SingleTurnAgentLoop`，可能因为 `DiffusionSingleTurnAgentLoop` 有特殊需求或后续单独处理。

- 装饰器应用一致性 (design): PR 未采纳此建议，仅装饰了 SingleTurnAgentLoop.run，可能因 DiffusionSingleTurnAgentLoop 有特殊需求或后续单独处理。

# 风险与影响

- 风险：技术风险较低：
 - **回归风险**：装饰器仅添加追踪逻辑，不改变核心生成流程，但若 `rollout_trace_op` 实现有 bug，可能影响单轮对话 Agent 的稳定性。
 - **性能风险**：装饰器可能引入额外开销，但通常追踪逻辑较轻量，影响可忽略。
 - **兼容性风险**：无，装饰器是向后兼容的增强功能。
 - **安全风险**：无。
- 影响：影响范围有限：
 - **对用户**：单轮对话 Agent 现在支持 rollout 追踪，便于 Vexact 演示精确 rollout，提升调试和演示能力。
 - **对系统**：仅影响 `SingleTurnAgentLoop` 的执行流，不改变其他模块。
 - **对团队**：为后续扩展追踪功能到其他 Agent Loop 提供参考模式。
 - 风险标记：装饰器副作用 , 设计一致性疑虑

# 关联脉络

- PR #5978 [tool, rollout, cfg] feat: per-sample tool environment routing for ToolAgentLoop: 同样涉及 Agent Loop 的增强功能（工具路由），可能共享类似的追踪或配置模式。