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

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

Эта функция требует бета-заголовок: "anthropic-beta": "code-execution-2025-05-22"

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

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

  • 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-05-22" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Вычисли среднее значение и стандартное отклонение для [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
            }
        ],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

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

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

  1. Claude оценивает, поможет ли выполнение кода ответить на ваш вопрос
  2. Claude пишет и выполняет код Python в безопасной изолированной среде
  3. Выполнение кода может происходить несколько раз в течение одного запроса
  4. Claude предоставляет результаты с любыми созданными диаграммами, вычислениями или анализом

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

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

JSON
{
  "type": "code_execution_20250522",
  "name": "code_execution"
}

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

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

{
  "role": "assistant",
  "container": {
    "id": "container_011CPR5CNjB747bTd36fQLFk",
    "expires_at": "2025-05-23T21:13:31.749448Z"
  },
  "content": [
    {
      "type": "text",
      "text": "Я вычислю среднее значение и стандартное отклонение для вас."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "name": "code_execution",
      "input": {
        "code": "import numpy as np\ndata = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\nmean = np.mean(data)\nstd = np.std(data)\nprint(f\"Среднее: {mean}\")\nprint(f\"Стандартное отклонение: {std}\")"
      }
    },
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "content": {
        "type": "code_execution_result",
        "stdout": "Среднее: 5.5\nСтандартное отклонение: 2.8722813232690143\n",
        "stderr": "",
        "return_code": 0
      }
    },
    {
      "type": "text",
      "text": "Среднее значение набора данных составляет 5.5, а стандартное отклонение приблизительно 2.87."
    }
  ],
  "id": "msg_01BqK2v4FnRs4xTjgL8EuZxz",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45,
    "output_tokens": 187,
  }
}

​
Результаты

Результаты выполнения кода включают:

  • stdout: Вывод из операторов print и успешного выполнения
  • stderr: Сообщения об ошибках, если выполнение кода не удалось
  • return_code (0 для успеха, не ноль для неудачи)
{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "NameError: name 'undefined_variable' is not defined",
    "return_code": 1
  }
}

​
Ошибки

Если возникает ошибка при использовании инструмента, будет code_execution_tool_result_error

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Возможные ошибки включают

  • unavailable: Инструмент выполнения кода недоступен
  • code_execution_exceeded: Время выполнения превысило максимально допустимое
  • container_expired: Контейнер истек и недоступен

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

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

​
Работа с файлами в выполнении кода

Выполнение кода может анализировать файлы, загруженные через Files API, такие как CSV-файлы, Excel-файлы и другие форматы данных. Это позволяет Claude читать, обрабатывать и генерировать выводы из ваших данных. Вы можете передавать несколько файлов на запрос.

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

​
Поддерживаемые типы файлов

Среда Python способна работать с, но не ограничивается следующими типами файлов

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

​
Загрузка файлов для выполнения кода

  1. Загрузите ваш файл используя Files API
  2. Ссылайтесь на файл в вашем сообщении, используя блок содержимого container_upload
  3. Включите инструмент выполнения кода в ваш 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-05-22,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "Проанализируй эти CSV-данные"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

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

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

from anthropic import Anthropic

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

# Запросите выполнение кода, которое создает файлы
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    betas=["code-execution-2025-05-22", "files-api-2025-04-14"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Создай визуализацию matplotlib и сохрани её как output.png"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "name": "code_execution"
    }]
)

# Извлеките идентификаторы файлов из ответа
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == '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}")

​
Контейнеры

Инструмент выполнения кода работает в безопасной контейнеризованной среде, специально разработанной для выполнения кода 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
  • Обработка файлов: pyarrow, openpyxl, xlrd, pillow
  • Математика и вычисления: sympy, mpmath
  • Утилиты: tqdm, python-dateutil, pytz, joblib

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

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

​
Пример

import os
from anthropic import Anthropic

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

# Первый запрос: Создайте файл со случайным числом
response1 = client.beta.messages.create(
    model="claude-opus-4-20250514",
    betas=["code-execution-2025-05-22"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Напиши файл со случайным числом и сохрани его в '/tmp/number.txt'"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "name": "code_execution"
    }]
)

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

# Второй запрос: Повторно используйте контейнер для чтения файла
response2 = client.beta.messages.create(
    container=container_id,  # Повторно используйте тот же контейнер
    model="claude-opus-4-20250514",
    betas=["code-execution-2025-05-22"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Прочитай число из '/tmp/number.txt' и вычисли его квадрат"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "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.