Agent S2: Um Framework Composicional Generalista-Especialista para Agentes de Uso Computacional

  🌐 [Blog do S2]  📄 [Artigo do S2]  🎥 [Vídeo do S2]

  🌐 [Blog do S1]  📄 [Artigo do S1 (ICLR 2025)]  🎥 [Vídeo do S1]

 

  

🥳 Atualizações

• 01/04/2025: Lançado o artigo do Agent S2 com novos resultados SOTA no OSWorld, WindowsAgentArena e AndroidWorld!
• 12/03/2025: Lançado o Agent S2 junto com a v0.2.0 da biblioteca gui-agents, estabelecendo novo estado da arte para agentes de uso computacional (CUA), superando o CUA/Operator da OpenAI e o Claude 3.7 Sonnet Computer-Use da Anthropic!
• 22/01/2025: O artigo do Agent S foi aceito no ICLR 2025!
• 21/01/2025: Lançada a versão v0.1.2 da biblioteca gui-agents, com suporte para Linux e Windows!
• 05/12/2024: Lançada a versão v0.1.0 da biblioteca gui-agents, permitindo usar o Agent-S para Mac, OSWorld e WindowsAgentArena com facilidade!
• 10/10/2024: Lançados o artigo do Agent S e o código fonte!

Índice

1. 💡 Introdução
2. 🎯 Resultados Atuais
3. 🛠️ Instalação & Configuração
4. 🚀 Uso
5. 🤝 Agradecimentos
6. 💬 Citação

💡 Introdução

Bem-vindo ao Agent S, um framework open-source projetado para permitir interação autônoma com computadores através da Interface Agente-Computador. Nossa missão é construir agentes GUI inteligentes que possam aprender com experiências passadas e executar tarefas complexas autonomamente em seu computador.

Se você tem interesse em IA, automação ou contribuir para sistemas de agentes de ponta, estamos animados em tê-lo aqui!

🎯 Resultados Atuais

Resultados da Taxa de Sucesso (%) do Agent S2 no conjunto de testes completo do OSWorld usando apenas capturas de tela como entrada.

🛠️ Instalação & Configuração

❗Aviso❗: Se estiver em uma máquina Linux, criar um ambiente conda interferirá com pyatspi. Atualmente, não há solução limpa para esse problema. Prossiga com a instalação sem usar conda ou qualquer ambiente virtual.

⚠️Isenção de Responsabilidade⚠️: Para aproveitar todo o potencial do Agent S2, utilizamos UI-TARS como modelo de grounding (7B-DPO ou 72B-DPO para melhor desempenho). Eles podem ser hospedados localmente ou em Hugging Face Inference Endpoints. Nosso código suporta Hugging Face Inference Endpoints. Consulte Hugging Face Inference Endpoints para mais informações sobre como configurar e consultar esse endpoint. No entanto, executar o Agent S2 não requer esse modelo, e você pode usar modelos baseados em API alternativos para visual grounding, como o Claude.

Instale o pacote:

pip install gui-agents

Defina suas chaves de API LLM e outras variáveis de ambiente. Você pode fazer isso adicionando a seguinte linha ao seu arquivo .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>

Alternativamente, você pode definir a variável de ambiente em seu script Python:

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

Também suportamos Azure OpenAI, Anthropic, Gemini, Open Router e inferência vLLM. Para mais informações, consulte models.md.

Configuração de Recuperação de Conhecimento da Web usando Perplexica

O Agent S funciona melhor com recuperação de conhecimento da web. Para ativar esse recurso, você precisa configurar o Perplexica:

1. Certifique-se de que o Docker Desktop está instalado e em execução em seu sistema.

2. Navegue até o diretório que contém os arquivos do projeto.

    cd Perplexica
    git submodule update --init
   

3. Renomeie o arquivo sample.config.toml para config.toml. Para configurações Docker, você só precisa preencher os seguintes campos:

   • OPENAI: Sua chave de API da OpenAI. Você só precisa preencher isso se desejar usar os modelos da OpenAI.

   • OLLAMA: Sua URL de API do Ollama. Você deve inserir como http://host.docker.internal:PORT_NUMBER. Se você instalou o Ollama na porta 11434, use http://host.docker.internal:11434. Para outras portas, ajuste conforme necessário. Você precisa preencher isso se desejar usar os modelos do Ollama em vez dos da OpenAI.

   • GROQ: Sua chave de API do Groq. Você só precisa preencher isso se desejar usar os modelos hospedados do Groq.

   • ANTHROPIC: Sua chave de API da Anthropic. Você só precisa preencher isso se desejar usar os modelos da Anthropic.

     Observação: Você pode alterar isso após iniciar o Perplexica a partir da caixa de diálogo de configurações.

   • SIMILARITY_MEASURE: A medida de similaridade a ser usada (Isso é preenchido por padrão; você pode deixar como está se não tiver certeza.)

4. Certifique-se de estar no diretório que contém o arquivo docker-compose.yaml e execute:

   docker compose up -d
   

5. Exporte sua URL do Perplexica usando a porta encontrada no arquivo docker-compose.yaml em app/ports, você verá 3000:3000. A porta é o número à esquerda (neste caso, 3000).

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

6. Nossa implementação do Agent S incorpora a API do Perplexica para integrar uma capacidade de mecanismo de busca, o que permite uma experiência do usuário mais conveniente e responsiva. Se você deseja personalizar a API para suas configurações e requisitos específicos, pode modificar a URL e os parâmetros de solicitação em agent_s/query_perplexica.py. Para um guia abrangente sobre como configurar a API do Perplexica, consulte a Documentação da API de Busca do Perplexica. Para um guia mais detalhado de configuração e uso, consulte o Repositório do Perplexica.

❗Aviso❗: O agente executará código Python diretamente para controlar seu computador. Use com cuidado.

🚀 Uso

Observação: Nossa melhor configuração usa o Claude 3.7 com pensamento estendido e UI-TARS-72B-DPO. Se você não conseguir executar o UI-TARS-72B-DPO devido a limitações de recursos, o UI-TARS-7B-DPO pode ser usado como uma alternativa mais leve com degradação mínima de desempenho.

CLI

Execute o Agent S2 com um modelo específico (o padrão é gpt-4o):

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

Ou use um endpoint personalizado:

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

Configurações do Modelo Principal

• --provider, --model
  • Propósito: Especifica o modelo principal de geração
  • Suporta: todos os provedores de modelos em models.md
  • Padrão: --provider "anthropic" --model "claude-3-7-sonnet-20250219"
• --model_url, --model_api_key
  • Propósito: Especifica o endpoint personalizado para o modelo principal de geração e sua chave de API
  • Observação: Estes são opcionais. Se não especificados, gui-agents usará as variáveis de ambiente para a URL e a chave de API.
  • Suporta: todos os provedores de modelos em models.md
  • Padrão: Nenhum

Opções de Configuração de Grounding

Você pode usar a Configuração 1 ou a Configuração 2:

(Padrão) Configuração 1: Modelos Baseados em API

• --grounding_model_provider, --grounding_model
  • Propósito: Especifica o modelo para visual grounding (previsão de coordenadas)
  • Suporta: todos os provedores de modelos em models.md
  • Padrão: --grounding_model_provider "anthropic" --grounding_model "claude-3-7-sonnet-20250219"
• ❗Importante❗ --grounding_model_resize_width
  • Propósito: Alguns provedores de API redimensionam imagens automaticamente. Portanto, o (x, y) gerado será relativo às dimensões da imagem redimensionada, em vez das dimensões originais da imagem.
  • Suporta: Redimensionamento da Anthropic
  • Dicas: Se seu grounding estiver impreciso mesmo para consultas muito simples, verifique novamente se a largura de redimensionamento está correta para a resolução da sua máquina.
  • Padrão: --grounding_model_resize_width 1366 (Anthropic)

Configuração 2: Endpoint Personalizado

• --endpoint_provider

  • Propósito: Especifica o provedor do endpoint
  • Suporta: HuggingFace TGI, vLLM, Open Router
  • Padrão: Nenhum

• --endpoint_url

  • Propósito: A URL para seu endpoint personalizado
  • Padrão: Nenhum

• --endpoint_api_key

  • Propósito: Sua chave de API para seu endpoint personalizado
  • Observação: Isso é opcional. Se não especificado, gui-agents usará as variáveis de ambiente para a chave de API.
  • Padrão: Nenhum

Observação: A Configuração 2 tem precedência sobre a Configuração 1.

Isso mostrará um prompt de consulta do usuário onde você pode inserir sua consulta e interagir com o Agent S2. Você pode usar qualquer modelo da lista de modelos suportados em models.md.

SDK gui_agents

Primeiro, importamos os módulos necessários. AgentS2 é a classe principal do agente para o Agent S2. OSWorldACI é nosso agente de grounding que traduz ações do agente em código Python executável.

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"

Em seguida, definimos nossos parâmetros de engine. engine_params é usado para o agente principal, e engine_params_for_grounding é para grounding. Para engine_params_for_grounding, suportamos a série Claude, GPT e 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
}

Então, definimos nosso agente de grounding e o 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, vamos consultar o 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])

Consulte gui_agents/s2/cli_app.py para mais detalhes sobre como o loop de inferência funciona.

Baixando a Base de Conhecimento

O Agent S2 usa uma base de conhecimento que é continuamente atualizada com novos conhecimentos durante a inferência. A base de conhecimento é baixada inicialmente ao inicializar o AgentS2. A base de conhecimento é armazenada como assets em nossos GitHub Releases. A inicialização do AgentS2 só baixará a base de conhecimento para sua plataforma especificada e versão do agente (por exemplo, s1, s2). Se você deseja baixar a base de conhecimento programaticamente, pode usar o seguinte código:

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

Isso baixará a base de conhecimento do Agent S2 para Linux da tag de release v0.2.2 para o diretório kb_data. Consulte nossos GitHub Releases ou tags de release que incluem as bases de conhecimento.

OSWorld

Para implantar o Agent S2 no OSWorld, siga as instruções de Implantação do OSWorld.

💬 Citações

Se você achar este código útil, por favor cite

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

Histórico de Estrelas