# AWorld Train
*为使用 AWorld 构建的智能体，提供与外部 RL/训练框架对接的、与框架无关的适配层、可运行示例与通用工具*
[![License: MIT][license-image]][license-url]
---
AWorld Train 为 AWorld 智能体生态系统和各种外部训练框架（如强化学习库）之间提供了一座桥梁。它被设计为框架无关的，可以选择你喜欢的训练环境使用AWorld 智能体。
下图说明了环境和训练集群之间的整体架构和交互：
## 环境构建
首先，您需要设置智能体工具将要运行的环境。
选择一台机器（也可以是训练机）。
机器规格建议：
- 为进行容量规划，为每个并发工作进程分配大约 **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=
TAVILY_API_KEY=
GOOGLE_API_KEY=
GOOGLE_CSE_ID=
DATALAB_API_KEY=
E2B_API_KEY=
MCP_LLM_BASE_URL=
MCP_LLM_MODEL_NAME=
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
export MCP_SERVER_URL=http://:/mcp
export MCP_SERVER_TOKEN=
# 或将它们添加到 .env 文件中
# echo "MCP_SERVER_URL=http://:/mcp" >> .env
# echo "MCP_SERVER_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/`）作为参考实现。
---
**AWorld Train** — 让你的 AWorld 智能体快速接入主流训练框架
[license-image]: https://img.shields.io/badge/License-MIT-yellow.svg
[license-url]: https://opensource.org/licenses/MIT