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: Agent S2論文を公開、OSWorld・WindowsAgentArena・AndroidWorldで新たなSOTA結果を達成！
  • 2025/03/12: Agent S2とgui-agents v0.2.0をリリース。コンピュータ利用エージェント(CUA)分野で新たな最先端技術を確立し、OpenAIのCUA/OperatorやAnthropicのClaude 3.7 Sonnet Computer-Useを凌駕！
  • 2025/01/22: Agent S論文がICLR 2025に採録されました！
  • 2025/01/21: gui-agentsライブラリv0.1.2をリリース、LinuxとWindowsをサポート！
  • 2024/12/05: gui-agentsライブラリv0.1.0をリリース、Mac・OSWorld・WindowsAgentArenaで簡単にAgent-Sが利用可能に！
  • 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を使用したWebからの検索設定

Agent SはWeb知識検索と組み合わせることで最高のパフォーマンスを発揮します。この機能を有効にするには、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:ポート番号 の形式で入力します。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 Search API Documentation を参照してください。 より詳細なセットアップと使用ガイドについては、Perplexica Repository をご覧ください。

❗警告❗: このエージェントはコンピュータを制御するために直接Pythonコードを実行します。取り扱いには十分注意してください。

🚀 使用方法

注記: 最適な設定は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
    • デフォルト: なし

  • --endpoint_url

    • 目的: カスタムエンドポイントのURL
    • デフォルト: なし

  • --endpoint_api_key

    • 目的: カスタムエンドポイント用のAPIキー
    • 注記: これはオプションです。指定しない場合、gui-agentsは環境変数からAPIキーを取得します。
    • デフォルト: なし

注意: 設定2は設定1よりも優先されます。

これによりユーザークエリプロンプトが表示され、クエリを入力してAgent S2と対話できます。models.mdに記載されているサポートモデルリストから任意のモデルを使用可能です。

gui_agents SDK

まず必要なモジュールをインポートします。AgentS2はAgent S2のメインエージェントクラスです。OSWorldACIはエージェントのアクションを実行可能なPythonコードに変換するグラウンディングエージェントです。

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 Deployment Instructions に従ってください。

💬 引用文献

このコードベースが役に立った場合は、以下の文献を引用してください

@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