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

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

Обзор

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

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

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

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

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

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

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

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

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

Мы по-прежнему рекомендуем принять меры предосторожности для изоляции 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
        # Установите необязательный параметр thinking (для 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.6 и Claude Opus 4.5:

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

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

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

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

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

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

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

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

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

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

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

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

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