Ferramenta de execução de código

Claude pode analisar dados, criar visualizações, realizar cálculos complexos, executar comandos de sistema, criar e editar arquivos, e processar arquivos enviados 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 (sandbox).

A execução de código é gratuita quando usada com busca na web ou busca de conteúdo web. Quando web_search_20260209 (ou posterior) ou web_fetch_20260209 (ou posterior) está incluído na sua requisição, não há cobranças adicionais para chamadas da ferramenta de execução de código além dos custos padrão de tokens de entrada e saída. As cobranças padrão de execução de código se aplicam quando essas ferramentas não estão incluídas.

A execução de código é um primitivo central para construir agentes de alto desempenho. Ela permite filtragem dinâmica nas ferramentas de busca na web e busca de conteúdo web, permitindo que Claude processe resultados antes que eles cheguem à "context window" (janela de contexto), melhorando a precisão enquanto reduz o consumo de tokens.



Compatibilidade de modelos

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



Disponibilidade de plataforma

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

• Claude API (Anthropic)
• Claude Platform on AWS
• Microsoft Foundry (requer uma implantação Hosted on Anthropic)

A execução de código não está atualmente disponível no Amazon Bedrock ou Google Cloud.



Início rápido

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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)



Como a execução de código funciona

Quando você adiciona a ferramenta de execução de código à sua requisiçã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: Executar comandos de shell para operações de sistema e gerenciamento de pacotes
   • Operações de arquivo: Criar, visualizar e editar arquivos diretamente, incluindo escrever código
3. Claude pode usar qualquer combinação dessas capacidades em uma única requisição
4. Todas as operações são executadas em um ambiente sandbox seguro
5. Claude fornece resultados com quaisquer gráficos, cálculos ou análises gerados



Quando Claude executa código

Claude executa código quando a requisição se beneficia de computação ou manipulação de arquivos:

• Matemática não trivial (números grandes, muitas etapas, resultados sensíveis à precisão)
• Análise de dados, parsing de arquivos ou visualização
• Execução de algoritmos ou simulação
• Solicitações explícitas para "executar", "computar" ou "rodar"

Claude responde diretamente sem executar código para:

• Aritmética simples e fatos matemáticos bem conhecidos
• Solicitações factuais, conversacionais ou criativas
• Conversões de unidades simples ou traduções

Se você quiser que Claude execute código para uma solicitação limítrofe, peça explicitamente (por exemplo, "execute código para verificar isso").



Usando execução de código com outras ferramentas de execução

Quando você fornece a execução de código junto com ferramentas fornecidas pelo cliente que também executam código (como uma ferramenta bash ou REPL personalizado), Claude está operando em um ambiente multi-computador. A ferramenta de execução de código roda no contêiner isolado da Anthropic, enquanto suas ferramentas fornecidas pelo cliente rodam em um ambiente separado que você controla. Claude pode às vezes confundir esses ambientes, tentando usar a ferramenta errada ou assumindo que o estado é compartilhado entre eles.

Para evitar isso, adicione instruções ao seu prompt do sistema que esclareçam a distinção:

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

Isso é especialmente importante ao combinar execução de código com busca na web ou busca de conteúdo web, que habilitam a execução de código automaticamente. Se sua aplicação já fornece uma ferramenta de shell do lado do cliente, a execução de código automática cria um segundo ambiente de execução que Claude precisa distinguir.



Como usar a ferramenta



Envie e analise seus próprios arquivos

Para analisar seus próprios arquivos de dados (como CSV, Excel ou imagens), envie-os através da Files API e referencie-os na sua requisição:

O ambiente Python pode processar vários tipos de arquivo enviados através da Files API, incluindo:

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



Enviar e analisar arquivos

1. Envie seu arquivo usando a Files API
2. Referencie o arquivo na sua mensagem usando um bloco de conteúdo container_upload
3. Inclua a ferramenta de execução de código na sua requisição de API

client = anthropic.Anthropic()

# Faça upload de um arquivo
file_object = client.beta.files.upload(
    file=open("data.csv", "rb"),
)

# Use o file_id com a execução de código
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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)



Recuperar arquivos gerados

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

# Inicializa o cliente
client = Anthropic()

# Solicita a execução de código que cria arquivos
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)


# Extrai os IDs dos arquivos 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.type == "bash_code_execution_result":
                # lista com tipo concreto: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Faz o download dos 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}")



Definição da ferramenta

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

{
  "type": "code_execution_20250825",
  "name": "code_execution"
}

Quando esta ferramenta é fornecida, Claude automaticamente ganha acesso a duas sub-ferramentas:

• bash_code_execution: Executar comandos de 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çã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, 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:



Motivo de parada pause_turn

A resposta pode incluir um stop_reason 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 requisição subsequente para permitir que Claude continue seu turno, ou modificar o conteúdo se desejar interromper a conversa.



Contêineres

A ferramenta de execução de código roda em um ambiente seguro e conteinerizado projetado especificamente para execução de código, com maior foco em Python.



Ambiente de runtime

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



Limites de recursos

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



Rede e segurança

• Acesso à internet: Completamente desabilitado por segurança
• Conexões externas: Nenhuma requisição de rede de saída permitida
• Isolamento de sandbox: Isolamento completo do sistema host e de outros contêineres
• Acesso a arquivos: Limitado apenas ao diretório de workspace
• Escopo de workspace: Assim como Files, os contêineres têm escopo limitado ao workspace da chave de API
• Expiração: Contêineres expiram 30 dias após a criação



Bibliotecas pré-instaladas

O ambiente Python isolado inclui estas bibliotecas comumente usadas:

• Ciência de dados: pandas, numpy, scipy, scikit-learn, statsmodels
• Visualização: matplotlib, seaborn
• Processamento de arquivos: 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 requisições de API fornecendo o ID do contêiner de uma resposta anterior. Isso permite que você mantenha arquivos criados entre requisições.



Exemplo

# Primeira requisição: crie um arquivo com um número aleatório
response1 = client.messages.create(
    model="claude-opus-4-8",
    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 requisição: reutilize o contêiner para ler o arquivo
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-8",
    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)



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"}}

// 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": ""}}}



Requisições em lote

Você pode incluir a ferramenta de execução de código na Messages Batches API. Chamadas da ferramenta de execução de código através da Messages Batches API têm o mesmo preço que aquelas em requisições regulares da Messages API.



Uso e preços

A execução de código é gratuita quando usada com busca na web ou web fetch. Quando web_search_20260209 (ou posterior) ou web_fetch_20260209 (ou posterior) está incluído na sua solicitação de API, não há cobranças adicionais para chamadas da ferramenta de execução de código além dos custos padrão de tokens de entrada e saída.

Quando usada sem essas ferramentas, a execução de código é cobrada por tempo de execução, rastreado separadamente do uso de tokens:

• O tempo de execução tem um mínimo de 5 minutos
• Cada organização recebe 1.550 horas gratuitas de uso por mês
• O uso adicional além de 1.550 horas é cobrado a US$ 0,05 por hora, por contêiner
• Se arquivos forem incluídos na solicitação, o tempo de execução é cobrado mesmo que a ferramenta não seja invocada, devido aos arquivos serem pré-carregados no contêiner

O uso da execução de código é rastreado na resposta:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 239,
    "server_tool_use": {
      "code_execution_requests": 1
    }
  }
}



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 arquivos e capacidades Bash, incluindo código em várias linguagens. Não há diferença de preço.



O que mudou



Retrocompatibilidade

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



Etapas de atualização

Para atualizar, atualize o tipo de ferramenta nas suas requisições de API:

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

Revise o tratamento de respostas (se estiver fazendo parsing de 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 Bash e operações de arquivo serão enviados (consulte a seção Formato de resposta)



Chamada programática de ferramentas

Para executar ferramentas dentro do contêiner de execução de código, consulte Chamada programática de ferramentas.



Retenção de dados

A execução de código roda em contêineres sandbox do lado do servidor. Os dados do contêiner, incluindo artefatos de execução, arquivos enviados e saídas, são retidos por até 30 dias. Essa retenção se aplica a todos os dados processados dentro do ambiente do contêiner. Arquivos que a execução de código cria na Files API (recuperáveis via client.beta.files.download()) persistem até serem explicitamente excluídos.

Para elegibilidade ZDR em todos os recursos, consulte API e retenção de dados.



Usando 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 em Agent Skills e Usando Agent Skills com a API.