ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

chapter9/gaia-experience/AWorld/train/README_zh.md

@@ -0,0 +1,248 @@
+<div align="center">
+
+# AWorld Train
+
+*为使用 AWorld 构建的智能体，提供与外部 RL/训练框架对接的、与框架无关的适配层、可运行示例与通用工具*
+
+[![License: MIT][license-image]][license-url]
+
+</div>
+
+---
+
+AWorld Train 为 AWorld 智能体生态系统和各种外部训练框架（如强化学习库）之间提供了一座桥梁。它被设计为框架无关的，可以选择你喜欢的训练环境使用AWorld 智能体。
+
+下图说明了环境和训练集群之间的整体架构和交互：
+
+![架构示意图](../readme_assets/train_env_agent_architecture.png)
+
+
+## 环境构建
+
+首先，您需要设置智能体工具将要运行的环境。
+
+选择一台机器（也可以是训练机）。
+
+机器规格建议：
+- 为进行容量规划，为每个并发工作进程分配大约 **2C4G**。
+- 示例：对于8个并发，计划需要 **约16C32G**。
+
+```bash
+# 克隆 AWorld 仓库
+git clone git@github.com:inclusionAI/AWorld.git
+cd /path/to/AWorld
+cp ./env/gaia-mcp-server/mcp_servers/.env_template ./env/gaia-mcp-server/mcp_servers/.env
+```
+编辑 `./env/gaia-mcp-server/mcp_servers/.env` 以配置任何需要身份验证的工具的令牌。
+
+```.env
+JINA_API_KEY=<YOUR_JINA_API_KEY>
+TAVILY_API_KEY=<YOUR_TAVILY_API_KEY>
+GOOGLE_API_KEY=<YOUR_GOOGLE_API_KEY>
+GOOGLE_CSE_ID=<YOUR_GOOGLE_CSE_ID>
+DATALAB_API_KEY=<YOUR_DATALAB_API_KEY>
+E2B_API_KEY=<YOUR_E2B_API_KEY>
+
+MCP_LLM_BASE_URL=<YOUR_MCP_LLM_BASE_URL>
+MCP_LLM_MODEL_NAME=<YOUR_MCP_LLM_MODEL_NAME>
+MCP_LLM_API_KEY=<YOUR_MCP_LLM_API_KEY>
+
+BROWSERUSE_LLM_BASE_URL=${MCP_LLM_BASE_URL}
+BROWSERUSE_LLM_MODEL_NAME=${MCP_LLM_MODEL_NAME}
+BROWSERUSE_LLM_API_KEY=${MCP_LLM_API_KEY}
+CODE_LLM_BASE_URL=${MCP_LLM_BASE_URL}
+CODE_LLM_MODEL_NAME=${MCP_LLM_MODEL_NAME}
+CODE_LLM_API_KEY=${MCP_LLM_API_KEY}
+THINK_LLM_BASE_URL=${MCP_LLM_BASE_URL}
+THINK_LLM_MODEL_NAME=${MCP_LLM_MODEL_NAME}
+THINK_LLM_API_KEY=${MCP_LLM_API_KEY}
+GUARD_LLM_BASE_URL=${MCP_LLM_BASE_URL}
+GUARD_LLM_MODEL_NAME=${MCP_LLM_MODEL_NAME}
+GUARD_LLM_API_KEY=${MCP_LLM_API_KEY}
+AUDIO_LLM_BASE_URL=${MCP_LLM_BASE_URL}
+AUDIO_LLM_MODEL_NAME=${MCP_LLM_MODEL_NAME}
+AUDIO_LLM_API_KEY=${MCP_LLM_API_KEY}
+IMAGE_LLM_BASE_URL=${MCP_LLM_BASE_URL}
+IMAGE_LLM_MODEL_NAME=${MCP_LLM_MODEL_NAME}
+IMAGE_LLM_API_KEY=${MCP_LLM_API_KEY}
+VIDEO_LLM_BASE_URL=${MCP_LLM_BASE_URL}
+VIDEO_LLM_MODEL_NAME=${MCP_LLM_MODEL_NAME}
+VIDEO_LLM_API_KEY=${MCP_LLM_API_KEY}
+```
+
+接下来，运行启动脚本以在本地启动 MCP 服务器：
+
+```bash
+cd /path/to/Aworld
+# --docker_dir 参数指定需要构建的env对应docker目录
+# e.g., --docker_dir=gaia-mcp-server
+python -m env.train_env --docker_dir=gaia-mcp-server
+```
+
+MCP 服务器成功启动后，将输出连接详细信息：
+```bash
+  {
+      "ip": "1xx.1xx.x.xx",
+      "port": 8000,
+      "token": "eyJhbGciOi...rYmQ"
+  }
+```
+您将需要此输出中的 `ip`、`port` 和 `token`，用于下一步在训练机上配置智能体。
+
+有关在 Kubernetes 上部署环境的说明，请参阅 [`../env/README.md`](../env/README.md)。
+
+## 训练集群设置
+
+### 1. 创建智能体或智能体集群
+现在，在训练集群机器上，您必须使 MCP 服务凭据对您的智能体可用。使用[环境构建](#环境构建)部分中的 `ip`、`port` 和 `token`，并将它们导出为环境变量或添加到 `.env` 文件中：
+```bash
+# 导出为环境变量
+# 将 <ip>、<port> 和 <token> 替换为环境构建中的 ip、port 和 token
+export MCP_SERVER_URL=http://<ip>:<port>/mcp
+export MCP_SERVER_TOKEN=<token>
+
+# 或将它们添加到 .env 文件中
+# echo "MCP_SERVER_URL=http://<ip>:<port>/mcp" >> .env
+# echo "MCP_SERVER_TOKEN=<token>" >> .env
+```
+
+然后安装 `aworld` 和强化学习框架：
+
+```bash
+# 推荐使用 Python>=3.10。
+
+# 安装 AWorld
+pip install aworld
+
+# 安装特定框架的依赖（以 VeRL 为例）
+pip install verl==0.5.0
+```
+
+配置好连接详细信息后，您可以在所选的训练框架内定义您的智能体。对于 VeRL，这是通过实现一个自定义的 `AgentLoop` 来完成的。
+
+例如，`GaiaAgentLoop` 继承自 `AworldAgentLoop` 并实现了 `build_agents` 方法。
+
+```python
+from aworld.agents.llm_agent import Agent
+from aworld.config import AgentConfig
+
+from train.adapter.verl.aworld_agent_loop import AworldAgentLoop
+from train.adapter.verl.common import get_agent_tool_env_and_servers
+
+class GaiaAgentLoop(AworldAgentLoop):
+    def build_agents(self):
+        # 获取环境配置和服务器详细信息。
+        # 注意：MCP 服务器必须正在运行（环境构建），并且
+        # MCP_SERVER_URL/MCP_SERVER_TOKEN 环境变量必须已设置。
+        gaia_env_config, gaia_env_servers = get_agent_tool_env_and_servers()
+
+        return Agent(
+            conf=AgentConfig(
+                # 从服务管理器获取动态的 llm 服务地址。
+                # llm 服务是在 VeRL 中启动的。
+                llm_base_url=self.get_llm_server_address(),
+                llm_model_name=self.get_llm_server_model_name(),
+            ),
+            name="gaia_super_agent",
+            system_prompt="你的系统提示",
+
+            # 智能体的 MCP 工具配置
+            mcp_config=gaia_env_config,
+            mcp_servers=gaia_env_servers,
+        )
+```
+
+### 2. 运行训练
+在运行训练之前，请在 `agent.yaml` 中指定您的自定义 `AgentLoop`：
+
+```yaml
+# 在 agent.yaml 中
+- name: gaia_agent
+  _target_: train.examples.train_gaia_with_aworld_verl.custom_agent_loop.GaiaAgentLoop
+```
+
+最后，运行训练脚本。该脚本通常是基于 VeRL 示例的 `run.sh` 文件。
+```bash
+bash run.sh
+```
+此脚本处理由 VeRL 编排的AgentLoop、奖励计算函数和训练流程。
+有关 `run.sh` 中的参数设置，请参阅 [VeRL 文档](https://verl.readthedocs.io/en/latest/examples/config.html)。
+
+一个完整的、可运行的示例，包括为 `GaiaAgentLoop` 定制的 `run.sh` 脚本，可在 [`./examples/train_gaia_with_aworld_verl/`](./examples/train_gaia_with_aworld_verl/) 中找到。
+
+## 进阶教程
+
+### 如何创建复杂的多智能体集群 (Swarm)
+除了单个智能体，您还可以训练一个多智能体集群。只需让您的 `build_agents` 方法（或等效的设置函数）返回一个 `Swarm` 对象而不是单个 `Agent` 对象即可。AWorld 和训练适配器将处理剩下的部分。
+
+```python
+# 在自定义的AgentLoop中
+def build_agents(self, ...) -> Union[Agent, Swarm]:
+    # ... 创建多个agent
+    agent_to_be_train = Agent(
+      conf=AgentConfig(
+          # 对于要训练的agent，llm_base_url 和 llm_model_name 是从 VeRL 启动的服务中获取的
+          llm_base_url=self.get_llm_server_address(),
+          llm_model_name=self.get_llm_server_model_name(),
+      ),
+    )
+
+    plan_agent = Agent(
+      conf=AgentConfig(
+          # 提供一个即用型的 OpenAI 兼容的 llm 服务地址、模型名称和 api_key
+          llm_base_url="",
+          llm_model_name="",
+          llm_api_key=""
+      ),
+    )
+    
+    exe_agent = Agent(
+      conf=AgentConfig(
+          # 提供一个即用型的 OpenAI 兼容的 llm 服务地址、模型名称和 api_key
+          llm_base_url="",
+          llm_model_name="",
+          llm_api_key=""
+      ),
+    )
+    
+    sum_agent = Agent(
+      conf=AgentConfig(
+          # 提供一个即用型的 OpenAI 兼容的 llm 服务地址、模型名称和 api_key
+          llm_base_url="",
+          llm_model_name="",
+          llm_api_key=""
+      ),
+    )
+
+    # 返回由以上定义的智能体组成的Swarm
+    return Swarm(
+        agent_to_be_train, plan_agent, exe_agent, sum_agent,
+        # ... 其他Swarm配置
+    )
+```
+
+### 如何集成其他训练框架
+AWorld Train 被设计为可扩展的。要为新的训练框架（例如 “Swift”）添加支持，通常需要：
+
+1.  **创建新的适配器**：在 `train/adapter/` 目录内，为您的框架创建一个新文件夹（例如 `swift/`）。
+2.  **实现核心逻辑**：创建一个主类（例如 `AworldAgentTrainer`），它继承自目标框架的某个基类。这个类将负责：
+    *   从框架的环境中接收任务或观察结果。
+    *   运行 AWorld 智能体（`Runners.sync_run(input=input, agent=agent)`）以获取动作。
+    *   将智能体的响应返回给框架。
+    *   处理奖励和更新。
+3.  **创建示例**：在 `train/examples/` 目录中添加一个新示例，以演示如何使用新的适配器。
+
+可以参考现有的 `verl` 适配器（`train/adapter/verl/`）作为参考实现。
+
+---
+
+<div align="center">
+
+**AWorld Train** — 让你的 AWorld 智能体快速接入主流训练框架
+
+[license-image]: https://img.shields.io/badge/License-MIT-yellow.svg
+[license-url]: https://opensource.org/licenses/MIT
+
+</div>
+
+