Agent S

这是什么？适合谁？

Agent S 是 simular-ai/Agent-S 这个开源仓库（Apache-2.0）的统称，核心是计算机操作智能体（computer-use agent，CUA）：你给一句自然语言任务，它截屏观察界面，然后通过点击、输入、滚动在普通桌面和网页应用里把事做完，支持 macOS、Windows 和 Linux。

仓库现在有两条线，别混着看：

• Agent S3（gui-agents 包）：仓库里今天真正能 pip install 上手的那一代。它在 OSWorld 的 100 步设置下单独跑到 66%，叠加 Behavior Best-of-N 后到 72.6%，官方称这是首次超过 OSWorld 的人类水平（约 72%）；零样本迁移到 WindowsAgentArena（50.2% → 3 次 rollout 选优 56.6%）和 AndroidWorld（68.1% → 71.6%）。
• Agent S4（2026-10-20 发布）：论文《Evolving Agent Interfaces》（arXiv 2610.28601）的产物。它不再只用人类给定的接口，而是让一个 Builder 从任务经验里自演进工具接口，把演出来的接口装到任务智能体上跑基准。用 Qwen3.8-27B 时，Agent S4 在 OSWorld V2 拿到 21.3%，是同一模型配固定接口的 3.8 倍，高于 GPT-5.5（13.0%）与 Claude Opus 4.8（20.6%）。注意 OSWorld V2 是严格二元判定（pass/fail，无部分分），21.3% 反映的是基准难度，不等于 21.3% 的任务会「做一半」。

同一家公司（Simular）另有托管产品 Sai，走 Simular API 在云电脑上跑，不需要自己装环境；本条目评的是开源仓库与本地部署路径。

适合谁：想在自己机器上复现 computer-use 基准、做 GUI 智能体研究或二次开发的工程师；需要「不依赖软件 API、直接操作界面」的自动化场景（老系统、无接口的内部工具）；正在对比 Claude Computer Use、OpenAI Operator 这类闭源方案的研究者。

不适合谁：只想要一个能稳定跑业务流的托管服务（那应该看 Sai 或闭源 CUA API）；没有模型 API 预算、也不打算配接地模型的人；只操作单一应用、可以用脚本或 API 解决的场景。

准备工作

1. Python 环境：能装 gui-agents，仓库以 pip install gui-agents 或 pip install -e . 两种方式使用。
2. 一个主生成模型凭据：OPENAI_API_KEY / ANTHROPIC_API_KEY 等；官方支持 Azure OpenAI、Anthropic、Gemini、OpenRouter 与 vLLM 推理端点。
3. 一个接地模型（grounding model）：这是必填项。官方推荐 ByteDance 的 UI-TARS-1.5-7B，部署在 Hugging Face Inference Endpoints 或其它服务上，另需 HF_TOKEN。
4. 单显示器环境：官方明确说明智能体是按单显示器设计的。
5. OCR 依赖（macOS）：brew install tesseract，否则 pytesseract 起不来。
6. 成本预期：每一步都要截屏送视觉模型，token 消耗与任务步数线性相关；接地模型是第二份调用，预算要按两套模型估。

快速上手：从装包到第一个任务

Step 1 — 安装 S3

pip install gui-agents
# 想边改代码边跑：clone 仓库后 pip install -e .
# macOS 还需要 OCR 依赖
brew install tesseract

Step 2 — 配置凭据

export OPENAI_API_KEY=<YOUR_API_KEY>
export ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>
export HF_TOKEN=<YOUR_HF_TOKEN>

Step 3 — 起接地模型端点：把 UI-TARS-1.5-7B 部署到 HF Inference Endpoints（或等价服务），拿到 URL。

Step 4 — 跑第一个任务

agent_s \
    --provider openai \
    --model gpt-5-2025-08-07 \
    --ground_provider huggingface \
    --ground_url http://localhost:8080 \
    --ground_model ui-tars-1.5-7b \
    --grounding_width 1920 \
    --grounding_height 1080

官方推荐组合是「主模型 OpenAI gpt-5-2025-08-07 + 接地模型 UI-TARS-1.5-7B」。上面这条命令跑的是不含 bBoN 的 S3。

Step 5 — 用 Python 调用（可选）

import os
os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>"

from gui_agents.s3.agents.agent_s import AgentS3
from gui_agents.s3.agents.grounding import OSWorldACI

# AgentS3 负责规划与动作，OSWorldACI 负责把动作翻译成可执行的 pyautogui 代码

成功判定：任务结束后能看到整个轨迹的每一步截图与动作日志，且目标界面状态真的变了（文件被改名、表单被提交、页面被切到指定标签）。不要只看 CLI 有没有报错。

初级用法

1. 老系统里的重复录入：没有 API 的内部管理后台，用截屏 + 坐标点击把「导出 → 改名 → 上传」串起来。先在测试账号上跑，确认不会误点「删除」类按钮再上真实数据。

2. 网页端的跨系统搬运：从一个后台复制订单号、到另一个后台查询状态、把结果填回表格。这类任务步骤固定、界面稳定，是 computer-use 最能体现价值的地方。

3. 冒烟测试：把「登录后台 → 打开设置页 → 保存一次配置」写成任务，跑在每晚的测试环境里，用截屏轨迹当证据。比写 Playwright 脚本省事，代价是慢且不确定。

高级玩法

1. Behavior Best-of-N（bBoN）：同一任务并行采样多条轨迹再选优，官方在 OSWorld 上正是靠它从 66% 提到 72.6%。代价是 token 与耗时成倍上升，适合离线评测、不适合交互式使用。

2. 开本地代码环境做「GUI 到脚本」的混合任务：加 --enable_local_env 后，智能体可以执行本地 Python / Bash 处理数据文件，再回到界面做需要人机交互的部分。官方对这个开关有明确警告（见踩坑 4）。

3. 换接地模型调分辨率：UI-TARS-1.5-7B 用 --grounding_width 1920 --grounding_height 1080，UI-TARS-72B 用 1000x1000。接地模型输出坐标系不同，这两个参数决定点击位置准不准。

4. 用 S4 做「接口演进」实验：pip install agent-s4（或 pip install -e ./agent_s4）指向仓库 clone 里的 osworld_setup/s4，导出 SHADOW_EVOL_SHARED_ROOT，再跑 python -m agent_s4.cli run。这条线是研究向的，需要 AWS 机器与模型凭据，不是产品向。

小技巧

• 主模型温度不设时，遇到 o3 这类要求固定温度的模型要显式传 --model_temperature 1.0。
• --max_trajectory_length 默认只保留 8 轮图像，长任务要么调大、要么把任务拆短。
• --enable_reflection 默认是 True，反射智能体会额外调用模型；想省预算可以先关掉做对照。
• 接地模型跑在本机时，--ground_url 指本机端口即可，不必绕公网，省一次往返延迟。
• 先在单显示器 + 固定分辨率的环境里调到稳定，再考虑多任务；分辨率一变，坐标映射就要重验。

进阶学习建议

• 先读 Agent S3 论文《Scaling Agents for Computer Use》（TMLR 2026），重点是 Behavior Best-of-N 与 reflection 的分工，这两块决定了它的分数是怎么来的。
• 再读 《Evolving Agent Interfaces》（Agent S4，arXiv 2610.28601），看 Builder / Task Agent 两段式怎么把接口演进变成可评测的变量。
• 仓库里的 models.md 列出支持的 provider 与模型组合，换模型前先查它，别自己猜参数。
• 想复现基准就去看 osworld_setup/：OSWorld 的默认基准、S4 的 osworld_v2_preflight 都在里面，先跑离线检查再开实验。
• 接地模型这条线建议直接读 UI-TARS 的模型卡，理解「坐标分辨率」这个概念的物理含义，比背参数有用。

常见踩坑

踩坑 1：多显示器下点错位置。 现象：单屏演示正常，插上副屏后动作落在错误窗口。 原因：官方明确说明智能体按单显示器设计，坐标空间是单一屏幕。 解决：跑任务时只保留一个显示器，或把目标窗口拖到主屏并固定分辨率。

踩坑 2：接地分辨率写错，全部点偏。 现象：智能体能说对要做什么，但点击总是偏几十像素。 原因：--grounding_width/--grounding_height 必须与接地模型输出坐标系一致（UI-TARS-1.5-7B 是 1920×1080，72B 是 1000×1000）。 解决：按模型卡核对这两值；换模型必须同步改。

踩坑 3：macOS 上 pytesseract 报错。 现象：安装成功、一跑就抛 OCR 相关异常。 原因：pytesseract 只是包装，系统还得有 tesseract 本体。 解决：brew install tesseract，重启终端后复跑。

踩坑 4：开了本地代码环境，等于把机器交给模型。 现象：任务过程中出现你没要求的文件操作或命令。 原因：--enable_local_env 让智能体用当前用户权限执行任意 Python / Bash，官方有明确 WARNING。 解决：只在可信环境、可信输入下开启；跑不可信任务请用沙箱或虚拟机；不要把带真实凭据的目录暴露给它。

踩坑 5：以为 pip install gui-agents 就装到了 S4。 现象：装完找不到 agent_s4 模块。 原因：官方写明 agent-s4 是独立包，装 gui-agents 不含它；而且 S4 还需要仓库 clone 里的 osworld_setup/s4 文件。 解决：pip install agent-s4 并导出 SHADOW_EVOL_SHARED_ROOT；缺文件时 CLI 会直接停下并提示要设什么。

踩坑 6：把基准分当产品可用度。 现象：看到 72.6% 就以为「七成任务能自己完成」。 原因：OSWorld 的分数口径（步数限制、bBoN 选优、二元判定）与办公场景的实际成功率不是一回事，S4 的 21.3% 尤其容易被误读。 解决：用自己的 3–5 个真实任务做小样本评测，再决定要不要投产。

踩坑 7：只配了主模型，没配接地模型。 现象：启动就报参数缺失。 原因：--ground_provider、--ground_url、--ground_model、--grounding_width、--grounding_height 都是必填。 解决：先起接地端点，再跑主命令；两者是两套凭据、两份账单。

环境与依赖速查

• 语言：Python；包名 gui-agents（S3）/ agent-s4（S4）
• 平台：macOS / Windows / Linux，单显示器
• 主模型 provider：Azure OpenAI、Anthropic、Gemini、OpenRouter、vLLM
• 接地模型：UI-TARS-1.5-7B（推荐）/ UI-TARS-72B
• 许可：Apache-2.0
• 托管替代：Sai（Simular API）

常见问题 FAQ

Q1：必须用 GPT-5 才能跑吗？

A：不是。主模型可以是 Azure OpenAI、Anthropic、Gemini、OpenRouter 或 vLLM 上的模型，官方推荐组合只是「最稳的默认值」。S4 的公开结果用的是 Qwen3.8-27B。

Q2：Agent S 和 Sai 是什么关系？

A：Sai 是同一家公司的托管产品，通过 Simular API 在云电脑上跑，不开源；Agent S 是开源仓库，自己装、自己付模型钱。评测口径与运行环境都不同。

Q3：能完全离线跑吗？

A：不行。主模型与接地模型都要联网调用（vLLM 自建可以内网，但仍是服务）。断网环境下这套方案跑不起来。

Q4：S3 和 S4 应该选哪个？

A：要做可用的桌面自动化，用 S3（gui-agents）；要做接口演进研究或复现 OSWorld V2，才碰 S4。S4 需要 clone 仓库、AWS 机器与额外配置，不是开箱即用。

Q5：一次任务大概花多少？

A：取决于步数与模型。每一步都是一次截屏 + 视觉模型调用，还叠加接地模型调用；bBoN 会再乘上采样条数。没有公开的固定单价，建议先用 3 个短任务测出单步成本再外推。

Q6：安全边界在哪？

A：智能体以当前用户权限操作你的机器，能点任何按钮、读任何屏幕内容。官方对本地代码环境有明确警告。生产使用建议：专用账号、沙箱或虚拟机、任务级白名单动作。

Q7：和 Claude Computer Use、OpenAI Operator 比呢？

A：闭源方案给的是托管能力与 SLA，Agent S 给的是可改的代码与可复现的基准分。本站另有 Claude Computer Use 与 OpenAI Operator 条目可对照阅读。

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

文中基准分数、安装命令、参数含义均取自仓库 README、S3 / S4 子目录 README 与论文摘要（核验日期 2026-11-07）；本站未在本机安装 gui-agents、未运行任何真实桌面任务，也未验证接地端点的实际可用性。

参考链接

• Agent S 仓库
• Agent S3 使用说明
• Agent S4 说明
• Agent S3 论文（TMLR 2026）
• Evolving Agent Interfaces（Agent S4 论文）
• UI-TARS-1.5-7B 模型卡
• Simular 官网