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

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

Обзор

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

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

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

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

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

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

Управление компьютером — это бета-функция с уникальными рисками, отличными от стандартных функций 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
• Реализации инструментов управления компьютером
• Цикл агента, который взаимодействует с 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,  # 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"
        if "20250124" in tool_version
        else "computer-use-2024-10-22"
    )

    # 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": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "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, запрашивается через API Claude, генерируется системный промпт, специфичный для управления компьютером. Он похож на системный промпт использования инструментов, но начинается с:

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 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. Получить больше видимости в сложные многошаговые операции

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

[Thinking]
I need to save a picture of a cat to the desktop. Let me break this down into steps:

1. First, I'll take a screenshot to see what's on the desktop
2. Then I'll look for a web browser to search for cat images
3. After finding a suitable image, I'll need to save it to the desktop

Let me start by taking a screenshot to see what's available...

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

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

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

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

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

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