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!
  • 2025/03/12: Выпущен Agent S2 вместе с версией v0.2.0 библиотеки gui-agents, устанавливающей новый стандарт для агентов компьютерного взаимодействия (CUA), превосходя OpenAI CUA/Operator и Claude 3.7 Sonnet Computer-Use от Anthropic!
  • 2025/01/22: Статья Agent S принята на ICLR 2025!
  • 2025/01/21: Выпущена версия v0.1.2 библиотеки gui-agents с поддержкой Linux и Windows!
  • 2024/12/05: Выпущена версия v0.1.0 библиотеки gui-agents, позволяющая легко использовать Agent-S для Mac, OSWorld и WindowsAgentArena!
  • 2024/10/10: Опубликованы статья Agent S и исходный код!

Содержание

  1. 💡 Введение
  2. 🎯 Текущие результаты
  3. 🛠️ Установка и настройка
  4. 🚀 Использование
  5. 🤝 Благодарности
  6. 💬 Цитирование

💡 Введение

Добро пожаловать в Agent S — фреймворк с открытым исходным кодом, предназначенный для автономного взаимодействия с компьютерами через Agent-Computer Interface. Наша миссия — создание интеллектуальных GUI-агентов, способных обучаться на прошлом опыте и выполнять сложные задачи на вашем компьютере автономно.

Если вас интересует ИИ, автоматизация или вклад в передовые агентные системы, мы рады видеть вас здесь!

🎯 Текущие результаты


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 эта модель не обязательна — вы можете использовать альтернативные API-модели для визуального заземления, например Claude.

Установка пакета:

pip install gui-agents

Установите ключи API LLM и другие переменные окружения. Это можно сделать, добавив следующую строку в файл .bashrc (Linux) или .zshrc (MacOS).

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 inference. Подробнее см. models.md.

Настройка получения данных из интернета с помощью Perplexica

Agent S работает лучше всего с веб-поиском знаний. Для активации этой функции необходимо настроить Perplexica:

  1. Убедитесь, что Docker Desktop установлен и запущен на вашей системе.

  2. Перейдите в директорию с файлами проекта.

     cd Perplexica
 git submodule update --init

  3. Переименуйте файл sample.config.toml в config.toml. Для настройки Docker необходимо заполнить только следующие поля:

    • OPENAI: Ваш API-ключ OpenAI. Заполняйте это поле только если хотите использовать модели OpenAI.

    • OLLAMA: URL вашего API Ollama. Укажите его в формате http://host.docker.internal:НОМЕР_ПОРТА. Если Ollama установлен на порту 11434, используйте http://host.docker.internal:11434. Для других портов укажите соответствующий номер. Заполняйте это поле, если хотите использовать модели Ollama вместо OpenAI.

    • GROQ: Ваш API-ключ Groq. Заполняйте это поле только если хотите использовать размещённые модели Groq.

    • ANTHROPIC: Ваш API-ключ Anthropic. Заполняйте это поле только если хотите использовать модели Anthropic.

      Примечание: Эти настройки можно изменить позже через диалог настроек после запуска Perplexica.

    • SIMILARITY_MEASURE: Метрика схожести (заполнена по умолчанию; можно оставить без изменений, если не уверены).

  4. Убедитесь, что находитесь в директории с файлом docker-compose.yaml, и выполните:

    docker compose up -d

  5. Экспортируйте URL Perplexica, используя порт из файла docker-compose.yaml. В разделе app/ports указано 3000:3000. Используйте левое число (в данном случае 3000).

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

  6. Наша реализация Agent S интегрирует API Perplexica для добавления функциональности поисковой системы, что обеспечивает более удобный и отзывчивый пользовательский опыт. Если вы хотите адаптировать API под свои настройки и требования, можно изменить URL и параметры запроса в файле agent_s/query_perplexica.py. Подробное руководство по настройке API Perplexica доступно в документации Perplexica Search API.

Для более детального руководства по настройке и использованию обратитесь к репозиторию Perplexica.

❗Внимание❗: Агент будет напрямую выполнять 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
    • По умолчанию: None

Опции конфигурации привязки

Вы можете использовать либо Конфигурацию 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 rescaling
    • Советы: Если ваша привязка неточна даже для очень простых запросов, проверьте, правильно ли указана ширина изменения размера для разрешения вашего экрана.
    • По умолчанию: --grounding_model_resize_width 1366 (Anthropic)
Конфигурация 2: Пользовательский эндпоинт

  • --endpoint_provider

    • Назначение: Указывает провайдера конечной точки
    • Поддерживается: HuggingFace TGI, vLLM, Open Router
    • По умолчанию: None

  • --endpoint_url

    • Назначение: URL вашего пользовательского endpoint
    • По умолчанию: None

  • --endpoint_api_key

    • Назначение: Ваш API-ключ для пользовательского endpoint
    • Примечание: Необязательный параметр. Если не указан, gui-agents будет использовать переменные окружения для API-ключа.
    • По умолчанию: None

Примечание: Конфигурация 2 имеет приоритет над Конфигурацией 1.

Это отобразит приглашение для пользовательского запроса, где вы можете ввести свой вопрос и взаимодействовать с Agent S2. Вы можете использовать любую модель из списка поддерживаемых моделей в models.md.

gui_agents SDK

Сначала импортируем необходимые модули. AgentS2 — это основной класс агента для Agent S2. OSWorldACI — наш grounding-агент, который преобразует действия агента в исполняемый 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 — для 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
}

Далее определяем grounding-агент и 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"
)

Это загрузит базу знаний Agent S2 для Linux из релиза с тегом v0.2.2 в директорию kb_data. См. наши GitHub Releases или теги релизов, включающие базы знаний.

OSWorld

Для развертывания Agent S2 в OSWorld следуйте инструкциям по развертыванию OSWorld.

WindowsAgentArena

Для развертывания агента 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