Agent S: 像人类一样使用电脑

🏆 Agent S3：首个在OSWorld上超越人类表现（72.60%）

  🌐 [S3博客]  📄 [S3论文]  🎥 [S3视频]

  🌐 [S2博客]  📄 [S2论文（COLM 2025）]  🎥 [S2视频]

  🌐 [S1博客]  📄 [S1论文（ICLR 2025）]  🎥 [S1视频]

 

  

🥳 更新

• 2025/12/15: Agent S3是首个在OSWorld上以令人印象深刻的**72.60%**成绩超越人类水平表现的模型！
• 2025/10/02: 发布了Agent S3及其技术论文，在OSWorld上创造了新的SOTA记录——69.9%（接近72%的人类表现），同时在WindowsAgentArena和AndroidWorld上也展现出强大的泛化能力！此外，它更加简单、快速且灵活。
• 2025/08/01: Agent S2.5发布（gui-agents v0.2.5）：更简单、更好、更快！在OSWorld-Verified上创下新SOTA。
• 2025/07/07: Agent S2论文已被COLM 2025接收！蒙特利尔见！
• 2025/04/27: Agent S论文荣获ICLR 2025 Agentic AI for Science Workshop的最佳论文奖🏆！
• 2025/04/01: 发布了Agent S2论文，并在OSWorld、WindowsAgentArena和AndroidWorld上取得了新的SOTA结果！
• 2025/03/12: 发布了Agent S2以及v0.2.0版的gui-agents，成为当前计算机使用代理（CUA）领域的最新技术水平，性能超越了OpenAI的CUA/Operator和Anthropic的Claude 3.7 Sonnet Computer-Use！
• 2025/01/22: Agent S论文已被ICLR 2025接收！
• 2025/01/21: 发布了v0.1.2版的gui-agents库，新增对Linux和Windows的支持！
• 2024/12/05: 发布了v0.1.0版的gui-agents库，使您能够轻松地在Mac、OSWorld和WindowsAgentArena上使用Agent S！
• 2024/10/10: 发布了Agent S论文及代码库！

目录

1. 💡 简介
2. 🎯 当前成果
3. 🛠️ 安装与设置
4. 🚀 使用方法
5. 🤝 致谢
6. 💬 引用

💡 简介

欢迎来到Agent S，这是一个开源框架，旨在通过代理-计算机界面实现与计算机的自主交互。我们的使命是构建智能GUI代理，使其能够从过往经验中学习，并在您的计算机上自主完成复杂任务。

无论您对人工智能、自动化感兴趣，还是希望为前沿的基于代理的系统做出贡献，我们都热烈欢迎您加入！

🎯 当前成果

在OSWorld上，仅使用Agent S3在100步设置下即可达到66%，已超过此前的最先进水平63.4%（GTA1 w/ GPT-5）。而通过结合行为Best-of-N策略，性能进一步提升至72.6%，超越了OSWorld上的人类水平表现（约72%）！

Agent S3还展现了强大的零样本泛化能力！在WindowsAgentArena上，仅使用Agent S3时准确率为50.2%，但通过从3次运行结果中选择最佳方案，准确率可提升至56.6%。同样地，在AndroidWorld上，性能也从68.1%提高到71.6%。

🛠️ 安装与设置

前提条件

• 单显示器：我们的代理专为单显示器屏幕设计
• 安全性：代理会运行Python代码来控制您的电脑，请谨慎使用
• 支持平台：Linux、Mac和Windows

安装

若不希望克隆仓库直接安装Agent S3，可运行：

pip install gui-agents

如果您想在修改代码的同时测试Agent S3，可以先克隆仓库，然后使用以下命令进行安装：

pip install -e .

别忘了还要brew install tesseract！Pytesseract需要此额外安装才能正常工作。

API配置

选项1：环境变量

将以下内容添加到您的.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>

选项2：Python脚本

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

支持的模型

我们支持Azure OpenAI、Anthropic、Gemini、Open Router以及vLLM推理。详细信息请参阅model.md。

接地模型（必填）

为获得最佳性能，我们推荐使用 Hugging Face 推理端点或其他提供商托管的 UI-TARS-1.5-7B。有关设置说明，请参阅 Hugging Face 推理端点。

🚀 使用方法

⚡️ 推荐配置：
为了达到最佳效果，我们建议将 OpenAI gpt-5-2025-08-07 作为主模型，并搭配 UI-TARS-1.5-7B 进行接地。

命令行界面

请注意，此处运行的是我们改进后的智能体 Agent S3，未启用 bBoN 功能。

使用所需参数运行 Agent S3：

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

本地编码环境（可选）

对于需要执行代码的任务（例如数据处理、文件操作、系统自动化），您可以启用本地编码环境：

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 \
    --enable_local_env

⚠️ 警告：本地编码环境会在您的本地机器上执行任意 Python 和 Bash 代码。请仅在受信任的环境中并使用受信任的输入时使用此功能。

必需参数

• --provider：主生成模型提供商（例如 openai、anthropic 等） - 默认值：“openai”
• --model：主生成模型名称（例如 gpt-5-2025-08-07） - 默认值：“gpt-5-2025-08-07”
• --ground_provider：接地模型的提供商 - 必填
• --ground_url：接地模型的 URL - 必填
• --ground_model：接地模型的名称 - 必填
• --grounding_width：接地模型输出坐标分辨率的宽度 - 必填
• --grounding_height：接地模型输出坐标分辨率的高度 - 必填

可选参数

• --model_temperature：所有模型调用的温度固定值（对于 o3 等模型必须设置为 1.0，其他模型可留空）

接地模型尺寸

接地宽度和高度应与您接地模型的输出坐标分辨率匹配：

• UI-TARS-1.5-7B：使用 --grounding_width 1920 --grounding_height 1080
• UI-TARS-72B：使用 --grounding_width 1000 --grounding_height 1000

其他可选参数

• --model_url：主生成模型的自定义 API URL - 默认值：“”
• --model_api_key：主生成模型的 API 密钥 - 默认值：“”
• --ground_api_key：接地模型端点的 API 密钥 - 默认值：“”
• --max_trajectory_length：轨迹中保留的最大图像轮次数 - 默认值：8
• --enable_reflection：启用反思代理协助工作代理 - 默认值：真
• --enable_local_env：启用本地编码环境以执行代码（警告：会在本地执行任意代码） - 默认值：假

本地编码环境详情

本地编码环境使 Agent S3 能够直接在您的机器上执行 Python 和 Bash 代码。这尤其适用于以下场景：

• 数据处理：操作电子表格、CSV 文件或数据库
• 文件操作：批量文件处理、内容提取或文件整理
• 系统自动化：配置更改、系统设置或自动化脚本
• 代码开发：编写、编辑或执行代码文件
• 文本处理：文档操作、内容编辑或格式化

启用后，该智能体可以使用 call_code_agent 操作来执行代码块，完成那些可以通过编程而非 GUI 交互来实现的任务。

要求：

• Python：与运行 Agent S3 相同的 Python 解释器（自动检测）
• Bash：位于 /bin/bash（macOS 和 Linux 上的标准路径）
• 系统权限：该智能体将以与其用户相同的权限运行

安全注意事项：

• 本地环境会以与运行该智能体的用户相同的权限执行任意代码
• 仅在受信任的环境中启用此功能
• 当智能体生成用于系统级操作的代码时要格外小心
• 对于不受信任的任务，建议在沙盒环境中运行
• Bash 脚本将被限制在 30 秒内执行完毕，以防止进程挂起

gui_agents SDK

首先，我们导入必要的模块。AgentS3 是 Agent S3 的主智能体类。OSWorldACI 是我们的接地智能体，负责将智能体动作转换为可执行的 Python 代码。

import pyautogui
import io
from gui_agents.s3.agents.agent_s import AgentS3
from gui_agents.s3.agents.grounding import OSWorldACI
from gui_agents.s3.utils.local_env import LocalEnv  # 可选：用于本地编码环境

# 加载您的 API 密钥。
from dotenv import load_dotenv
load_dotenv()

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

接下来，我们定义引擎参数。engine_params 用于主智能体，而 engine_params_for_grounding 则用于接地部分。对于 engine_params_for_grounding，我们支持自定义端点，如 HuggingFace TGI、vLLM 和 Open Router。

engine_params = {
  "engine_type": provider,
  "model": model,
  "base_url": model_url,           # 可选
  "api_key": model_api_key,        # 可选
  "temperature": model_temperature # 可选
}

# 从自定义端点加载接地引擎
ground_provider = "<your_ground_provider>"
ground_url = "<your_ground_url>"
ground_model = "<your_ground_model>"
ground_api_key = "<your_ground_api_key>"

# 根据您模型的输出坐标分辨率设置接地尺寸
# UI-TARS-1.5-7B：grounding_width=1920，grounding_height=1080
# UI-TARS-72B：grounding_width=1000，grounding_height=1000
grounding_width = 1920  # 输出坐标分辨率的宽度
grounding_height = 1080  # 输出坐标分辨率的高度

engine_params_for_grounding = {
  "engine_type": ground_provider,
  "model": ground_model,
  "base_url": ground_url,
  "api_key": ground_api_key,  # 可选
  "grounding_width": grounding_width,
  "grounding_height": grounding_height,
}

然后，我们定义接地智能体和 Agent S3。

# 可选：启用本地编码环境
enable_local_env = False  # 设置为 True 以启用本地代码执行
local_env = LocalEnv() if enable_local_env else None

grounding_agent = OSWorldACI(
    env=local_env,  # 传递 local_env 以获得代码执行能力
    platform=current_platform,
    engine_params_for_generation=engine_params,
    engine_params_for_grounding=engine_params_for_grounding,
    width=1920,  # 可选：屏幕宽度
    height=1080  # 可选：屏幕高度
)

agent = AgentS3(
    engine_params,
    grounding_agent,
    platform=current_platform,
    max_trajectory_length=8,  # 可选：最多保留的图像轮次
    enable_reflection=True     # 可选：启用反思代理
)

最后，让我们查询该代理！

# 获取屏幕截图。
screenshot = pyautogui.screenshot()
buffered = io.BytesIO() 
screenshot.save(buffered, format="PNG")
screenshot_bytes = buffered.getvalue()

obs = {
  "screenshot": screenshot_bytes,
}

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

exec(action[0])

有关推理循环如何工作的更多详细信息，请参阅 gui_agents/s3/cli_app.py。

OSWorld

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

💬 引用

如果您觉得这个代码库有用，请引用以下文献：

@misc{Agent-S3,
      title={计算机使用代理规模化的不合理有效性}, 
      author={Gonzalo Gonzalez-Pumariega 和 Vincent Tu、Chih-Lun Lee、Jiachen Yang、Ang Li 和 Xin Eric Wang},
      year={2025},
      eprint={2510.02250},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2510.02250}, 
}

@misc{Agent-S2,
      title={Agent S2：用于计算机使用代理的组合式通才-专才框架}, 
      author={Saaket Agashe、Kyle Wong、Vincent Tu、Jiachen Yang、Ang Li 和 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：一个像人类一样使用计算机的开放代理框架}},
    author={Saaket Agashe、Jiuzhou Han、Shuyu Gan、Jiachen Yang、Ang Li 和 Xin Eric Wang},
    booktitle={国际学习表征会议（ICLR）},
    year={2025},
    url={https://arxiv.org/abs/2410.08164}
}

星标历史

Agent S 快速上手指南

Agent S 是一个开源框架，旨在通过智能体 - 计算机接口（Agent-Computer Interface）实现自主的电脑操作。最新版本的 Agent S3 在 OSWorld 基准测试中首次超越人类表现（72.60%），支持 Windows、macOS 和 Linux。

环境准备

系统要求

• 操作系统：Linux、macOS 或 Windows
• 显示器：仅支持单显示器环境
• 安全提示：代理将运行 Python 代码控制您的电脑，请在受信任的环境中谨慎使用

前置依赖

1. Python 环境：确保已安装 Python（用于运行 Agent S3 的解释器将被自动检测）
2. Tesseract OCR：Pytesseract 依赖此项，必须安装
   • macOS: brew install tesseract
   • Linux (Ubuntu/Debian): sudo apt-get install tesseract-ocr
   • Windows: 下载并安装 Tesseract 安装包
3. API Keys：准备以下密钥之一或多个
   • OpenAI API Key
   • Anthropic API Key
   • Hugging Face Token (用于部署 Grounding 模型)

安装步骤

方式一：直接安装（推荐）

无需克隆仓库，直接通过 pip 安装：

pip install gui-agents

方式二：源码安装（开发模式）

如需修改代码或测试最新功能：

git clone https://github.com/simular-ai/Agent-S.git
cd Agent-S
pip install -e .

国内加速建议：如果下载缓慢，可使用国内镜像源安装：

pip install gui-agents -i https://pypi.tuna.tsinghua.edu.cn/simple

配置 API 密钥

选项 1：环境变量（推荐） 在 ~/.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>

然后执行 source ~/.bashrc 或 source ~/.zshrc 生效。

选项 2：Python 脚本内配置

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

部署 Grounding 模型（必需）

为获得最佳性能，推荐部署 UI-TARS-1.5-7B 模型。

• 推荐使用 Hugging Face Inference Endpoints 托管。
• 记录生成的 Endpoint URL，后续启动时需填入 --ground_url。

基本使用

命令行启动 (CLI)

以下命令使用推荐的 OpenAI gpt-5-2025-08-07 作为主模型，配合 UI-TARS-1.5-7B 进行视觉定位：

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

参数说明

• --ground_url: 替换为您实际的 Grounding 模型服务地址。
• --grounding_width / --grounding_height: 需与模型输出分辨率一致。
  • UI-TARS-1.5-7B: 1920 x 1080
  • UI-TARS-72B: 1000 x 1000

启用本地代码执行环境（可选）

若任务涉及数据处理、文件操作或系统自动化，可开启本地编码环境，允许 Agent 直接执行 Python/Bash 代码：

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 \
    --enable_local_env

⚠️ 警告：--enable_local_env 会在本地执行任意代码。请仅在受信任的环境中使用，并注意系统权限安全。

Python SDK 使用示例

您也可以通过代码调用 Agent S3：

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

# 初始化接地代理 (Grounding Agent)
grounding_agent = OSWorldACI(
    provider="huggingface",
    model="ui-tars-1.5-7b",
    url="http://localhost:8080",
    width=1920,
    height=1080
)

# 初始化主代理
agent = AgentS3(
    provider="openai",
    model="gpt-5-2025-08-07",
    grounding_agent=grounding_agent
)

# 开始执行任务
agent.run("请帮我打开浏览器并搜索最新的 AI 新闻")