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

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

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

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



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

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



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

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

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

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



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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "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)



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

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

1. Claude оценивает, поможет ли выполнение кода ответить на ваш вопрос
2. Инструмент автоматически предоставляет Claude следующие возможности:
   • Команды Bash: выполнение команд оболочки для системных операций и управления пакетами
   • Операции с файлами: создание, просмотр и редактирование файлов напрямую, включая написание кода
3. Claude может использовать любую комбинацию этих возможностей в одном запросе
4. Все операции выполняются в безопасной изолированной среде
5. Claude предоставляет результаты вместе со всеми сгенерированными графиками, вычислениями или анализом



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

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

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

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

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

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



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

Когда вы предоставляете инструмент выполнения кода вместе с клиентскими инструментами, которые также запускают код (например, инструментом 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 должен отличать от первой.



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



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

Чтобы проанализировать собственные файлы данных (например, 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=open("data.csv", "rb"),
)

# Используйте file_id с выполнением кода
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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)



Получение сгенерированных файлов

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

# Инициализируем клиент
client = Anthropic()

# Запрашиваем выполнение кода, создающего файлы
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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):
    file_ids = []
    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":
                # список с конкретным типом: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.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"
}

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

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



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

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



Ответ команды 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
  }
}



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

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

{
  "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_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "numLines": 4,
    "startLine": 1,
    "totalLines": 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_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_result",
    "oldStart": 3,
    "oldLines": 1,
    "newStart": 3,
    "newLines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}



Результаты

Все результаты выполнения включают:

• stdout: вывод успешного выполнения
• stderr: сообщения об ошибках, если выполнение завершилось неудачно
• return_code: 0 при успехе, ненулевое значение при ошибке

Дополнительные поля для операций с файлами:

• Просмотр: file_type, content, numLines, startLine, totalLines
• Создание: is_file_update (существовал ли файл ранее)
• Редактирование: oldStart, oldLines, newStart, newLines, lines (формат diff)



Ошибки

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

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

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

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



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

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



Контейнеры

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



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

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



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

• Память: 5 ГиБ ОЗУ
• Дисковое пространство: 5 ГиБ хранилища рабочей области
• ЦП: 1 ЦП



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

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



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

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



Пример

# Первый запрос: создаём файл со случайным числом
response1 = client.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# Извлекаем идентификатор контейнера из первого ответа
container_id = response1.container.id

# Второй запрос: повторно используем контейнер для чтения файла
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-8",
    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)



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

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

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

// Code execution streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"code\":\"import pandas as pd\\ndf = pd.read_csv('data.csv')\\nprint(df.head())\"}"}}

// Pause while code executes

// Execution results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": ""}}}



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

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



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

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

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

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

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

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



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

Обновившись до code-execution-2025-08-25, вы получаете доступ к возможностям работы с файлами и Bash, включая код на нескольких языках. Разницы в цене нет.



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



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

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



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

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

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

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

• Прежние блоки для ответов выполнения Python больше не будут отправляться
• Вместо них будут отправляться новые типы ответов для Bash и операций с файлами (см. раздел «Формат ответа»)



Программный вызов инструментов

О запуске инструментов внутри контейнера выполнения кода см. в разделе Программный вызов инструментов.



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

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

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



Использование выполнения кода с Agent Skills

Инструмент выполнения кода позволяет Claude использовать Agent Skills. Навыки — это модульные возможности, состоящие из инструкций, скриптов и ресурсов, которые расширяют функциональность Claude.

Подробнее см. в разделах Agent Skills и Использование Agent Skills с API.