simular-ai/Agent-S

🌐 [S3 blog] 📄 [S3 Paper] 🎥 [S3 Video]

🌐 [S2 blog] 📄 [S2 Paper (COLM 2025)] 🎥 [S2 Video]

🌐 [S1 blog] 📄 [S1 Paper (ICLR 2025)] 🎥 [S1 Video]

2025/12/15: Agent S3는 OSWorld에서 **72.60%**라는 인상적인 점수로 인간 수준의 성능을 뛰어넘은 최초의 모델입니다! -
2025/10/02: Agent S3와 기술 논문을 출시하여 OSWorld에서 **69.9%**의 새로운 SOTA(State-of-the-Art)를 기록했으며(인간 성능인 72%에 근접), WindowsAgentArena 및 AndroidWorld에서 강력한 일반화 성능을 보여주었습니다! 또한 더 단순하고, 빠르며, 유연합니다! -
2025/08/01: Agent S2.5가 출시되었습니다 (gui-agents v0.2.5): 더 단순하고, 더 뛰어나며, 더 빠릅니다! OSWorld-Verified에서 새로운 SOTA를 달성했습니다! -
2025/07/07: Agent S2 논문이 COLM 2025에 채택되었습니다! Montreal에서 만납시다! -
2025/04/27: Agent S 논문이 ICLR 2025 Agentic AI for Science Workshop에서 최우수 논문상(Best Paper Award) 🏆을 수상했습니다! -
2025/04/01: OSWorld, WindowsAgentArena, AndroidWorld에서 새로운 SOTA 결과를 담은 Agent S2 논문을 출시했습니다! -
2025/03/12: 컴퓨터 사용 에이전트 (CUA, Computer Use Agents)의 새로운 SOTA인 gui-agents v0.2.0과 함께 Agent S2를 출시했습니다. 이는 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 논문과 코드베이스를 출시했습니다!

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

AI, 자동화, 또는 최첨단 에이전트 기반 시스템에 기여하는 것에 관심이 있다면, 여러분과 함께하게 되어 기쁩니다!

OSWorld에서 Agent S3 단독으로 100-step 설정 시 66%에 도달하며, 기존의 최고 성능(State-of-the-art, SOTA)인 63.4%(GTA1 w/ GPT-5)를 이미 넘어섰습니다. Behavior Best-of-N을 추가하면 성능은 72.6%까지 더욱 상승하며, 이는 OSWorld에서의 인간 수준 성능(~72%)을 능가하는 수치입니다!

Agent S3는 강력한 제로샷 일반화 (Zero-shot Generalization) 능력도 보여줍니다! WindowsAgentArena에서 Agent S3만 사용했을 때의 정확도는 50.2%였으나, 3개의 롤아웃 (Rollouts) 중에서 선택함으로써 56.6%로 상승했습니다. 마찬가지로 AndroidWorld에서도 성능이 68.1%에서 71.6%로 향상되었습니다.

단일 모니터: 저희 에이전트는 단일 모니터 화면을 위해 설계되었습니다.
보안: 에이전트는 컴퓨터를 제어하기 위해 Python 코드를 실행합니다 - 주의해서 사용하십시오.
지원 플랫폼: Linux, Mac, Windows

저장소(Repository)를 클론(Clone)하지 않고 Agent S3를 설치하려면 다음을 실행하세요:

pip install gui-agents

변경 사항을 적용하면서 Agent S3를 테스트하고 싶다면, 저장소를 클론한 후 다음을 사용하여 설치하세요:

pip install -e .

brew install tesseract도 잊지 마세요.

! Pytesseract가 작동하려면 이 추가 설치가 필요합니다.

(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>

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

저희는 Azure OpenAI, Anthropic, Gemini, Open Router 및 vLLM 추론 (Inference)을 지원합니다. 자세한 내용은 models.md를 참조하세요.

최적의 성능을 위해 Hugging Face Inference Endpoints 또는 다른 제공업체에 호스팅된 UI-TARS-1.5-7B 사용을 권장합니다. 설정 지침은 Hugging Face Inference Endpoints를 참조하세요.

⚡️

권장 설정:

최상의 구성을 위해, 메인 모델로 OpenAI gpt-5-2025-08-07을 사용하고, 그라운딩 (Grounding)을 위해 UI-TARS-1.5-7B를 함께 사용하는 것을 권장합니다.

참고: 이는 bBoN 없이 개선된 에이전트인 Agent S3를 실행하는 것입니다.

필요한 파라미터와 함께 Agent S3를 실행하세요:

agent_s \
--provider openai \
--model gpt-5-2025-08-07 \
...

코드 실행(예: 데이터 처리, 파일 조작, 시스템 자동화)이 필요한 작업의 경우, 로컬 코딩 환경(local coding environment)을 활성화할 수 있습니다:

agent_s \
--provider openai \
--model gpt-5-2025-08-07 \
...

경고 (WARNING): 로컬 코딩 환경은 사용자의 머신에서 임의의 Python 및 Bash 코드를 로컬로 실행합니다. 신뢰할 수 있는 환경과 신뢰할 수 있는 입력값에 대해서만 이 기능을 사용하십시오.

--provider: 메인 생성 모델 제공자 (예: openai, anthropic 등) - 기본값: "openai"

--model: 메인 생성 모델 이름 (예: gpt-5-2025-08-07) - 기본값: "gpt-5-2025-08-07"

--ground_provider: 그라운딩 모델 (grounding model)의 제공자

--ground_url: 필수: 그라운딩 모델의 URL

--ground_model: 필수: 그라운딩 모델의 모델 이름

--grounding_width: 필수: 그라운딩 모델의 출력 좌표 해상도 너비

--grounding_height: 필수: 그라운딩 모델의 출력 좌표 해상도 높이

--model_temperature: 필수: 모든 모델 호출에 적용할 온도 (Temperature) (o3와 같은 모델의 경우 1.0으로 설정해야 하지만, 다른 모델의 경우 비워둘 수 있음)

그라운딩 너비와 높이는 사용 중인 그라운딩 모델의 출력 좌표 해상도와 일치해야 합니다:

UI-TARS-1.5-7B: --grounding_width 1920 --grounding_height 1080 사용

UI-TARS-72B: --grounding_width 1000 --grounding_height 1000 사용

--model_url: 메인 생성 모델을 위한 커스텀 API URL - 기본값: ""

--model_api_key: 메인 생성 모델을 위한 API 키 - 기본값: ""

--ground_api_key: 그라운딩 모델 엔드포인트를 위한 API 키 - 기본값: ""

--max_trajectory_length: 궤적(trajectory)에 유지할 이미지 턴(image turns)의 최대 수 - 기본값: 8

--enable_reflection: 워커 에이전트(worker agent)를 보조하기 위한 리플렉션 에이전트(reflection agent) 활성화 - 기본값: True

--enable_local_env: 코드 실행을 위한 로컬 코딩 환경 활성화 (경고: 임의의 코드를 로컬에서 실행함) - 기본값: False

로컬 코딩 환경 (local coding environment)을 사용하면 Agent S3가 사용자의 머신에서 Python 및 Bash 코드를 직접 실행할 수 있습니다. 이는 특히 다음과 같은 작업에 유용합니다:

데이터 처리 (Data Processing): 스프레드시트, CSV 파일 또는 데이터베이스 조작
파일 작업 (File Operations): 대량 파일 처리, 콘텐츠 추출 또는 파일 정리
시스템 자동화 (System Automation): 설정 변경, 시스템 설정 또는 자동화 스크립트
코드 개발 (Code Development): 코드 파일 작성, 편집 또는 실행
텍스트 처리 (Text Processing): 문서 조작, 콘텐츠 편집 또는 포맷팅

이 기능이 활성화되면, 에이전트는 GUI 상호작용 대신 프로그래밍을 통해 완료할 수 있는 작업에 대해 코드 블록을 실행하기 위해 call_code_agent 액션을 사용할 수 있습니다.

요구 사항 (Requirements):

Python: Agent S3를 실행하는 데 사용되는 것과 동일한 Python 인터프리터 (자동 감지됨)
Bash: /bin/bash에서 사용 가능 (macOS 및 Linux 표준)
시스템 권한 (System Permissions): 에이전트는 이를 실행하는 사용자와 동일한 권한으로 실행됩니다

보안 고려 사항 (Security Considerations):

• 로컬 환경은 에이전트를 실행하는 사용자와 동일한 권한으로 임의의 코드를 실행합니다.
• 신뢰할 수 있는 환경에서만 이 기능을 활성화하십시오.
• 에이전트가 시스템 수준의 작업을 위한 코드를 생성할 때는 주의하십시오.
• 신뢰할 수 없는 작업의 경우 샌드박스 (sandboxed) 환경에서 실행하는 것을 고려하십시오.
• Bash 스크립트는 프로세스 중단을 방지하기 위해 30초의 타임아웃 (timeout)과 함께 실행됩니다.

먼저, 필요한 모듈을 임포트(import)합니다. AgentS3는 Agent S3를 위한 메인 에이전트 클래스입니다. OSWorldACI는 에이전트의 행동을 실행 가능한 Python 코드로 변환하는 그라운딩 (grounding) 에이전트입니다.

import pyautogui
import io
from gui_agents.s3.agents.agent_s import AgentS3
...

다음으로, 엔진 파라미터 (engine parameters)를 정의합니다. engine_params는 메인 에이전트용으로 사용되며, engine_params_for_grounding은 그라운딩용으로 사용됩니다. engine_params_for_grounding의 경우, HuggingFace TGI, vLLM, Open Router와 같은 커스텀 엔드포인트 (custom endpoints)를 지원합니다.

engine_params = {
"engine_type": provider,
"model": model,
...

그런 다음, 그라운딩 에이전트와 Agent S3를 정의합니다.

# 선택 사항: 로컬 코딩 환경 활성화
enable_local_env = False # 로컬 코드 실행을 활성화하려면 True로 설정
local_env = LocalEnv() if enable_local_env else None
...

마지막으로, 에이전트(agent)에게 쿼리(query)를 날려봅시다!

# 스크린샷 가져오기.
screenshot = pyautogui.screenshot()
buffered = io.BytesIO()
...

추론 루프(inference loop)가 어떻게 작동하는지에 대한 더 자세한 내용은 gui_agents/s3/cli_app.py를 참조하세요.

OSWorld에서 Agent S3를 배포하려면 OSWorld 배포(Deployment) 지침을 따르세요.

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

@misc{Agent-S3,
title={The Unreasonable Effectiveness of Scaling Agents for Computer Use},
author={Gonzalo Gonzalez-Pumariega and Vincent Tu and Chih-Lun Lee and Jiachen Yang and Ang Li and Xin Eric Wang},
...