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

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

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

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

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

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

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

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

• Claude API (Anthropic)
• Microsoft Azure AI Foundry

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

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

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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:

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

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

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

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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 "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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 и ссылайтесь на них в вашем запросе:

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

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

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

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

# First, upload a file
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"' \

# Then use the file_id with code execution
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)


# Extract file IDs from the response
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


# Download the created files
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}")

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

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

# First, upload a file
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

# Extract file_id (using jq)
FILE_ID=$(jq -r '.id' file_response.json)

# Then use it with code execution
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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"
        }]
    }'

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

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

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

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

• Память: 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

# Initialize the client
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

# First request: Create a file with a random number
response1 = client.messages.create(
    model="claude-opus-4-6",
    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"}],
)

# Extract the container ID from the first response
container_id = response1.container.id

# Second request: Reuse the container to read the file
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-6",
    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"}}

// 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.

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

Code execution is free when used with web search or web fetch. When web_search_20260209 or web_fetch_20260209 is included in your API request, there are no additional charges for code execution tool calls beyond the standard input and output token costs.

When used without these tools, code execution is billed by execution time, tracked separately from token usage:

• Execution time has a minimum of 5 minutes
• Each organization receives 1,550 free hours of usage per month
• Additional usage beyond 1,550 hours is billed at $0.05 per hour, per container
• If files are included in the request, execution time is billed even if the tool is not invoked, due to files being preloaded onto the container

Code execution usage is tracked in the response:

"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 и файлов (см. раздел Формат ответа)

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

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

# Enable programmatic calling for your tools
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Get weather for 5 cities and find the warmest"}
    ],
    tools=[
        {"type": "code_execution_20250825", "name": "code_execution"},
        {
            "name": "get_weather",
            "description": "Get weather for a city",
            "input_schema": {...},
            "allowed_callers": [
                "code_execution_20250825"
            ],  # Enable programmatic calling
        },
    ],
)

Подробнее в документации программного вызова инструментов.

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

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

Подробнее в документации Agent Skills и руководстве API Agent Skills.