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

🥳 업데이트

  • 2025/07/07: Agent S2 논문이 COLM 2025에 채택되었습니다! 몬트리올에서 만나요!
  • 2025/04/01: OSWorld, WindowsAgentArena, AndroidWorld에서 새로운 SOTA 결과를 포함한 Agent S2 논문을 공개했습니다!
  • 2025/03/12: 컴퓨터 사용 에이전트(CUA) 분야의 새로운 최첨단 기술인 Agent S2와 gui-agents v0.2.0을 출시했습니다. OpenAI의 CUA/Operator와 Anthropic의 Claude 3.7 Sonnet Computer-Use를 능가하는 성능을 보여줍니다!
  • 2025/01/22: Agent S 논문이 ICLR 2025에 채택되었습니다!
  • 2025/01/21: Linux 및 Windows 지원이 추가된 gui-agents 라이브러리 v0.1.2 버전을 출시했습니다!
  • 2024/12/05: Mac, OSWorld, WindowsAgentArena에서 Agent-S를 쉽게 사용할 수 있는 gui-agents 라이브러리 v0.1.0 버전을 출시했습니다!
  • 2024/10/10: Agent S 논문과 코드베이스를 공개했습니다!

목차

  1. 💡 소개
  2. 🎯 현재 결과
  3. 🛠️ 설치 및 설정
  4. 🚀 사용 방법
  5. 🤝 감사의 말
  6. 💬 인용

💡 소개

Agent S에 오신 것을 환영합니다. 이는 Agent-Computer Interface를 통해 컴퓨터와 자율적으로 상호작용할 수 있도록 설계된 오픈소스 프레임워크입니다. 우리의 목표는 과거 경험을 학습하고 컴퓨터에서 복잡한 작업을 자율적으로 수행할 수 있는 지능형 GUI 에이전트를 구축하는 것입니다.

AI, 자동화 또는 최첨단 에이전트 기반 시스템에 기여하는 데 관심이 있으시다면, 여러분의 참여를 기대합니다!

🎯 현재 결과


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%

🛠️ 설치 및 설정

참고: 저희 에이전트는 pyautogui 코드를 반환하며 단일 모니터 화면을 기준으로 설계되었습니다.

❗경고❗: Linux 머신을 사용 중이라면, conda 환경을 생성하면 pyatspi와 충돌이 발생할 수 있습니다. 현재로서는 이 문제에 대한 깔끔한 해결책이 없습니다. conda나 가상 환경을 사용하지 않고 설치를 진행하세요.

⚠️면책 조항⚠️: Agent S2의 전체 성능을 활용하기 위해 UI-TARS를 그라운딩 모델로 사용합니다(더 나은 성능을 위해 7B-DPO 또는 72B-DPO 버전 권장). 이 모델은 로컬 또는 Hugging Face Inference Endpoints에서 호스팅할 수 있습니다. 저희 코드는 Hugging Face Inference Endpoints를 지원합니다. 엔드포인트 설정 및 쿼리 방법에 대한 자세한 내용은 Hugging Face Inference Endpoints를 참조하세요. 다만 Agent S2 실행 시 이 모델이 반드시 필요한 것은 아니며, Claude와 같은 API 기반의 대체 시각적 그라운딩 모델을 사용할 수도 있습니다.

패키지 설치:

pip install gui-agents

LLM API 키 및 기타 환경 변수를 설정하세요. Linux에서는 .bashrc 파일에, MacOS에서는 .zshrc 파일에 다음 줄을 추가하여 설정할 수 있습니다.

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

또는 Python 스크립트 내에서 환경 변수를 설정할 수도 있습니다:

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

Azure OpenAI, Anthropic, Gemini, Open Router 및 vLLM 추론도 지원합니다. 자세한 내용은 models.md를 참조하세요.

Perplexica를 이용한 웹 기반 검색 설정

Agent S는 웹 기반 지식 검색과 함께 사용할 때 최적의 성능을 발휘합니다. 이 기능을 활성화하려면 Perplexica를 설정해야 합니다:

  1. 시스템에 Docker Desktop이 설치되어 실행 중인지 확인하세요.

  2. 프로젝트 파일이 포함된 디렉토리로 이동합니다.

     cd Perplexica
 git submodule update --init

  3. sample.config.toml 파일을 config.toml로 이름을 변경합니다. Docker 설정의 경우 다음 필드만 채우면 됩니다:

    • OPENAI: OpenAI API 키. OpenAI 모델을 사용하려는 경우에만 입력하세요.

    • OLLAMA: Ollama API URL. http://host.docker.internal:PORT_NUMBER 형식으로 입력하세요. Ollama를 11434 포트에 설치한 경우 http://host.docker.internal:11434를 사용하세요. 다른 포트를 사용하는 경우 해당 포트로 조정하세요. OpenAI 대신 Ollama 모델을 사용하려는 경우 이 필드를 채워야 합니다.

    • GROQ: Groq API 키. Groq 호스팅 모델을 사용하려는 경우에만 입력하세요.

    • ANTHROPIC: Anthropic API 키. Anthropic 모델을 사용하려는 경우에만 입력하세요.

      참고: 이러한 설정은 Perplexica를 시작한 후 설정 대화상자에서 변경할 수 있습니다.

    • SIMILARITY_MEASURE: 사용할 유사도 측정 방법 (기본값으로 채워져 있습니다; 확실하지 않은 경우 그대로 두셔도 됩니다.)

  4. docker-compose.yaml 파일이 있는 디렉토리에 있는지 확인하고 다음 명령을 실행하세요:

    docker compose up -d

  5. docker-compose.yaml 파일의 app/ports 섹션에서 3000:3000과 같은 포트 설정을 찾으세요. 포트는 왼쪽 숫자입니다 (이 경우 3000). 이 포트를 사용하여 Perplexica URL을 내보냅니다.

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

  6. Agent S 구현에는 Perplexica API가 통합되어 검색 엔진 기능을 제공하며, 더 편리하고 반응성이 뛰어난 사용자 경험을 가능하게 합니다. API를 사용자 설정과 특정 요구 사항에 맞게 조정하려면 agent_s/query_perplexica.py에서 URL과 요청 매개변수 메시지를 수정할 수 있습니다. Perplexica API 구성에 대한 포괄적인 가이드는 Perplexica 검색 API 문서를 참조하세요. 더 자세한 설정 및 사용 가이드는 Perplexica 저장소를 참조하세요.

❗경고❗: 이 에이전트는 컴퓨터를 제어하기 위해 파이썬 코드를 직접 실행합니다. 사용 시 주의하세요.

🚀 사용 방법

참고: 최적의 구성은 Claude 3.7과 확장 사고 기능, UI-TARS-72B-DPO를 사용하는 것입니다. 리소스 제약으로 UI-TARS-72B-DPO를 실행할 수 없는 경우, UI-TARS-7B-DPO를 대체제로 사용할 수 있으며 성능 저하는 최소화됩니다.

CLI

특정 모델로 Agent S2 실행 (기본값은 gpt-4o):

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

또는 커스텀 엔드포인트 사용:

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

메인 모델 설정

  • --provider, --model
    • 용도: 메인 생성 모델 지정
    • 지원: models.md의 모든 모델 제공자
    • 기본값: --provider "anthropic" --model "claude-3-7-sonnet-20250219"
  • --model_url, --model_api_key
    • 용도: 메인 생성 모델의 커스텀 엔드포인트와 API 키 지정
    • 참고: 선택 사항입니다. 지정하지 않으면 gui-agents는 URL과 API 키에 대해 환경 변수를 기본값으로 사용합니다.
    • 지원: models.md의 모든 모델 제공자
    • 기본값: 없음

그라운딩 구성 옵션

구성 1 또는 구성 2 중 하나를 사용할 수 있습니다:

(기본) 구성 1: API 기반 모델
  • --grounding_model_provider, --grounding_model
    • 용도: 시각적 그라운딩(좌표 예측)을 위한 모델 지정
    • 지원: models.md의 모든 모델 제공자
    • 기본값: --grounding_model_provider "anthropic" --grounding_model "claude-3-7-sonnet-20250219"
  • ❗중요❗ --grounding_model_resize_width
    • 용도: 일부 API 제공자는 이미지를 자동으로 크기 조정합니다. 따라서 생성된 (x, y) 좌표는 원본 이미지 크기가 아닌 크기 조정된 이미지 차원에 상대적입니다.
    • 지원: Anthropic 크기 조정
    • 팁: 매우 간단한 쿼리에 대해서도 그라운딩이 부정확한 경우, 머신의 해상도에 맞게 크기 조정 너비가 올바른지 다시 확인하세요.
    • 기본값: --grounding_model_resize_width 1366 (Anthropic)
구성 2: 커스텀 엔드포인트

  • --endpoint_provider

    • 목적: 엔드포인트 제공자를 지정합니다
    • 지원: HuggingFace TGI, vLLM, Open Router
    • 기본값: None

  • --endpoint_url

    • 목적: 사용자 정의 엔드포인트 URL
    • 기본값: None

  • --endpoint_api_key

    • 목적: 사용자 정의 엔드포인트 API 키
    • 참고: 선택 사항입니다. 지정하지 않으면 gui-agents는 환경 변수의 API 키를 기본값으로 사용합니다.
    • 기본값: None

참고: 구성 2는 구성 1보다 우선 적용됩니다.

이렇게 하면 사용자 쿼리 프롬프트가 표시되며, 여기에 쿼리를 입력하고 Agent S2와 상호작용할 수 있습니다. models.md에 나열된 지원 모델 중 어떤 모델이든 사용할 수 있습니다.

gui_agents SDK

먼저 필요한 모듈을 임포트합니다. AgentS2는 Agent S2의 주요 에이전트 클래스입니다. OSWorldACI는 에이전트 동작을 실행 가능한 파이썬 코드로 변환하는 그라운딩 에이전트입니다.

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"

다음으로 엔진 파라미터를 정의합니다. engine_params는 메인 에이전트에 사용되며, engine_params_for_grounding은 그라운딩용입니다. engine_params_for_grounding의 경우 Claude, GPT 시리즈, 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
}

그런 다음 그라운딩 에이전트와 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"
)

마지막으로 에이전트에 쿼리를 보내봅시다!

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

추론 루프 작동 방식에 대한 자세한 내용은 gui_agents/s2/cli_app.py를 참조하세요.

지식 베이스 다운로드

Agent S2는 추론 중에 새로운 지식으로 지속적으로 업데이트되는 지식 베이스를 사용합니다. 지식 베이스는 AgentS2 초기화 시 처음 다운로드됩니다. 지식 베이스는 GitHub Releases에 에셋으로 저장되어 있습니다. AgentS2 초기화는 지정한 플랫폼과 에이전트 버전(예: s1, s2)에 대한 지식 베이스만 다운로드합니다. 프로그래밍 방식으로 지식 베이스를 다운로드하려면 다음 코드를 사용할 수 있습니다:

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

이 코드는 릴리스 태그 v0.2.2에서 Linux용 Agent S2 지식 베이스를 kb_data 디렉토리에 다운로드합니다. 지식 베이스가 포함된 릴리스 태그나 GitHub Releases를 참조하세요.

OSWorld

OSWorld에서 Agent S2를 배포하려면 OSWorld Deployment instructions를 따라주세요.

WindowsAgentArena

Agent S2를 WindowsAgentArena에 배포하려면 WindowsAgentArena 배포 가이드를 따라주세요.

💬 인용

이 코드베이스가 유용하다고 생각되시면 인용해 주세요

@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 History Chart