Claude Platform Docs
MessagesИнструменты

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

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

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", часто по несколько за ход (пакетное действие).

SDK для Python и TypeScript включают класс, который передаёт эти вызовы вашему коду рабочего стола и запрашивает подтверждение у вашей функции обратного вызова. См. Использование браузера и компьютера с наборами инструментов SDK.

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

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

Использование компьютера несёт уникальные риски, отличные от стандартных функций 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 увидел снимок экрана рабочего стола, ответ может выглядеть так:

Output
{
  "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. Предоставьте Claude инструмент использования компьютера и пользовательскую подсказку

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

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

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

  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. 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,