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

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

Инструмент выполнения кода в настоящее время находится в открытой бета-версии.Чтобы использовать эту функцию, добавьте заголовок бета-версии "code-execution-2025-08-25" к вашим запросам API.

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

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

Модель	Версия инструмента
Claude Opus 4.1 (`claude-opus-4-1-20250805`)	`code_execution_20250825`
Claude Opus 4 (`claude-opus-4-20250514`)	`code_execution_20250825`
Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)	`code_execution_20250825`
Claude Sonnet 4 (`claude-sonnet-4-20250514`)	`code_execution_20250825`
Claude Sonnet 3.7 (`claude-3-7-sonnet-20250219`) (устарела)	`code_execution_20250825`
Claude Haiku 4.5 (`claude-haiku-4-5-20251001`)	`code_execution_20250825`
Claude Haiku 3.5 (`claude-3-5-haiku-latest`)	`code_execution_20250825`

Текущая версия code_execution_20250825 поддерживает команды Bash и операции с файлами. Также доступна устаревшая версия code_execution_20250522 (только Python). Подробности миграции см. в разделе Обновление до последней версии инструмента.

Более старые версии инструмента не гарантируют обратную совместимость с более новыми моделями. Всегда используйте версию инструмента, соответствующую версии вашей модели.

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

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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"
        }]
    }'

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

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

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

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

Выполнение команд Bash

Попросите Claude проверить информацию о системе и установить пакеты:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Check the Python version and list installed packages"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Создание и редактирование файлов напрямую

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Create a config.yaml file with database settings, then update the port from 5432 to 3306"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

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

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

Использование Files API с Code Execution требует двух заголовков бета-версии: "anthropic-beta": "code-execution-2025-08-25,files-api-2025-04-14"

Окружение Python может обрабатывать различные типы файлов, загруженные через Files API, включая:

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

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

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

# Сначала загрузите файл
curl https://api.anthropic.com/v1/files \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --form 'file=@"data.csv"' \

# Затем используйте file_id с выполнением кода
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

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

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

from anthropic import Anthropic

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

# Запросите выполнение кода, которое создает файлы
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25", "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"
    }]
)

# Извлеките ID файлов из ответа
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':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        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}")

Комбинирование операций

Сложный рабочий процесс, использующий все возможности:

# Сначала загрузите файл
curl https://api.anthropic.com/v1/files \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --form 'file=@"data.csv"' \
    > file_response.json

# Извлеките file_id (используя jq)
FILE_ID=$(jq -r '.id' file_response.json)

# Затем используйте его с выполнением кода
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "Analyze this CSV data: create a summary report, save visualizations, and create a README with the findings"
                },
                {
                    "type": "container_upload", 
                    "file_id": "'$FILE_ID'"
                }
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

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

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

JSON

{
  "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"
  }
}

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

Инструмент	Код ошибки	Описание
Все инструменты	`unavailable`	Инструмент временно недоступен
Все инструменты	`execution_time_exceeded`	Выполнение превысило максимальный лимит времени
Все инструменты	`container_expired`	Контейнер истек и больше недоступен
Все инструменты	`invalid_tool_input`	Неверные параметры, предоставленные инструменту
Все инструменты	`too_many_requests`	Превышен лимит частоты запросов для использования инструмента
text_editor	`file_not_found`	Файл не существует (для операций просмотра/редактирования)
text_editor	`string_not_found`	`old_str` не найден в файле (для str_replace)

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

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

Контейнеры

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

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

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

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

Память: 5GiB RAM
Дисковое пространство: 5GiB рабочего хранилища
CPU: 1 CPU

Сетевые возможности и безопасность

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

Пример

import os
from anthropic import Anthropic

# Инициализируйте клиент
client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# Первый запрос: Создайте файл со случайным числом
response1 = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25"],
    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 контейнера из первого ответа
container_id = response1.container.id

# Второй запрос: Повторно используйте контейнер для чтения файла
response2 = client.beta.messages.create(
    container=container_id,  # Повторно используйте тот же контейнер
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25"],
    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"
    }]
)

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

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

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

// Выполнение кода передается потоком
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())\"}"}}

// Пауза во время выполнения кода

// Результаты выполнения передаются потоком
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.

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

Code execution tool usage is tracked separately from token usage. Execution time has a minimum of 5 minutes. If files are included in the request, execution time is billed even if the tool is not used due to files being preloaded onto the container. Each organization receives 50 free hours of usage with the code execution tool per day. Additional usage beyond the first 50 hours is billed at $0.05 per hour, per container.

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

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

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

Компонент	Устаревший	Текущий
Заголовок бета-версии	`code-execution-2025-05-22`	`code-execution-2025-08-25`
Тип инструмента	`code_execution_20250522`	`code_execution_20250825`
Возможности	Только Python	Команды Bash, операции с файлами
Типы ответов	`code_execution_result`	`bash_code_execution_result`, `text_editor_code_execution_result`

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

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

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

Чтобы обновить, вам нужно внести следующие изменения в ваши запросы API:

Обновите заголовок бета-версии:

- "anthropic-beta": "code-execution-2025-05-22"
+ "anthropic-beta": "code-execution-2025-08-25"

Обновите тип инструмента:

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

Проверьте обработку ответов (если вы программно анализируете ответы):
- Предыдущие блоки для ответов выполнения Python больше не будут отправляться
- Вместо этого будут отправляться новые типы ответов для операций Bash и файлов (см. раздел Формат ответа)

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

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

Первые шаги

Модели и цены

Создавайте с Claude

Возможности

Инструменты

Навыки агента

Agent SDK

MCP в API

Claude на сторонних платформах

Инженерия подсказок

Тестирование и оценка

Усилить защиту

​Совместимость моделей

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

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

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

​Выполнение команд Bash

​Создание и редактирование файлов напрямую

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

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

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

​Комбинирование операций

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

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

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

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

​Результаты

​Ошибки

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

​Контейнеры

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

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

​Сетевые возможности и безопасность

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

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

​Пример

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

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

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

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

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

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

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

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

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

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

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

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

Выполнение команд Bash

Создание и редактирование файлов напрямую

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

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

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

Комбинирование операций

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

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

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

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

Результаты

Ошибки

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

Контейнеры

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

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

Сетевые возможности и безопасность

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

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

Пример

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

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

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

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

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

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

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

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