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

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

Обзор

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

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

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

Для поддержки моделей см. Справочник инструментов.

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

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

В некоторых обстоятельствах 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
• Реализации инструментов компьютерного взаимодействия
• Цикл агента, который взаимодействует с Claude API и выполняет инструменты компьютерного взаимодействия
• Веб-интерфейс для взаимодействия с контейнером, циклом агента и инструментами.

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

Основой компьютерного взаимодействия является "цикл агента" - цикл, в котором 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,  # Add iteration limit to prevent infinite loops
):
    """
    A simple agent loop for Claude computer use interactions.

    This function handles the back-and-forth between:
    1. Sending user messages to Claude
    2. Claude requesting to use tools
    3. Your app executing those tools
    4. Sending tool results back to Claude
    """
    # Set up tools and API parameters
    client = Anthropic(api_key=api_key)
    beta_flag = (
        "computer-use-2025-11-24"
        if "20251124" in tool_version
        else "computer-use-2025-01-24"
    )
    text_editor_type = (
        "text_editor_20250728"
        if "20251124" in tool_version
        else f"text_editor_{tool_version}"
    )

    # Configure tools - you should already have these initialized elsewhere
    tools = [
        {
            "type": f"computer_{tool_version}",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        },
        {"type": text_editor_type, "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "name": "bash"},
    ]

    # Main agent loop (with iteration limit to prevent runaway API costs)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Set up optional thinking parameter (for Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # Call the Claude API
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking,
        )

        # Add Claude's response to the conversation history
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Check if Claude used any tools
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # In a real app, you would execute the tool here
                # For example: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Format the result for Claude
                tool_results.append(
                    {"type": "tool_result", "tool_use_id": block.id, "content": result}
                )

        # If no tools were used, Claude is done - return the final messages
        if not tool_results:
            return messages

        # Add tool results to messages for the next iteration with Claude
        messages.append({"role": "user", "content": tool_results})

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

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

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

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

1. Укажите простые, четко определенные задачи и предоставьте явные инструкции для каждого шага.
2. Claude иногда предполагает результаты своих действий без явной проверки их результатов. Чтобы предотвратить это, вы можете подсказать Claude с помощью After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. Explicitly show your thinking: "I have evaluated step X..." If not correct, try again. Only when you confirm a step was executed correctly should you move on to the next one.
3. Некоторые элементы пользовательского интерфейса (такие как раскрывающиеся списки и полосы прокрутки) могут быть сложными для Claude при манипулировании с помощью движений мыши. Если вы столкнулись с этим, попробуйте подсказать модели использовать сочетания клавиш.
4. Для повторяемых задач или взаимодействий пользовательского интерфейса включите примеры скриншотов и вызовов инструментов успешных результатов в вашу подсказку.
5. Если вам нужно, чтобы модель вошла в систему, предоставьте ей имя пользователя и пароль в вашей подсказке внутри тегов xml, таких как <robot_credentials>. Использование компьютерного взаимодействия в приложениях, требующих входа, увеличивает риск плохих результатов из-за инъекции подсказок. Перед предоставлением модели учетных данных для входа ознакомьтесь с руководством по смягчению инъекций подсказок.

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

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

You have access to a set of functions you can use to answer the user's question. This includes access to a sandboxed computing environment. You do NOT currently have the ability to inspect files or interact with external resources, except by invoking the below functions.

Как и при обычном использовании инструмента, поле 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 Sonnet 4.6 и Claude Opus 4.5:

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

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

Комбинирование с расширенным мышлением

Для комбинирования компьютерного взаимодействия с расширенным мышлением см. Расширенное мышление.

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

Чтобы добавить другие инструменты наряду с компьютерным взаимодействием, включите их в тот же массив tools. Приведенный выше быстрый старт показывает этот паттерн с инструментом bash и инструментом текстового редактора. Вы можете добавить свои собственные определения пользовательских инструментов таким же образом.

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

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

• Виртуализированная или контейнеризированная среда, подходящая для компьютерного использования с Claude
• Реализация по крайней мере одного из инструментов компьютерного использования схемы Anthropic
• Цикл агента, который взаимодействует с Claude API и выполняет результаты 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 для задач, требующих идеальной точности или чувствительной информации пользователя без надзора человека.

Хранение данных

Компьютерное использование — это инструмент на стороне клиента. Все скриншоты, действия мыши, вводы с клавиатуры и любые файлы, участвующие в сеансе, захватываются и хранятся в вашей среде, а не Anthropic. Anthropic обрабатывает изображения скриншотов и запросы действий в реальном времени как часть вызова API, но не сохраняет их после возврата ответа.

Поскольку ваше приложение контролирует, где и как хранятся данные компьютерного использования, компьютерное использование имеет право на ZDR. Для приемлемости ZDR по всем функциям см. API и хранение данных.

Цены

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

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