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 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 (web_search_20260209, web_fetch_20260209 ou posterior). Quando uma dessas ferramentas está na sua requisição, não há cobranças adicionais pela execução de código nessa requisição além dos custos padrão de tokens. Isso cobre tanto a execução de código por trás da filtragem dinâmica quanto qualquer código que Claude execute diretamente. O preço padrão de execução de código se aplica quando elas não estão incluídas.

A execução de código também alimenta a filtragem dinâmica nas ferramentas de busca na web e busca de conteúdo web: Claude filtra os resultados dentro do ambiente de execução de código antes que eles cheguem à janela de contexto. Quando a filtragem dinâmica é executada, a API provisiona automaticamente a execução de código necessária para a requisição, então você não precisa adicionar a ferramenta de execução de código à sua requisição para isso.



Compatibilidade de modelos

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

Cada versão da ferramenta se baseia na anterior:

• code_execution_20250825 suporta comandos Bash e operações de arquivo.
• code_execution_20260120 adiciona persistência de estado do REPL e chamada programática de ferramentas de dentro do sandbox. Claude Haiku 4.5 aceita os tipos de ferramenta code_execution_20260120 e code_execution_20260521, mas a chamada programática de ferramentas e a persistência de estado do REPL que depende dela não estão disponíveis nele, então as versões mais recentes se comportam como code_execution_20250825 nesse caso.
• code_execution_20260521 é o mesmo runtime que code_execution_20260120. A diferença é que a descrição da ferramenta informa Claude sobre o limite de 90 segundos de tempo real em cada célula Python na chamada programática de ferramentas, para que Claude possa planejar células de longa duração. Uma célula que excede o limite retorna um resultado normal de execução de código com um return_code diferente de zero e uma mensagem de status detection_timeout em sua saída. Isso é separado do código de erro execution_time_exceeded, que a API retorna quando uma invocação inteira da ferramenta excede o tempo máximo de execução.

Todas as três versões da ferramenta estão em disponibilidade geral e não exigem um cabeçalho anthropic-beta. Os cabeçalhos beta legados de execução de código continuam sendo opt-ins válidos.

Os exemplos nesta página usam code_execution_20250825, que cobre as operações de Bash e arquivo que eles demonstram e se comporta da mesma forma em todos os modelos da tabela; use code_execution_20260120 ou posterior quando precisar de chamada programática de ferramentas ou persistência de estado do REPL. As ferramentas atuais de busca na web e busca de conteúdo web (web_search_20260209, web_fetch_20260209 e posteriores) exigem code_execution_20260120 ou posterior como sua versão de execução de código.



Disponibilidade por plataforma

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

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

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



Início rápido

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Use the code execution tool to 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.to_json())

A resposta intercala blocos server_tool_use (os comandos que Claude executou) com seus blocos de resultado de ferramenta, seguidos pelo texto do Claude. O nível superior também inclui um objeto container cujo id você pode reutilizar entre requisições. Consulte Formato de resposta para as estruturas dos blocos.



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 do sistema
   • 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 contêiner seguro e isolado. O contêiner não tem acesso à internet, então Claude não pode baixar pacotes em tempo de execução: apenas as bibliotecas pré-instaladas estão disponíveis
5. A API executa todos os comandos no lado do servidor e retorna os resultados ao Claude dentro da mesma requisição, então você nunca executa código nem envia de volta blocos tool_result por conta própria. Uma exceção é quando Claude chama uma das suas ferramentas de cliente junto com a execução de código: a API retorna a chamada de execução de código sem seu resultado. O resultado chega em uma resposta posterior, depois que você envia de volta os blocos tool_result para suas ferramentas de cliente
6. Cada requisição é executada em um novo contêiner, a menos que você passe de volta o ID de contêiner de uma resposta anterior (consulte Reutilização de contêiner)
7. Claude fornece resultados com quaisquer gráficos, cálculos ou análises gerados

O contêiner tem Python pré-instalado. Claude escreve Python com a sub-ferramenta de operações de arquivo e o executa com um comando Bash. Com code_execution_20260120 ou posterior e chamada programática de ferramentas, o estado do interpretador Python (como vinculações de variáveis) também persiste entre requisições que reutilizam o contêiner.



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

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").



Trabalhar com arquivos



Enviar e analisar 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=Path("data.csv"))

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



Recuperar arquivos gerados

Quando Claude cria arquivos durante a execução de código, o ID de cada arquivo criado aparece no resultado da ferramenta de execução de código, e você pode baixá-lo com a Files API:

client = Anthropic()

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


# Extrair IDs de arquivos da resposta
def extract_file_ids(response: BetaMessage) -> list[str]:
    file_ids: list[str] = []
    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 output_block in content_item.content:
                    file_ids.append(output_block.file_id)
    return file_ids


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

Ambos os campos são fixos: type seleciona a versão da ferramenta, e name deve ser code_execution.

Quando você fornece essa ferramenta, 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

Quando Claude executa código, a resposta também inclui um objeto container de nível superior com o id do contêiner e o timestamp expires_at. Passe esse ID de volta no parâmetro de requisição de nível superior container para continuar usando o mesmo contêiner. Consulte Reutilização de contêiner.



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,
    "content": []
  }
}



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_view_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "num_lines": 4,
    "start_line": 1,
    "total_lines": 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_create_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_str_replace_result",
    "old_start": 3,
    "old_lines": 1,
    "new_start": 3,
    "new_lines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}



Resultados

Os resultados de comando Bash (bash_code_execution_result) 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
• content: Uma lista com uma entrada para cada arquivo que o comando criou. Cada entrada contém o file_id para recuperar o arquivo com a Files API

Os resultados de operação de arquivo têm seus próprios campos:

• Visualizar (text_editor_code_execution_view_result): file_type, content, num_lines, start_line, total_lines
• Criar (text_editor_code_execution_create_result): is_file_update (se o arquivo já existia)
• Editar (text_editor_code_execution_str_replace_result): old_start, old_lines, new_start, new_lines, 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:

Um contêiner expirado não pode ser reutilizado: requisições que o referenciam retornam um erro em vez de restaurá-lo. Envie a requisição novamente sem o parâmetro container para obter um novo contêiner.



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 requisição subsequente para permitir que Claude continue seu turno, ou modificar o conteúdo se quiser interromper a conversa.



Contêineres

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



Ambiente de execução

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



Limites de recursos

• Memória: 5 GiB de RAM
• Espaço em disco: 5 GiB de armazenamento de workspace
• CPU: 1 CPU
• Tempo de execução: Uma invocação de ferramenta que ultrapassa o tempo máximo de execução retorna um erro execution_time_exceeded. Com chamada programática de ferramentas, cada célula do REPL também tem um limite de 90 segundos de tempo real



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 a Files API, os contêineres têm escopo no 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

O contêiner também inclui ferramentas de linha de comando como unzip, unrar, 7zip, bc, rg (ripgrep), fd e sqlite.

O contêiner não tem acesso à internet, então Claude não pode baixar ou instalar pacotes adicionais em tempo de execução: apenas as bibliotecas pré-instaladas estão disponíveis.



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. Com code_execution_20260120 ou posterior e chamada programática de ferramentas, o estado do interpretador Python também persiste.

Contêineres expiram 30 dias após a criação. Após cerca de 5 minutos de inatividade, um contêiner é salvo em checkpoint, e enviar uma requisição com seu ID dentro da janela de 30 dias o restaura. O timestamp expires_at no objeto container da resposta é um valor rotativo mais curto e não reporta o limite de 30 dias. Um contêiner que expirou não pode ser reutilizado. Envie a requisição novamente sem o parâmetro container para obter um novo contêiner.



Exemplo

client = anthropic.Anthropic()

# Primeira requisição: criar um arquivo com um número aleatório em um novo contêiner
response1 = client.messages.create(
    model="claude-opus-5",
    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"}],
)

# Segunda requisição: passar o ID do contêiner de volta para que o Claude reutilize o mesmo contêiner
response2 = client.messages.create(
    container=response1.container.id,
    model="claude-opus-5",
    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.to_json())



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 multicomputador. A ferramenta de execução de código é executada no contêiner isolado 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 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.

Quando Claude chama uma das suas ferramentas de cliente junto com a execução de código, a API retorna a chamada de execução de código sem seu resultado. O resultado chega em uma resposta posterior, depois que você envia de volta os blocos tool_result para suas ferramentas de cliente.



Streaming

Com streaming habilitado ("stream": true), você receberá eventos de execução de código conforme eles ocorrem. A entrada da sub-ferramenta é transmitida como eventos input_json_delta, e cada bloco de resultado chega inteiro em um único evento content_block_start:

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "bash_code_execution"}}

// Tool input streamed as partial JSON
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"command\": \"python analyze.py\"}"}}

// Pause while the command runs

// Execution result delivered as a complete block
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "bash_code_execution_result", "stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": "", "return_code": 0, "content": []}}}



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 busca de páginas web (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 pelo 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 chamada, porque os arquivos são 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

A versão mais recente da ferramenta é code_execution_20260521. Para alternar entre as três versões atuais, atualize a string type na sua requisição: todas as três retornam os blocos de resposta documentados em Formato de resposta. Consulte Compatibilidade de modelos para saber o que cada versão adiciona e quais modelos a suportam.

O restante desta seção cobre a migração da versão legada code_execution_20250522 (somente Python) para as versões atuais da ferramenta.



O que mudou



Compatibilidade retroativa

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



Etapas de atualização

Para atualizar, altere 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):

• A API não envia mais os blocos anteriores para respostas de execução Python
• Em vez disso, a API envia novos tipos de resposta para Bash e operações de arquivo (consulte Formato de resposta)



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 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 com client.beta.files.download()) persistem até serem explicitamente excluídos.

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



Próximos passos