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

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

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

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

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

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

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

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

• Claude API (Anthropic)
• Microsoft Azure AI Foundry

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

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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 предоставляет результаты с любыми созданными диаграммами, вычислениями или анализом

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

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

# Upload a file
file_object = client.beta.files.upload(
    file=open("data.csv", "rb"),
)

# Use the file_id with code execution
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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:

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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":
                # concrete-typed list: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    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}")

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

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

{
  "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 ЦП

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

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

Пример

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

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

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

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

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

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

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

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

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

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

Узнайте больше в документации Agent Skills и руководстве API Agent Skills.