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

🥳 Atualizações

  • 07/07/2025: O artigo Agent S2 foi aceito na COLM 2025! Nos vemos em Montreal!
  • 01/04/2025: Lançado o artigo Agent S2 com novos resultados SOTA em OSWorld, WindowsAgentArena e AndroidWorld!
  • 12/03/2025: Lançado o Agent S2 junto com a versão v0.2.0 de gui-agents, o 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 Agent S foi aceito na 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 que você use o Agent-S para Mac, OSWorld e WindowsAgentArena com facilidade!
  • 10/10/2024: Lançado o artigo Agent S e seu 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 de código aberto projetado para permitir interação autônoma com computadores através da Interface Agente-Computador. Nossa missão é construir agentes de GUI inteligentes que possam aprender com experiências passadas e executar tarefas complexas de forma autônoma no seu computador.

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

🎯 Resultados Atuais


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%

🛠️ Instalação & Configuração

Observação: Nosso agente retorna código pyautogui e é destinado a uma tela de monitor único.

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

⚠️Aviso Legal⚠️: Para aproveitar todo o potencial do Agent S2, utilizamos UI-TARS como modelo de ancoragem (7B-DPO ou 72B-DPO para melhor desempenho). Eles podem ser hospedados localmente ou em Hugging Face Inference Endpoints. Nosso código é compatível com Hugging Face Inference Endpoints. Consulte Hugging Face Inference Endpoints para obter mais informações sobre como configurar e consultar este endpoint. No entanto, a execução do Agent S2 não requer este modelo, e você pode usar modelos alternativos baseados em API para ancoragem visual, como o Claude.

Instale o pacote:

pip install gui-agents

Configure 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 diretamente no seu script Python:

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

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

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

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

  1. Certifique-se de que o Docker Desktop está instalado e em execução no 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 com 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 da API Ollama. Insira-a 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 da Groq. Você só precisa preencher isso se desejar usar os modelos hospedados da 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 essas configurações após iniciar o Perplexica, através da caixa de diálogo de configurações.

    • SIMILARITY_MEASURE: A medida de similaridade a ser usada (isso já vem 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 a URL do Perplexica usando a porta encontrada no arquivo docker-compose.yaml. Em app/ports, você verá 3000:3000. A porta é o número do lado esquerdo (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 proporciona uma experiência de usuário mais conveniente e responsiva. Se você deseja personalizar a API de acordo com suas configurações e requisitos específicos, pode modificar a URL e os parâmetros de mensagem da 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á diretamente código Python para controlar seu computador. Use com cuidado.

🚀 Como Usar

Nota: Nossa melhor configuração utiliza Claude 3.7 com pensamento estendido e UI-TARS-72B-DPO. Se você não conseguir executar UI-TARS-72B-DPO devido a limitações de recursos, UI-TARS-7B-DPO pode ser usado como 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
    • Finalidade: Especifica o modelo principal de geração
    • Suporta: todos os provedores de modelo em models.md
    • Padrão: --provider "anthropic" --model "claude-3-7-sonnet-20250219"
  • --model_url, --model_api_key
    • Finalidade: 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 chave de API.
    • Suporta: todos os provedores de modelo em models.md
    • Padrão: Nenhum

Opções de Configuração de Grounding

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

(Padrão) Configuração 1: Modelos Baseados em API
  • --grounding_model_provider, --grounding_model
    • Finalidade: Especifica o modelo para grounding visual (previsão de coordenadas)
    • Suporta: todos os provedores de modelo em models.md
    • Padrão: --grounding_model_provider "anthropic" --grounding_model "claude-3-7-sonnet-20250219"
  • ❗Importante❗ --grounding_model_resize_width
    • Finalidade: Alguns provedores de API redimensionam imagens automaticamente. Portanto, as coordenadas (x, y) geradas serão relativas às dimensões da imagem redimensionada, não às dimensões originais.
    • Suporta: Redimensionamento da Anthropic
    • Dicas: Se seu grounding estiver impreciso mesmo para consultas muito simples, verifique 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 de endpoint
    • Suporta: HuggingFace TGI, vLLM, Open Router
    • Padrão: None

  • --endpoint_url

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

  • --endpoint_api_key

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

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

Isso exibirá um prompt de consulta onde você pode inserir sua pergunta 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 S2. OSWorldACI é nosso agente de fundamentação 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 os parâmetros do motor. engine_params é usado para o agente principal e engine_params_for_grounding é para fundamentação. 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
}

Depois, definimos nosso agente de fundamentação 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 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 (ex: s1, s2). Se você quiser 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.

WindowsAgentArena

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

💬 Citações

Se 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

Star History Chart