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

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 de API:

  1. O Claude avalia se a execução de código ajudaria a responder à sua pergunta
  2. O 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. O 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",
  "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,
    "server_tool_use": {
      "execution_time_seconds": 1.5
    }
  }
}

​
Resultados

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

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

Os possíveis erros incluem

  • unavailable: A ferramenta de execução de código não está disponí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 de volta como está em uma solicitação subsequente para permitir que o Claude continue seu turno, ou modificar o conteúdo se desejar interromper a conversa.

​
Contêineres

A ferramenta de execução de código é executada em um ambiente containerizado seguro, 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 de workspace
  • CPU: 1 CPU
  • Tempo limite de execução: A execução é limitada por solicitação de mensagens e pode ser controlada com o parâmetro max_execution_duration
  • Expiração do contêiner: Após 1 hora de inatividade, o contêiner não pode ser acessado novamente

​
Rede e segurança

  • Acesso à internet: Completamente desativado por segurança
  • Conexões externas: Nenhuma solicitação de rede de saída permitida
  • Isolamento sandbox: Isolamento completo do sistema host e outros contêineres
  • Acesso a arquivos: Limitado apenas ao diretório de workspace

​
Bibliotecas pré-instaladas

O ambiente Python em sandbox inclui estas bibliotecas comumente usadas:

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

​
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 o Claude leia, processe e gere insights a partir dos seus dados.

O uso da 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 arquivos suportados

O ambiente Python é capaz de trabalhar com, mas não limitado a, os seguintes tipos de arquivos

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

​
Exemplo

  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 de 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"' \

# Depois use o file_id com a 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"
        }]
    }'

​
Streaming

Com o streaming ativado, 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 da 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. As chamadas da ferramenta de execução de código através da API de Lotes de Mensagens são precificadas da mesma forma que as solicitações regulares da API de Mensagens.

​
Uso e preços

O uso da ferramenta de execução de código é rastreado separadamente do uso de tokens. O tempo de execução é de no mínimo 5 minutos. Se arquivos forem incluídos na solicitação, o tempo de execução é cobrado mesmo que a ferramenta não seja usada, devido aos arquivos serem pré-carregados no contêiner.

Preço: $0,05 por hora de sessão.