Agent S2: Ein kompositionelles Generalist-Spezialist-Framework für Computer-Nutzungs-Agenten

  🌐 [S2 Blog]  📄 [S2 Paper]  🎥 [S2 Video]

  🌐 [S1 Blog]  📄 [S1 Paper (ICLR 2025)]  🎥 [S1 Video]

 

  

🥳 Aktualisierungen

• 2025/04/01: Veröffentlichung des Agent S2 Papers mit neuen SOTA-Ergebnissen auf OSWorld, WindowsAgentArena und AndroidWorld!
• 2025/03/12: Veröffentlichung von Agent S2 zusammen mit v0.2.0 von gui-agents, dem neuen State-of-the-Art für Computer-Nutzungs-Agenten (CUA), das OpenAI's CUA/Operator und Anthropic's Claude 3.7 Sonnet Computer-Use übertrifft!
• 2025/01/22: Das Agent S Paper wurde für ICLR 2025 akzeptiert!
• 2025/01/21: Veröffentlichung von v0.1.2 der gui-agents Bibliothek mit Unterstützung für Linux und Windows!
• 2024/12/05: Veröffentlichung von v0.1.0 der gui-agents Bibliothek, die die Nutzung von Agent-S für Mac, OSWorld und WindowsAgentArena vereinfacht!
• 2024/10/10: Veröffentlichung des Agent S Papers und des Codebases!

Inhaltsverzeichnis

1. 💡 Einführung
2. 🎯 Aktuelle Ergebnisse
3. 🛠️ Installation & Einrichtung
4. 🚀 Verwendung
5. 🤝 Danksagungen
6. 💬 Zitierung

💡 Einführung

Willkommen bei Agent S, einem Open-Source-Framework, das autonome Interaktion mit Computern über die Agent-Computer-Schnittstelle ermöglicht. Unsere Mission ist es, intelligente GUI-Agenten zu entwickeln, die aus vergangenen Erfahrungen lernen und komplexe Aufgaben auf Ihrem Computer autonom ausführen können.

Egal, ob Sie sich für KI, Automatisierung oder die Mitarbeit an zukunftsweisenden agentenbasierten Systemen interessieren – wir freuen uns, dass Sie hier sind!

🎯 Aktuelle Ergebnisse

Ergebnisse der Erfolgsrate (%) von Agent S2 auf dem OSWorld-Volltestset unter ausschließlicher Verwendung von Screenshot-Eingaben.

🛠️ Installation & Einrichtung

❗Warnung❗: Wenn Sie einen Linux-Rechner verwenden, kann die Erstellung einer conda-Umgebung mit pyatspi kollidieren. Derzeit gibt es keine saubere Lösung für dieses Problem. Führen Sie die Installation ohne conda oder eine virtuelle Umgebung durch.

⚠️Haftungsausschluss⚠️: Um das volle Potenzial von Agent S2 auszuschöpfen, verwenden wir UI-TARS als Grounding-Modell (7B-DPO oder 72B-DPO für bessere Leistung). Diese können lokal oder auf Hugging Face Inference Endpoints gehostet werden. Unser Code unterstützt Hugging Face Inference Endpoints. Weitere Informationen zur Einrichtung und Abfrage dieses Endpoints finden Sie unter Hugging Face Inference Endpoints. Die Ausführung von Agent S2 erfordert dieses Modell jedoch nicht, und Sie können alternative API-basierte Modelle für visuelles Grounding verwenden, wie z.B. Claude.

Installieren Sie das Paket:

pip install gui-agents

Setzen Sie Ihre LLM-API-Schlüssel und andere Umgebungsvariablen. Dies können Sie tun, indem Sie die folgende Zeile zu Ihrer .bashrc (Linux) oder .zshrc (MacOS) Datei hinzufügen.

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

Alternativ können Sie die Umgebungsvariable in Ihrem Python-Skript setzen:

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

Wir unterstützen auch Azure OpenAI, Anthropic, Gemini, Open Router und vLLM-Inferenz. Weitere Informationen finden Sie unter models.md.

Einrichtung der Web-Retrieval mit Perplexica

Agent S funktioniert am besten mit Web-Wissensabruf. Um diese Funktion zu aktivieren, müssen Sie Perplexica einrichten:

1. Stellen Sie sicher, dass Docker Desktop installiert und auf Ihrem System ausgeführt wird.

2. Navigieren Sie zu dem Verzeichnis, das die Projektdateien enthält.

    cd Perplexica
    git submodule update --init
   

3. Benennen Sie die Datei sample.config.toml in config.toml um. Für Docker-Setups müssen Sie nur die folgenden Felder ausfüllen:

   • OPENAI: Ihr OpenAI-API-Schlüssel. Sie müssen dies nur ausfüllen, wenn Sie OpenAIs Modelle verwenden möchten.

   • OLLAMA: Ihre Ollama-API-URL. Geben Sie sie als http://host.docker.internal:PORT_NUMMER ein. Wenn Sie Ollama auf Port 11434 installiert haben, verwenden Sie http://host.docker.internal:11434. Für andere Ports passen Sie dies entsprechend an. Sie müssen dies ausfüllen, wenn Sie Ollamas Modelle anstelle von OpenAIs Modellen verwenden möchten.

   • GROQ: Ihr Groq-API-Schlüssel. Sie müssen dies nur ausfüllen, wenn Sie Groqs gehostete Modelle verwenden möchten.

   • ANTHROPIC: Ihr Anthropic-API-Schlüssel. Sie müssen dies nur ausfüllen, wenn Sie Anthropic-Modelle verwenden möchten.

     Hinweis: Sie können diese Einstellungen nach dem Start von Perplexica über das Einstellungsdialogfeld ändern.

   • SIMILARITY_MEASURE: Das zu verwendende Ähnlichkeitsmaß (Dies ist standardmäßig ausgefüllt; Sie können es unverändert lassen, wenn Sie sich unsicher sind.)

4. Stellen Sie sicher, dass Sie sich in dem Verzeichnis befinden, das die docker-compose.yaml-Datei enthält, und führen Sie aus:

   docker compose up -d
   

5. Exportieren Sie Ihre Perplexica-URL mit dem Port, der in der docker-compose.yaml-Datei unter app/ports zu finden ist. Sie sehen 3000:3000. Der Port ist die linke Zahl (in diesem Fall 3000).

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

6. Unsere Implementierung von Agent S integriert die Perplexica-API, um eine Suchmaschinenfunktionalität einzubinden, die ein bequemeres und reaktionsschnelleres Benutzererlebnis ermöglicht. Wenn Sie die API an Ihre Einstellungen und spezifischen Anforderungen anpassen möchten, können Sie die URL und die Nachricht der Anfrageparameter in agent_s/query_perplexica.py ändern. Eine umfassende Anleitung zur Konfiguration der Perplexica-API finden Sie in der Perplexica Search API Dokumentation. Für eine detailliertere Einrichtungs- und Verwendungsanleitung lesen Sie bitte das Perplexica Repository.

❗Warnung❗: Der Agent führt direkt Python-Code aus, um Ihren Computer zu steuern. Bitte verwenden Sie ihn mit Vorsicht.

🚀 Verwendung

Hinweis: Unsere beste Konfiguration verwendet Claude 3.7 mit erweitertem Denken und UI-TARS-72B-DPO. Wenn Sie UI-TARS-72B-DPO aufgrund von Ressourcenbeschränkungen nicht ausführen können, kann UI-TARS-7B-DPO als leichtere Alternative mit minimalem Leistungsverlust verwendet werden.

CLI

Führen Sie Agent S2 mit einem bestimmten Modell aus (Standard ist gpt-4o):

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

Oder verwenden Sie einen benutzerdefinierten Endpunkt:

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

Hauptmodell-Einstellungen

• --provider, --model
  • Zweck: Gibt das Hauptgenerierungsmodell an
  • Unterstützt: alle Modellanbieter in models.md
  • Standard: --provider "anthropic" --model "claude-3-7-sonnet-20250219"
• --model_url, --model_api_key
  • Zweck: Gibt den benutzerdefinierten Endpunkt für das Hauptgenerierungsmodell und Ihren API-Schlüssel an
  • Hinweis: Diese sind optional. Wenn nicht angegeben, verwendet gui-agents standardmäßig Ihre Umgebungsvariablen für die URL und den API-Schlüssel.
  • Unterstützt: alle Modellanbieter in models.md
  • Standard: None

Grounding-Konfigurationsoptionen

Sie können entweder Konfiguration 1 oder Konfiguration 2 verwenden:

(Standard) Konfiguration 1: API-basierte Modelle

• --grounding_model_provider, --grounding_model
  • Zweck: Gibt das Modell für visuelles Grounding (Koordinatenvorhersage) an
  • Unterstützt: alle Modellanbieter in models.md
  • Standard: --grounding_model_provider "anthropic" --grounding_model "claude-3-7-sonnet-20250219"
• ❗Wichtig❗ --grounding_model_resize_width
  • Zweck: Einige API-Anbieter skalieren Bilder automatisch neu. Daher werden die generierten (x, y)-Koordinaten relativ zu den neu skalierten Bildabmessungen sein, nicht zu den ursprünglichen Bildabmessungen.
  • Unterstützt: Anthropic Rescaling
  • Tipps: Wenn Ihr Grounding selbst für sehr einfache Abfragen ungenau ist, überprüfen Sie, ob Ihre Reskalierungsbreite korrekt für die Auflösung Ihres Computers ist.
  • Standard: --grounding_model_resize_width 1366 (Anthropic)

Konfiguration 2: Benutzerdefinierter Endpunkt

• --endpoint_provider

  • Zweck: Gibt den Endpunktanbieter an
  • Unterstützt: HuggingFace TGI, vLLM, Open Router
  • Standard: None

• --endpoint_url

  • Zweck: Die URL für Ihren benutzerdefinierten Endpunkt
  • Standard: None

• --endpoint_api_key

  • Zweck: Ihr API-Schlüssel für Ihren benutzerdefinierten Endpunkt
  • Hinweis: Dies ist optional. Wenn nicht angegeben, verwendet gui-agents standardmäßig Ihre Umgebungsvariablen für den API-Schlüssel.
  • Standard: None

Hinweis: Konfiguration 2 hat Vorrang vor Konfiguration 1.

Dadurch wird eine Benutzerabfrage-Eingabeaufforderung angezeigt, in der Sie Ihre Abfrage eingeben und mit Agent S2 interagieren können. Sie können jedes Modell aus der Liste der unterstützten Modelle in models.md verwenden.

gui_agents SDK

Zuerst importieren wir die notwendigen Module. AgentS2 ist die Hauptagentenklasse für Agent S2. OSWorldACI ist unser Grounding-Agent, der Agentenaktionen in ausführbaren Python-Code übersetzt.

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"

Als nächstes definieren wir unsere Engine-Parameter. engine_params wird für den Hauptagenten verwendet, und engine_params_for_grounding ist für Grounding. Für engine_params_for_grounding unterstützen wir die Claude-, GPT-Serie und 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
}

Dann definieren wir unseren Grounding-Agenten und 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"
)

Schließlich fragen wir den Agenten ab!

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

Weitere Details zur Funktionsweise der Inferenzschleife finden Sie in gui_agents/s2/cli_app.py.

Herunterladen der Wissensdatenbank

Agent S2 verwendet eine Wissensdatenbank, die während der Inferenz kontinuierlich mit neuem Wissen aktualisiert wird. Die Wissensdatenbank wird zunächst beim Initialisieren von AgentS2 heruntergeladen. Die Wissensdatenbank wird als Assets unter unseren GitHub Releases gespeichert. Die AgentS2-Initialisierung lädt nur die Wissensdatenbank für Ihre angegebene Plattform und Agentenversion (z.B. s1, s2) herunter. Wenn Sie die Wissensdatenbank programmatisch herunterladen möchten, können Sie den folgenden Code verwenden:

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

Dadurch wird die Wissensdatenbank von Agent S2 für Linux vom Release-Tag v0.2.2 in das Verzeichnis kb_data heruntergeladen. Weitere Informationen finden Sie in unseren GitHub Releases oder Release-Tags, die die Wissensdatenbanken enthalten.

OSWorld

Um Agent S2 in OSWorld bereitzustellen, folgen Sie den OSWorld-Bereitstellungsanweisungen.

💬 Zitierung

Wenn Sie diese Codebasis nützlich finden, zitieren Sie bitte

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

Star-Historie