Agent S2: Un marco composicional generalista-especialista para agentes de uso informático

🌐 [Blog S2] 📄 [Artículo S2] 🎥 [Video S2]

🌐 [Blog S1] 📄 [Artículo S1 (ICLR 2025)] 🎥 [Video S1]

🥳 Actualizaciones

2025/04/01: Publicado el artículo de Agent S2 con nuevos resultados SOTA en OSWorld, WindowsAgentArena y AndroidWorld!
2025/03/12: Lanzamiento de Agent S2 junto con la versión v0.2.0 de gui-agents, el nuevo estado del arte para agentes de uso informático (CUA), superando a CUA/Operator de OpenAI y Claude 3.7 Sonnet Computer-Use de Anthropic!
2025/01/22: ¡El artículo de Agent S ha sido aceptado en ICLR 2025!
2025/01/21: Lanzada la versión v0.1.2 de la biblioteca gui-agents, con soporte para Linux y Windows!
2024/12/05: Lanzada la versión v0.1.0 de la biblioteca gui-agents, permitiendo usar Agent-S para Mac, OSWorld y WindowsAgentArena fácilmente!
2024/10/10: ¡Publicado el artículo de Agent S y el código fuente!

💡 Introducción

Bienvenido a Agent S, un marco de código abierto diseñado para permitir la interacción autónoma con computadoras a través de la Interfaz Agente-Computadora. Nuestra misión es construir agentes GUI inteligentes que puedan aprender de experiencias pasadas y realizar tareas complejas de forma autónoma en tu computadora.

¡Ya sea que te interese la IA, la automatización o contribuir a sistemas de agentes de vanguardia, estamos emocionados de tenerte aquí!

🎯 Resultados Actuales

Resultados de la Tasa de Éxito (%) de Agent S2 en el conjunto de pruebas completo de OSWorld usando solo capturas de pantalla.

Benchmark	Agent S2	SOTA Anterior	Δ mejora
OSWorld (15 pasos)	27.0%	22.7% (UI-TARS)	+4.3%
OSWorld (50 pasos)	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%

🛠️ Instalación & Configuración

❗Advertencia❗: Si estás en una máquina Linux, crear un entorno conda interferirá con pyatspi. Actualmente no hay una solución limpia para este problema. Procede con la instalación sin usar conda o cualquier entorno virtual.

⚠️Descargo de responsabilidad⚠️: Para aprovechar todo el potencial de Agent S2, utilizamos UI-TARS como modelo de anclaje (7B-DPO o 72B-DPO para mejor rendimiento). Pueden alojarse localmente o en Hugging Face Inference Endpoints. Nuestro código soporta Hugging Face Inference Endpoints. Consulta Hugging Face Inference Endpoints para más información sobre cómo configurar y consultar este endpoint. Sin embargo, ejecutar Agent S2 no requiere este modelo, y puedes usar modelos basados en API alternativos para anclaje visual, como Claude.

Instala el paquete:

pip install gui-agents

Configura tus claves de API de LLM y otras variables de entorno. Puedes hacer esto añadiendo la siguiente línea a tu archivo .bashrc (Linux) o .zshrc (MacOS).

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

Alternativamente, puedes establecer la variable de entorno en tu script Python:

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

También soportamos Azure OpenAI, Anthropic, Gemini, Open Router e inferencia vLLM. Para más información consulta models.md.

Configuración de Recuperación Web usando Perplexica

Agent S funciona mejor con recuperación de conocimiento web. Para habilitar esta función, necesitas configurar Perplexica:

Asegúrate de que Docker Desktop esté instalado y en ejecución en tu sistema.
Navega al directorio que contiene los archivos del proyecto.
```
 cd Perplexica
 git submodule update --init
```
Renombra el archivo sample.config.toml a config.toml. Para configuraciones Docker, solo necesitas completar los siguientes campos:
- OPENAI: Tu clave API de OpenAI. Solo necesitas completar esto si deseas usar los modelos de OpenAI.
- OLLAMA: Tu URL API de Ollama. Debes ingresarla como http://host.docker.internal:PORT_NUMBER. Si instalaste Ollama en el puerto 11434, usa http://host.docker.internal:11434. Para otros puertos, ajusta según corresponda. Necesitas completar esto si deseas usar los modelos de Ollama en lugar de los de OpenAI.
- GROQ: Tu clave API de Groq. Solo necesitas completar esto si deseas usar los modelos alojados de Groq.
- ANTHROPIC: Tu clave API de Anthropic. Solo necesitas completar esto si deseas usar modelos de Anthropic.
  
  Nota: Puedes cambiar estos después de iniciar Perplexica desde el diálogo de configuración.
- SIMILARITY_MEASURE: La medida de similitud a usar (Está completada por defecto; puedes dejarla como está si no estás seguro).
Asegúrate de estar en el directorio que contiene el archivo docker-compose.yaml y ejecuta:
```
docker compose up -d
```
Exporta tu URL de Perplexica usando el puerto encontrado en el archivo docker-compose.yaml bajo app/ports, verás 3000:3000. El puerto es el número de la izquierda (en este caso, 3000).
```
export PERPLEXICA_URL=http://localhost:{port}/api/search
```
Nuestra implementación de Agent S incorpora la API de Perplexica para integrar una capacidad de motor de búsqueda, lo que permite una experiencia de usuario más conveniente y receptiva. Si deseas personalizar la API según tus configuraciones y requisitos específicos, puedes modificar la URL y los parámetros del mensaje de solicitud en agent_s/query_perplexica.py. Para una guía completa sobre cómo configurar la API de Perplexica, consulta la Documentación de la API de Búsqueda de Perplexica. Para una guía más detallada de configuración y uso, consulta el Repositorio de Perplexica.

❗Advertencia❗: El agente ejecutará código Python directamente para controlar tu computadora. Por favor, usa con cuidado.

🚀 Uso

Nota: Nuestra mejor configuración usa Claude 3.7 con pensamiento extendido y UI-TARS-72B-DPO. Si no puedes ejecutar UI-TARS-72B-DPO debido a limitaciones de recursos, UI-TARS-7B-DPO puede usarse como alternativa más ligera con una degradación mínima de rendimiento.

CLI

Ejecuta Agent S2 con un modelo específico (el predeterminado es gpt-4o):

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

O usa un endpoint personalizado:

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

Configuración del Modelo Principal

--provider, --model
- Propósito: Especifica el modelo principal de generación
- Soporta: todos los proveedores de modelos en models.md
- Predeterminado: --provider "anthropic" --model "claude-3-7-sonnet-20250219"
--model_url, --model_api_key
- Propósito: Especifica el endpoint personalizado para el modelo principal de generación y tu clave API
- Nota: Estos son opcionales. Si no se especifican, gui-agents usará tus variables de entorno para la URL y la clave API.
- Soporta: todos los proveedores de modelos en models.md
- Predeterminado: Ninguno

Opciones de Configuración de Anclaje

Puedes usar la Configuración 1 o la Configuración 2:

(Predeterminado) Configuración 1: Modelos Basados en API

--grounding_model_provider, --grounding_model
- Propósito: Especifica el modelo para anclaje visual (predicción de coordenadas)
- Soporta: todos los proveedores de modelos en models.md
- Predeterminado: --grounding_model_provider "anthropic" --grounding_model "claude-3-7-sonnet-20250219"
❗Importante❗ --grounding_model_resize_width
- Propósito: Algunos proveedores de API reescalan imágenes automáticamente. Por lo tanto, las coordenadas (x, y) generadas serán relativas a las dimensiones de la imagen reescalada, no a las dimensiones originales.
- Soporta: Reescalado de Anthropic
- Consejos: Si tu anclaje es inexacto incluso para consultas muy simples, verifica que el ancho de reescalado sea correcto para la resolución de tu máquina.
- Predeterminado: --grounding_model_resize_width 1366 (Anthropic)

Configuración 2: Endpoint Personalizado

--endpoint_provider
- Propósito: Especifica el proveedor del endpoint
- Soporta: HuggingFace TGI, vLLM, Open Router
- Predeterminado: Ninguno
--endpoint_url
- Propósito: La URL para tu endpoint personalizado
- Predeterminado: Ninguno
--endpoint_api_key
- Propósito: Tu clave API para tu endpoint personalizado
- Nota: Esto es opcional. Si no se especifica, gui-agents usará tus variables de entorno para la clave API.
- Predeterminado: Ninguno

Nota: La Configuración 2 tiene prioridad sobre la Configuración 1.

Esto mostrará un prompt de consulta de usuario donde puedes ingresar tu consulta e interactuar con Agent S2. Puedes usar cualquier modelo de la lista de modelos soportados en models.md.

SDK `gui_agents`

Primero, importamos los módulos necesarios. AgentS2 es la clase principal del agente para Agent S2. OSWorldACI es nuestro agente de anclaje que traduce las acciones del agente en código Python ejecutable.

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"

A continuación, definimos nuestros parámetros del motor. engine_params se usa para el agente principal, y engine_params_for_grounding es para el anclaje. Para engine_params_for_grounding, soportamos la serie Claude, GPT y 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
}

Luego, definimos nuestro agente de anclaje y 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"
)

¡Finalmente, consultemos al agente!

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

Consulta gui_agents/s2/cli_app.py para más detalles sobre cómo funciona el bucle de inferencia.

Descarga de la Base de Conocimiento

Agent S2 usa una base de conocimiento que se actualiza continuamente con nuevo conocimiento durante la inferencia. La base de conocimiento se descarga inicialmente al inicializar AgentS2. La base de conocimiento se almacena como activos en nuestros GitHub Releases. La inicialización de AgentS2 solo descargará la base de conocimiento para tu plataforma especificada y versión del agente (ej. s1, s2). Si deseas descargar la base de conocimiento programáticamente, puedes usar el siguiente código:

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

Esto descargará la base de conocimiento de Agent S2 para Linux desde la etiqueta de release v0.2.2 al directorio kb_data. Consulta nuestros GitHub Releases o etiquetas de release que incluyan las bases de conocimiento.

OSWorld

Para desplegar Agent S2 en OSWorld, sigue las instrucciones de Despliegue en OSWorld.

💬 Citas

Si encuentras útil este código base, por favor cita

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

Translation Not Available Yet

Agent S2: Un marco composicional generalista-especialista para agentes de uso informático

🥳 Actualizaciones

Tabla de Contenidos

💡 Introducción

🎯 Resultados Actuales

🛠️ Instalación & Configuración

Configuración de Recuperación Web usando Perplexica

🚀 Uso

CLI

Configuración del Modelo Principal

Opciones de Configuración de Anclaje

(Predeterminado) Configuración 1: Modelos Basados en API

Configuración 2: Endpoint Personalizado

SDK `gui_agents`

Descarga de la Base de Conocimiento

OSWorld

💬 Citas

Historial de Estrellas

Agent S2: Un marco composicional generalista-especialista para agentes de uso informático

🥳 Actualizaciones

Tabla de Contenidos

💡 Introducción

🎯 Resultados Actuales

🛠️ Instalación & Configuración

Configuración de Recuperación Web usando Perplexica

🚀 Uso

CLI

Configuración del Modelo Principal

Opciones de Configuración de Anclaje

(Predeterminado) Configuración 1: Modelos Basados en API

Configuración 2: Endpoint Personalizado

SDK gui_agents

Descarga de la Base de Conocimiento

OSWorld

💬 Citas

Historial de Estrellas

SDK `gui_agents`