A ferramenta de execução de código permite que Claude execute código Python em um ambiente seguro e isolado. Claude pode analisar dados, criar visualizações, realizar cálculos complexos e processar arquivos carregados diretamente dentro da conversa da API.

A ferramenta de execução de código está atualmente em beta.

Este recurso requer o cabeçalho beta: "anthropic-beta": "code-execution-2025-05-22"

​
Modelos suportados

A ferramenta de execução de código está disponível em:

  • 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)

​
Início rápido

Aqui está um exemplo simples que pede ao Claude para realizar um cálculo:

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": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
            }
        ],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

​
Como funciona a execução de código

Quando você adiciona a ferramenta de execução de código à sua solicitação da API:

  1. Claude avalia se a execução de código ajudaria a responder sua pergunta
  2. Claude escreve e executa código Python em um ambiente sandbox seguro
  3. A execução de código pode ocorrer várias vezes durante uma única solicitação
  4. Claude fornece resultados com quaisquer gráficos, cálculos ou análises gerados

​
Definição da ferramenta

A ferramenta de execução de código não requer parâmetros adicionais:

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

​
Formato de resposta

Aqui está um exemplo de resposta com execução de código:

{
  "role": "assistant",
  "container": {
    "id": "container_011CPR5CNjB747bTd36fQLFk",
    "expires_at": "2025-05-23T21:13:31.749448Z"
  },
  "content": [
    {
      "type": "text",
      "text": "I'll calculate the mean and standard deviation for you."
    },
    {
      "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: {mean}\")\nprint(f\"Standard deviation: {std}\")"
      }
    },
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "content": {
        "type": "code_execution_result",
        "stdout": "Mean: 5.5\nStandard deviation: 2.8722813232690143\n",
        "stderr": "",
        "return_code": 0
      }
    },
    {
      "type": "text",
      "text": "The mean of the dataset is 5.5 and the standard deviation is approximately 2.87."
    }
  ],
  "id": "msg_01BqK2v4FnRs4xTjgL8EuZxz",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45,
    "output_tokens": 187,
  }
}

​
Resultados

Os resultados da execução de código incluem:

  • stdout: Saída de declarações print e execução bem-sucedida
  • stderr: Mensagens de erro se a execução do código falhar
  • return_code (0 para sucesso, não-zero para falha)
{
  "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
  }
}

​
Erros

Se houver um erro ao usar a ferramenta, haverá um 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"
  }
}

Possíveis erros incluem

  • unavailable: A ferramenta de execução de código está indisponível
  • code_execution_exceeded: O tempo de execução excedeu o máximo permitido
  • container_expired: O contêiner expirou e não está disponível

​
Motivo de parada pause_turn

A resposta pode incluir um motivo de parada pause_turn, que indica que a API pausou um turno de longa duração. Você pode fornecer a resposta como está em uma solicitação subsequente para permitir que Claude continue seu turno, ou modificar o conteúdo se desejar interromper a conversa.

​
Trabalhando com Arquivos na Execução de Código

A execução de código pode analisar arquivos carregados via API de Arquivos, como arquivos CSV, arquivos Excel e outros formatos de dados. Isso permite que Claude leia, processe e gere insights de seus dados. Você pode passar múltiplos arquivos por solicitação.

Usar a API de Arquivos com Execução de Código requer dois cabeçalhos beta: "anthropic-beta": "code-execution-2025-05-22,files-api-2025-04-14"

​
Tipos de arquivo suportados

O ambiente Python é capaz de trabalhar com, mas não limitado aos seguintes tipos de arquivo

  • CSV
  • Excel (.xlsx, .xls)
  • JSON
  • XML
  • Imagens (JPEG, PNG, GIF, WebP)
  • Arquivos de texto (.txt, .md, .py, etc)

​
Carregando arquivos para execução de código

  1. Carregue seu arquivo usando a API de Arquivos
  2. Referencie o arquivo em sua mensagem usando um bloco de conteúdo container_upload
  3. Inclua a ferramenta de execução de código em sua solicitação da API
# Primeiro, carregue um arquivo
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"' \

# Então use o file_id com execução de código
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": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

​
Recuperando arquivos criados pela execução de código

Quando Claude cria arquivos durante a execução de código (por exemplo, salvando gráficos matplotlib, gerando CSVs), você pode recuperar esses arquivos usando a API de Arquivos:

from anthropic import Anthropic

# Inicialize o cliente
client = Anthropic()

# Solicite execução de código que cria arquivos
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": "Create a matplotlib visualization and save it as output.png"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "name": "code_execution"
    }]
)

# Extraia IDs de arquivo da resposta
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

# Baixe os arquivos criados
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}")

​
Contêineres

A ferramenta de execução de código executa em um ambiente seguro e containerizado projetado especificamente para execução de código Python.

​
Ambiente de execução

  • Versão do Python: 3.11.12
  • Sistema operacional: Contêiner baseado em Linux
  • Arquitetura: x86_64 (AMD64)

​
Limites de recursos

  • Memória: 1GiB RAM
  • Espaço em disco: 5GiB de armazenamento do workspace
  • CPU: 1 CPU

​
Rede e segurança

  • Acesso à internet: Completamente desabilitado por segurança
  • Conexões externas: Nenhuma solicitação de rede de saída permitida
  • Isolamento de sandbox: Isolamento completo do sistema host e outros contêineres
  • Acesso a arquivos: Limitado apenas ao diretório do workspace
  • Escopo do workspace: Como Arquivos, contêineres são limitados ao workspace da chave da API
  • Expiração: Contêineres expiram 1 hora após a criação

​
Bibliotecas pré-instaladas

O ambiente Python isolado inclui essas bibliotecas comumente usadas:

  • Ciência de Dados: pandas, numpy, scipy, scikit-learn, statsmodels
  • Visualização: matplotlib
  • Processamento de Arquivos: pyarrow, openpyxl, xlrd, pillow
  • Matemática e Computação: sympy, mpmath
  • Utilitários: tqdm, python-dateutil, pytz, joblib

​
Reutilização de contêiner

Você pode reutilizar um contêiner existente em múltiplas solicitações da API fornecendo o ID do contêiner de uma resposta anterior. Isso permite manter arquivos criados entre solicitações.

​
Exemplo

import os
from anthropic import Anthropic

# Inicialize o cliente
client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# Primeira solicitação: Crie um arquivo com um número aleatório
response1 = client.beta.messages.create(
    model="claude-opus-4-20250514",
    betas=["code-execution-2025-05-22"],
    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_20250522",
        "name": "code_execution"
    }]
)

# Extraia o ID do contêiner da primeira resposta
container_id = response1.container.id

# Segunda solicitação: Reutilize o contêiner para ler o arquivo
response2 = client.beta.messages.create(
    container=container_id,  # Reutilize o mesmo contêiner
    model="claude-opus-4-20250514",
    betas=["code-execution-2025-05-22"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Read the number from '/tmp/number.txt' and calculate its square"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "name": "code_execution"
    }]
)

​
Streaming

Com streaming habilitado, você receberá eventos de execução de código conforme eles ocorrem:

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

// Execução de código transmitida
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())\"}"}}

// Pausa enquanto o código executa

// Resultados de execução transmitidos
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": ""}}}

​
Solicitações em lote

Você pode incluir a ferramenta de execução de código na API de Lotes de Mensagens. Chamadas da ferramenta de execução de código através da API de Lotes de Mensagens são precificadas da mesma forma que aquelas em solicitações regulares da API de Mensagens.

​
Uso e preços

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.