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 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 em 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 web_fetch_20260209 está incluído em sua solicitaçã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 é uma primitiva central para construir agentes de alto desempenho. Ela permite filtragem dinâmica em ferramentas de busca na web e busca de conteúdo web, permitindo que Claude processe resultados antes que eles atinjam a 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 da plataforma

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

• Claude API (Anthropic)
• Microsoft Azure AI Foundry

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

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-7",
    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 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 seguro em sandbox
5. Claude fornece resultados com quaisquer gráficos gerados, cálculos ou análise

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

Quando você fornece 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 é executada no contêiner em sandbox da Anthropic, enquanto suas ferramentas fornecidas pelo cliente são executadas em um ambiente separado que você controla. Claude às vezes pode 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 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

Fazer upload e analisar seus próprios arquivos

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

O ambiente Python pode processar vários tipos de arquivo enviados via a Files API, incluindo:

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

Fazer upload e analisar arquivos

1. Faça upload do seu arquivo usando a Files API
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

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 execução de código
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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:

# Inicialize o cliente
client = Anthropic()

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


# Extraia file IDs 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":
                # concrete-typed list: List[BashCodeExecutionOutputBlock]
                for file in content_item.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}")

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 essa ferramenta é fornecida, Claude ganha automaticamente 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çã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:

Motivo de parada pause_turn

A resposta pode incluir um motivo de parada pause_turn, que indica que a API pausou uma volta de longa duração. Você pode fornecer a resposta novamente 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 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 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 arquivos: Limitado apenas ao diretório de espaço de trabalho
• Escopo do espaço de trabalho: Como Files, 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 essas 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 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

# Primeira solicitação: Criar um arquivo com um número aleatório
response1 = client.messages.create(
    model="claude-opus-4-7",
    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"}],
)

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

# Segunda solicitação: Reutilizar o contêiner para ler o arquivo
response2 = client.messages.create(
    container=container_id,  # Reutilizar o mesmo contêiner
    model="claude-opus-4-7",
    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 o streaming ativado, 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"}}

// Código executado em streaming
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 é executado

// Resultados de execução em streaming
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 têm o mesmo preço das solicitações da API de Mensagens regular.

Uso e preços

Code execution is free when used with web search or web fetch. When web_search_20260209 or web_fetch_20260209 is included in your API request, there are no additional charges for code execution tool calls beyond the standard input and output token costs.

When used without these tools, code execution is billed by execution time, tracked separately from token usage:

• Execution time has a minimum of 5 minutes
• Each organization receives 1,550 free hours of usage per month
• Additional usage beyond 1,550 hours is billed at $0.05 per hour, per container
• If files are included in the request, execution time is billed even if the tool is not invoked, due to files being preloaded onto the container

Code execution usage is tracked in the response:

"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 recursos Bash, incluindo código em múltiplas linguagens. Não há diferença de preço.

O que mudou

Compatibilidade com versões anteriores

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

Etapas de atualização

Para atualizar, atualize o tipo de ferramenta em suas solicitações de API:

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

Revisar 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 Bash e operações de arquivo serão enviados (consulte a seção Formato de Resposta)

Chamada de ferramenta programática

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

Retenção de dados

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

Para elegibilidade de ZDR em todos os recursos, consulte Retenção de API e 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 recursos modulares que consistem em instruções, scripts e recursos que estendem a funcionalidade do Claude.

Saiba mais na documentação de Agent Skills e no guia da API de Agent Skills.