Refactor AgentScope ReAct Agent workflow example (agentscope-ai#303)

Author: pan-x-c

README.md

@@ -358,7 +358,7 @@ This project is built upon many excellent open-source projects, including:
 + [verl](https://github.com/volcengine/verl) and [PyTorch's FSDP](https://pytorch.org/docs/stable/fsdp.html) for LLM training;
 + [vLLM](https://github.com/vllm-project/vllm) for LLM inference;
 + [Data-Juicer](https://github.com/modelscope/data-juicer?tab=readme-ov-file) for data processing pipelines;
-+ [AgentScope](https://github.com/modelscope/agentscope) for agentic workflow;
++ [AgentScope](https://github.com/agentscope-ai/agentscope) for agentic workflow;
 + [Ray](https://github.com/ray-project/ray) for distributed systems;
 + we have also drawn inspirations from RL frameworks like [OpenRLHF](https://github.com/OpenRLHF/OpenRLHF), [TRL](https://github.com/huggingface/trl) and [ChatLearn](https://github.com/alibaba/ChatLearn);
 + ......

README_zh.md

@@ -358,7 +358,7 @@ trinity run --config examples/grpo_gsm8k/gsm8k.yaml
 + [verl](https://github.com/volcengine/verl) 和 [PyTorch's FSDP](https://pytorch.org/docs/stable/fsdp.html) 用于大模型训练；
 + [vLLM](https://github.com/vllm-project/vllm) 用于大模型推理；
 + [Data-Juicer](https://github.com/modelscope/data-juicer?tab=readme-ov-file) 用于数据处理管道；
-+ [AgentScope](https://github.com/modelscope/agentscope) 用于智能体工作流；
++ [AgentScope](https://github.com/agentscope-ai/agentscope) 用于智能体工作流；
 + [Ray](https://github.com/ray-project/ray) 用于分布式系统；
 + 我们也从 [OpenRLHF](https://github.com/OpenRLHF/OpenRLHF)、[TRL](https://github.com/huggingface/trl) 和 [ChatLearn](https://github.com/alibaba/ChatLearn) 等框架中汲取了灵感；
 + ......

docs/sphinx_doc/assets/agentscope_gsm8k_reward.png

@@ -45,7 +45,7 @@ This project is built upon many excellent open-source projects, including:
 + [verl](https://github.com/volcengine/verl) and [PyTorch's FSDP](https://pytorch.org/docs/stable/fsdp.html) for LLM training;
 + [vLLM](https://github.com/vllm-project/vllm) for LLM inference;
 + [Data-Juicer](https://github.com/modelscope/data-juicer?tab=readme-ov-file) for data processing pipelines;
-+ [AgentScope](https://github.com/modelscope/agentscope) for agentic workflow;
++ [AgentScope](https://github.com/agentscope-ai/agentscope) for agentic workflow;
 + [Ray](https://github.com/ray-project/ray) for distributed systems;
 + we have also drawn inspirations from RL frameworks like [OpenRLHF](https://github.com/OpenRLHF/OpenRLHF), [TRL](https://github.com/huggingface/trl) and [ChatLearn](https://github.com/alibaba/ChatLearn);
 + ......

docs/sphinx_doc/assets/agentscope_gsm8k_turns.png

@@ -44,7 +44,7 @@ Trinity-RFT 是一个灵活、通用的大语言模型（LLM）强化微调（RF
 + [verl](https://github.com/volcengine/verl) 和 [PyTorch's FSDP](https://pytorch.org/docs/stable/fsdp.html) 用于大模型训练；
 + [vLLM](https://github.com/vllm-project/vllm) 用于大模型推理；
 + [Data-Juicer](https://github.com/modelscope/data-juicer?tab=readme-ov-file) 用于数据处理管道；
-+ [AgentScope](https://github.com/modelscope/agentscope) 用于智能体工作流；
++ [AgentScope](https://github.com/agentscope-ai/agentscope) 用于智能体工作流；
 + [Ray](https://github.com/ray-project/ray) 用于分布式系统；
 + 我们也从 [OpenRLHF](https://github.com/OpenRLHF/OpenRLHF)、[TRL](https://github.com/huggingface/trl) 和 [ChatLearn](https://github.com/alibaba/ChatLearn) 等框架中汲取了灵感；
 + ......

docs/sphinx_doc/source/main.md

@@ -1,143 +1,202 @@
-# ReAct 例子
+# ReAct Agent 训练
 
-本示例用于演示如何通过我们兼容 OpenAI 接口的 `ModelWrapper` 类，将 Trinity-RFT 训练工作流适配到你自己的智能体项目中。
+本节将会展示如何借助 Trinity-RFT 训练一个基于智能体框架实现的 ReAct Agent。这里我们以 [AgentScope](https://github.com/agentscope-ai/agentscope) 框架为例，并使用其内置的 ReAct 智能体来解决 GSM8K 数学问题。开发者可以参考此示例，将 Trinity-RFT 的训练工作流适配到自己的智能体项目中。
 
-这里我们以 [AgentScope](https://github.com/modelscope/agentscope) 框架为例，但你完全可以使用其他任何框架，因为 Trinity 提供了极大的灵活性。该示例利用一个采用 ReAct 风格推理并支持原生工具调用的智能体（Agent），在 GSM8K 数学数据集上对模型进行微调。
 
 ## 关键特性
 
-此示例突出了 Trinity-RFT 框架的几项高级特性：
+在介绍案例之前，我们先来看看 Trinity-RFT 在训练智能体应用方面的几个重要特性。
 
-### 与外部智能体框架的无缝集成
-Trinity-RFT 被设计为高度模块化，因此你可以轻松地将来自外部框架（如 AgentScope）的复杂、现成的智能体逻辑直接嵌入到 Trinity 的 `Workflow` 中。
+### 兼容各种智能体框架
 
-- **无需重写智能体**：你不必在 Trinity 内重新实现智能体的复杂逻辑（例如 ReAct 循环、内存管理或工具调用）。
-- **关注高层编排**：正如我们在 `AgentScopeReactV2MathWorkflow` 中所展示的那样，Trinity 工作流只需初始化并调用外部智能体的 `reply` 方法。Trinity 对底层复杂性负责，使你能专注于高层任务编排和奖励设计。
+当前智能体开发框架众多，对模型的封装和调用方式也各不相同。为了最大限度地兼容各种框架，Trinity-RFT 对 `openai.OpenAI` 以及 `openai.AsyncOpenAI` 接口进行了封装，只要你的智能体框架支持使用 openai 接口调用模型，就可以通过 Trinity-RFT 提供的 `OpenAI` 或是 `AsyncOpenAI` 实例对智能体进行训练。当然，你也可以不使用任何智能体框架，直接借助 Trinity-RFT 提供的 openai 接口实现自己的智能体。
 
-### 通用多步训练
-现代智能体任务通常涉及多步推理、工具使用和观察。Trinity-RFT 原生支持跨这些多步交互的训练。
 
-- **逐步步经验生成**：Trinity 不仅从最终结果进行学习，还能将智能体推理轨迹中的每一步视为独立的学习经验（experience）。
-- **奖励分配**：解决任务的奖励（reward）会传播至成功轨迹内的所有 experience，使模型能够学习整个推理链，而不仅仅是最终响应。这由配置中的 `advantage_fn` 控制。
+### 无需修改智能体代码
 
-### 原生工具调用支持
-Trinity-RFT 的推理引擎和训练流水线专为支持原生 OpenAI `tool_calls` 格式而构建。
+智能体的训练需要收集智能体运行中产生的对话历史以及其他相关信息（例如 `token_id`，`logprobs`），这往往需要对智能体应用代码进行一定的修改。Trinity-RFT 通过封装 `openai.OpenAI` 或 `openai.AsyncOpenAI` 实例的方式，在模型调用时自动收集训练所需的各种信息，从而避免了对智能体自身代码的修改。
 
-- **学习使用工具**：该框架允许模型学习*何时*调用工具、*调用哪个*工具以及*使用什么*参数，全部采用标准 `tool_calls` 格式。
-- **易操作性**：这种原生支持确保了与任何消费 OpenAI API 格式的服务或环境无缝集成，例如 `MCP_server`（多智能体协作平台）或其他工具使用评估器。
 
-## 工作原理
+### 支持多轮次交互
 
-下面我们逐步介绍如何执行此流程。
+智能体任务通常涉及多步推理、工具使用和观察。为了支持训练智能体应用，Trinity-RFT 原生支持包含多轮交互的训练任务，且不限制交互轮次（只需确保每次模型调用的序列长度不超过模型所支持的上限），这意味着你可以根据任务的复杂度，设计动态长度的交互过程。Trinity-RFT 通过动态同步机制，能够在收集到足够的训练样本后立即启动训练任务，从而提升训练效率。
 
-### 工作流 (`workflow.py`)
 
-核心逻辑封装在 `AgentScopeReactV2MathWorkflow` 类中。
+## 实现流程
 
-1.  **初始化 (`__init__`)**
-    - 首先初始化 AgentScope 环境和所需的 Agent（`ReActAgentV2`）。
-    - 最关键的集成步骤是将 Trinity 的模型客户端注入到 Agent 中：
-      ```python
-      self.openai_client = model.get_openai_client()
-      # self.openai_client = get_openai_async_client() # or async client depend on whether you are using async openai client
-      # ...
-      self.agent.model.client = self.openai_client
-      ```
-      这确保了 Agent 发出的所有 API 请求都通过 Trinity 的 `ModelWrapper` 进行路由，后者会记录完整的对话历史。
+我们将逐步介绍如何使用 Trinity-RFT 训练一个基于 AgentScope 实现的 ReAct 智能体。
 
-2.  **执行 (`run`)**
-    - `run` 方法非常简洁，它只是将任务描述传递给 Agent。
-      ```python
-      content = self.agent.reply(msg).content # your agent logic
-      ```
-    - 在 Agent 完成其多步推理并产生最终答案后，Trinity 从模型历史中提取所有中间轮次：
-      ```python
-      experiences = self.model.extract_experience_from_history(clear_history=True)
-      ```
-    - 基于最终答案计算奖励，并将其应用于从该轨迹生成的所有 `Experience` 对象。然后这些 experiences 被发送到 Buffer 中用于训练。
 
-### 配置说明
+### 1. 更换智能体的 OpenAI 客户端
 
-配置文件用于微调整个系统的行为。以下是本示例的关键参数：
+{class}`AgentScopeReActAgent <trinity.common.workflows.agentscope.react.react_agent.AgentScopeReActAgent>` 封装了 AgentScope 的 ReAct 智能体，并在初始化时注入 Trinity-RFT 提供的 `openai.AsyncOpenAI` 实例，而后续的执行过程均由 AgentScope 智能体自行处理，无需任何修改。
 
-#### 原生工具调用设置
 
-`explorer.rollout_model` 部分的这些设置用于配置基于 vLLM 的引擎，以生成和解析兼容 OpenAI 的工具调用。
-我们使用 `Qwen3` 模型并通过 vLLM 托管模型。不同模型的配置可参考 [vLLM Toolcalls](https://docs.vllm.ai/en/stable/features/tool_calling.html#qwen-models)
+```python
+# A simplified version of trinity.common.workflows.agentscope.react.react_agent.AgentScopeReActAgent
+class AgentScopeReActAgent:
+    def __init__(
+        self,
+        openai_client: openai.AsyncOpenAI,  # provided by Trinity-RFT
+        # some other params
+    ):
+        """Initialize the AgentScope ReAct agent with specified tools and model.
+
+        Args:
+            openai_client (openai.AsyncOpenAI): An instance of AsyncOpenAI client.
+        """
+        self.agent_model = OpenAIChatModel(
+            api_key="EMPTY",
+            model_name=model_name,
+            generate_kwargs=generate_kwargs,
+            stream=False,
+        )
+        # patch the OpenAIChatModel to use the openai_client provided by Trinity-RFT
+        self.agent_model.client = openai_client
+        self.agent = ReActAgent(
+            name="react_agent",
+            model=self.agent_model,
+        )
+
+    async def reply(self, query):
+        """Generate a response based on the query."""
+        # no need to modify your agent logic
+        return await self.agent.reply(
+            Msg("user", query, role="user")
+        )
+```
+
+```{note}
+这里用一个新类封装 AgentScope 的 ReAct 智能体主要是为了清晰地展示更换 OpenAI 客户端的过程。
+在实践中，你可以直接修改现有智能体的 OpenAI 客户端，而无需创建一个新的类。
+```
+
+
+### 2. 实现训练工作流
+
+{class}`AgentScopeReActWorkflow <trinity.common.workflows.agentscope.react.react_workflow.AgentScopeReActWorkflow>` 展示了智能体的训练流程，其核心 `run_async` 方法包含三个步骤：
+
+  1. 调用智能体完成指定任务并获取任务结果。
+  2. 对任务结果进行评估，计算奖励。
+  3. 收集任务执行中产生的可训练数据并集合奖励生成训练样本（`Experience`）。
+
+```python
+# A simplified version of trinity.common.workflows.agentscope.react.react_workflow.AgentScopeReActWorkflow
+class AgentScopeReActWorkflow(Workflow):
+    def __init__(
+        self,
+        *,
+        task: Task,
+        model: ModelWrapper,
+        auxiliary_models: Optional[List[openai.OpenAI]] = None,
+    ):
+        # initialize the agent
+        self.agent = AgentScopeReActAgent(
+            openai_client=model.get_openai_async_client(),
+            # some other params
+        )
+        # get query from the task
+        self.query = task.raw_task.get(task.format_args.prompt_key)  # type: ignore [index]
+
+    async def run_async(self):
+        """Run the workflow asynchronously."""
+        # Step 1: call the ReAct agent to solve the task
+        response = await self.agent.reply(self.query)
+        # Step 2: calculate the reward based on the response
+        reward = await self.calculate_reward(response)
+        # Step 3: construct experiences from the interaction history and return them
+        return self.construct_experiences(reward)
+
+    async def calculate_reward(self, response) -> float:
+        """Calculate the reward based on the response."""
+        # your reward logic
+
+    def construct_experiences(self, reward: float) -> List[Experience]:
+        """Construct experiences from the agent's interaction history.
+
+        Returns:
+            List: A list of Experience objects.
+        """
+        # Extract all interaction history generated by this task
+        exps = self.model.extract_experience_from_history()
+        # update the reward for each experience
+        for exp in exps:
+            exp.reward = reward
+        return exps
+
+```
+
+### 3.训练配置
+
+Trinity-RFT 借助配置文件来控制整个训练流程，下面是本示例的关键配置参数说明。
+
+#### 推理模型配置
+
+`explorer.rollout_model` 部分负责配置智能体应用所使用的模型，其中的关键参数如下：
 
 
 ```yaml
 explorer:
   rollout_model:
     # ...
-    enable_auto_tool_choice: true # 允许模型生成 `tool_calls`
+    enable_openai_client: true     # 启用 OpenAI Client
+    enable_history: true           # 启用调用历史自动记录
+    enable_auto_tool_choice: true  # 允许模型生成 `tool_calls`
     tool_call_parser: hermes       # 指定格式化解析工具调用输出的解析器
     reasoning_parser: deepseek_r1  # 有助于解析模型的思维过程
-    enable_thinking: true          # 允许模型生成中间“思考”内容
+    enable_thinking: true          # 是否启用模型深度思考能力（主要针对 Qwen3 系列模型）
 ```
 
-#### 多步训练策略
+#### 多步训练算法
 
-`algorithm` 部分的此设置定义了如何处理多步 rollout 产生的 experience。
+`algorithm` 部分负责配置智能体应用所使用的训练算法，其中的关键参数如下：
 
 ```yaml
 algorithm:
   algorithm_type: grpo
-  advantage_fn: step_wise_grpo # 多步训练的关键
+  advantage_fn: step_wise_grpo # 多步训练的关键，该策略告诉 Trinity 为智能体执行路径中的每一步创建独立的训练样本。`grpo` 算法随后使用这些样本来更新模型。
 ```
--   `step_wise_grpo`：该策略告诉 Trinity 为智能体执行路径中的每一步创建独立的训练样本。`grpo` 算法随后使用这些样本来更新模型。
 
-#### 异步同步提升效率
+#### 动态同步配置
 
-由于多步 rollout 会产生数量不固定的 experience，等待固定数量的 *rollout* 是低效的。我们采用动态同步策略。
+由于智能体应用在完成不同任务时，交互轮次往往不固定，导致生成的训练样本数量也不固定；为此需要开启 Trinity-RFT 的动态同步功能，以便在收集到足够的训练样本后立即启动训练任务，从而提升训练效率。相关配置如下：
 
 ```yaml
 synchronizer:
-  sync_style: dynamic_by_explorer # 当积累足够 experience 时即开始训练
-  sync_interval: 2
+  sync_style: dynamic_by_explorer # 当产生足够训练数据时，trainer 立即启动训练任务，而不是将生成的数据补齐到一个固定规模，能够有效提升训练效率
+  sync_interval: 2  # 每执行两个批次的任务后检查是否需要同步更新模型参数
 ```
--   `sync_style: dynamic_by_explorer`：当缓冲区收集到足够的 *experience*（即单个对话轮次）时，trainer 即启动一次训练任务，而不是等待固定数量的完整智能体轨迹。这显著提高了 GPU 利用率和训练吞吐量。
-
-## 如何运行示例
-
-1.  **前置条件**：确保已安装 Trinity 及本示例所需依赖（如 `AgentScope`）。请参考 [Agentscope Github link](https://github.com/agentscope-ai/agentscope/tree/v0)
-
-> **注意**：本示例需要以下来源之一的 AgentScope：
->  - Commit: `ad13ed5dacecb79d20abf626769f8c7d7a7d2afb`
->  - 分支: [`v0`](https://github.com/agentscope-ai/agentscope/tree/v0)
-
-2. 下载你想使用的模型，并填写 `examples/agentscope_tool_react/agentscopev0_tool_react_gsm8k.yaml` 或 `examples/agentscope_tool_react/agentscopev0_tool_react_dapo.yaml` 中的配置文件
-
-3.  **启动训练任务**：从仓库根目录运行以下命令。
 
-    ```bash
-    trinity run --config examples/agentscope_tool_react/agentscopev0_tool_react_gsm8k.yaml
-    ```
 
-    或
+## 运行示例
 
-    ```bash
-    trinity run --config examples/agentscope_tool_react/agentscopev0_tool_react_dapo.yaml
-    ```
+1. 安装依赖库：按照 [安装指南](/tutorial/installation.md) 成功安装 Trinity-RFT，并且安装了 AgentScope 的 v1.0 及以上版本。
 
+```bash
+pip install agentscope>=1.0.4
+```
 
-GSM8K 数据集的示例非常简单，在 8 块 H20 GPU 上几分钟内即可收敛。
-
-![](../../assets/agentscope_gsm8k_reward.png)
+2. 下载模型和数据集:
 
-DAPO 数据集的示例耗时稍长，但也能够收敛。
+```bash
+huggingface-cli download Qwen/Qwen3-8B
+huggingface-cli download openai/gsm8k --repo-type dataset
+```
 
-![](../../assets/agentscope_dapo_reward.png)
+3. 启动训练任务:
 
-我们还可以看到，模型总体上开始更多地使用工具调用来解决问题。
+  ```bash
+  # Navigate to the Trinity-RFT root directory
+  cd /path/to/Trinity-RFT
 
-![](../../assets/agentscope_dapo_turns.png)
+  # Run the training for GSM8k dataset:
+  trinity run --config examples/agentscope_react/gsm8k.yaml
+  ```
 
-我们也可以把使用 v1 版本的 AgentScope 仓库，然后对 Qwen3-4b-instrcut-2507 进行训练：
 
-![](../../assets/agentscope_dapo_qwen3-4B_reward.png)
+## 结果展示
 
 
-## 总结
+reward 变化曲线：
 
-这个示例虽然简单，但展示了 Trinity 在训练使用工具的复杂多步智能体方面的强大功能和灵活性。通过无缝集成外部智能体逻辑，并提供对多步训练和工具调用的原生支持，Trinity-RFT 使你能够高效地在复杂且真实的任务上微调模型。
+![](../../assets/agentscope_gsm8k_reward.png)

docs/sphinx_doc/source/tutorial/example_react.md

@@ -0,0 +1,5 @@
+# AgentScope ReAct Agent Training Example
+
+This example demonstrates how to train the [AgentScope](https://github.com/agentscope-ai/agentscope) built-in ReAct Agent using Trinity-RFT. We use the GSM8K dataset as an example. Developers can refer to this example to adapt Trinity-RFT's training to their own agent projects.
+
+Full documentation is available at: https://modelscope.github.io/Trinity-RFT/en/main/tutorial/example_react.html