Agent S2: A Compositional Generalist-Specialist Framework for Computer Use Agents

🌐 [S2 blog] 📄 [S2 Paper (COLM 2025)] 🎥 [S2 Video]

🌐 [S1 blog] 📄 [S1 Paper (ICLR 2025)] 🎥 [S1 Video]

🥳 更新动态

2025/07/07: Agent S2 论文被 COLM 2025 接收！我们蒙特利尔见！
2025/04/01: 发布 Agent S2 论文，在 OSWorld、WindowsAgentArena 和 AndroidWorld 上取得新的 SOTA 结果！
2025/03/12: 发布 Agent S2 及 gui-agents v0.2.0 版本，成为计算机使用代理（CUA）领域的新标杆，性能超越 OpenAI 的 CUA/Operator 和 Anthropic 的 Claude 3.7 Sonnet Computer-Use！
2025/01/22: Agent S 论文被 ICLR 2025 接收！
2025/01/21: 发布 gui-agents 库 v0.1.2 版本，新增对 Linux 和 Windows 的支持！
2024/12/05: 发布 gui-agents 库 v0.1.0 版本，可轻松将 Agent-S 用于 Mac、OSWorld 和 WindowsAgentArena 平台！
2024/10/10: 发布 Agent S 论文及代码库！

💡 项目介绍

欢迎来到 Agent S —— 一个通过 Agent-Computer Interface 实现计算机自主交互的开源框架。我们的使命是构建能通过历史经验学习、在计算机上自主执行复杂任务的智能 GUI 代理系统。

无论您对 AI、自动化感兴趣，还是希望参与前沿智能体系统的开发，我们都期待您的加入！

🎯 当前成果

Results of Agent S2's Successful Rate (%) on the OSWorld full test set using Screenshot input only.

Benchmark	Agent S2	Previous SOTA	Δ improve
OSWorld (15 step)	27.0%	22.7% (UI-TARS)	+4.3%
OSWorld (50 step)	34.5%	32.6% (OpenAI CUA)	+1.9%
WindowsAgentArena	29.8%	19.5% (NAVI)	+10.3%
AndroidWorld	54.3%	46.8% (UI-TARS)	+7.5%

🛠️ 安装与配置

注意：我们的智能体返回 pyautogui 代码，且仅适用于单显示器屏幕环境。

❗警告❗: Linux 环境下创建 conda 虚拟环境会干扰 pyatspi 运行。目前尚无完美解决方案，安装时请勿使用 conda 或任何虚拟环境。

⚠️免责声明⚠️：为充分发挥 Agent S2 的全部潜力，我们使用 UI-TARS 作为基础模型（推荐 7B-DPO 或 72B-DPO 以获得更佳性能）。该模型可本地部署或托管于 Hugging Face Inference Endpoints。我们的代码支持 Hugging Face Inference Endpoints，详情请参阅 Hugging Face Inference Endpoints 了解如何设置和查询此终端节点。但运行 Agent S2 并非必须使用此模型，您也可选用其他基于 API 的视觉基础模型，例如 Claude。

安装包：

pip install gui-agents

设置您的 LLM API 密钥及其他环境变量。可通过在 .bashrc（Linux）或 .zshrc（MacOS）文件中添加以下行实现：

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

或者，您也可以在 Python 脚本中设置环境变量：

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

我们还支持 Azure OpenAI、Anthropic、Gemini、Open Router 和 vLLM 推理。更多信息请参阅 models.md。

配置基于 Perplexica 的网络检索功能

Agent S 结合网络知识检索表现最佳。启用此功能需先配置 Perplexica：

确保您的系统已安装并运行 Docker Desktop。

进入包含项目文件的目录：

 cd Perplexica
 git submodule update --init

将 sample.config.toml 文件重命名为 config.toml。对于 Docker 部署，只需填写以下字段：
- OPENAI: 您的 OpenAI API 密钥。仅当您希望使用 OpenAI 模型时需要填写。
- OLLAMA: 您的 Ollama API URL。应填写为 http://host.docker.internal:端口号。例如 Ollama 安装在 11434 端口时使用 http://host.docker.internal:11434。若希望使用 Ollama 模型而非 OpenAI 模型，则需填写此项。
- GROQ: 您的 Groq API 密钥。仅当希望使用 Groq 托管模型时需要填写。
- ANTHROPIC: 您的 Anthropic API 密钥。仅当希望使用 Anthropic 模型时需要填写。
  
  注意：这些配置可在启动 Perplexica 后通过设置对话框修改。
- SIMILARITY_MEASURE: 使用的相似度度量方法（已默认填充，不确定时可保持原值）
确保当前目录包含 docker-compose.yaml 文件并执行：
```
docker compose up -d
```
根据 docker-compose.yaml 文件中 app/ports 下的端口号（例如 3000:3000 左侧数字）导出 Perplexica URL：
```
export PERPLEXICA_URL=http://localhost:{端口号}/api/search
```
我们的 Agent S 实现集成了 Perplexica API 以提供搜索引擎功能，从而带来更便捷的交互体验。如需根据个人需求定制 API，可修改 agent_s/query_perplexica.py 中的请求参数 URL 和消息内容。完整配置指南请参阅 Perplexica 搜索 API 文档。

更详细的安装使用指南请参考 Perplexica 代码仓库。

❗警告❗：该代理将直接运行 Python 代码来控制您的计算机。使用时请务必谨慎。

🚀 使用指南

注意：我们的最佳配置使用 Claude 3.7 配合扩展思考模式和 UI-TARS-72B-DPO 模型。若因资源限制无法运行 UI-TARS-72B-DPO，可采用轻量级替代方案 UI-TARS-7B-DPO，性能损失极小。

命令行界面

运行 Agent S2 并指定模型（默认为 gpt-4o）：

agent_s2 \
  --provider "anthropic" \
  --model "claude-3-7-sonnet-20250219" \
  --grounding_model_provider "anthropic" \
  --grounding_model "claude-3-7-sonnet-20250219" \

或使用自定义终端节点：

agent_s2 \
  --provider "anthropic" \
  --model "claude-3-7-sonnet-20250219" \
  --endpoint_provider "huggingface" \
  --endpoint_url "<endpoint_url>/v1/"

主模型设置

--provider, --model
- 功能：指定主生成模型
- 支持：models.md 中所有模型提供商
- 默认值：--provider "anthropic" --model "claude-3-7-sonnet-20250219"
--model_url, --model_api_key
- 功能：指定主生成模型的自定义终端节点及 API 密钥
- 注意：此为可选参数。若未指定，gui-agents 将默认使用环境变量中的 URL 和 API 密钥。
- 支持：models.md 中所有模型提供商
- 默认值：无

视觉定位配置选项

可采用配置方案 1 或 2：

（默认）配置方案 1：基于 API 的模型

--grounding_model_provider, --grounding_model
- 功能：指定用于视觉定位（坐标预测）的模型
- 支持：models.md 中所有模型提供商
- 默认值：--grounding_model_provider "anthropic" --grounding_model "claude-3-7-sonnet-20250219"
❗重要❗ --grounding_model_resize_width
- 功能：部分 API 提供商会自动调整图像尺寸。因此生成的 (x, y) 坐标将基于调整后的图像尺寸，而非原始尺寸。
- 支持：Anthropic 尺寸调整
- 提示：若即使简单查询也出现定位不准，请检查重设宽度值是否与您的屏幕分辨率匹配。
- 默认值：--grounding_model_resize_width 1366（Anthropic）

配置方案 2：自定义终端节点

--endpoint_provider
- 作用：指定终端点提供商
- 支持：HuggingFace TGI、vLLM、Open Router
- 默认值：无
--endpoint_url
- 作用：自定义终端点的URL地址
- 默认值：无
--endpoint_api_key
- 作用：自定义终端点的API密钥
- 注意：此为可选参数。若未指定，gui-agents将默认使用环境变量中的API密钥。
- 默认值：无

注意：配置方案2的优先级高于配置方案1。

这将显示用户查询提示符，您可在此输入查询内容并与Agent S2进行交互。您可以使用models.md中列出的任何支持模型。

`gui_agents` SDK开发套件

首先导入必要模块。AgentS2是Agent S2的主代理类，OSWorldACI是我们的基础代理，负责将代理动作转换为可执行的Python代码。

import pyautogui
import io
from gui_agents.s2.agents.agent_s import AgentS2
from gui_agents.s2.agents.grounding import OSWorldACI

# Load in your API keys.
from dotenv import load_dotenv
load_dotenv()

current_platform = "linux"  # "darwin", "windows"

接着定义引擎参数。engine_params用于主代理，engine_params_for_grounding用于基础代理。对于engine_params_for_grounding，我们支持Claude系列、GPT系列以及Hugging Face推理终端点。

engine_params = {
  "engine_type": provider,
  "model": model,
  "base_url": model_url,     # Optional
  "api_key": model_api_key,  # Optional
}

# Grounding Configuration 1: Load the grounding engine from an API based model
grounding_model_provider = "<your_grounding_model_provider>"
grounding_model = "<your_grounding_model>"
grounding_model_resize_width = 1366
screen_width, screen_height = pyautogui.size()

engine_params_for_grounding = {
  "engine_type": grounding_model_provider,
  "model": grounding_model,
  "grounding_width": grounding_model_resize_width,
  "grounding_height": screen_height
  * grounding_model_resize_width
  / screen_width,
}

# Grounding Configuration 2: Load the grounding engine from a HuggingFace TGI endpoint
endpoint_provider = "<your_endpoint_provider>"
endpoint_url = "<your_endpoint_url>"
endpoint_api_key = "<your_api_key>"

engine_params_for_grounding = {
  "engine_type": endpoint_provider,
  "base_url": endpoint_url,
  "api_key": endpoint_api_key,  # Optional
}

然后定义基础代理和Agent S2实例。

grounding_agent = OSWorldACI(
    platform=current_platform,
    engine_params_for_generation=engine_params,
    engine_params_for_grounding=engine_params_for_grounding
)

agent = AgentS2(
  engine_params,
  grounding_agent,
  platform=current_platform,
  action_space="pyautogui",
  observation_type="screenshot",
  search_engine="Perplexica",  # Assuming you have set up Perplexica.
  embedding_engine_type="openai"  # Supports "gemini", "openai"
)

最后即可向代理发起查询！

# Get screenshot.
screenshot = pyautogui.screenshot()
buffered = io.BytesIO() 
screenshot.save(buffered, format="PNG")
screenshot_bytes = buffered.getvalue()

obs = {
  "screenshot": screenshot_bytes,
}

instruction = "Close VS Code"
info, action = agent.predict(instruction=instruction, observation=obs)

exec(action[0])

有关推理循环的具体实现，请参考gui_agents/s2/cli_app.py文件。

下载知识库

Agent S2使用一个在推理过程中持续更新知识的知识库。该知识库会在初始化AgentS2时首次下载。知识库以资源文件形式存储在我们的GitHub Releases中。AgentS2初始化时仅会下载指定平台和代理版本（如s1、s2）对应的知识库。如需通过编程方式下载知识库，可使用以下代码：

download_kb_data(
    version="s2",
    release_tag="v0.2.2",
    download_dir="kb_data",
    platform="linux"  # "darwin", "windows"
)

此代码将从发布标签v0.2.2下载Linux版Agent S2的知识库至kb_data目录。请参考我们的GitHub Releases或包含知识库的发布标签。

OSWorld操作系统环境

要在 OSWorld 中部署 Agent S2，请按照 OSWorld 部署说明进行操作。

WindowsAgentArena 竞技场

如需在 WindowsAgentArena 中部署 Agent S2，请参照 WindowsAgentArena 部署指南进行操作。

💬 引用

如果您认为该代码库对您有所帮助，请引用：

@misc{Agent-S2,
      title={Agent S2: A Compositional Generalist-Specialist Framework for Computer Use Agents}, 
      author={Saaket Agashe and Kyle Wong and Vincent Tu and Jiachen Yang and Ang Li and Xin Eric Wang},
      year={2025},
      eprint={2504.00906},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2504.00906}, 
}

@inproceedings{Agent-S,
    title={{Agent S: An Open Agentic Framework that Uses Computers Like a Human}},
    author={Saaket Agashe and Jiuzhou Han and Shuyu Gan and Jiachen Yang and Ang Li and Xin Eric Wang},
    booktitle={International Conference on Learning Representations (ICLR)},
    year={2025},
    url={https://arxiv.org/abs/2410.08164}
}