simular-ai/Agent-S 操作计算机的智能代理框架

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

无论您对人工智能、自动化感兴趣，还是对基于代理的尖端系统做出贡献，我们都很高兴您能来到这里！

• 访问官网：https://github.com/simular-ai/Agent-S

仅使用屏幕截图输入，代理 S2 在 OSWorld 完整测试集上的成功率（％）结果。

❗警告❗：如果您使用的是 Linux 系统，创建conda环境会干扰pyatspi。目前，尚无彻底的解决方案。请在不使用conda任何虚拟环境的情况下继续安装。

⚠️免责声明⚠️：为了充分发挥 Agent S2 的潜力，我们使用UI-TARS作为基础模型（7B-DPO 或 72B-DPO 可获得更佳性能）。它们可以托管在本地，也可以托管在 Hugging 人脸推理端点上。我们的代码支持 Hugging 人脸推理端点。查看Hugging 人脸推理端点，了解更多关于如何设置和查询此端点的信息。但是，运行 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。

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:PORT_NUMBER。如果您在端口 11434 上安装了 Ollama，请使用http://host.docker.internal:11434。对于其他端口，请相应调整。如果您希望使用 Ollama 的模型而不是 OpenAI 的 ，则需要填写此项。

   • GROQ：您的 Groq API 密钥。仅当您希望使用 Groq 托管模型时才需要填写此密钥。

   • ANTHROPIC：您的 Anthropic API 密钥。仅当您希望使用 Anthropic 模型时才需要填写此密钥。

     注意：您可以在启动 Perplexica 后从设置对话框更改这些。

   • SIMILARITY_MEASURE：要使用的相似性度量（默认填写；如果不确定，可以保留原样。）

4. 确保您位于包含该文件的目录中docker-compose.yaml并执行：

   docker compose up -d

5. 接下来，导出你的 Perplexica URL。此 URL 用于与 Perplexica API 后端进行交互。端口号由config.toml你的 Perplexica 目录中的 指定。

   export PERPLEXICA_URL=http://localhost:{port}/api/search

6. 我们实施的 Agent S 集成了 Perplexica API，以集成搜索引擎功能，从而提供更便捷、响应更快的用户体验。如果您想根据自己的设置和特定需求定制 API，可以修改 URL 和请求参数消息 agent_s/query_perplexica.py。有关配置 Perplexica API 的详细指南，请参阅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：

• --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 rescaling
  • 提示：如果即使对于非常简单的查询，您的接地也不准确，请仔细检查您的重新缩放宽度是否适合您的机器的分辨率。
  • 默认值：（--grounding_model_resize_width 1366人择）

• --endpoint_provider

  • 目的：指定端点提供者
  • 支持：HuggingFace TGI、vLLM、Open Router
  • 默认值：无

• --endpoint_url

  • 目的：自定义端点的 URL
  • 默认值：无

• --endpoint_api_key

  • 目的：您的自定义端点的 API 密钥
  • 注意：此项为可选。若未指定，gui-agents则默认使用环境变量作为 API 密钥。
  • 默认值：无

注意：配置 2 优先于配置 1。

这将显示一个用户查询提示，您可以在其中输入查询并与代理 S2 交互。您可以使用models.md中受支持模型列表中的任何模型。

首先，我们导入必要的模块。AgentS2是代理 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 人脸推理端点。

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
}

然后，我们定义接地代理和代理 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.
)

最后我们来查询一下代理吧！

# 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有关推理循环如何工作的更多详细信息，请参阅。

代理 S2 使用知识库，该知识库在推理过程中不断更新新知识。初始化时会下载知识库AgentS2。知识库作为资产存储在我们的GitHub 版本中。AgentS2初始化将仅下载您指定平台和代理版本（例如 s1、s2）的知识库。如果您想以编程方式下载知识库，可以使用以下代码：

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

这会将 Agent S2 的 Linux 知识库从发布标签下载v0.2.2到kb_data相应目录。请参阅包含该知识库的GitHub 发布或发布标签。

要在 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}
}