使用 REA 构建 RL 环境¶

REA 将录制的 Web 应用会话转变成可运行的环境，用于训练和测试 AI 智能体。智能体可以在不运行原始应用的情况下练习查找问题、创建文件夹、编辑记录等任务。

REA 会构建智能体所调用的工具、这些工具使用的本地数据，以及一个用于检查环境能否启动并响应的测试。当录制内容确认了变更效果时，REA 会支持这些变更。之后，你可以将环境与你的 RL 框架配合使用，以设置任务目标、检查奖励并运行训练。

开始之前¶

安装 REA 及其智能体集成。要录制应用，你还需要一个运行中的测试实例和 Chrome 系列浏览器。请选择一个允许智能体创建、编辑和删除数据的实例。REA 会录制你提供的应用；你需要启动它并准备好测试数据。

要运行导出后的环境，请安装 AgentEnv 框架 并启动 Docker。REA 的兼容性检查使用 AgentEnv 0.9.1334 版本与 Python 3.12。

构建环境有两种方式：让智能体录制应用，或从已有录制开始。

1. 使用你的智能体录制并构建¶

为智能体提供应用 URL、所需操作、浏览器可执行文件路径以及输出目录。对于包含文件夹的应用，可参考以下提示词：

Use REA to build an AgentEnv environment from my test web app at
http://127.0.0.1:3000. Cover listing, creating, renaming, and deleting folders.
You may create and remove test folders. Leave the existing data unchanged.

Sign in as admin using the password in APP_PASSWORD. Use the browser at
/absolute/path/to/chromium. Save the environment to
/absolute/path/to/my-env, which does not exist yet.

Record the session, check which operations the environment supports, and
export it. Report any unsupported operations and what is missing.

请将 URL、账户、路径和文件夹操作替换为你自己的内容。在启动 REA 的 MCP 服务器的环境中设置 APP_PASSWORD，这样 REA 就能使用它，而无需在提示词中写入密码。

你的智能体会检查应用、录制会话、检查结果，并导出一个包含可运行环境的文件夹。它会报告哪些操作有效、哪些需要更多证据。应用仅在录制期间使用；导出后的环境会从已保存的数据运行。

当智能体导出文件夹后，请跳到运行环境。下一节是面向已有录制的另一种方式。

2. 或者从已保存的录制进行构建¶

HAR 文件记录浏览器的网络请求和响应。请从浏览器网络面板导出一个包含 API 响应体的 HAR 文件，或使用你已有的录制。要涵盖创建、编辑和删除操作，请录制这些操作以及展示其结果的读取操作。

将环境构建到新的或空目录中：

rea environment-build ./session.har ./my-env --name my-env --json

你也可以传入 REA 的 capture-browser-scenario 或 inspect-web-network-capture 命令保存的 Evidence JSON。这里，Evidence 指 REA 保存的录制及其来源信息。构建过程接受 HAR 文件及这些 JSON 录制。它会读取本地数据并写入环境文件夹，而无需联系应用。

添加 --dry-run 可在不写入文件夹的情况下查看构建报告。对于未发布的 REA 检出（checkout），请搭配其打包后的包使用 --package-tarball，以便导出后的环境运行相同的实现。

构建报告会告诉你环境支持哪些功能：

构建成功意味着文件夹已创建。请检查报告，确认它支持你的任务所需的操作。coverage: null 表示构建无法为该环境准备状态，它将使用回放。

3. 运行环境¶

无论你的智能体导出了文件夹，还是你从 HAR 构建了它，都可以使用 AgentEnv 运行：

agent-env run ./my-env

如果智能体报告的文件夹路径不同，请使用该路径。首次运行会构建容器镜像，因此需要访问镜像和软件包源。

REA 包含一个名为冒烟任务（smoke task）的基础测试。它会检查预期工具数量，并在存在合适的读取工具时调用该工具并检查其响应状态。通过此测试表明环境能在所测试的设置中启动并响应。它尚不会对智能体在应用任务上的表现进行评分。

该文件夹包含录制、描述可用操作的工具清单、Dockerfile、环境配置以及测试。导出参考 对每个文件进行了说明。

4. 添加任务与奖励检查¶

从一个导出的工具支持的任务开始。为它设定明确的目标和可检查的结果。例如，如果支持创建文件夹，请让你的智能体执行：

Use this exported environment to add an AgentEnv task that asks an agent
to create a folder named Practice. Check the saved environment state to
confirm the folder exists with that name, and use that check to score the
result. Reset the environment before each run so attempts start with the
same data. Use the AgentEnv task and verifier formats.

这要求你的智能体（agent）围绕 REA 生成的环境来帮助构建任务及其评分检查。检索类任务可能会将答案与记录值进行核对。改变数据的任务则应检查最终状态。当状态可用时，环境支持重置、加载和回读操作，以实现可重复运行。

请参阅 AgentEnv 文档 了解任务配置、智能体连接、评分和执行。将生成的任务连接到你所选的 RL 训练工作流中。

改进缺失的操作¶

为了让 REA 支持某项变更，录制需要展示变更前后的情况。在针对测试应用进行录制时：

1. 在进行更改之前，先读取列表和一个现有条目。重复这些初始读取，以显示哪些值会独立变化。
2. 创建一个测试条目，将其读回，并在下一次更改前读取列表。用第二个条目和不同的文本重复此操作。
3. 编辑每个测试条目，然后再次读取该条目和列表。在创建与首次编辑之间留出超过一秒的时间，以显示与时间相关的变化。
4. 删除测试条目，然后将其读回并读取列表，以确认它们已被移除。

如果任务需要，还要录制筛选、搜索、排序和分页操作。智能体应在使用录制结果前检查每个录制步骤是否已完成。录制工作流 提供了详细的浏览器操作说明，包括超时以及如何处理应用分配的 ID。

根据报告中的提示决定接下来录制什么：

其他情况请参阅完整原因表。从新的录制内容重建，并再次检查报告。新的录制会替换构建输入；不支持合并多次单独的录制会话。

与原始应用进行比较¶

为了进行更有力的检查，请针对真实应用录制独立的调用序列，从与原始录制相同的测试数据开始。这就是一次探针（probe）。在每个探针序列之前恢复该起始数据，然后将保存的探针录制与环境进行比较：

rea environment-compare ./my-env/envs/my-env/manifest.json \
  --evidence ./my-env/envs/my-env/evidence.json \
  --probe ./probe-create-edit-delete.json --probe ./probe-reads.json --json

每个探针文件必须是来自 REA 的 Evidence JSON 捕获。比较过程离线运行，并报告响应中的差异、不支持的调用和缺失的观察结果。它会考虑 ID、时间和已建模生成值中受支持的差异。一致性适用于这些探针所检查的调用。具体规则请参阅比较参考。

共享环境之前¶

导出的文件夹包含保留的响应体和本地源路径。标准认证头会被排除，但自定义头、查询值和请求体令牌可能会保留。请审查你计划共享的内容。凭据名称警告会指出值得审查的值；它们不会移除此类值，也不能证明录制中不含任何凭据。

有关直接 MCP 服务、回放行为、状态控制和资源限制，请参阅环境参考。实现索引 链接了相关贡献 PR 及其验证记录。