Readme i18n

simular-ai/Agent-S

Share
English(original)DeutschEspañolfrançais日本語한국어PortuguêsРусский中文
Translated at: 14 Jul 2025Is latest

Logo 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]

  simular-ai%2FAgent-S | Trendshift

Discord    PyPI Downloads

🥳 Aktualisierungen

  • 2025/07/07: Das Agent S2 Paper wurde für COLM 2025 angenommen! Wir sehen uns in Montreal!
  • 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-Use-Agents (CUA), das OpenAIs CUA/Operator und Anthropics Claude 3.7 Sonnet Computer-Use übertrifft!
  • 2025/01/22: Das Agent S Paper wurde für ICLR 2025 angenommen!
  • 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 Codebase!

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 Interface ermöglicht. Unsere Mission ist es, intelligente GUI-Agents zu entwickeln, die aus vergangenen Erfahrungen lernen und komplexe Aufgaben auf Ihrem Computer autonom ausführen können.

Egal, ob Sie an KI, Automatisierung oder der Mitwirkung an zukunftsweisenden Agenten-basierten Systemen interessiert sind – wir freuen uns, dass Sie hier sind!

🎯 Aktuelle Ergebnisse


Results of Agent S2's Successful Rate (%) on the OSWorld full test set using Screenshot input only.

BenchmarkAgent S2Previous SOTAΔ improve
OSWorld (15 step)27.0%22.7% (UI-TARS)+4.3%
OSWorld (50 step)34.5%32.6% (OpenAI CUA)+1.9%
WindowsAgentArena29.8%19.5% (NAVI)+10.3%
AndroidWorld54.3%46.8% (UI-TARS)+7.5%

🛠️ Installation & Einrichtung

Hinweis: Unser Agent gibt pyautogui-Code zurück und ist für einen einzelnen Monitorbildschirm ausgelegt.

❗Warnung❗: Falls Sie einen Linux-Rechner verwenden, kann die Erstellung einer conda-Umgebung mit pyatspi interferieren. 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 jedoch nicht zwingend dieses Modell – Sie können auch alternative API-basierte Modelle für visuelles Grounding verwenden, wie z.B. Claude.

Installieren Sie das Paket:

pip install gui-agents

Legen Sie Ihre LLM-API-Schlüssel und andere Umgebungsvariablen fest. 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 auch 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 auf Ihrem System installiert und gestartet ist.

  2. Navigieren Sie zum Verzeichnis mit den Projektdateien.

     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. Dies ist nur erforderlich, wenn Sie OpenAIs Modelle nutzen möchten.

    • OLLAMA: Ihre Ollama API-URL. Geben Sie diese als http://host.docker.internal:PORT_NUMMER ein. Falls Ollama auf Port 11434 läuft, verwenden Sie http://host.docker.internal:11434. Passen Sie den Port bei Bedarf an. Dies ist nur erforderlich, wenn Sie Ollama-Modelle statt OpenAIs nutzen möchten.

    • GROQ: Ihr Groq API-Schlüssel. Dies ist nur erforderlich, wenn Sie Groqs gehostete Modelle nutzen möchten.

    • ANTHROPIC: Ihr Anthropic API-Schlüssel. Dies ist nur erforderlich, wenn Sie Anthropic-Modelle nutzen möchten.

      Hinweis: Diese Einstellungen können später über das Einstellungsmenü in Perplexica geändert werden.

    • SIMILARITY_MEASURE: Das zu verwendende Ähnlichkeitsmaß (Standardwert voreingestellt; bei Unsicherheit können Sie dies unverändert lassen.)

  4. Stellen Sie sicher, dass Sie sich im Verzeichnis mit der docker-compose.yaml-Datei befinden, und führen Sie aus:

    docker compose up -d

  5. Exportieren Sie Ihre Perplexica-URL mit dem Port aus der docker-compose.yaml-Datei. Unter app/ports finden Sie 3000:3000. Der relevante Port ist die linke Zahl (hier 3000).

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

  6. Unsere Implementierung von Agent S integriert die Perplexica-API, um eine Suchmaschinenfunktionalität bereitzustellen, was eine komfortablere und reaktionsschnellere Nutzererfahrung ermöglicht. Falls Sie die API an Ihre spezifischen Anforderungen anpassen möchten, können Sie die URL und die Anfrageparameter in agent_s/query_perplexica.py modifizieren. Eine detaillierte Anleitung zur Konfiguration der Perplexica-API finden Sie in der Perplexica Search API Dokumentation. Für eine ausführlichere Setup- und Nutzungsanleitung besuchen 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. Falls 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/"

Hauptmodelleinstellungen

  • --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: Keine

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 beziehen sich die generierten (x, y)-Koordinaten auf die neu skalierten Bildabmessungen und nicht auf die Originalabmessungen.
    • Unterstützt: Anthropic Rescaling
    • Tipps: Wenn Ihr Grounding selbst bei sehr einfachen Abfragen ungenau ist, überprüfen Sie, ob die Reskalierungsbreite für Ihre Bildschirmauflösung korrekt ist.
    • Standard: --grounding_model_resize_width 1366 (Anthropic)
Konfiguration 2: Benutzerdefinierter Endpunkt

  • --endpoint_provider

    • Zweck: Gibt den Endpunkt-Provider an
    • Unterstützt: HuggingFace TGI, vLLM, Open Router
    • Standard: Keiner

  • --endpoint_url

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

  • --endpoint_api_key

    • Zweck: Ihr API-Schlüssel für den benutzerdefinierten Endpunkt
    • Hinweis: Dies ist optional. Falls nicht angegeben, greift gui-agents auf Ihre Umgebungsvariablen für den API-Schlüssel zurück.
    • Standard: Keiner

Hinweis: Konfiguration 2 hat Vorrang vor Konfiguration 1.

Dies zeigt eine Eingabeaufforderung für Benutzeranfragen, wo 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 Haupt-Agentenklasse 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 Haupt-Agenten verwendet, und engine_params_for_grounding dient dem Grounding. Für engine_params_for_grounding unterstützen wir die Claude-, GPT-Serien 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 initial beim Initialisieren von AgentS2 heruntergeladen. Die Wissensdatenbank ist als Assets unter unseren GitHub Releases gespeichert. Die Initialisierung von AgentS2 lädt nur die Wissensdatenbank für Ihre spezifizierte Plattform und Agentenversion (z.B. s1, s2) herunter. Falls Sie die Wissensdatenbank programmatisch herunterladen möchten, können Sie folgenden Code verwenden:

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

Dies lädt die Wissensdatenbank von Agent S2 für Linux vom Release-Tag v0.2.2 in das Verzeichnis kb_data herunter. Siehe unsere GitHub Releases oder Release-Tags, die die Wissensdatenbanken enthalten.

OSWorld

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

WindowsAgentArena

Um Agent S2 in der WindowsAgentArena bereitzustellen, folgen Sie den Bereitstellungsanweisungen für WindowsAgentArena.

💬 Zitate

Falls 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

Star History Chart