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

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

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

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

Поддерживаемые модели

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

Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
Claude Haiku 3.5 (claude-3-5-haiku-latest)

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

Вот простой пример, который просит 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-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Вычисли среднее значение и стандартное отклонение для [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-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Проверь версию Python и список установленных пакетов"
        }],
        "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-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Создай файл config.yaml с настройками базы данных, затем обнови порт с 5432 на 3306"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

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

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

Использование Files API с выполнением кода требует двух бета-заголовков: "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-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "Проанализируй эти CSV данные"},
                {"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-opus-4-1-20250805",
    betas=["code-execution-2025-08-25", "files-api-2025-04-14"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Создай визуализацию matplotlib и сохрани её как 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.get('type') == 'code_execution_result':
                for file in content_item.get('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"Скачано: {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-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "Проанализируй эти CSV данные: создай сводный отчет, сохрани визуализации и создай README с результатами"
                },
                {
                    "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)

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

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

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

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

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

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

Наука о данных: pandas, numpy, scipy, scikit-learn, statsmodels
Визуализация: matplotlib, seaborn
Обработка файлов: pyarrow, openpyxl, 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-opus-4-1-20250805",
    betas=["code-execution-2025-08-25"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Напиши файл со случайным числом и сохрани его в '/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-opus-4-1-20250805",
    betas=["code-execution-2025-08-25"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Прочитай число из '/tmp/number.txt' и вычисли его квадрат"
    }],
    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.

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

The code execution tool usage is tracked separately from token usage. Execution time is 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. Pricing: $0.05 per session-hour.

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

Обновившись до 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 и операций с файлами (см. раздел Формат ответа)

Первые шаги

Модели и цены

Узнать о Claude

Возможности

Инструменты

Протокол контекста модели (MCP)

Варианты использования

Инженерия промптов

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

Усилить защитные меры

Юридический центр

​Поддерживаемые модели

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

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

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

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

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

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

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

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

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

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

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

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

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

​Результаты

​Ошибки

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

​Контейнеры

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

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

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

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

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

​Пример

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

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

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

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

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

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

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

Поддерживаемые модели

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

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

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

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

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

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

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

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

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

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

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

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

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

Результаты

Ошибки

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

Контейнеры

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

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

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

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

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

Пример

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

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

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

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

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

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

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