Claude pode analisar dados, criar visualizações, realizar cálculos complexos, executar comandos do sistema, criar e editar arquivos e processar arquivos enviados diretamente na conversa da API. A ferramenta de execução de código permite que Claude execute comandos Bash e manipule arquivos, incluindo escrever código, em um ambiente seguro e isolado.
A ferramenta de execução de código está atualmente em beta público.Para usar este recurso, adicione o cabeçalho beta "code-execution-2025-08-25" às suas solicitações de API.

Compatibilidade de modelos

A ferramenta de execução de código está disponível nos seguintes modelos:
ModeloVersão da Ferramenta
Claude Opus 4.1 (claude-opus-4-1-20250805)code_execution_20250825
Claude Opus 4 (claude-opus-4-20250514)code_execution_20250825
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)code_execution_20250825
Claude Sonnet 4 (claude-sonnet-4-20250514)code_execution_20250825
Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)code_execution_20250825
Claude Haiku 4.5 (claude-haiku-4-5-20251001)code_execution_20250825
Claude Haiku 3.5 (claude-3-5-haiku-latest)code_execution_20250825
A versão atual code_execution_20250825 suporta comandos Bash e operações de arquivo. Uma versão legada code_execution_20250522 (apenas Python) também está disponível. Consulte Atualizar para a versão mais recente da ferramenta para detalhes de migração.
Versões mais antigas da ferramenta não têm garantia de compatibilidade com versões mais recentes de modelos. Sempre use a versão da ferramenta que corresponde à versão do seu modelo.

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-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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"
        }]
    }'

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. Claude avalia se a execução de código ajudaria a responder sua pergunta
  2. A ferramenta fornece automaticamente ao Claude as seguintes capacidades:
    • Comandos Bash: Execute comandos de shell para operações do sistema e gerenciamento de pacotes
    • Operações de arquivo: Crie, visualize e edite arquivos diretamente, incluindo escrever código
  3. Claude pode usar qualquer combinação dessas capacidades em uma única solicitação
  4. Todas as operações são executadas em um ambiente sandbox seguro
  5. Claude fornece resultados com quaisquer gráficos gerados, cálculos ou análises

Como usar a ferramenta

Executar comandos Bash

Peça ao Claude para verificar informações do sistema e instalar pacotes:
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-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Check the Python version and list installed packages"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Criar e editar arquivos diretamente

Claude pode criar, visualizar e editar arquivos diretamente no sandbox usando as capacidades de manipulação de arquivos:
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-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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"
        }]
    }'

Enviar e analisar seus próprios arquivos

Para analisar seus próprios arquivos de dados (CSV, Excel, imagens, etc.), envie-os via Files API e faça referência a eles em sua solicitação:
Usar a Files API com Code Execution requer dois cabeçalhos beta: "anthropic-beta": "code-execution-2025-08-25,files-api-2025-04-14"
O ambiente Python pode processar vários tipos de arquivo enviados via Files API, incluindo:
  • CSV
  • Excel (.xlsx, .xls)
  • JSON
  • XML
  • Imagens (JPEG, PNG, GIF, WebP)
  • Arquivos de texto (.txt, .md, .py, etc)

Enviar e analisar arquivos

  1. Envie seu arquivo usando a Files API
  2. Faça referência ao 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
# 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: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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"
        }]
    }'

Recuperar arquivos gerados

Quando Claude cria arquivos durante a execução de código, você pode recuperar esses arquivos usando a Files API:
from anthropic import Anthropic

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25", "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}")

Combinar operações

Um fluxo de trabalho complexo usando todas as capacidades:
# 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: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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"
        }]
    }'

Definição da ferramenta

A ferramenta de execução de código não requer parâmetros adicionais:
JSON
{
  "type": "code_execution_20250825",
  "name": "code_execution"
}
Quando esta ferramenta é fornecida, Claude ganha automaticamente acesso a duas sub-ferramentas:
  • bash_code_execution: Execute comandos de shell
  • text_editor_code_execution: Visualize, crie e edite arquivos, incluindo escrever código

Formato de resposta

A ferramenta de execução de código pode retornar dois tipos de resultados dependendo da operação:

Resposta de comando 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
  }
}

Respostas de operação de arquivo

Visualizar arquivo:
{
  "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
  }
}
Criar arquivo:
{
  "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
  }
}
Editar arquivo (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"]
  }
}

Resultados

Todos os resultados de execução incluem:
  • stdout: Saída da execução bem-sucedida
  • stderr: Mensagens de erro se a execução falhar
  • return_code: 0 para sucesso, não-zero para falha
Campos adicionais para operações de arquivo:
  • Visualizar: file_type, content, numLines, startLine, totalLines
  • Criar: is_file_update (se o arquivo já existia)
  • Editar: oldStart, oldLines, newStart, newLines, lines (formato diff)

Erros

Cada tipo de ferramenta pode retornar erros específicos: Erros comuns (todas as ferramentas):
{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}
Códigos de erro por tipo de ferramenta:
FerramentaCódigo de ErroDescrição
Todas as ferramentasunavailableA ferramenta está temporariamente indisponível
Todas as ferramentasexecution_time_exceededA execução excedeu o limite de tempo máximo
Todas as ferramentascontainer_expiredO contêiner expirou e não está mais disponível
Todas as ferramentasinvalid_tool_inputParâmetros inválidos fornecidos à ferramenta
Todas as ferramentastoo_many_requestsLimite de taxa excedido para uso da ferramenta
text_editorfile_not_foundArquivo não existe (para operações de visualização/edição)
text_editorstring_not_foundO old_str não foi encontrado no arquivo (para str_replace)

Razão de parada pause_turn

A resposta pode incluir uma razão de parada pause_turn, que indica que a API pausou uma volta de longa duração. Você pode fornecer a resposta como está em uma solicitação subsequente para deixar Claude continuar sua volta, 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, com maior foco em Python.

Ambiente de tempo de execução

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

Limites de recursos

  • Memória: 5GiB RAM
  • Espaço em disco: 5GiB de armazenamento de espaço de trabalho
  • 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 de outros contêineres
  • Acesso a arquivo: Limitado apenas ao diretório de espaço de trabalho
  • Escopo do espaço de trabalho: Como Arquivos, os contêineres estão no escopo do espaço de trabalho da chave de API
  • Expiração: Os contêineres expiram 30 dias após a criação

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 Arquivo: pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab[pycairo], Img2pdf
  • Matemática e Computação: sympy, mpmath
  • Utilitários: tqdm, python-dateutil, pytz, joblib, unzip, unrar, 7zip, bc, rg (ripgrep), fd, sqlite

Reutilização de contêiner

Você pode reutilizar um contêiner existente em várias solicitações de API fornecendo o ID do contêiner de uma resposta anterior. Isso permite que você mantenha arquivos criados entre solicitações.

Exemplo

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.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25"],
    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.beta.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25"],
    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"
    }]
)

Streaming

Com o streaming habilitado, você receberá eventos de execução de código conforme ocorrem:
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": ""}}}

Solicitações em lote

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

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.

Atualizar para a versão mais recente da ferramenta

Ao atualizar para code-execution-2025-08-25, você obtém acesso a manipulação de arquivo e capacidades Bash, incluindo código em múltiplas linguagens. Não há diferença de preço.

O que mudou

ComponenteLegadoAtual
Cabeçalho betacode-execution-2025-05-22code-execution-2025-08-25
Tipo de ferramentacode_execution_20250522code_execution_20250825
CapacidadesApenas PythonComandos Bash, operações de arquivo
Tipos de respostacode_execution_resultbash_code_execution_result, text_editor_code_execution_result

Compatibilidade com versões anteriores

  • Toda execução de código Python existente continua funcionando exatamente como antes
  • Nenhuma alteração necessária para fluxos de trabalho apenas Python existentes

Etapas de atualização

Para atualizar, você precisa fazer as seguintes alterações em suas solicitações de API:
  1. Atualize o cabeçalho beta:
    - "anthropic-beta": "code-execution-2025-05-22"
    + "anthropic-beta": "code-execution-2025-08-25"
    
  2. Atualize o tipo de ferramenta:
    - "type": "code_execution_20250522"
    + "type": "code_execution_20250825"
    
  3. Revise o tratamento de resposta (se analisar respostas programaticamente):
    • Os blocos anteriores para respostas de execução Python não serão mais enviados
    • Em vez disso, novos tipos de resposta para operações Bash e arquivo serão enviados (consulte a seção Formato de Resposta)

Usar execução de código com Agent Skills

A ferramenta de execução de código permite que Claude use Agent Skills. Skills são capacidades modulares que consistem em instruções, scripts e recursos que estendem a funcionalidade do Claude. Saiba mais na documentação de Agent Skills e guia de API de Agent Skills.