Инструмент компьютерного управления

​

Обзор

• Захват скриншотов: Просмотр того, что в настоящее время отображается на экране
• Управление мышью: Клики, перетаскивание и перемещение курсора
• Ввод с клавиатуры: Ввод текста и использование сочетаний клавиш
• Автоматизация рабочего стола: Взаимодействие с любым приложением или интерфейсом

​

Совместимость моделей

​

Соображения безопасности

​

Быстрый старт

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",  # или другая совместимая модель
    max_tokens=1024,
    tools=[
        {
          "type": "computer_20250124",
          "name": "computer",
          "display_width_px": 1024,
          "display_height_px": 768,
          "display_number": 1,
        },
        {
          "type": "text_editor_20250124",
          "name": "str_replace_editor"
        },
        {
          "type": "bash_20250124",
          "name": "bash"
        }
    ],
    messages=[{"role": "user", "content": "Сохраните изображение кошки на мой рабочий стол."}],
    betas=["computer-use-2025-01-24"]
)
print(response)

​

Как работает компьютерное управление

​

Вычислительная среда

1. Виртуальный дисплей: Виртуальный сервер дисплея X11 (использующий Xvfb), который отображает интерфейс рабочего стола, который Claude будет видеть через скриншоты и управлять с помощью действий мыши/клавиатуры.
2. Окружение рабочего стола: Легкий пользовательский интерфейс с менеджером окон (Mutter) и панелью (Tint2), работающий на Linux, который обеспечивает согласованный графический интерфейс для взаимодействия Claude.
3. Приложения: Предустановленные приложения Linux, такие как Firefox, LibreOffice, текстовые редакторы и менеджеры файлов, которые Claude может использовать для выполнения задач.
4. Реализации инструментов: Код интеграции, который переводит абстрактные запросы инструментов Claude (такие как “переместить мышь” или “сделать скриншот”) в фактические операции в виртуальной среде.
5. Цикл агента: Программа, которая обрабатывает связь между Claude и окружением, отправляя действия Claude в окружение и возвращая результаты (скриншоты, выходные данные команд) обратно Claude.

1. Получает запросы на использование инструмента от Claude
2. Переводит их в действия в вашей вычислительной среде
3. Захватывает результаты (скриншоты, выходные данные команд и т. д.)
4. Возвращает эти результаты Claude

​

Как реализовать компьютерное управление

​

Начните с нашей эталонной реализацией

• Контейнеризованная среда, подходящая для компьютерного управления с Claude
• Реализации инструментов компьютерного управления
• Цикл агента, который взаимодействует с API Claude и выполняет результаты tool_use
• Веб-интерфейс для взаимодействия с контейнером, циклом агента и инструментами.

​

Понимание цикла мультиагента

async def sampling_loop(
    *,
    model: str,
    messages: list[dict],
    api_key: str,
    max_tokens: int = 4096,
    tool_version: str,
    thinking_budget: int | None = None,
    max_iterations: int = 10,  # Добавьте ограничение итераций, чтобы предотвратить бесконечные циклы
):
    """
    Простой цикл агента для взаимодействия Claude с компьютерным управлением.

    Эта функция обрабатывает взаимодействие между:
    1. Отправкой сообщений пользователя Claude
    2. Claude запрашивает использование инструментов
    3. Ваше приложение выполняет эти инструменты
    4. Отправкой результатов инструментов обратно Claude
    """
    # Настройка инструментов и параметров API
    client = Anthropic(api_key=api_key)
    beta_flag = "computer-use-2025-01-24" if "20250124" in tool_version else "computer-use-2024-10-22"

    # Настройка инструментов - вы должны уже иметь их инициализированными где-то еще
    tools = [
        {"type": f"computer_{tool_version}", "name": "computer", "display_width_px": 1024, "display_height_px": 768},
        {"type": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "name": "bash"}
    ]

    # Основной цикл агента (с ограничением итераций, чтобы предотвратить неконтролируемые затраты на API)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Настройка необязательного параметра мышления (для Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # Вызов API Claude
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking
        )

        # Добавьте ответ Claude в историю разговора
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Проверьте, использовал ли Claude какие-либо инструменты
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # В реальном приложении вы бы выполнили инструмент здесь
                # Например: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Отформатируйте результат для Claude
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # Если инструменты не использовались, Claude готов - верните финальные сообщения
        if not tool_results:
            return messages

        # Добавьте результаты инструментов в сообщения для следующей итерации с Claude
        messages.append({"role": "user", "content": tool_results})

"betas": ["computer-use-2025-01-24"]

"betas": ["computer-use-2025-01-24"]

​

Оптимизируйте производительность модели с помощью подсказок

1. Укажите простые, четко определенные задачи и предоставьте явные инструкции для каждого шага.
2. Claude иногда предполагает результаты своих действий без явной проверки их результатов. Чтобы предотвратить это, вы можете подсказать Claude с помощью После каждого шага сделайте скриншот и тщательно оцените, достигли ли вы правильного результата. Явно покажите свое мышление: "Я оценил шаг X..." Если это неправильно, попробуйте снова. Только когда вы подтвердите, что шаг был выполнен правильно, переходите к следующему.
3. Некоторые элементы пользовательского интерфейса (такие как раскрывающиеся списки и полосы прокрутки) могут быть сложными для Claude при манипулировании с помощью движений мыши. Если вы столкнетесь с этим, попробуйте подсказать модели использовать сочетания клавиш.
4. Для повторяемых задач или взаимодействий пользовательского интерфейса включите примеры скриншотов и вызовов инструментов успешных результатов в вашу подсказку.
5. Если вам нужно, чтобы модель вошла в систему, предоставьте ей имя пользователя и пароль в вашей подсказке внутри тегов xml, таких как <robot_credentials>. Использование компьютерного управления в приложениях, требующих входа, увеличивает риск плохих результатов из-за внедрения подсказок. Пожалуйста, ознакомьтесь с нашим руководством по смягчению внедрения подсказок перед предоставлением модели учетных данных для входа.

​

Системные подсказки

У вас есть доступ к набору функций, которые вы можете использовать для ответа на вопрос пользователя. Это включает доступ к изолированной вычислительной среде. В настоящее время у вас нет возможности проверять файлы или взаимодействовать с внешними ресурсами, кроме как путем вызова приведенных ниже функций.

​

Доступные действия

• screenshot - Захватить текущий дисплей
• left_click - Щелкнуть по координатам [x, y]
• type - Ввести текстовую строку
• key - Нажать клавишу или комбинацию клавиш (например, “ctrl+s”)
• mouse_move - Переместить курсор на координаты

• scroll - Прокрутить в любом направлении с контролем количества
• left_click_drag - Щелкнуть и перетащить между координатами
• right_click, middle_click - Дополнительные кнопки мыши
• double_click, triple_click - Множественные клики
• left_mouse_down, left_mouse_up - Точное управление кликом
• hold_key - Удерживать клавишу при выполнении других действий
• wait - Пауза между действиями

// Сделать скриншот
{
  "action": "screenshot"
}

// Щелкнуть по позиции
{
  "action": "left_click",
  "coordinate": [500, 300]
}

// Ввести текст
{
  "action": "type",
  "text": "Hello, world!"
}

// Прокрутить вниз (Claude 4/3.7)
{
  "action": "scroll",
  "coordinate": [500, 400],
  "scroll_direction": "down",
  "scroll_amount": 3
}

​

Параметры инструмента

​

Включите возможность мышления в моделях Claude 4 и Claude Sonnet 3.7

"thinking": {
  "type": "enabled",
  "budget_tokens": 1024
}

1. Понять процесс принятия решений модели
2. Выявить потенциальные проблемы или неправильные представления
3. Учиться на подходе Claude к решению проблем
4. Получить больше видимости в сложные многошаговые операции

[Мышление]
Мне нужно сохранить изображение кошки на рабочий стол. Давайте разберем это на шаги:

1. Сначала я сделаю скриншот, чтобы увидеть, что находится на рабочем столе
2. Затем я буду искать веб-браузер для поиска изображений кошек
3. После нахождения подходящего изображения мне нужно будет сохранить его на рабочий стол

Давайте начнем со скриншота, чтобы увидеть, что доступно...

​

Дополнение компьютерного управления другими инструментами

• Выполнять системные команды (инструмент bash)
• Редактировать файлы конфигурации или скрипты (инструмент текстового редактора)
• Интегрироваться с пользовательскими API или сервисами (пользовательские инструменты)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-01-24" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 2000,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      },
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Find flights from San Francisco to a place with warmer weather."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

​

Создайте пользовательскую среду компьютерного управления

• Виртуализированная или контейнеризованная среда, подходящая для компьютерного управления с Claude
• Реализация по крайней мере одного из инструментов компьютерного управления, определенных Anthropic
• Цикл агента, который взаимодействует с API Claude и выполняет результаты tool_use с использованием реализаций вашего инструмента
• API или пользовательский интерфейс, который позволяет вводить данные пользователем для запуска цикла агента

​

Реализуйте инструмент компьютерного управления

def handle_computer_action(action_type, params):
    if action_type == "screenshot":
        return capture_screenshot()
    elif action_type == "left_click":
        x, y = params["coordinate"]
        return click_at(x, y)
    elif action_type == "type":
        return type_text(params["text"])
    # ... обработайте другие действия

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)
        
        # Верните результат Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

while True:
    response = client.beta.messages.create(...)
    
    # Проверьте, использовал ли Claude какие-либо инструменты
    tool_results = process_tool_calls(response)
    
    if not tool_results:
        # Больше нет использования инструментов, задача завершена
        break
        
    # Продолжите разговор с результатами инструментов
    messages.append({"role": "user", "content": tool_results})

​

Обработайте ошибки

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Coordinates (1200, 900) are outside display bounds (1024x768).",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Failed to perform click action. The application may be unresponsive.",
      "is_error": true
    }
  ]
}

​

Следуйте лучшим практикам реализации

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Позвольте пользовательскому интерфейсу обновиться

def validate_action(action_type, params):
    if action_type == "left_click":
        x, y = params.get("coordinate", (0, 0))
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordinates out of bounds"
    return True, None

import logging

def log_action(action_type, params, result):
    logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")

​

Понимание ограничений компьютерного управления

1. Задержка: текущая задержка компьютерного управления для взаимодействия человека и ИИ может быть слишком медленной по сравнению с обычными действиями, направляемыми человеком на компьютере. Мы рекомендуем сосредоточиться на вариантах использования, где скорость не критична (например, сбор справочной информации, автоматизированное тестирование программного обеспечения) в доверенных средах.
2. Точность и надежность компьютерного зрения: Claude может допускать ошибки или галлюцинировать при выводе конкретных координат при создании действий. Claude Sonnet 3.7 вводит возможность мышления, которая может помочь вам понять рассуждение модели и выявить потенциальные проблемы.
3. Точность и надежность выбора инструмента: Claude может допускать ошибки или галлюцинировать при выборе инструментов при создании действий или предпринимать неожиданные действия для решения проблем. Кроме того, надежность может быть ниже при взаимодействии с нишевыми приложениями или несколькими приложениями одновременно. Мы рекомендуем пользователям тщательно подсказывать модель при запросе сложных задач.
4. Надежность прокрутки: Claude Sonnet 3.7 представил выделенные действия прокрутки с управлением направлением, которое улучшает надежность. Модель теперь может явно прокручивать в любом направлении (вверх/вниз/влево/вправо) на указанное количество.
5. Взаимодействие с электронными таблицами: Клики мыши для взаимодействия с электронными таблицами улучшены в Claude Sonnet 3.7 с добавлением более точных действий управления мышью, таких как left_mouse_down, left_mouse_up и новая поддержка клавиш-модификаторов. Выбор ячеек может быть более надежным при использовании этих точных элементов управления и комбинировании клавиш-модификаторов с кликами.
6. Создание учетной записи и создание контента на социальных и коммуникационных платформах: Хотя Claude будет посещать веб-сайты, мы ограничиваем его способность создавать учетные записи или создавать и делиться контентом или иным образом участвовать в выдаче себя за человека на веб-сайтах и платформах социальных сетей. Мы можем обновить эту возможность в будущем.
7. Уязвимости: Уязвимости, такие как взлом или внедрение подсказок, могут сохраняться в системах передовых ИИ, включая бета-API компьютерного управления. В некоторых случаях Claude будет следовать командам, найденным в содержимом, иногда даже в конфликте с инструкциями пользователя. Например, инструкции Claude на веб-страницах или содержащиеся в изображениях могут переопределить инструкции или привести к ошибкам Claude. Мы рекомендуем: a. Ограничить компьютерное управление доверенными средами, такими как виртуальные машины или контейнеры с минимальными привилегиями b. Избегать предоставления доступа компьютерного управления к конфиденциальным учетным записям или данным без строгого надзора c. Информировать конечных пользователей о соответствующих рисках и получать их согласие перед включением или запросом разрешений, необходимых для функций компьютерного управления в ваших приложениях
8. Неправомерные или незаконные действия: В соответствии с условиями обслуживания Anthropic вы не должны использовать компьютерное управление для нарушения каких-либо законов или нашей Политики приемлемого использования.

​

Цены

• Screenshot images (see Vision pricing)
• Tool execution results returned to Claude

​

Следующие шаги