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]

🥳 Mises à jour

2025/07/07 : L'article Agent S2 est accepté à COLM 2025 ! Rendez-vous à Montréal !
2025/04/01 : Publication de l'article Agent S2 avec de nouveaux résultats SOTA sur OSWorld, WindowsAgentArena et AndroidWorld !
2025/03/12 : Lancement d'Agent S2 avec la version v0.2.0 de gui-agents, le nouvel état de l'art pour les agents d'utilisation informatique (CUA), surpassant OpenAI CUA/Operator et Claude 3.7 Sonnet Computer-Use d'Anthropic !
2025/01/22 : L'article Agent S est accepté à ICLR 2025 !
2025/01/21 : Sortie de la version v0.1.2 de la bibliothèque gui-agents, avec support pour Linux et Windows !
2024/12/05 : Sortie de la version v0.1.0 de la bibliothèque gui-agents, vous permettant d'utiliser Agent-S pour Mac, OSWorld et WindowsAgentArena facilement !
2024/10/10 : Publication de l'article Agent S et du code source !

💡 Introduction

Bienvenue sur Agent S, un framework open-source conçu pour permettre une interaction autonome avec les ordinateurs via l'Interface Agent-Ordinateur. Notre mission est de développer des agents GUI intelligents capables d'apprendre des expériences passées et d'exécuter des tâches complexes de manière autonome sur votre machine.

Que vous soyez intéressé par l'IA, l'automatisation ou que vous souhaitiez contribuer à des systèmes innovants basés sur des agents, nous sommes ravis de vous accueillir !

🎯 Résultats actuels

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%

🛠️ Installation & Configuration

Remarque : Notre agent génère du code pyautogui et est conçu pour un écran unique.

❗Avertissement❗ : Si vous utilisez une machine Linux, la création d'un environnement conda interférera avec pyatspi. À ce jour, il n'existe pas de solution propre à ce problème. Procédez à l'installation sans utiliser conda ni aucun environnement virtuel.

⚠️Avertissement⚠️ : Pour exploiter pleinement le potentiel d'Agent S2, nous utilisons UI-TARS comme modèle d'ancrage (7B-DPO ou 72B-DPO pour de meilleures performances). Ces modèles peuvent être hébergés localement ou sur Hugging Face Inference Endpoints. Notre code prend en charge Hugging Face Inference Endpoints. Consultez Hugging Face Inference Endpoints pour plus d'informations sur la configuration et l'interrogation de ce point de terminaison. Cependant, l'exécution d'Agent S2 ne nécessite pas ce modèle, et vous pouvez utiliser d'autres modèles basés sur des API pour l'ancrage visuel, comme Claude.

Installez le package :

pip install gui-agents

Configurez vos clés d'API LLM et autres variables d'environnement. Vous pouvez le faire en ajoutant la ligne suivante à votre fichier .bashrc (Linux) ou .zshrc (MacOS).

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

Alternativement, vous pouvez définir la variable d'environnement dans votre script Python :

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

Nous prenons également en charge Azure OpenAI, Anthropic, Gemini, Open Router et l'inférence vLLM. Pour plus d'informations, consultez models.md.

Configuration de la récupération web avec Perplexica

Agent S fonctionne mieux avec la récupération de connaissances web. Pour activer cette fonctionnalité, vous devez configurer Perplexica :

Assurez-vous que Docker Desktop est installé et en cours d'exécution sur votre système.
Accédez au répertoire contenant les fichiers du projet.
```
 cd Perplexica
 git submodule update --init
```
Renommez le fichier sample.config.toml en config.toml. Pour les configurations Docker, vous n'avez besoin de remplir que les champs suivants :
- OPENAI : Votre clé API OpenAI. À remplir uniquement si vous souhaitez utiliser les modèles d'OpenAI.
- OLLAMA : L'URL de votre API Ollama. Saisissez-la sous la forme http://host.docker.internal:PORT_NUMBER. Si Ollama est installé sur le port 11434, utilisez http://host.docker.internal:11434. Pour d'autres ports, ajustez en conséquence. À remplir uniquement si vous préférez utiliser les modèles d'Ollama plutôt que ceux d'OpenAI.
- GROQ : Votre clé API Groq. À remplir uniquement si vous souhaitez utiliser les modèles hébergés par Groq.
- ANTHROPIC : Votre clé API Anthropic. À remplir uniquement si vous souhaitez utiliser les modèles d'Anthropic.
  
  Remarque : Vous pouvez modifier ces paramètres ultérieurement depuis la boîte de dialogue des paramètres de Perplexica.
- SIMILARITY_MEASURE : La mesure de similarité à utiliser (préremplie par défaut ; vous pouvez la conserver telle quelle si vous n'êtes pas sûr).
Assurez-vous d'être dans le répertoire contenant le fichier docker-compose.yaml et exécutez :
```
docker compose up -d
```
Exportez l'URL de Perplexica en utilisant le port indiqué dans le fichier docker-compose.yaml. Sous app/ports, vous verrez 3000:3000. Le port correspond au nombre à gauche (ici, 3000).
```
export PERPLEXICA_URL=http://localhost:{port}/api/search
```
Notre implémentation de l'Agent S intègre l'API Perplexica pour ajouter une fonctionnalité de moteur de recherche, offrant ainsi une expérience utilisateur plus pratique et réactive. Si vous souhaitez adapter l'API à vos paramètres et besoins spécifiques, vous pouvez modifier l'URL et les paramètres de requête dans agent_s/query_perplexica.py. Pour un guide complet sur la configuration de l'API Perplexica, consultez la Documentation de l'API de recherche Perplexica. Pour un guide d'installation et d'utilisation plus détaillé, veuillez vous référer au Dépôt Perplexica.

❗Avertissement❗ : L'agent exécutera directement du code Python pour contrôler votre ordinateur. Veuillez l'utiliser avec précaution.

🚀 Utilisation

Remarque : Notre meilleure configuration utilise Claude 3.7 avec une réflexion étendue et UI-TARS-72B-DPO. Si vous ne pouvez pas exécuter UI-TARS-72B-DPO en raison de contraintes de ressources, UI-TARS-7B-DPO peut être utilisé comme alternative plus légère avec une dégradation minimale des performances.

CLI

Exécutez Agent S2 avec un modèle spécifique (par défaut gpt-4o) :

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

Ou utilisez un endpoint personnalisé :

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

Paramètres du Modèle Principal

--provider, --model
- Objectif : Spécifie le modèle principal de génération
- Prise en charge : tous les fournisseurs de modèles dans models.md
- Par défaut : --provider "anthropic" --model "claude-3-7-sonnet-20250219"
--model_url, --model_api_key
- Objectif : Spécifie l'endpoint personnalisé pour le modèle principal de génération et votre clé API
- Note : Ces paramètres sont optionnels. S'ils ne sont pas spécifiés, gui-agents utilisera par défaut les variables d'environnement pour l'URL et la clé API.
- Prise en charge : tous les fournisseurs de modèles dans models.md
- Par défaut : Aucun

Options de Configuration du Grounding

Vous pouvez utiliser soit la Configuration 1, soit la Configuration 2 :

(Par défaut) Configuration 1 : Modèles basés sur API

--grounding_model_provider, --grounding_model
- Objectif : Spécifie le modèle pour le grounding visuel (prédiction des coordonnées)
- Prise en charge : tous les fournisseurs de modèles dans models.md
- Par défaut : --grounding_model_provider "anthropic" --grounding_model "claude-3-7-sonnet-20250219"
❗Important❗ --grounding_model_resize_width
- Objectif : Certains fournisseurs d'API redimensionnent automatiquement les images. Par conséquent, les coordonnées (x, y) générées seront relatives aux dimensions de l'image redimensionnée, et non aux dimensions originales.
- Prise en charge : Redimensionnement Anthropic
- Conseils : Si votre grounding est inexact même pour des requêtes très simples, vérifiez que la largeur de redimensionnement est correcte pour la résolution de votre machine.
- Par défaut : --grounding_model_resize_width 1366 (Anthropic)

Configuration 2 : Endpoint Personnalisé

--endpoint_provider
- Objectif : Spécifie le fournisseur de point de terminaison
- Pris en charge : HuggingFace TGI, vLLM, Open Router
- Par défaut : Aucun
--endpoint_url
- Objectif : L'URL de votre point de terminaison personnalisé
- Par défaut : Aucun
--endpoint_api_key
- Objectif : Votre clé API pour le point de terminaison personnalisé
- Remarque : Ce paramètre est facultatif. S'il n'est pas spécifié, gui-agents utilisera par défaut les variables d'environnement pour la clé API.
- Par défaut : Aucun

Remarque : La Configuration 2 prime sur la Configuration 1.

Cela affichera une invite de requête utilisateur où vous pourrez saisir votre question et interagir avec l'Agent S2. Vous pouvez utiliser n'importe quel modèle de la liste des modèles pris en charge dans models.md.

SDK `gui_agents`

D'abord, nous importons les modules nécessaires. AgentS2 est la classe principale de l'agent S2. OSWorldACI est notre agent d'ancrage qui traduit les actions de l'agent en code Python exécutable.

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"

Ensuite, nous définissons nos paramètres de moteur. engine_params est utilisé pour l'agent principal, et engine_params_for_grounding pour l'ancrage. Pour engine_params_for_grounding, nous prenons en charge les séries Claude, GPT et les 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
}

Puis, nous définissons notre agent d'ancrage et l'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"
)

Enfin, interrogeons l'agent !

# 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])

Consultez gui_agents/s2/cli_app.py pour plus de détails sur le fonctionnement de la boucle d'inférence.

Téléchargement de la Base de Connaissances

L'Agent S2 utilise une base de connaissances qui se met continuellement à jour avec de nouvelles connaissances pendant l'inférence. La base de connaissances est initialement téléchargée lors de l'initialisation de AgentS2. La base de connaissances est stockée sous forme d'assets dans nos GitHub Releases. L'initialisation de AgentS2 ne téléchargera que la base de connaissances pour votre plateforme spécifiée et la version de l'agent (par exemple s1, s2). Si vous souhaitez télécharger la base de connaissances programmatiquement, vous pouvez utiliser le code suivant :

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

Cela téléchargera la base de connaissances de l'Agent S2 pour Linux à partir du tag de version v0.2.2 vers le répertoire kb_data. Consultez nos GitHub Releases ou les tags de version incluant les bases de connaissances.

OSWorld

Pour déployer Agent S2 dans OSWorld, suivez les instructions de déploiement OSWorld.

WindowsAgentArena

Pour déployer l'Agent S2 dans WindowsAgentArena, suivez les Instructions de déploiement de WindowsAgentArena.

💬 Citations

Si vous trouvez ce codebase utile, veuillez citer

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