Agent S2 : Un cadre compositionnel généraliste-spécialiste pour les agents d'utilisation informatique

  🌐 [Blog S2]  📄 [Article S2]  🎥 [Vidéo S2]

  🌐 [Blog S1]  📄 [Article S1 (ICLR 2025)]  🎥 [Vidéo S1]

 

  

🥳 Actualités

• 01/04/2025 : Publication de l'article Agent S2 avec de nouveaux résultats SOTA sur OSWorld, WindowsAgentArena et AndroidWorld !
• 12/03/2025 : Lancement d'Agent S2 avec la version 0.2.0 de gui-agents, établissant un nouveau state-of-the-art pour les agents d'utilisation informatique (CUA), surpassant OpenAI CUA/Operator et Claude 3.7 Sonnet Computer-Use d'Anthropic !
• 22/01/2025 : L'article Agent S est accepté à ICLR 2025 !
• 21/01/2025 : Sortie de la version 0.1.2 de la bibliothèque gui-agents, avec support pour Linux et Windows !
• 05/12/2024 : Sortie de la version 0.1.0 de la bibliothèque gui-agents, permettant d'utiliser facilement Agent-S pour Mac, OSWorld et WindowsAgentArena !
• 10/10/2024 : Publication de l'article Agent S et du code source !

Table des matières

1. 💡 Introduction
2. 🎯 Résultats actuels
3. 🛠️ Installation & Configuration
4. 🚀 Utilisation
5. 🤝 Remerciements
6. 💬 Citation

💡 Introduction

Bienvenue dans 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 créer 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 ordinateur.

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

🎯 Résultats actuels

Taux de réussite (%) d'Agent S2 sur l'ensemble de test complet d'OSWorld en utilisant uniquement des captures d'écran.

🛠️ Installation & Configuration

❗Avertissement❗ : Si vous êtes sur 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). Ils 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

Définissez 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 :

1. Assurez-vous que Docker Desktop est installé et en cours d'exécution sur votre système.

2. Accédez au répertoire contenant les fichiers du projet.

    cd Perplexica
    git submodule update --init
   

3. 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. Vous ne devez remplir ce champ que si vous souhaitez utiliser les modèles d'OpenAI.

   • OLLAMA : Votre URL API Ollama. Vous devez l'entrer sous la forme http://host.docker.internal:PORT_NUMBER. Si vous avez installé Ollama sur le port 11434, utilisez http://host.docker.internal:11434. Pour d'autres ports, ajustez en conséquence. Vous devez remplir ce champ si vous souhaitez utiliser les modèles d'Ollama au lieu de ceux d'OpenAI.

   • GROQ : Votre clé API Groq. Vous ne devez remplir ce champ que si vous souhaitez utiliser les modèles hébergés par Groq.

   • ANTHROPIC : Votre clé API Anthropic. Vous ne devez remplir ce champ que si vous souhaitez utiliser les modèles d'Anthropic.

     Remarque : Vous pouvez modifier ces paramètres après avoir démarré Perplexica depuis la boîte de dialogue des paramètres.

   • SIMILARITY_MEASURE : La mesure de similarité à utiliser (ce champ est rempli par défaut ; vous pouvez le laisser tel quel si vous n'êtes pas sûr).

4. Assurez-vous d'être dans le répertoire contenant le fichier docker-compose.yaml et exécutez :

   docker compose up -d
   

5. Exportez votre URL Perplexica en utilisant le port trouvé dans le fichier docker-compose.yaml sous app/ports, vous verrez 3000:3000. Le port est le nombre à gauche (dans ce cas, 3000).

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

6. Notre implémentation d'Agent S intègre l'API Perplexica pour ajouter une fonctionnalité de moteur de recherche, ce qui permet une expérience utilisateur plus pratique et réactive. Si vous souhaitez adapter l'API à vos paramètres et exigences 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é, consultez le Dépôt Perplexica.

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

🚀 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 point de terminaison 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
  • Prend 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 le point de terminaison personnalisé pour le modèle principal de génération et votre clé API
  • Remarque : Ces paramètres sont optionnels. S'ils ne sont pas spécifiés, gui-agents utilisera par défaut vos variables d'environnement pour l'URL et la clé API.
  • Prend en charge : tous les fournisseurs de modèles dans models.md
  • Par défaut : Aucun

Options de configuration d'ancrage

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 l'ancrage visuel (prédiction des coordonnées)
  • Prend 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 de l'image.
  • Prend en charge : Redimensionnement Anthropic
  • Conseils : Si votre ancrage 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 : Point de terminaison personnalisé

• --endpoint_provider

  • Objectif : Spécifie le fournisseur du point de terminaison
  • Prend 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 votre point de terminaison personnalisé
  • Remarque : Ce paramètre est optionnel. S'il n'est pas spécifié, gui-agents utilisera par défaut vos variables d'environnement pour la clé API.
  • Par défaut : Aucun

Remarque : La Configuration 2 prend le pas sur la Configuration 1.

Cela affichera une invite de requête utilisateur où vous pouvez entrer votre requête et interagir avec 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

Tout d'abord, nous importons les modules nécessaires. AgentS2 est la classe principale de l'agent pour 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 est pour l'ancrage. Pour engine_params_for_grounding, nous prenons en charge la série Claude, GPT et 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 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

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 de manière programmatique, 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 d'Agent S2 pour Linux à partir de la version v0.2.2 dans le répertoire kb_data. Consultez nos GitHub Releases ou les tags de version qui incluent les bases de connaissances.

OSWorld

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

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

Historique des étoiles