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

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

Инструмент использования компьютера — это определённый Anthropic клиентский набор инструментов («client toolset»): одна запись {"type": "computer_toolset_20260801"} в tools даёт Claude 17 инструментов-членов, таких как screenshot, left_click, type и zoom, а ваше приложение выполняет каждый вызов в среде, которую вы контролируете. В настоящее время он недоступен в Claude Managed Agents. Вызовы Claude представляют собой блоки tool_use, у которых name — это имя члена и которые содержат "toolset_name": "computer", часто по несколько за ход (пакетное действие).

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

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

Использование компьютера несёт уникальные риски, отличные от стандартных функций API. Эти риски возрастают при взаимодействии с интернетом.

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

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

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

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

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

Добавьте набор инструментов использования компьютера в массив tools запроса Messages API в виде {"type": "computer_toolset_20260801"}. Запросу не нужен бета-заголовок. В этом примере также объявляются инструмент текстового редактора и инструмент bash, которые Claude обычно использует вместе с использованием компьютера:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {"type": "computer_toolset_20260801"},
        {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "name": "bash"},
    ],
    messages=[{"role": "user", "content": "Save a picture of a cat to my desktop."}],
)
print(response)

Когда Claude действует на рабочем столе, ответ имеет stop_reason со значением tool_use и содержит один или несколько блоков tool_use членов, каждый из которых называет инструмент-член и содержит "toolset_name": "computer". В середине выполнения этой задачи, после того как Claude увидел снимок экрана рабочего стола, ответ может выглядеть так:

{
  "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the web browser to find a picture of a cat."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [512, 742] }
    },
    {
      "type": "tool_use",
      "id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

Ваше приложение выполняет каждый вызов по порядку в вашей собственной среде, возвращает по одному блоку tool_result на каждый блок tool_use и снова вызывает API; раздел Как работает использование компьютера описывает этот цикл, а остальная часть этой страницы показывает, как его реализовать.

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

1. 1

   Предоставьте Claude инструмент использования компьютера и пользовательскую подсказку

   • Добавьте набор инструментов использования компьютера (и, при необходимости, другие инструменты) в массив tools вашего запроса к API.
   • Включите пользовательскую подсказку, требующую взаимодействия с рабочим столом, например: «Сохрани картинку с котом на мой рабочий стол».
2. 2

   Claude отвечает вызовами инструментов-членов

   • Claude оценивает, могут ли действия на рабочем столе помочь с запросом пользователя.
   • Если да, Claude отвечает одним или несколькими блоками tool_use членов, такими как screenshot, left_click или type, каждый из которых содержит "toolset_name": "computer". Ответ с несколькими такими блоками является пакетным действием.
   • Ответ API имеет stop_reason со значением tool_use, что сигнализирует о запросе на использование инструментов.
3. 3

   Выполните вызовы по порядку и верните результаты

   • Переберите все блоки tool_use в ответе по порядку. Для каждого из них выполните диспетчеризацию по name члена вместе с toolset_name и выполните это действие с input блока в вашем контейнере или виртуальной машине.
   • Продолжите разговор новым сообщением user, содержащим по одному блоку tool_result на каждый блок tool_use, сопоставленному по tool_use_id, причём каждый из них повторяет "toolset_name": "computer". Верните изображение для screenshot и zoom; для остальных действий достаточно короткого текста, например OK.
   • Если действие завершилось неудачей, верните is_error: true для этого блока и ответьте на остальную часть пакета, как описано в разделе Пакетные действия.
4. 4

   Claude продолжает, пока задача не будет выполнена

   • Claude анализирует результаты инструментов, чтобы определить, нужны ли дополнительные действия или задача выполнена.
   • Если Claude определяет, что нужны дополнительные действия, он отвечает ещё одним stop_reason со значением tool_use, и вам следует вернуться к шагу 3.
   • В противном случае он возвращает текстовый ответ пользователю.

Повторение шагов 3 и 4 без участия пользователя называется «agent loop» (агентным циклом) — то есть Claude отвечает запросом на использование инструментов, а ваше приложение отвечает Claude результатами выполнения этого запроса.

Пакетные действия

Claude может спланировать короткую последовательность действий, например щёлкнуть, ввести текст, а затем сделать снимок экрана, и вернуть их вместе в одном ответе. Это называется «batch action» (пакетным действием); оно использует ту же форму ответа, что и параллельное использование инструментов, с одним отличием: вы выполняете блоки по порядку, а не одновременно.

Ответ с пакетом из трёх действий выглядит так:

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [640, 60] }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "name": "type",
      "toolset_name": "computer",
      "input": { "text": "pictures of cats" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ]
}

Верните по одному блоку tool_result на каждый блок tool_use, сопоставленному по tool_use_id, все в следующем сообщении user. Каждый результат для инструмента-члена должен содержать "toolset_name": "computer"; результат, в котором он опущен или в котором указан другой набор инструментов, чем в его блоке tool_use, отклоняется. Изображение нужно только для результатов screenshot и zoom; для остальных членов достаточно короткого текстового подтверждения, например OK (cursor_position возвращает координаты в виде текста):

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "toolset_name": "computer",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

Выполняйте блоки по порядку и останавливайтесь при первой ошибке. Последующие действия в пакете обычно зависят от предыдущих: type в этом примере вводит текст в то, на чём сфокусировался предшествующий щелчок. Выполняйте блоки последовательно в том порядке, в котором они появляются в content, и если один из них завершается неудачей, не выполняйте остальные. Каждому блоку tool_use по-прежнему нужен tool_result, поэтому ответьте на пакет следующим образом:

• Для каждого успешно выполненного действия верните его обычный результат.
• Для действия, завершившегося неудачей, верните is_error: true с текстовым описанием того, что пошло не так.
• Для каждого последующего действия в пакете верните is_error: true ровно с этим текстом (инструмент использования браузера использует собственный текст остановки):

{
  "type": "tool_result",
  "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}

Затем Claude видит, какие действия выполнены успешно, какое завершилось неудачей и какие были пропущены, и перепланирует на следующем ходу. Запрос, оставляющий без ответа любой блок tool_use в пакете, отклоняется с ошибкой invalid_request_error, поэтому агентный цикл, который читает только первый блок, завершится ошибкой при следующем вызове. Если ваше приложение просит человека подтверждать значимые действия, выполняйте эту проверку перед запуском каждого блока, поскольку пакет может завершить многошаговое действие в рамках одного хода.

Claude обычно завершает пакет действием screenshot, чтобы увидеть результат, прежде чем решить, что делать дальше. Когда пакет не заканчивается им, ваше приложение может прикрепить снимок экрана в виде дополнительного блока image к последнему результату в пакете, чтобы Claude всегда видел текущее состояние экрана, что экономит один цикл обмена по сравнению с ожиданием запроса от 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 с соответствующими сопоставлениями портов для просмотра среды и взаимодействия с ней.

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

Обновляете существующую интеграцию computer_20251124? Начните с раздела Миграция с computer_20251124; остальная часть этого раздела применима как к новым, так и к перенесённым интеграциям.

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

Ядро использования компьютера — это «агентный цикл»: цикл, в котором Claude запрашивает действия инструментов, ваше приложение выполняет их и возвращает результаты Claude. Цикл использует клиент, созданный вами в разделе Быстрый старт, массив tools, объявляющий только набор инструментов использования компьютера, и вспомогательную функцию обработки вызовов инструментов из раздела Реализация инструмента использования компьютера. Если вы также объявляете другие инструменты, например инструменты bash и текстового редактора из раздела «Быстрый старт», обрабатывайте их блоки tool_use в том же проходе; вспомогательная функция отвечает только на вызовы членов использования компьютера, а цикл считает ход без отвеченных вызовов завершённым. Вот упрощённый пример:

def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
        )

        # Добавляем ответ Claude в историю диалога
        messages.append({"role": "assistant", "content": response.content})

        # Выполняем запрошенные Claude действия по порядку и собираем результаты
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

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

    return messages

Цикл продолжается до тех пор, пока 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>. Использование компьютера в приложениях, требующих входа в систему, повышает риск неблагоприятных исходов в результате инъекции подсказок. Ознакомьтесь с разделом Противодействие джейлбрейкам и инъекциям подсказок, прежде чем предоставлять модели учётные данные для входа.
6. При формировании массива content пользовательского хода размещайте текст инструкции перед изображением снимка экрана. Предоставление описания цели до обработки изображения повышает точность щелчков.
7. Claude использует действие zoom для изучения области в полном разрешении, когда его спрашивают о мелком тексте или конкретных элементах интерфейса, которые неразборчивы при стандартном разрешении снимка экрана, например об именах файлов на боковой панели, заголовках вкладок, тексте строки состояния, номерах строк или надписях на кнопках. Если Claude не использует масштабирование, когда вы этого ожидаете, спрашивайте о конкретной области или элементе, а не об экране в целом.
8. Если вы хотите, чтобы каждое пакетное действие заканчивалось снимком экрана, укажите это в системной подсказке, например: End each group of actions with a screenshot so you can verify the result before continuing.

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

Когда вы включаете инструмент использования компьютера в запрос, API генерирует «system prompt» (системную подсказку), специфичную для использования компьютера. Она похожа на системную подсказку использования инструментов, но начинается так:

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

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

Каждое действие является инструментом-членом набора инструментов использования компьютера: Claude называет член в блоке tool_use, содержащем "toolset_name": "computer", а input блока содержит только параметры этого члена, без поля action. Набор инструментов содержит 17 инструментов-членов:

При реализации членов учитывайте следующее:

• Координаты указываются в пикселях снимка экрана. Каждое значение coordinate, start_coordinate и region, а также позиция, которую сообщает cursor_position, находятся в пиксельном пространстве возвращаемых вами снимков всего дисплея с началом координат в верхнем левом углу. Изображения масштабирования этого не меняют: после zoom Claude по-прежнему выражает координаты в пространстве полного снимка экрана, никогда не относительно увеличенного изображения. Если вы уменьшаете снимки экрана перед возвратом, масштабируйте координаты Claude обратно, прежде чем применять их к реальному дисплею (см. Подбор размера снимков экрана под ограничения изображений).
• Все члены включены по умолчанию, включая zoom. Если ваша среда не может создавать изображения масштабирования, исключите этот член с помощью configs (см. Параметры инструмента), а не оставляйте его включённым и возвращайте ошибки. Если Claude вызывает член, который вы исключили или не реализовали, верните tool_result с is_error: true для этого блока.
• Выполняйте диспетчеризацию по паре (toolset_name, name). Именно toolset_name помечает блок как действие компьютера: пользовательский инструмент в том же запросе может иметь то же имя, что и член, а более поздняя версия набора инструментов может добавить члены (см. Клиентские наборы инструментов).

{
  "type": "tool_use",
  "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300], "text": "shift" }
}

{
  "type": "tool_use",
  "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
  "name": "left_click_drag",
  "toolset_name": "computer",
  "input": {
    "start_coordinate": [200, 300],
    "coordinate": [600, 300]
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
  "name": "scroll",
  "toolset_name": "computer",
  "input": {
    "coordinate": [500, 400],
    "scroll_direction": "down",
    "scroll_amount": 3
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
  "name": "key",
  "toolset_name": "computer",
  "input": { "text": "Tab", "repeat": 4 }
}

{
  "type": "tool_use",
  "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
  "name": "zoom",
  "toolset_name": "computer",
  "input": { "region": [100, 200, 400, 350] }
}

{
  "type": "tool_use",
  "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
  "name": "cursor_position",
  "toolset_name": "computer",
  "input": {}
}

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

Запись набора инструментов в массиве tools принимает четыре параметра; правила, общие с набором инструментов использования браузера, перечислены в разделе Клиентские наборы инструментов.

Например, эта запись исключает zoom для среды, которая его не реализует, и устанавливает точку останова кэша на определении набора инструментов:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}

Если ваш агентный цикл может выполнять только одно действие за цикл обмена, установите disable_parallel_tool_use в true в tool_choice; тогда Claude возвращает не более одного блока tool_use члена за ход (см. Отключение параллельного использования инструментов).

Запись отклоняет следующие параметры из более ранних версий инструмента, и запрос, включающий любой из них, возвращает invalid_request_error:

• name: имена членов фиксированы версией набора инструментов.
• display_width_px, display_height_px и display_number: координаты всегда находятся в пиксельном пространстве возвращаемых вами снимков экрана.
• enable_zoom: масштабирование — это инструмент-член, которым вы управляете через configs.

Запись также нельзя объявлять в одном запросе с записью computer_20251124 или другим инструментом с именем computer. Сведения о strict, input_examples, размещении defer_loading, tool_choice, потоковой передаче и ограничениях вызывающих сторон см. в разделе Клиентские наборы инструментов.

Сочетание с размышлениями

Чтобы сочетать использование компьютера с размышлениями, см. Размышления.

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

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

Для задач, которые не выходят за пределы веб-страниц, вы также можете объявить инструмент использования браузера в том же запросе: два набора инструментов работают независимо, каждый в своей системе координат, а вызовы членов с одинаковыми именами, таких как screenshot или key, различаются по toolset_name.

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

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

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

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

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

1. 1

   Настройте вычислительную среду

   Создайте виртуальный дисплей или подключитесь к существующему дисплею, с которым будет взаимодействовать Claude. Обычно это включает настройку Xvfb (X Virtual Framebuffer) или аналогичной технологии.

2. 2

   Реализуйте обработчики действий

   Создайте функции для обработки каждого типа действия, которое может запросить Claude:

   PythonTypeScriptC#GoJavaPHPRuby

   

   # Данные изображения-заглушки; реальный исполнитель захватывает экран и возвращает байты PNG
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   def capture_screenshot() -> list[ImageBlockParam]:
       # screenshot отвечает блоком изображения, а не текстом: возвращаем список содержимого результата
       return [
           {
               "type": "image",
               "source": {"type": "base64", "media_type": "image/png", "data": PLACEHOLDER_PNG},
           }
       ]
   
   
   def click(coordinate=None):
       if coordinate is None:
           return "clicked at current cursor"
       x, y = coordinate
       return f"clicked at ({x}, {y})"
   
   
   def type_text(text):
       return f"typed: {text}"
   
   
   def handle_computer_action(name, tool_input):
       match name:
           case "screenshot":
               return capture_screenshot()
           case "left_click":
               # coordinate необязателен; без него щелчок выполняется там, где уже находится курсор
               return click(tool_input.get("coordinate"))
           case "type":
               return type_text(tool_input["text"])
       # Обрабатывайте другие действия по мере необходимости
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   Обработайте вызовы инструментов Claude

   Извлеките и выполните вызовы инструментов из ответов Claude:

   PythonTypeScriptC#GoJavaPHPRuby

   

   NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
   
   
   def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
       """
       Run the computer actions in Claude's response in order and answer each
       one. After the first failure the rest are skipped, because Claude planned
       them assuming the earlier actions succeeded.
       """
       tool_results: list[ToolResultBlockParam] = []
       failed = False
       for block in response.content:
           # Объявлен только набор инструментов computer; направляйте сюда другие инструменты, если добавите их
           if block.type != "tool_use" or block.toolset_name != "computer":
               continue
           result: ToolResultBlockParam = {
               "type": "tool_result",
               "tool_use_id": block.id,
               "toolset_name": "computer",
           }
           if failed:
               result["content"] = NOT_EXECUTED
               result["is_error"] = True
           else:
               try:
                   # Строка или список блоков содержимого, например изображение скриншота
                   result["content"] = handle_computer_action(block.name, block.input)
               except Exception as err:
                   result["content"] = f"Error: {err}"
                   result["is_error"] = True
                   failed = True
           tool_results.append(result)
       return tool_results

4. 4

   Реализуйте агентный цикл

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

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

Сообщайте Claude о неудавшемся действии в виде tool_result с is_error: true и кратким описанием и включайте "toolset_name": "computer", как и в любом другом результате члена. Если неудавшееся действие было частью пакетного действия, ответьте на оставшиеся блоки в пакете показанным там текстом остановки вместо их выполнения.

Например, когда захват снимка экрана завершается неудачей:

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

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

Подбор размера снимков экрана под ограничения изображений

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

Если ваш экран больше ограничения, изменяйте размер каждого снимка экрана перед возвратом и масштабируйте возвращаемые Claude координаты обратно в исходное пространство экрана. Поскольку набор инструментов не принимает размеры дисплея, изменение размера и масштабирование координат в коде вашего приложения — это всё, что вам нужно:

import math

screen_width, screen_height = 1512, 982


def get_scale_factor(width, height):
    """Calculate scale factor to meet API constraints."""
    long_edge = max(width, height)
    total_pixels = width * height

    long_edge_scale = 1568 / long_edge
    total_pixels_scale = math.sqrt(1_150_000 / total_pixels)

    return min(1.0, long_edge_scale, total_pixels_scale)


# При захвате снимка экрана
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Измените размер изображения до масштабированных размеров перед отправкой в Claude
screenshot = capture_and_resize(scaled_width, scaled_height)


# При обработке координат от Claude масштабируйте их обратно
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

Когда вы выбираете разрешение дисплея и возвращаете снимки экрана:

• Для общих задач рабочего стола используйте 1024x768 или 1280x720; для веб-приложений используйте 1280x800 или 1366x768.
• Избегайте разрешений выше 1920x1080, чтобы предотвратить проблемы с производительностью.
• Кодируйте снимки экрана в base64 PNG или JPEG и рассмотрите сжатие больших снимков экрана для повышения производительности.
• Включайте соответствующие метаданные, такие как временная метка или состояние дисплея.
• Если вы используете более высокие разрешения, убедитесь, что координаты точно масштабируются.

Управление историей скриншотов

Длинные агентные циклы быстро накапливают скриншоты (примерно 1 000–1 800 входных токенов каждый). Также применяются ограничения запросов API. Как только один запрос содержит более 20 изображений, к каждому изображению в нём применяется более строгое ограничение на размер стороны. Цикл, сохраняющий историю скриншотов, достигает этого количества за несколько десятков ходов, поэтому либо изменяйте размер каждого скриншота так, чтобы ни одна сторона не превышала 2000 px, либо удаляйте старые скриншоты, чтобы в запросе оставалось не более 20.

Чтобы кэширование подсказок (prompt caching) оставалось эффективным при ограничении контекста:

• Разместите одну точку останова («breakpoint») cache_control после системной подсказки и определений инструментов. Ещё до трёх точек разместите на последнем блоке tool_result каждого из самых последних ходов и сдвигайте их на каждом ходу. В рамках пакетного действия маркеры на нескольких блоках действуют как одна точка останова, но каждый из них всё равно учитывается в лимите из четырёх, поэтому используйте по одному маркеру на ход.
• Удаляйте старые снимки экрана пакетами, а не по одному на каждом ходу. Удаление снимка на каждом ходу каждый раз меняет префикс и делает кэш недействительным. Разумное значение по умолчанию — хранить последние три снимка и выполнять удаление каждые 25 ходов, чтобы префикс оставался побайтово идентичным между удалениями. Если ваши снимки превышают 2000 px по любой из сторон, выберите интервал, при котором каждый запрос содержит не более 20 изображений.
• При работе с Claude Fable 5.1, Claude Opus 5.5 и Claude Sonnet 5.5 избегайте удаления снимков на стороне клиента: удаление более раннего снимка экрана делает недействительными все последующие блоки «thinking» (размышлений) в каждом запросе, который всё ещё содержит эти ходы. Вместо этого уменьшайте снимки экрана до 2000 px или меньше по каждой стороне и используйте серверную очистку результатов инструментов, чтобы убирать старые снимки из контекста. Если удаление всё же необходимо, с этого момента всегда задавайте prefix_mismatch_behavior: "drop_block". После каждого удаления Claude продолжает работу без размышлений, созданных после удалённого снимка, — в этом запросе и во всех последующих. В Claude Sonnet 5.5 block_binding работает только с thinking: {"type": "adaptive"}. При between_tools только добавляйте записи в историю, не изменяя существующие, либо удаляйте блоки размышлений начиная с отредактированного хода.

Диагностика проблем с кликами

Если клики не попадают в цель, причина обычно одна из следующих:

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

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Allow UI to update

display_width, display_height = 1024, 768


def validate_action(action_type, params):
    if action_type == "left_click" and "coordinate" in params:
        x, y = params["coordinate"]
        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}")

Миграция с computer_20251124

Переход с computer_20251124 на набор инструментов необязателен: модели, перечисленные для computer_20251124 в разделе Более ранние версии инструмента, продолжают принимать его с соответствующим бета-заголовком, поэтому существующая интеграция продолжит работать, пока вы её не измените. Исключение составляют модели Claude 5.5 и более поздние в Claude API и Google Cloud: там они принимают только набор инструментов. Обновите интеграцию, прежде чем переводить её на одну из этих моделей. В Amazon Bedrock Claude Opus 5.5 и Claude Sonnet 5.5 по-прежнему принимают computer_20251124. Для обновления внесите следующие изменения одновременно:

1. Удалите бета-заголовок. Уберите anthropic-beta: computer-use-2025-11-24 из ваших запросов. В SDK удалите параметр betas и вызывайте Messages API через стандартный клиент, а не через пространство имён beta.
2. Измените запись tools. Установите type в computer_toolset_20260801 и удалите name, display_width_px, display_height_px, display_number и enable_zoom. Набор инструментов отклоняет каждое из этих полей.
3. Решите, оставлять ли zoom включённым. В наборе инструментов zoom включён по умолчанию, тогда как enable_zoom по умолчанию равен false. Если ваша среда не реализует zoom, добавьте "configs": {"zoom": {"enabled": false}}, чтобы сохранить прежнее поведение; в противном случае реализуйте его (см. Доступные действия).
4. Обрабатывайте каждый блок в ходе. Обновите ваш агентный цикл так, чтобы он перебирал каждый блок tool_use в ответе, а не читал только первый, и выполнял диспетчеризацию по name блока вместе с toolset_name, а не по input.action. Входные данные элементов больше не содержат поля action; остальные поля не изменились.
5. Выполняйте блоки по порядку и используйте текст остановки. Выполняйте блоки последовательно, останавливайтесь при первой ошибке и отвечайте на оставшиеся блоки текстом Not executed: an earlier computer action in this turn failed., как описано в разделе Пакетные действия. Если ваш цикл пока не может выполнять пакеты, в разделе Параметры инструмента объясняется, как ограничить Claude одним действием за ход.
6. Возвращайте toolset_name в результатах. Добавьте "toolset_name": "computer" в каждый tool_result, отвечающий на вызов элемента. Результаты могут содержать только содержимое text и image.
7. Поддерживайте repeat для key. Элемент key принимает необязательный счётчик repeat от 1 до 100. Обработчик, игнорирующий нераспознанные поля, нажал бы клавишу один раз, поэтому сделайте так, чтобы ваш обработчик key учитывал repeat.
8. Изменяйте размер скриншотов самостоятельно. Набор инструментов отклоняет скриншот или изображение zoom, превышающее ограничения изображений модели, вместо того чтобы уменьшать его. Изменяйте размер перед возвратом изображения и продолжайте масштабировать координаты, как описано в разделе Подбор размера скриншотов под ограничения изображений.
9. Удалите неподдерживаемые параметры. Перенесите любой defer_loading из записи в configs с одинаковым значением для каждого включённого элемента. Остальные параметры, не поддерживаемые в записях набора инструментов, перечислены в разделе Клиентские наборы инструментов.

Вот запись tools до изменения, отправляемая с заголовком anthropic-beta: computer-use-2025-11-24:

{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}

Вот запись tools после изменения, отправляемая без бета-заголовка. Объект configs оставляет zoom выключенным, чтобы соответствовать прежней записи, в которой enable_zoom не задан; полностью опустите configs, чтобы принять значение по умолчанию и позволить Claude использовать zoom:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  }
}

Следующая пара показывает блок tool_use до и после изменения. Имя действия перемещается из input.action в name, а блок получает toolset_name:

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "computer",
  "input": { "action": "left_click", "coordinate": [500, 300] }
}

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300] }
}

Более ранние версии инструмента

Две более ранние версии инструмента использования компьютера остаются доступными в бета-версии для существующих интеграций, для моделей, не поддерживающих набор инструментов, и на платформах, где набор инструментов в настоящее время недоступен. Каждая требует своего бета-заголовка в каждом запросе, а их параметры задокументированы в справочнике beta Messages API. В SDK передавайте заголовок через параметр betas и используйте пространство имён beta; заголовок нужен только инструменту использования компьютера, а не инструментам bash или текстового редактора в том же запросе.

Ограничения

1. Задержка: Текущая задержка использования компьютера при взаимодействии человека и ИИ может быть слишком велика по сравнению с обычными действиями на компьютере, выполняемыми человеком. Сосредоточьтесь на сценариях, где скорость не критична (например, фоновый сбор информации, автоматизированное тестирование программного обеспечения), в доверенных средах.
2. Точность и надёжность компьютерного зрения: Claude может ошибаться или галлюцинировать при выводе конкретных координат во время генерации действий. Вывод суммаризированных размышлений Claude может помочь вам понять рассуждения модели и выявить потенциальные проблемы; установите display: "summarized" в конфигурации размышлений, поскольку модели, поддерживающие набор инструментов, по умолчанию опускают текст размышлений.
3. Точность и надёжность выбора инструментов: Claude может ошибаться или галлюцинировать при выборе инструментов во время генерации действий либо предпринимать неожиданные действия для решения проблем. Кроме того, надёжность может быть ниже при взаимодействии с нишевыми приложениями или несколькими приложениями одновременно. Тщательно формулируйте подсказки для модели при запросе сложных задач.
4. Надёжность прокрутки: Действие прокрутки поддерживает управление направлением (вверх, вниз, влево, вправо) и заданную величину. В приложениях, где прокрутка не срабатывает, могут помочь клавиатурные альтернативы, такие как Page Down.
5. Взаимодействие с электронными таблицами: Используйте действия точного управления мышью (left_mouse_down, left_mouse_up) и комбинации с клавишами-модификаторами для выбора отдельных ячеек. Сложные операции с электронными таблицами всё ещё могут требовать нескольких попыток.
6. Создание учётных записей и генерация контента на социальных и коммуникационных платформах: Хотя Claude посещает веб-сайты, его способность создавать учётные записи, генерировать и публиковать контент или иным образом выдавать себя за человека на сайтах и платформах социальных сетей ограничена.
7. Уязвимости: Джейлбрейки и инъекции подсказок могут влиять на использование компьютера, как и на любую передовую систему ИИ, в том числе через инструкции, встроенные в веб-страницы или изображения; применяйте меры предосторожности из раздела Соображения безопасности.
8. Неприемлемые или незаконные действия: В соответствии с Условиями обслуживания Anthropic вы не должны применять использование компьютера для нарушения каких-либо законов или Политики допустимого использования.

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

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

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

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

Цены

Использование компьютера следует стандартному ценообразованию на использование инструментов. При использовании инструмента для работы с компьютером:

Накладные расходы на определение набора инструментов: Объявление computer_toolset_20260801 с его членами по умолчанию добавляет к запросу около 4 500 входных токенов (около 4 520 на Claude Fable 5, Claude Mythos 5, Claude Opus 5 и Claude Opus 4.8 и около 4 590 на Claude Sonnet 5), что покрывает определения входящих в набор инструментов и системную подсказку для использования инструментов. Отключение zoom с помощью configs убирает около 410 из этих токенов. Точное количество для запроса сообщается в поле usage ответа, и вы можете оценить его заранее с помощью конечной точки подсчёта токенов.

Более ранние версии инструмента: Следующие цифры относятся к версиям инструмента computer_20251124 и computer_20250124, а не к computer_toolset_20260801:

• Накладные расходы на системную подсказку: 466–499 токенов, добавляемых к системной подсказке
• Определение инструмента: около 735 входных токенов на одно определение инструмента (измерено с computer_20250124)

Дополнительное потребление токенов:

• Снимки экрана и увеличенные изображения, возвращаемые в результатах инструментов, тарифицируются как входные изображения (см. ценообразование Vision)
• Результаты выполнения инструментов, возвращаемые Claude

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

Compatibility