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:| Modelo | Versã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:Como funciona a execução de código
Quando você adiciona a ferramenta de execução de código à sua solicitação de 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: 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
- 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 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:Criar e editar arquivos diretamente
Claude pode criar, visualizar e editar arquivos diretamente no sandbox usando as capacidades de manipulação de arquivos: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"- CSV
- Excel (.xlsx, .xls)
- JSON
- XML
- Imagens (JPEG, PNG, GIF, WebP)
- Arquivos de texto (.txt, .md, .py, etc)
Enviar e analisar arquivos
- Envie seu arquivo usando a Files API
- Faça referência ao 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 de API
Recuperar arquivos gerados
Quando Claude cria arquivos durante a execução de código, você pode recuperar esses arquivos usando a Files API:Combinar operações
Um fluxo de trabalho complexo usando todas as capacidades:Definição da ferramenta
A ferramenta de execução de código não requer parâmetros adicionais:JSON
bash_code_execution: Execute comandos de shelltext_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
Respostas de operação de arquivo
Visualizar arquivo:Resultados
Todos os resultados de execução incluem:stdout: Saída da execução bem-sucedidastderr: Mensagens de erro se a execução falharreturn_code: 0 para sucesso, não-zero para falha
- 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):| 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 de tempo máximo |
| 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 | Arquivo não existe (para operações de visualização/edição) |
| text_editor | string_not_found | O 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
Streaming
Com o streaming habilitado, você receberá eventos de execução de código conforme ocorrem: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 paracode-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
| 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 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:-
Atualize o cabeçalho beta:
-
Atualize o tipo de ferramenta:
-
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)