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

Claude может взаимодействовать с компьютерными окружениями через инструмент компьютерного взаимодействия, который предоставляет возможности снятия скриншотов и управления мышью/клавиатурой для автономного взаимодействия с рабочим столом.

Обзор

Компьютерное взаимодействие — это бета-функция, которая позволяет Claude взаимодействовать с окружениями рабочего стола. Этот инструмент предоставляет:

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

Хотя компьютерное взаимодействие может быть дополнено другими инструментами, такими как bash и текстовый редактор для более комплексных рабочих процессов автоматизации, компьютерное взаимодействие конкретно относится к возможности инструмента компьютерного взаимодействия видеть и управлять окружениями рабочего стола.

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

Компьютерное взаимодействие доступно для следующих моделей Claude:

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

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

Вот как начать работу с компьютерным взаимодействием:

Как работает компьютерное взаимодействие

Мы называем повторение шагов 3 и 4 без ввода пользователя "циклом агента" — то есть Claude отвечает запросом использования инструмента, а ваше приложение отвечает Claude результатами оценки этого запроса.

Вычислительное окружение

Компьютерное взаимодействие требует изолированного вычислительного окружения, где Claude может безопасно взаимодействовать с приложениями и веб-сайтами. Это окружение включает:

1. Виртуальный дисплей: Виртуальный сервер дисплея X11 (использующий Xvfb), который отображает интерфейс рабочего стола, который Claude будет видеть через скриншоты и управлять с помощью действий мыши/клавиатуры.

2. Окружение рабочего стола: Легкий пользовательский интерфейс с оконным менеджером (Mutter) и панелью (Tint2), работающий на Linux, который предоставляет согласованный графический интерфейс для взаимодействия Claude.

3. Приложения: Предустановленные приложения Linux, такие как Firefox, LibreOffice, текстовые редакторы и файловые менеджеры, которые Claude может использовать для выполнения задач.

4. Реализации инструментов: Код интеграции, который переводит абстрактные запросы инструментов Claude (такие как "переместить мышь" или "сделать скриншот") в фактические операции в виртуальном окружении.

5. Цикл агента: Программа, которая обрабатывает связь между Claude и окружением, отправляя действия Claude в окружение и возвращая результаты (скриншоты, выходные данные команд) обратно Claude.

Когда вы используете компьютерное взаимодействие, Claude не подключается напрямую к этому окружению. Вместо этого ваше приложение:

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

Для безопасности и изоляции эталонная реализация запускает все это внутри контейнера Docker с соответствующими сопоставлениями портов для просмотра и взаимодействия с окружением.

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

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

Мы создали эталонную реализацию, которая включает все необходимое для быстрого начала работы с компьютерным взаимодействием:

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

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

Основой компьютерного взаимодействия является "цикл агента" — цикл, в котором Claude запрашивает действия инструмента, ваше приложение их выполняет и возвращает результаты Claude. Вот упрощенный пример:

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})

Цикл продолжается до тех пор, пока Claude не ответит без запроса каких-либо инструментов (завершение задачи) или не будет достигнут максимальный предел итераций. Эта защита предотвращает потенциальные бесконечные циклы, которые могут привести к неожиданным затратам на API.

Мы рекомендуем попробовать эталонную реализацию перед чтением остальной части этой документации.

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

Вот несколько советов о том, как получить лучшее качество выходных данных:

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

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

Когда один из инструментов, определенных Anthropic, запрашивается через API Claude, генерируется системная подсказка, специфичная для компьютерного взаимодействия. Она похожа на системную подсказку использования инструмента, но начинается с:

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

Как и при обычном использовании инструментов, поле system_prompt, предоставленное пользователем, по-прежнему соблюдается и используется при построении объединенной системной подсказки.

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

Инструмент компьютерного взаимодействия поддерживает эти действия:

Базовые действия (все версии)

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

Расширенные действия (computer_20250124) Доступны в моделях Claude 4 и Claude Sonnet 3.7:

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

Расширенные действия (computer_20251124) Доступны в Claude Opus 4.5:

• Все действия из computer_20250124
• zoom — Просмотр определенной области экрана в полном разрешении. Требует enable_zoom: true в определении инструмента. Принимает параметр region с координатами [x1, y1, x2, y2], определяющими верхний левый и нижний правый углы области для проверки.

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

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

Claude Sonnet 3.7 представил новую возможность "мышления", которая позволяет вам видеть процесс рассуждения модели при работе над сложными задачами. Эта функция помогает вам понять, как Claude подходит к проблеме, и может быть особенно ценна для отладки или образовательных целей.

Чтобы включить мышление, добавьте параметр thinking в ваш запрос API:

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

Параметр budget_tokens указывает, сколько токенов Claude может использовать для мышления. Это вычитается из вашего общего бюджета max_tokens.

Когда мышление включено, Claude вернет свой процесс рассуждения как часть ответа, что может помочь вам:

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

Вот пример того, как может выглядеть выходные данные мышления:

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

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

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

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

Инструмент компьютерного взаимодействия может быть объединен с другими инструментами для создания более мощных рабочих процессов автоматизации. Это особенно полезно, когда вам нужно:

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

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

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

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

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

Инструмент компьютерного использования реализован как инструмент без схемы. При использовании этого инструмента вам не нужно предоставлять схему ввода, как с другими инструментами; схема встроена в модель Claude и не может быть изменена.

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

При реализации инструмента компьютерного использования могут возникнуть различные ошибки. Вот как их обрабатывать:

Обработка масштабирования координат для более высоких разрешений

API ограничивает изображения максимум 1568 пикселями на самом длинном краю и примерно 1,15 мегапиксела в целом (см. изменение размера изображения для получения подробной информации). Например, экран 1512x982 уменьшается примерно до 1330x864. Claude анализирует это меньшее изображение и возвращает координаты в этом пространстве, но ваш инструмент выполняет клики в исходном пространстве экрана.

Это может привести к тому, что координаты клика Claude не попадут в свои цели, если вы не обработаете преобразование координат.

Чтобы исправить это, измените размер скриншотов самостоятельно и масштабируйте координаты Claude обратно:

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

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

Функциональность компьютерного использования находится в бета-версии. Хотя возможности Claude передовые, разработчики должны знать о её ограничениях:

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 и новая поддержка клавиш-модификаторов. Выбор ячеек может быть более надёжным при использовании этих детальных элементов управления и комбинировании клавиш-модификаторов с кликами.

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

Цены

Computer use follows the standard tool use pricing. When using the computer use tool:

System prompt overhead: The computer use beta adds 466-499 tokens to the system prompt

Computer use tool token usage:

Additional token consumption:

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

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

Мы по-прежнему рекомендуем принять меры предосторожности для изоляции Claude от конфиденциальных данных и действий, чтобы избежать рисков, связанных с внедрением подсказок.

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