Agent S2.5 在 OSWorld 基准上的完整部署与评测实战：本地 VMware 与 AWS 云端双方案运行指南-平芜编程栈

人工智能
大模型
AI Agent
自主智能体
GUI 自动化

【免费下载链接】Agent-S

Agent S: an open agentic framework that uses computers like a human

项目地址：https://gitcode.com/GitHub_Trending/ag/Agent-S

本指南以仓库 osworld_setup/s2_5/OSWorld.md 为核心骨架，详细讲解如何将 Agent S2.5（Agent S 家族中采用无层级 Worker 架构的精简版本）接入 OSWorld 桌面智能体评测环境，并给出本地 VMware 与 AWS 云端两套可运行的评测方案。读者读完本文后将掌握：Agent S2.5 评测运行脚本的全部命令行参数与含义、单任务执行循环的内部机制、OSWorldACI 将"自然语言描述动作"落地为"屏幕坐标 + PyAutoGUI 代码"的完整原理，以及如何利用多进程并行与断点续跑机制高效完成整批评测。

一、Agent S2.5 与 OSWorld：评测前必读的背景

OSWorld 是评估计算机智能体（Computer Use Agent）能否像人类一样完成操作系统级任务的经典桌面基准：智能体收到一段自然语言指令（例如"在 LibreOffice Calc 中把 A2 单元格设为 100 并保存"），通过截图观察屏幕状态，逐步输出鼠标键盘动作，最后由环境根据任务完成度给出 0~1 之间的奖励分数。

仓库中的 Agent S2.5（代码位于 gui_agents/s2_5/）是这个评测场景下直接可用的智能体实现。它的核心设计是去层级化（no hierarchy）：与其前后版本（S2 的 Manager/Worker 层级、S3 的反思式复合方案）不同，AgentS2_5 只保留一个直接面向任务的 Worker，用更少的推理开销完成同样的桌面操作任务。其类定义注释原文即点明了设计动机："Agent that uses no hierarchy for less inference time"（见 agent_s.py）。

从 agent_s.py 可以看到 AgentS2_5 的推理接口非常简洁：

def predict(self, instruction: str, observation: Dict) -> Tuple[Dict, List[str]]: executor_info, actions = self.executor.generate_next_action( instruction=instruction, obs=observation ) info = {**{k: v for d in [executor_info or {}] for k, v in d.items()}} return info, actions

每次predict只调用一次Worker.generate_next_action，返回当前步的动作代码列表。这意味着在 OSWorld 评测中，Agent S2.5 的每个决策回合只有一次主模型调用（外加可选的反思模型调用），评测速度与 Token 成本都更可控。

二、Step 1：安装并配置 Agent S2.5

原文档的第一步是"Set up Agent S2.5"。安装与初始化 Agent S2.5 本身，请以仓库根目录的 README.md 为准：其中包含依赖安装（见 requirements.txt 与 setup.py）、环境变量（OpenAI/Anthropic 等 API Key，run.py顶部通过load_dotenv()加载.env文件）以及多模态模型引擎的配置说明（仓库提供了 models.md 作为模型选型参考）。

在评测脚本中，Agent S2.5 的初始化代码集中在 run.py：

from gui_agents.s2_5.agents.agent_s import AgentS2_5 from gui_agents.s2_5.agents.grounding import OSWorldACI grounding_agent = OSWorldACI( platform="linux", engine_params_for_generation=engine_params, engine_params_for_grounding=engine_params_for_grounding, width=args.screen_width, height=args.screen_height, ) agent = AgentS2_5(engine_params, grounding_agent, platform="linux")

这里有两个核心概念值得展开：

engine_params（生成模型参数）：驱动 Worker 主智能体的多模态大模型配置，包含engine_type（如openai、anthropic、azure、vllm、huggingface、gemini、open_router、parasail）、model、base_url、api_key、temperature等字段。底层引擎实现见 engine.py，例如LMMEngineOpenAI在未显式传入api_key时会回退读取环境变量OPENAI_API_KEY，并对连接错误、速率限制使用backoff指数退避重试（最长 60 秒），评测时的网络抖动不会轻易中断整个任务。
engine_params_for_grounding（坐标模型参数）：多出grounding_width与grounding_height两个字段，用于声明坐标定位模型（Grounding Model）输入截图被 processor 缩放后的分辨率。评测时这两项必须正确填写，否则坐标缩放会失真（详见第四节）。

三、Step 2：把运行文件复制进 OSWorld 环境

原文档明确指出：请先按照 OSWorld 官方仓库的说明完成OSWorld 环境设置（安装desktop_env依赖、准备 Ubuntu 虚拟机镜像/AMI 等），然后将本目录osworld_setup/s2_5/下的运行文件整体复制到你的 OSWorld 仓库目录中。

原文档给出了两套运行方案的明确分工，这里完整保留并补充说明：

运行文件	适用场景	核心差异
run.py + lib_run_single.py	AWS 云端批量评测	支持多环境并行、进程崩溃自动重启、通过`IMAGE_ID_MAP`按区域自动选择 AMI 快照
run_local.py + lib_run_single_local.py	本地 VMware单机评测	串行执行、固定使用`signed_in_state_1`快照、内置四路日志（normal/debug/stdout/sdebug）

在 OSWorld 目录中，run.py/run_local.py位于仓库根目录（与desktop_env、evaluation_examples平级），lib_run_single*.py与之同目录；运行脚本通过相对路径约定读取评测任务定义，例如默认的任务清单路径是evaluation_examples/test_all.json，任务配置位于evaluation_examples/examples/{domain}/{example_id}.json。

四、运行命令与全部参数详解

4.1 AWS 云端评测（run.py）

run.py是一个支持multiprocessing并行评测的完整调度器。其命令行参数定义在 config() 中，以下是完整参数表（含默认值与作用说明）：

环境相关参数

参数	类型	默认值	说明
`--path_to_vm`	str	`None`	本地虚拟机（VMware/VirtualBox 等）的 vmx 路径；AWS 场景可留空
`--provider_name`	str	`vmware`	虚拟化提供方，可选`vmware`、`docker`、`aws`、`azure`、`gcp`、`virtualbox`
`--headless`	flag	关闭	是否在无显示器（headless）机器上运行
`--action_space`	str	`pyautogui`	动作空间类型，评测脚本默认使用 PyAutoGUI 生成代码动作
`--observation_type`	枚举	`screenshot`	观测类型，可选`screenshot`、`a11y_tree`、`screenshot_a11y_tree`、`som`；当选择`a11y_tree`、`screenshot_a11y_tree`或`som`时，`DesktopEnv`会自动开启无障碍树（`require_a11y_tree=True`）
`--num_envs`	int	`1`	并行运行的环境（进程）数量，用于多机/多实例并行评测
`--screen_width`	int	`1920`	虚拟机屏幕宽度
`--screen_height`	int	`1080`	虚拟机屏幕高度
`--sleep_after_execution`	float	`1.0`	每次动作执行后等待的时间（秒），用于等待界面渲染稳定
`--max_steps`	int	`15`	每个任务允许的最大动作步数
`--domain`	str	`all`	只评测指定领域（如`LibreOffice`、`VLC`等）；`all`表示评测 test_all.json 中全部领域
`--test_all_meta_path`	str	`evaluation_examples/test_all.json`	任务清单文件路径
`--test_config_base_dir`	str	`evaluation_examples`	任务配置（examples）所在基目录
`--result_dir`	str	`./results`	评测结果输出根目录
`--region`	str	`us-east-1`	AWS 区域，用于从`desktop_env/providers/aws/manager.py`的`IMAGE_ID_MAP`中选择对应区域与屏幕分辨率的 AMI 快照
`--client_password`	str	`""`	虚拟机的客户端密码（`DesktopEnv`需要时使用）

智能体相关参数

参数	类型	默认值	说明
`--max_trajectory_length`	int	`8`	上下文窗口内保留的最大截图轮数，超过后按模型类型执行消息裁剪策略（见第六节）

生成模型（主 LLM）参数

参数	类型	默认值	说明
`--model_provider`	str	`openai`	主模型引擎类型
`--model`	str	`gpt-4o`	主模型名称
`--model_url`	str	`""`	主模型 API 地址（兼容中转/私有部署）
`--model_api_key`	str	`""`	主模型 API Key，缺省时回退环境变量
`--model_temperature`	float	`None`	强制固定主模型 temperature（例如`o3`系列只能以`1.0`运行）；为`None`时使用各次调用传入的默认值

坐标定位模型（Grounding Model）参数

参数	类型	默认值	说明
`--ground_provider`	str	必填	坐标定位模型引擎类型
`--ground_url`	str	必填	坐标定位模型 API 地址
`--ground_api_key`	str	`""`	坐标定位模型 API Key
`--ground_model`	str	必填	坐标定位模型名称
`--grounding_width`	int	必填	截图经 processor 缩放后的宽度（定位模型输入分辨率）
`--grounding_height`	int	必填	截图经 processor 缩放后的高度（定位模型输入分辨率）

典型启动命令示例：

python run.py \ --provider_name aws \ --observation_type screenshot \ --action_space pyautogui \ --num_envs 8 \ --max_steps 15 \ --max_trajectory_length 8 \ --model_provider openai \ --model gpt-4o \ --ground_provider openai \ --ground_url "https://your-grounding-model-endpoint/v1" \ --ground_model "your-grounding-model" \ --grounding_width 1280 \ --grounding_height 720 \ --region us-east-1 \ --result_dir ./results

4.2 本地 VMware 评测（run_local.py）

run_local.py 是面向本地单机、串行执行的轻量版本，参数大体与run.py一致，但有以下关键差异：

没有--num_envs、--region、--client_password参数（不涉及多进程与 AWS）；
--sleep_after_execution默认值为3.0（本地环境更保守的等待时长）；
--max_trajectory_length默认值为3；
额外提供--temperature参数，默认1.0；
创建DesktopEnv时固定使用snapshot_name="signed_in_state_1"（即 OSWorld 官方为评测准备的"已登录状态"虚拟机快照，确保每个任务从干净状态出发）；
日志系统配置了四路输出：logs/normal-*.log、logs/debug-*.log、logs/sdebug-*.log与标准输出，方便本地排查（见 run_local.py）。

典型启动命令示例：

python run_local.py \ --provider_name vmware \ --path_to_vm "/path/to/your/ubuntu.vmx" \ --observation_type screenshot \ --max_steps 15 \ --model_provider openai \ --model gpt-4o \ --ground_provider openai \ --ground_url "https://your-grounding-model-endpoint/v1" \ --ground_model "your-grounding-model" \ --grounding_width 1280 \ --grounding_height 720 \ --result_dir ./results

关于 API Key 的来源：两个脚本都调用load_dotenv()加载环境变量；OpenAI 引擎缺省回退读取OPENAI_API_KEY、Anthropic 引擎回退读取ANTHROPIC_API_KEY（见 engine.py）。你也可以把 key 直接写在--model_api_key/--ground_api_key参数中。

五、单任务执行循环：lib_run_single 内部机制

无论云端还是本地，最终每个任务都交给run_single_example执行。以 lib_run_single.py 为例，其流程如下：

重置智能体与环境：调用agent.reset(runtime_logger)清空 Worker 的对话历史与反思记录；调用env.reset(task_config=example)将虚拟机恢复到指定快照并加载任务配置。
等待环境就绪：time.sleep(60)等待 60 秒，让虚拟机启动并进入稳定状态，随后通过env._get_obs()获取初始截图观测obs。
初始化产物：将初始截图写入step_0.png，把任务指令写入instruction.txt，并开始屏幕录制env.controller.start_recording()。
循环执行直到完成：在step_idx < max_steps的循环中：
- 调用agent.predict(instruction, obs)获取(response, actions)，其中actions是形如"import pyautogui; pyautogui.click(x, y, clicks=1, button='left')"的可执行代码字符串；
- 逐个动作调用env.step(action, args.sleep_after_execution)执行并返回新的观测、奖励、完成标志与附加信息；
- 将每一步的截图保存为step_{step_idx+1}_{timestamp}.png，并把包含完整计划、思考、动作、奖励、完成标志等信息的response追加写入traj.jsonl；
- 一旦done=True立即结束循环。
评估与收尾：调用env.evaluate()获得该任务 0~1 的最终得分，追加到共享scores列表、写入result.txt，最后结束录制得到recording.mp4。

本地版本 lib_run_single_local.py 与之几乎一致，仅在动作执行前增加time.sleep(0.5)（合计约 3.5 秒/步的节奏），并在异常处理上做区分。

六、Agent S2.5 决策原理：从自然语言到屏幕坐标

这是整个评测链路的技术核心。Agent S2.5 的动作生成分三层协作完成，理解这三层就能理解为什么评测时需要"生成模型 + 坐标定位模型"两套模型配置。

6.1 Worker：生成自然语言计划与"描述式动作"

worker.py 中的Worker是唯一决策者。它的系统提示词由 procedural_memory.py 中的construct_simple_worker_procedural_memory动态生成：代码会遍历OSWorldACI的所有带@agent_action装饰器的方法，用inspect.signature把每个动作的签名与 docstring 拼进提示词，并明确要求模型按四个固定段落输出：

(Previous action verification)—— 依据截图验证上一步动作是否成功；
(Screenshot Analysis)—— 分析当前桌面状态；
(Next Action)—— 用自然语言描述下一步动作；
(Grounded Action)—— 将动作翻译为调用 API 的 Python 代码块，例如：

agent.click("The menu button at the top right of the window", 1, "left")

提示词还包含 10 条硬性约束，例如"每次只执行一个动作""必须只用提供的 API 方法""优先使用agent.hotkey()快捷键""任务完成立即agent.done()、无法完成则agent.fail()"等。注意：这里模型输出的 click 参数是自然语言描述（如"窗口右上角的菜单按钮"），而不是坐标——真正的坐标由 OSWorldACI 负责换算。

6.2 OSWorldACI：把描述翻译成坐标与可执行代码

grounding.py 中的OSWorldACI承担"描述 → 坐标 → PyAutoGUI 代码"的落地工作，Worker.generate_next_action在拿到计划后调用agent.assign_coordinates(plan, obs)完成坐标分配（见 worker.py）。其内部机制可拆解为三条链路：

视觉坐标生成（generate_coords）：对agent.click、agent.type、agent.scroll、agent.drag_and_drop等动作，把元素描述与当前截图拼成"Query:{ref_expr}\nOutput only the coordinate of one point..."提示，交给坐标定位模型，并用正则从响应中提取第一个坐标点（见 grounding.py）。
文本坐标生成（generate_text_coords）：对agent.highlight_text_span这类文本定位动作，先用pytesseract（OCR）对截图生成"Word id → 文本 → 包围盒"表，再让文本跨度模型（text_span_agent，由PHRASE_TO_WORD_COORDS_PROMPT驱动）选出短语对应的首/尾单词 id，从而算出高亮起点与终点坐标（见 grounding.py）。
坐标缩放（resize_coordinates）：定位模型输出的是其输入分辨率下的坐标，评测环境是 1920×1080 屏幕，因此必须按grounding_width/grounding_height与screen_width/screen_height的比例做线性缩放（见 grounding.py）。这就是--grounding_width、--grounding_height必须如实填写的根本原因。

落地阶段通过parse_single_code_from_string+extract_first_agent_function+eval将"描述式动作"解析为实际调用，由OSWorldACI的@agent_action方法（click/type/scroll/drag_and_drop/hotkey/switch_applications/set_cell_values 等，共 13 个）生成最终可执行的 PyAutoGUI 代码。以 click 为例，生成形如pyautogui.click(x, y, clicks=n, button='left')的代码并同时支持hold_keys键保持；set_cell_values则内嵌一段通过 UNO API 操作 LibreOffice Calc 单元格的完整脚本。若解析失败，Worker 会降级为agent.wait(1.0)，保证任务不会被单步异常中断（见 worker.py）。

6.3 Reflection：可选的轨迹反思

Worker默认开启反思（enable_reflection=True）：从第 2 步起，反思模型（使用REFLECTION_ON_TRAJECTORY提示词，见 procedural_memory.py）会基于当前轨迹判断是否陷入"重复动作循环"或"偏离计划"，并把反思结论注入主模型下一轮的generator_message。反思结果会随每步轨迹记录到traj.jsonl中（reflection字段），便于事后分析智能体行为。

6.4 上下文裁剪策略（flush_messages）

评测步数一多，历史消息（尤其是多张截图）会逼近上下文上限。Worker.flush_messages按引擎类型区分两种策略（见 worker.py）：

长上下文模型（anthropic/openai/gemini）：保留全部文本，只裁剪掉超出max_trajectory_length的旧截图（图片轮数受--max_trajectory_length控制）；
其他引擎：直接丢弃最早的整轮对话（生成器每 2 条消息算一轮、反思器每 1 条算一轮）。

6.5 引擎封装

所有模型调用统一走 mllm.py 的LMMAgent，它根据engine_type分派到 engine.py 中对应的LMMEngine*实现，并统一把截图编码为 base64 图片消息。特别地，若model为claude-3-7-sonnet-20250219，Worker 会自动启用 thinking 模式（use_thinking=True），并通过split_thinking_response把思考内容与正式回答分离（当前实现不把思考 token 放回上下文）。

七、AWS 并行评测调度与断点续跑

若使用云端方案，run.py 的调度器值得单独说明（对应test()函数，见 run.py）：

任务分发：distribute_tasks把test_all.json展平为(domain, example_id)元组队列；若指定--domain，则只保留该领域任务。
多进程执行：按--num_envs启动多个EnvProcess工作进程，每个进程内创建独立的OSWorldACI、AgentS2_5与DesktopEnv实例，共享一个Manager.Queue任务队列和Manager.list分数列表。
进程守护与重启：主进程每 5 秒巡检一次，发现某工作进程退出会立即以EnvProcess-Restart-N重启并接续队列（避免单个环境崩溃拖垮整批评测）；若所有进程同时死亡则主动报错退出。
优雅退出：注册了SIGINT/SIGTERM信号处理器，收到中断信号时会先关闭所有环境（env.close()）、终止全部工作进程，再退出，尽量避免脏数据残留。
断点续跑：get_unfinished会扫描结果目录{result_dir}/{action_space}/{observation_type}/{model}，凡是缺少result.txt的已存在任务目录会被清空重跑，已完成的（有result.txt）任务从清单中剔除，从而支持中途中断后继续评测；get_result则会即时打印当前累计成功率（Current Success Rate: xx.xx%）。
参数落盘：启动时会把本次运行的全部参数写入{result_dir}/{action_space}/{observation_type}/{model}/args.json，保证每次评测的配置可追溯、可复现。

八、评测产物与结果解读

每次运行会在--result_dir下生成按{action_space}/{observation_type}/{model}/{domain}/{example_id}组织的目录，每个任务目录内包含：

文件	内容
`step_0.png`	环境就绪后的初始截图
`step_{n}_{timestamp}.png`	每一步动作执行后的屏幕截图
`instruction.txt`	该任务的自然语言指令
`traj.jsonl`	逐步轨迹日志，每行含`full_plan`、`executor_plan`、`plan_code`、`reflection`、`step_num`、`action`、`reward`、`done`、`screenshot_file`等字段
`result.txt`	任务最终得分（0~1，`env.evaluate()`的结果）
`recording.mp4`	从任务开始到结束的屏幕录像
`runtime.log`	该任务的运行日志（由`setup_logger`写入）

评测结束后，run.py会输出Average score: ...，run_local.py会输出Average score: ...，即 OSWorld 官方口径的 Success Rate。所有任务完成后，你可以对result.txt按领域聚合，得到各领域（如 LibreOffice、VLC、GIMP、Chrome 等）的细粒度成功率。

九、常见问题与注意事项

坐标定位模型参数缺失：--ground_provider、--ground_url、--ground_model、--grounding_width、--grounding_height在run.py与run_local.py中均为必填（required=True），缺一不可；grounding_width/height必须与实际部署的定位模型 processor 输出分辨率一致，否则点击位置会系统性偏移。
API Key 配置：脚本依赖.env（load_dotenv()）或对应环境变量（OPENAI_API_KEY、ANTHROPIC_API_KEY）；未配置时引擎会直接抛出ValueError提示。
快照状态：本地 VMware 方案固定使用signed_in_state_1快照——请确认你的 OSWorld 虚拟机存在该命名的快照；AWS 方案由IMAGE_ID_MAP按--region与屏幕分辨率自动匹配 AMI，因此--region要与实例所在区域一致。
观测类型与无障碍树：只有a11y_tree、screenshot_a11y_tree、som三种观测类型才会开启require_a11y_tree；默认的screenshot方案完全依赖视觉定位模型，无需额外依赖。
agent.done()/agent.fail()：Worker 提示词要求任务完成或确定无法完成时立即终止；如果评测日志中大量出现FAIL，请优先检查坐标定位模型效果与--grounding_*参数，而不是主模型本身。
上下文长度：长任务建议保持默认--max_trajectory_length（云端 8 / 本地 3）并根据主模型上下文窗口微调；裁剪策略对长上下文模型（anthropic/openai/gemini）与普通模型不同，切换引擎时留意行为差异。

按上述流程完成配置后，即可在本地 VMware 或 AWS 上完整复现 Agent S2.5 在 OSWorld 基准上的端到端评测；若需要进一步比较不同模型/轨迹方案的优劣，可参考仓库中 osworld_setup/s3/ 的 BBON（Behavior Narrator + Comparative Judge）方案，对多组结果目录做基于行为描述的轨迹对比评判。