Agent S2： 面向计算机使用智能体的组合式通才-专才框架

  🌐 [S2技术博客]  📄 [S2论文]  🎥 [S2演示视频]

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

 

  

🥳 最新动态

• 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论文及代码库！

目录

1. 💡 项目介绍
2. 🎯 当前成果
3. 🛠️ 安装与配置
4. 🚀 使用指南
5. 🤝 致谢
6. 💬 引用说明

💡 项目介绍

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

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

🎯 当前成果

Agent S2在OSWorld完整测试集上仅使用屏幕截图输入的成功率(%)表现

🛠️ 安装与配置

❗警告❗：Linux系统下使用conda环境会干扰pyatspi。目前尚无完美解决方案，请直接安装而不使用conda或任何虚拟环境。

⚠️声明⚠️：为发挥Agent S2全部潜力，我们使用UI-TARS作为视觉定位模型（7B-DPO或72B-DPO可获得更佳性能）。该模型可本地部署或通过Hugging Face Inference Endpoints调用。我们的代码支持Hugging Face Inference Endpoints，详见Hugging Face企业级专用终端。但运行Agent S2并非必须此模型，您也可选用Claude等API模型进行视觉定位。

安装包：

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：

1. 确保系统已安装并运行Docker Desktop

2. 进入项目目录

    cd Perplexica
    git submodule update --init
   

3. 将sample.config.toml重命名为config.toml。Docker部署只需填写以下字段：

   • OPENAI：OpenAI API密钥（仅需在使用OpenAI模型时填写）
   • OLLAMA：Ollama API URL（格式为http://host.docker.internal:端口号，默认11434端口）
   • GROQ：Groq API密钥（仅需使用Groq托管模型时填写）
   • ANTHROPIC：Anthropic API密钥（仅需使用Anthropic模型时填写）
   • SIMILARITY_MEASURE：相似度度量方式（默认已填充，不确定时可保持原样）

4. 确保位于含docker-compose.yaml文件的目录后执行：

   docker compose up -d
   

5. 根据docker-compose.yaml文件中app/ports下的端口号（左侧数字）设置环境变量：

   export PERPLEXICA_URL=http://localhost:{端口号}/api/search
   

6. Agent S通过Perplexica API集成搜索引擎功能。如需自定义配置，可修改agent_s/query_perplexica.py中的请求参数。完整配置指南参见Perplexica搜索API文档。详细使用说明请参考Perplexica代码库。

❗警告❗：本智能体会直接运行Python代码控制您的计算机，请谨慎使用。

🚀 使用指南

注意：最佳配置为Claude 3.7扩展思维模式+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密钥
  • 注意：非必填。未指定时将使用环境变量中的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密钥
  • 注意：非必填。未指定时将使用环境变量中的API密钥
  • 默认：无

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

运行后将显示查询提示框，您可输入指令与Agent S2交互。支持models.md列出的所有模型。

gui_agents SDK开发

首先导入必要模块。AgentS2是主智能体类，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用于视觉定位。定位模块支持Claude、GPT系列及Hugging Face Inference Endpoints。

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时会自动下载对应平台和版本（如s1/s2）的知识库，存储于GitHub Releases的assets中。如需编程式下载知识库，可使用以下代码：

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

这将下载v0.2.2版本Linux平台知识库至kb_data目录。完整知识库版本请参考GitHub Releases。

OSWorld部署

在OSWorld中部署Agent S2，请遵循OSWorld部署指南。

💬 引用说明

如果本代码库对您的研究有帮助，请引用：

@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}
}

项目星标历史