Ferramenta de execução de código

Claude pode analisar dados, criar visualizações, realizar cálculos complexos, executar comandos do sistema, criar e editar arquivos, e processar arquivos carregados diretamente dentro da 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" beta header às suas solicitações da API.

Recentemente atualizamos a ferramenta de execução de código para suportar comandos Bash e manipulação direta de arquivos. Para instruções sobre como atualizar para a versão mais recente da ferramenta, veja Atualizar para a versão mais recente da ferramenta.

Modelos suportados

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

Claude Opus 4.1 (claude-opus-4-1-20250805)
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-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "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 da API:

Claude avalia se a execução de código ajudaria a responder sua pergunta
A ferramenta fornece automaticamente ao Claude as seguintes capacidades:
- Comandos Bash: Executar comandos shell para operações do sistema e gerenciamento de pacotes
- Operações de arquivo: Criar, visualizar e editar arquivos diretamente, incluindo escrever código
Claude pode usar qualquer combinação dessas capacidades em uma única solicitação
Todas as operações são executadas em um ambiente sandbox seguro
Claude fornece resultados com quaisquer gráficos, cálculos ou análises geradas

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-opus-4-1-20250805",
        "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-opus-4-1-20250805",
        "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"
        }]
    }'

Carregar e analisar seus próprios arquivos

Para analisar seus próprios arquivos de dados (CSV, Excel, imagens, etc.), carregue-os via API de Arquivos e referencie-os em sua solicitação:

Usar a API de Arquivos com Execução de Código 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 carregados via API de Arquivos, incluindo:

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

Carregar e analisar arquivos

Carregue seu arquivo usando a API de Arquivos
Referencie o arquivo em sua mensagem usando um bloco de conteúdo container_upload
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"' \

# Em seguida, 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-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "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 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-1-20250805",
    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"
    }]
)

# Extraia IDs de arquivo da resposta
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.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}")

Combinar operações

Um fluxo de trabalho complexo usando todas as capacidades:

# 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"' \
    > file_response.json

# Extraia file_id (usando jq)
FILE_ID=$(jq -r '.id' file_response.json)

# Em seguida, use-o 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-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "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 automaticamente ganha acesso a duas sub-ferramentas:

bash_code_execution: Executar comandos shell
text_editor_code_execution: Visualizar, criar e editar 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ções 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, diferente de 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:

Ferramenta	Código de Erro	Descrição
Todas as ferramentas	`unavailable`	A ferramenta está temporariamente indisponível
Todas as ferramentas	`execution_time_exceeded`	A execução excedeu o limite máximo de tempo
Todas as ferramentas	`container_expired`	O contêiner expirou e não está mais disponível
Todas as ferramentas	`invalid_tool_input`	Parâmetros inválidos fornecidos à ferramenta
Todas as ferramentas	`too_many_requests`	Limite de taxa excedido para uso da ferramenta
text_editor	`file_not_found`	O arquivo não existe (para operações de visualizar/editar)
text_editor	`string_not_found`	O `old_str` não foi encontrado no arquivo (para str_replace)

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 deixar Claude continuar seu turno, ou modificar o conteúdo se você 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 um foco maior em 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 do 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, os contêineres são delimitados ao workspace da chave da API
Expiração: Os contêineres expiram 1 hora após a criação

Bibliotecas pré-instaladas

O ambiente Python em sandbox inclui essas bibliotecas comumente usadas:

Ciência de Dados: pandas, numpy, scipy, scikit-learn, statsmodels
Visualização: matplotlib, seaborn
Processamento de Arquivos: pyarrow, openpyxl, 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 da 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

# 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-1-20250805",
    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"
    }]
)

# 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-1-20250805",
    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 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.

Atualizar para a versão mais recente da ferramenta

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

O que mudou

Componente	Legado	Atual
Cabeçalho beta	`code-execution-2025-05-22`	`code-execution-2025-08-25`
Tipo de ferramenta	`code_execution_20250522`	`code_execution_20250825`
Capacidades	Apenas Python	Comandos Bash, operações de arquivo
Tipos de resposta	`code_execution_result`	`bash_code_execution_result`, `text_editor_code_execution_result`

Compatibilidade com versões anteriores

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

Etapas de atualização

Para atualizar, você precisa fazer as seguintes alterações em suas solicitações da API:

Atualize o cabeçalho beta:

- "anthropic-beta": "code-execution-2025-05-22"
+ "anthropic-beta": "code-execution-2025-08-25"

Atualize o tipo de ferramenta:

- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"

Revise o tratamento de resposta (se analisando 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 de arquivo serão enviados (veja a seção Formato de Resposta)

Primeiros passos

Modelos e preços

Saiba mais sobre Claude

Capacidades

Ferramentas

Protocolo de Contexto do Modelo (MCP)

Casos de uso

Engenharia de prompts

Testar e avaliar

Fortalecer proteções

Centro legal

​Modelos suportados

​Início rápido

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

​Como usar a ferramenta

​Executar comandos Bash

​Criar e editar arquivos diretamente

​Carregar e analisar seus próprios arquivos

​Carregar e analisar arquivos

​Recuperar arquivos gerados

​Combinar operações

​Definição da ferramenta

​Formato de resposta

​Resposta de comando Bash

​Respostas de operações de arquivo

​Resultados

​Erros

​Motivo de parada pause_turn

​Contêineres

​Ambiente de execução

​Limites de recursos

​Rede e segurança

​Bibliotecas pré-instaladas

​Reutilização de contêiner

​Exemplo

​Streaming

​Solicitações em lote

​Uso e preços

​Atualizar para a versão mais recente da ferramenta

​O que mudou

​Compatibilidade com versões anteriores

​Etapas de atualização

Modelos suportados

Início rápido

Como funciona a execução de código

Como usar a ferramenta

Executar comandos Bash

Criar e editar arquivos diretamente

Carregar e analisar seus próprios arquivos

Carregar e analisar arquivos

Recuperar arquivos gerados

Combinar operações

Definição da ferramenta

Formato de resposta

Resposta de comando Bash

Respostas de operações de arquivo

Resultados

Erros

Motivo de parada `pause_turn`

Contêineres

Ambiente de execução

Limites de recursos

Rede e segurança

Bibliotecas pré-instaladas

Reutilização de contêiner

Exemplo

Streaming

Solicitações em lote

Uso e preços

Atualizar para a versão mais recente da ferramenta

O que mudou

Compatibilidade com versões anteriores

Etapas de atualização