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

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

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

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



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

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

Каждая версия инструмента основывается на предыдущей:

• code_execution_20250825 поддерживает команды Bash и операции с файлами.
• code_execution_20260120 добавляет сохранение состояния REPL и программный вызов инструментов изнутри песочницы. Claude Haiku 4.5 принимает типы инструментов code_execution_20260120 и code_execution_20260521, но программный вызов инструментов и зависящее от него сохранение состояния REPL на этой модели недоступны, поэтому более новые версии ведут себя там так же, как code_execution_20250825.
• code_execution_20260521 — это та же среда выполнения, что и code_execution_20260120. Разница в том, что описание инструмента сообщает Claude о 90-секундном ограничении реального времени на каждую ячейку Python при программном вызове инструментов, чтобы Claude мог планировать длительно выполняющиеся ячейки. Ячейка, превысившая лимит, возвращает обычный результат выполнения кода с ненулевым return_code и сообщением о статусе detection_timeout в выводе. Это отдельный случай от кода ошибки execution_time_exceeded, который API возвращает, когда весь вызов инструмента превышает максимальное время выполнения.

Все три версии инструмента общедоступны и не требуют заголовка anthropic-beta. Устаревшие бета-заголовки выполнения кода остаются действительными способами включения функции.

В примерах на этой странице используется code_execution_20250825, который охватывает демонстрируемые операции Bash и работу с файлами и ведёт себя одинаково на всех моделях из таблицы; используйте code_execution_20260120 или более позднюю версию, когда вам нужен программный вызов инструментов или сохранение состояния REPL. Текущие инструменты веб-поиска и веб-загрузки (web_search_20260209, web_fetch_20260209 и более поздние) требуют code_execution_20260120 или более поздней версии в качестве версии выполнения кода.



Доступность на платформах

Выполнение кода доступно на:

• Claude API (Anthropic)
• Claude Platform на AWS
• Microsoft Foundry (требуется развёртывание с размещением у Anthropic)

Выполнение кода в настоящее время недоступно на Amazon Bedrock и Google Cloud.



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

Вот пример, в котором Claude просят выполнить вычисление:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Use the code execution tool to calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response.to_json())

В ответе блоки server_tool_use (команды, которые выполнил Claude) чередуются с блоками результатов инструментов, после чего следует текст Claude. На верхнем уровне также присутствует объект container, чей id вы можете повторно использовать между запросами. Структуру блоков см. в разделе Формат ответа.



Как работает выполнение кода

Когда вы добавляете инструмент выполнения кода в свой запрос к API:

1. Claude оценивает, поможет ли выполнение кода ответить на ваш вопрос
2. Инструмент автоматически предоставляет Claude следующие возможности:
   • Команды Bash: запуск команд оболочки для системных операций
   • Операции с файлами: создание, просмотр и редактирование файлов напрямую, включая написание кода
3. Claude может использовать любую комбинацию этих возможностей в одном запросе
4. Все операции выполняются в безопасном изолированном контейнере. У контейнера нет доступа к интернету, поэтому Claude не может загружать пакеты во время выполнения: доступны только предустановленные библиотеки
5. API выполняет каждую команду на стороне сервера и возвращает результаты Claude в рамках того же запроса, поэтому вам никогда не нужно самостоятельно выполнять код или отправлять обратно блоки tool_result. Единственное исключение — когда Claude вызывает один из ваших клиентских инструментов наряду с выполнением кода: API возвращает вызов выполнения кода без его результата. Результат приходит в более позднем ответе, после того как вы отправите обратно блоки tool_result для ваших клиентских инструментов
6. Каждый запрос выполняется в новом контейнере, если только вы не передаёте обратно идентификатор контейнера из предыдущего ответа (см. Повторное использование контейнера)
7. Claude предоставляет результаты вместе со всеми созданными графиками, вычислениями или анализом

В контейнере предустановлен Python. Claude пишет код на Python с помощью подинструмента операций с файлами и запускает его командой Bash. При использовании code_execution_20260120 или более поздней версии вместе с программным вызовом инструментов состояние интерпретатора Python (например, привязки переменных) также сохраняется между запросами, повторно использующими контейнер.



Когда Claude запускает код

Claude запускает код, когда запрос выигрывает от вычислений или обработки файлов:

• Нетривиальная математика (большие числа, много шагов, результаты, чувствительные к точности)
• Анализ данных, разбор файлов или визуализация
• Выполнение алгоритмов или симуляция
• Явные просьбы «запустить», «вычислить» или «выполнить»

Claude отвечает напрямую, не запуская код, в следующих случаях:

• Простая арифметика и общеизвестные математические факты
• Фактологические, разговорные или творческие запросы
• Простые преобразования единиц измерения или переводы

Если вы хотите, чтобы Claude запустил код для пограничного запроса, попросите об этом явно (например, «запусти код, чтобы проверить это»).



Работа с файлами



Загрузка и анализ собственных файлов

Чтобы проанализировать собственные файлы данных (например, CSV, Excel или изображения), загрузите их через Files API и сошлитесь на них в своём запросе:

Среда Python может обрабатывать различные типы файлов, загруженных через Files API, в том числе:

• CSV
• Excel (.xlsx, .xls)
• JSON
• XML
• Изображения (JPEG, PNG, GIF, WebP)
• Текстовые файлы (.txt, .md, .py и другие)



Загрузка и анализ файлов

1. Загрузите файл с помощью Files API
2. Сошлитесь на файл в своём сообщении, используя блок содержимого container_upload
3. Включите инструмент выполнения кода в свой запрос к API

client = anthropic.Anthropic()

# Загрузите файл
file_object = client.beta.files.upload(file=Path("data.csv"))

# Используйте file_id с выполнением кода
response = client.beta.messages.create(
    model="claude-opus-5",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": file_object.id},
            ],
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response.to_json())



Получение созданных файлов

Когда Claude создаёт файлы в ходе выполнения кода, идентификатор каждого созданного файла появляется в результате инструмента выполнения кода, и вы можете скачать его с помощью Files API:

client = Anthropic()

# Запрашиваем выполнение кода, создающего файлы
response = client.beta.messages.create(
    model="claude-opus-5",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a matplotlib visualization and save it as output.png",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)


# Извлекаем идентификаторы файлов из ответа
def extract_file_ids(response: BetaMessage) -> list[str]:
    file_ids: list[str] = []
    for item in response.content:
        if item.type == "bash_code_execution_tool_result":
            content_item = item.content
            if content_item.type == "bash_code_execution_result":
                for output_block in content_item.content:
                    file_ids.append(output_block.file_id)
    return file_ids


# Скачиваем созданные файлы
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id)
    file_content = client.beta.files.download(file_id)
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")



Определение инструмента

Инструмент выполнения кода не требует дополнительных параметров:

{
  "type": "code_execution_20250825",
  "name": "code_execution"
}

Оба поля фиксированы: type выбирает версию инструмента, а name должно быть равно code_execution.

Когда вы предоставляете этот инструмент, Claude автоматически получает доступ к двум подинструментам:

• bash_code_execution: запуск команд оболочки
• text_editor_code_execution: просмотр, создание и редактирование файлов, включая написание кода

Когда Claude запускает код, ответ также содержит объект container верхнего уровня с id контейнера и временной меткой expires_at. Передайте этот идентификатор обратно в параметре запроса верхнего уровня container, чтобы продолжить использовать тот же контейнер. См. Повторное использование контейнера.



Формат ответа

Инструмент выполнения кода может возвращать два типа результатов в зависимости от операции:



Ответ команды Bash

{
  "type": "server_tool_use",
  "id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "name": "bash_code_execution",
  "input": {
    "command": "ls -la | head -5"
  }
},
{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "content": {
    "type": "bash_code_execution_result",
    "stdout": "total 24\ndrwxr-xr-x 2 user user 4096 Jan 1 12:00 .\ndrwxr-xr-x 3 user user 4096 Jan 1 11:00 ..\n-rw-r--r-- 1 user user  220 Jan 1 12:00 data.csv\n-rw-r--r-- 1 user user  180 Jan 1 12:00 config.json",
    "stderr": "",
    "return_code": 0,
    "content": []
  }
}



Ответы операций с файлами

Просмотр файла:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "text_editor_code_execution",
  "input": {
    "command": "view",
    "path": "config.json"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": {
    "type": "text_editor_code_execution_view_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "num_lines": 4,
    "start_line": 1,
    "total_lines": 4
  }
}

Создание файла:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "text_editor_code_execution",
  "input": {
    "command": "create",
    "path": "new_file.txt",
    "file_text": "Hello, World!"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": {
    "type": "text_editor_code_execution_create_result",
    "is_file_update": false
  }
}

Редактирование файла (str_replace):

{
  "type": "server_tool_use",
  "id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "name": "text_editor_code_execution",
  "input": {
    "command": "str_replace",
    "path": "config.json",
    "old_str": "\"debug\": true",
    "new_str": "\"debug\": false"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "content": {
    "type": "text_editor_code_execution_str_replace_result",
    "old_start": 3,
    "old_lines": 1,
    "new_start": 3,
    "new_lines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}



Результаты

Результаты команд Bash (bash_code_execution_result) включают:

• stdout: вывод при успешном выполнении
• stderr: сообщения об ошибках, если выполнение завершилось неудачно
• return_code: 0 при успехе, ненулевое значение при ошибке
• content: список с записью для каждого файла, созданного командой. Каждая запись содержит file_id для получения файла через Files API

Результаты операций с файлами имеют собственные поля:

• Просмотр (text_editor_code_execution_view_result): file_type, content, num_lines, start_line, total_lines
• Создание (text_editor_code_execution_create_result): is_file_update (существовал ли файл ранее)
• Редактирование (text_editor_code_execution_str_replace_result): old_start, old_lines, new_start, new_lines, lines (формат diff)



Ошибки

Каждый тип инструмента может возвращать определённые ошибки:

Общие ошибки (все инструменты):

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Коды ошибок по типам инструментов:

Контейнер с истёкшим сроком действия нельзя использовать повторно: запросы, ссылающиеся на него, возвращают ошибку вместо его восстановления. Отправьте запрос снова без параметра container, чтобы получить новый контейнер.



Причина остановки pause_turn

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



Контейнеры

Инструмент выполнения кода работает в безопасной контейнеризованной среде, специально разработанной для выполнения кода, с основным акцентом на Python.



Среда выполнения

• Версия Python: 3.11
• Операционная система: контейнер на базе Linux
• Архитектура: x86_64 (AMD64)



Ограничения ресурсов

• Память: 5 ГиБ ОЗУ
• Дисковое пространство: 5 ГиБ хранилища рабочей области
• ЦП: 1 ЦП
• Время выполнения: вызов инструмента, превысивший максимальное время выполнения, возвращает ошибку execution_time_exceeded. При программном вызове инструментов каждая ячейка REPL также имеет 90-секундное ограничение реального времени



Сеть и безопасность

• Доступ к интернету: полностью отключён в целях безопасности
• Внешние соединения: исходящие сетевые запросы не разрешены
• Изоляция песочницы: полная изоляция от хост-системы и других контейнеров
• Доступ к файлам: ограничен только каталогом рабочей области
• Область действия рабочей области: как и в Files API, контейнеры привязаны к рабочей области ключа API
• Срок действия: контейнеры истекают через 30 дней после создания



Предустановленные библиотеки

Изолированная среда Python включает следующие часто используемые библиотеки:

• Наука о данных: pandas, numpy, scipy, scikit-learn, statsmodels
• Визуализация: matplotlib, seaborn
• Обработка файлов: pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab[pycairo], Img2pdf
• Математика и вычисления: sympy, mpmath
• Утилиты: tqdm, python-dateutil, pytz, joblib

Контейнер также включает инструменты командной строки, такие как unzip, unrar, 7zip, bc, rg (ripgrep), fd и sqlite.

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



Повторное использование контейнера

Вы можете повторно использовать существующий контейнер в нескольких запросах к API, передавая идентификатор контейнера из предыдущего ответа. Это позволяет сохранять созданные файлы между запросами. При использовании code_execution_20260120 или более поздней версии вместе с программным вызовом инструментов состояние интерпретатора Python также сохраняется.

Контейнеры истекают через 30 дней после создания. Примерно через 5 минут бездействия для контейнера создаётся контрольная точка, и отправка запроса с его идентификатором в пределах 30-дневного окна восстанавливает его. Временная метка expires_at в объекте container ответа — это более короткое скользящее значение, которое не отражает 30-дневный лимит. Контейнер с истёкшим сроком действия нельзя использовать повторно. Отправьте запрос снова без параметра container, чтобы получить новый контейнер.



Пример

client = anthropic.Anthropic()

# Первый запрос: создать файл со случайным числом в новом контейнере
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Write a file with a random number and save it to '/tmp/number.txt'",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Второй запрос: передать ID контейнера обратно, чтобы Claude использовал тот же контейнер
response2 = client.messages.create(
    container=response1.container.id,
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Read the number from '/tmp/number.txt' and calculate its square",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response2.to_json())



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

Когда вы предоставляете выполнение кода наряду с клиентскими инструментами, которые также запускают код (например, инструментом Bash или пользовательским REPL), Claude работает в многокомпьютерной среде. Инструмент выполнения кода работает в изолированном контейнере Anthropic, тогда как ваши клиентские инструменты работают в отдельной среде, которую контролируете вы. Claude иногда может путать эти среды, пытаясь использовать не тот инструмент или предполагая, что состояние разделяется между ними.

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

When multiple code execution environments are available, be aware that:
- Variables, files, and state do NOT persist between different execution environments
- Use the code_execution tool for general-purpose computation in Anthropic's sandboxed environment
- Use client-provided execution tools (e.g., bash) when you need access to the user's local system, files, or data
- If you need to pass results between environments, explicitly include outputs in subsequent tool calls rather than assuming shared state

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

Когда Claude вызывает один из ваших клиентских инструментов наряду с выполнением кода, API возвращает вызов выполнения кода без его результата. Результат приходит в более позднем ответе, после того как вы отправите обратно блоки tool_result для ваших клиентских инструментов.



Потоковая передача

При включённой потоковой передаче ("stream": true) вы будете получать события выполнения кода по мере их возникновения. Входные данные подинструмента передаются потоком в виде событий input_json_delta, а каждый блок результата приходит целиком в одном событии content_block_start:

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "bash_code_execution"}}

// Tool input streamed as partial JSON
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"command\": \"python analyze.py\"}"}}

// Pause while the command runs

// Execution result delivered as a complete block
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "bash_code_execution_result", "stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": "", "return_code": 0, "content": []}}}



Пакетные запросы

Вы можете включить инструмент выполнения кода в Messages Batches API. Вызовы инструмента выполнения кода через Messages Batches API тарифицируются так же, как и в обычных запросах Messages API.



Использование и цены

Выполнение кода бесплатно при использовании с веб-поиском или веб-загрузкой. Когда web_search_20260209 (или более поздняя версия) или web_fetch_20260209 (или более поздняя версия) включены в ваш запрос к API, дополнительная плата за вызовы инструмента выполнения кода не взимается, помимо стандартной стоимости входных и выходных токенов.

При использовании без этих инструментов выполнение кода оплачивается по времени выполнения, которое отслеживается отдельно от использования токенов:

• Минимальное время выполнения составляет 5 минут
• Каждая организация получает 1 550 бесплатных часов использования в месяц
• Дополнительное использование сверх 1 550 часов оплачивается по ставке $0.05 USD за час, за контейнер
• Если в запрос включены файлы, время выполнения оплачивается, даже если инструмент не вызывается, поскольку файлы предварительно загружаются в контейнер

Использование выполнения кода отслеживается в ответе:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 239,
    "server_tool_use": {
      "code_execution_requests": 1
    }
  }
}



Обновление до последней версии инструмента

Последняя версия инструмента — code_execution_20260521. Для перехода между тремя текущими версиями обновите строку type в своём запросе: все три возвращают блоки ответа, описанные в разделе Формат ответа. См. раздел Совместимость с моделями, чтобы узнать, что добавляет каждая версия и какие модели её поддерживают.

Остальная часть этого раздела посвящена миграции с устаревшей версии code_execution_20250522 (только Python) на текущие версии инструмента.



Что изменилось



Обратная совместимость

• Всё существующее выполнение кода на Python продолжает работать точно так же, как раньше
• Никаких изменений в существующих рабочих процессах, использующих только Python, не требуется



Шаги обновления

Для обновления измените тип инструмента в своих запросах к API:

- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"

Проверьте обработку ответов (если вы программно разбираете ответы):

• API больше не отправляет прежние блоки для ответов выполнения Python
• Вместо этого API отправляет новые типы ответов для Bash и операций с файлами (см. Формат ответа)



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

Выполнение кода происходит в изолированных контейнерах на стороне сервера. Данные контейнера, включая артефакты выполнения, загруженные файлы и выходные данные, хранятся до 30 дней. Этот срок хранения применяется ко всем данным, обрабатываемым в среде контейнера. Файлы, которые выполнение кода создаёт в Files API (доступные для получения через client.beta.files.download()), сохраняются до явного удаления.

О соответствии требованиям ZDR для всех функций см. раздел API и хранение данных.



Дальнейшие шаги