---
title: Ferramenta de execução de código
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool
description: Execute código Python e bash em um contêiner isolado para analisar dados, gerar arquivos e iterar em soluções.
featureMetadata:
  status: ga
  zdr: not-eligible
  supportedModels:
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-opus-5-5
    - claude-opus-5
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-sonnet-4-6
    - claude-sonnet-4-5-20250929
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
  supportedPlatforms:
    Claude API: ga
    Claude Platform on AWS: ga
    Microsoft Foundry:
      availability: ga
      note: No [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry), a execução de código requer uma [implantação Hosted on Anthropic](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
  details:
    - Todos os modelos compatíveis aceitam as três [versões da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#tool-versions). No Claude Haiku 4.5, a chamada programática de ferramentas e a persistência de estado do REPL não estão disponíveis, então as versões mais recentes se comportam como `code_execution_20250825` nele.
    - Para o [Claude Mythos Preview](https://anthropic.com/glasswing), a execução de código é compatível com a Claude API e o Microsoft Foundry.
---

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 isolado, ou "sandbox" (ambiente isolado).

**A execução de código é gratuita quando usada com web search ou web fetch (`web_search_20260209`, `web_fetch_20260209` ou posteriores).** Quando uma dessas ferramentas está na sua solicitação, não há cobranças adicionais pela execução de código nessa solicitação além dos custos padrão de tokens. Isso abrange 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 "dynamic filtering" (filtragem dinâmica) nas ferramentas [web search](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool) e [web fetch](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-fetch-tool): Claude filtra os resultados dentro do ambiente de execução de código antes que eles cheguem à "context window" (janela de contexto). Quando a filtragem dinâmica é executada, a API provisiona automaticamente a execução de código necessária para a solicitação, então você não precisa adicionar a ferramenta de execução de código à sua solicitação para isso.

<Note>
  Entre em contato pelo [formulário de feedback](https://forms.gle/LTAU6Xn2puCJMi1n6) para compartilhar seu feedback sobre este recurso.
</Note>

## Versões da ferramenta

A ferramenta de execução de código tem três versões atuais, e todos os [modelos compatíveis](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#compatibility) aceitam as três. Cada versão se baseia na anterior:

* `code_execution_20250825` oferece suporte a comandos Bash e operações de arquivo.
* `code_execution_20260120` adiciona a persistência de estado do "REPL" (read-eval-print loop) e a "[programmatic tool calling](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling)" (chamada programática de ferramentas) de dentro do sandbox. O 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` nele.
* `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 tempo real de 90 segundos 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 é diferente do [código de erro](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#errors) `execution_time_exceeded`, que a API retorna quando uma invocação inteira da ferramenta excede o tempo máximo de execução.

Nenhuma das três versões da ferramenta requer um cabeçalho `anthropic-beta`. Os cabeçalhos beta legados de execução de código continuam sendo opções de ativação válidas.

Os exemplos nesta página usam `code_execution_20250825`, que abrange as operações Bash e de arquivo que eles demonstram e se comporta da mesma forma em todos os modelos compatíveis; use `code_execution_20260120` ou posterior quando precisar de chamada programática de ferramentas ou persistência de estado do REPL. As ferramentas atuais [web search](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool) e [web fetch](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-fetch-tool) (`web_search_20260209`, `web_fetch_20260209` e posteriores) exigem `code_execution_20260120` ou posterior como sua versão de execução de código.

Não há garantia de que versões mais antigas da ferramenta permaneçam compatíveis com modelos mais novos. Ao adotar um novo modelo, verifique [Versões da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#tool-versions) e [Compatibilidade](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#compatibility), e prefira a versão mais recente da ferramenta que sua integração suporta.

Para verificar se um modelo aceita a ferramenta de execução de código antes de enviar uma solicitação, leia o valor `capabilities.server_tools.code_execution.supported` na Models API. Não use o valor de nível superior `capabilities.code_execution` para isso. Ele informa se o código executado nesta ferramenta pode chamar as outras ferramentas da sua solicitação, como na chamada programática de ferramentas. [Usando a Models API](https://platform.claude.com/docs/pt-BR/models/overview#using-the-models-api) descreve ambos os campos.

<Note>
  Se você ainda estiver usando o legado `code_execution_20250522` (somente Python), consulte [Atualizar para a versão mais recente da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version) para migrar dele.
</Note>

## Início rápido

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

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-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"
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 4096 \
    --message '{
      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]"
    }' \
    --tool '{type: code_execution_20250825, name: code_execution}'
  ```

  ```python Python
  client = anthropic.Anthropic()

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

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-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" }]
  });

  console.log(JSON.stringify(response));
  ```

  ```csharp C#
  AnthropicClient client = new();

  var message = await client.Messages.Create(new()
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [new() { Role = 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 = [new CodeExecutionTool20250825()]
  });

  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Use the code execution tool to calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]")),
  	},
  	Tools: []anthropic.ToolUnionParam{
  		{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(4096L)
      .addUserMessage("Use the code execution tool to calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]")
      .addTool(CodeExecutionTool20250825.builder().build())
      .build();

  Message response = client.messages().create(params);
  IO.println(ObjectMappers.jsonMapper().valueToTree(response));
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 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]',
          ],
      ],
      model: Model::CLAUDE_OPUS_5_5,
      tools: [new CodeExecutionTool20250825()],
  );

  echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_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: [Anthropic::CodeExecutionTool20250825.new]
  )

  puts message.to_json
  ```
</CodeGroup>

A resposta intercala blocos `server_tool_use` (os comandos que Claude executou) com seus blocos de resultado da ferramenta, seguidos pelo texto de Claude. O nível superior também inclui um objeto `container` cujo `id` você pode [reutilizar entre solicitações](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#container-reuse). Consulte [Formato da resposta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#response-format) para ver as estruturas dos blocos.

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

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 a Claude os seguintes recursos:

   * **Comandos Bash:** Execute comandos de shell para operações do sistema
   * **Operações de arquivo:** Crie, visualize e edite arquivos diretamente, incluindo escrever código

3. Claude pode usar qualquer combinação desses recursos em uma única solicitação

4. Todas as operações são executadas em um "container" (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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#pre-installed-libraries) estão disponíveis

5. A API executa todos os comandos no lado do servidor e retorna os resultados a Claude na mesma solicitação, então você nunca executa código nem envia blocos `tool_result` por conta própria. Uma exceção é quando Claude chama uma de 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 solicitação é executada em um novo contêiner, a menos que você passe de volta o ID do contêiner de uma resposta anterior (consulte [Reutilização de contêiner](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#container-reuse))

7. Claude fornece os resultados com quaisquer gráficos, cálculos ou análises gerados

O contêiner tem Python pré-instalado. Claude escreve Python com a subferramenta de operações de arquivo e o executa com um comando Bash. Com `code_execution_20260120` ou posterior e a [chamada programática de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling), o estado do interpretador Python (como as vinculações de variáveis) também persiste entre solicitações que reutilizam o contêiner.

### Quando Claude executa código

Claude executa código quando a solicitaçã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, análise sintática de arquivos ou visualização
* Execução de algoritmos ou simulação
* Solicitações explícitas para "rodar", "calcular" ou "executar"

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 ou traduções simples

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 pela Files API e faça referência a eles na sua solicitação.

O ambiente Python pode processar vários tipos de arquivo enviados pela 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](https://platform.claude.com/docs/pt-BR/build-with-claude/files)
2. **Faça referência ao arquivo** na sua mensagem usando um bloco de conteúdo `container_upload`
3. **Inclua a ferramenta de execução de código** na sua solicitação de API

<CodeGroup>
  ```bash cURL
  # Primeiro, faça upload de um arquivo e capture o ID do arquivo (usando jq)
  FILE_ID=$(curl --fail-with-body -sS https://api.anthropic.com/v1/files \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -F "file=@data.csv" | jq -r '.id')

  # Em seguida, use o file_id com a execução de código
  curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 4096,
      "messages": [{
        "role": "user",
        "content": [
          {"type": "text", "text": "Analyze this CSV data"},
          {"type": "container_upload", "file_id": "'"$FILE_ID"'"}
        ]
      }],
      "tools": [{
        "type": "code_execution_20250825",
        "name": "code_execution"
      }]
    }'
  ```

  ```bash CLI
  # Primeiro, faça upload de um arquivo e capture o ID do arquivo
  FILE_ID=$(ant files upload --file ./data.csv --transform id --raw-output)

  # Em seguida, use o file_id com a execução de código
  ant messages create <<YAML
  model: claude-opus-5-5
  max_tokens: 4096
  messages:
    - role: user
      content:
        - type: text
          text: Analyze this CSV data
        - type: container_upload
          file_id: $FILE_ID
  tools:
    - type: code_execution_20250825
      name: code_execution
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  # Faça upload de um arquivo
  file_object = client.files.upload(file=Path("data.csv"))

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

  ```typescript TypeScript
  import { createReadStream } from "node:fs";
  // ...
  const client = new Anthropic();

  // Faça upload de um arquivo
  const fileObject = await client.files.upload({
    file: createReadStream("data.csv")
  });

  // Use o file_id com a execução de código
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "Analyze this CSV data" },
          { type: "container_upload", file_id: fileObject.id }
        ]
      }
    ],
    tools: [
      {
        type: "code_execution_20250825",
        name: "code_execution"
      }
    ]
  });

  console.log(JSON.stringify(response));
  ```

  ```csharp C#
  AnthropicClient client = new();

  // Faça upload de um arquivo
  var fileObject = await client.Files.Upload(new FileUploadParams
  {
      File = File.OpenRead("data.csv")
  });

  // Use o file_id com a execução de código
  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [
          new()
          {
              Role = Role.User,
              Content = new([
                  new TextBlockParam { Text = "Analyze this CSV data" },
                  new ContainerUploadBlockParam { FileID = fileObject.ID }
              ])
          }
      ],
      Tools = [new CodeExecutionTool20250825()]
  };

  var response = await client.Messages.Create(parameters);
  Console.WriteLine(response);
  ```

  ```go Go
  ctx := context.Background()
  client := anthropic.NewClient()

  // Faça upload de um arquivo
  file, err := os.Open("data.csv")
  if err != nil {
  	log.Fatal(err)
  }
  defer file.Close()

  fileObject, err := client.Files.Upload(ctx, anthropic.FileUploadParams{
  	File: file,
  })
  if err != nil {
  	log.Fatal(err)
  }

  // Use o file_id com a execução de código
  response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(
  			anthropic.NewTextBlock("Analyze this CSV data"),
  			anthropic.NewContainerUploadBlock(fileObject.ID),
  		),
  	},
  	Tools: []anthropic.ToolUnionParam{
  		{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(response.RawJSON())
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  // Faça upload de um arquivo
  FileMetadata fileObject = client.files().upload(
      FileUploadParams.builder()
          .file(Path.of("data.csv"))
          .build()
  );

  // Use o file_id com a execução de código
  Message response = client.messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(4096L)
          .addUserMessageOfBlockParams(List.of(
              ContentBlockParam.ofText(TextBlockParam.builder()
                  .text("Analyze this CSV data")
                  .build()),
              ContentBlockParam.ofContainerUpload(ContainerUploadBlockParam.builder()
                  .fileId(fileObject.id())
                  .build())
          ))
          .addTool(CodeExecutionTool20250825.builder().build())
          .build()
  );

  IO.println(ObjectMappers.jsonMapper().valueToTree(response));
  ```

  ```php PHP
  $client = new Client();

  // Faça upload de um arquivo
  $fileObject = $client->files->upload(
      file: FileParam::fromResource(fopen('data.csv', 'r')),
  );

  // Use o file_id com a execução de código
  $response = $client->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 4096,
      messages: [
          [
              'role' => 'user',
              'content' => [
                  TextBlockParam::with(text: 'Analyze this CSV data'),
                  ContainerUploadBlockParam::with(fileID: $fileObject->id),
              ],
          ],
      ],
      tools: [new CodeExecutionTool20250825()],
  );

  echo json_encode($response), PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # Faça upload de um arquivo
  file_object = client.files.upload(
    file: Pathname("data.csv")
  )

  # Use o file_id com a execução de código
  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "Analyze this CSV data" },
          { type: "container_upload", file_id: file_object.id }
        ]
      }
    ],
    tools: [
      Anthropic::CodeExecutionTool20250825.new
    ]
  )

  puts response.to_json
  ```
</CodeGroup>

### Recuperar arquivos gerados

Quando Claude salva arquivos em seu diretório de saída durante a execução de código (consulte [Como os arquivos gerados são capturados](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#how-generated-files-are-captured)), o ID de cada arquivo aparece no resultado da ferramenta de execução de código, e você pode baixá-lo com a [Files API](https://platform.claude.com/docs/pt-BR/build-with-claude/files):

<CodeGroup exclude="shell">
  <CodeGroupItem language="cURL">
    Baixar todos os arquivos gerados exige um loop sobre os IDs de arquivo no resultado da ferramenta, o que requer mais lógica do que um único comando de shell. Use o [Claude SDK](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/overview) para isso.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Baixar todos os arquivos gerados exige um loop sobre os IDs de arquivo no resultado da ferramenta, o que requer mais lógica do que um único comando de shell. Use o [Claude SDK](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/overview) para isso.
  </CodeGroupItem>

  ```python Python
  client = Anthropic()

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


  # Baixa os arquivos criados
  for file_id in extract_file_ids(response):
      file_metadata = client.files.retrieve_metadata(file_id)
      file_content = client.files.download(file_id)
      file_content.write_to_file(file_metadata.filename)
      print(f"Downloaded: {file_metadata.filename}")
  ```

  ```typescript TypeScript
  import { writeFile } from "node:fs/promises";

  const client = new Anthropic();

  // Solicita a execução de código que cria arquivos
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    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 e baixa cada arquivo criado
  for (const block of response.content) {
    if (block.type === "bash_code_execution_tool_result") {
      const result = block.content;
      if (result.type === "bash_code_execution_result") {
        for (const outputBlock of result.content) {
          const [fileMetadata, fileResponse] = await Promise.all([
            client.files.retrieveMetadata(outputBlock.file_id),
            client.files.download(outputBlock.file_id)
          ]);
          await writeFile(fileMetadata.filename, await fileResponse.bytes());
          console.log(`Downloaded: ${fileMetadata.filename}`);
        }
      }
    }
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [new() { Role = Role.User, Content = "Create a matplotlib visualization and save it as output.png" }],
      Tools = [new CodeExecutionTool20250825()]
  };

  var response = await client.Messages.Create(parameters);

  // Coleta os IDs de arquivo dos resultados da ferramenta
  List<string> fileIds = [];
  foreach (var block in response.Content)
  {
      if (!block.TryPickBashCodeExecutionToolResult(out var toolResult))
          continue;
      if (!toolResult.Content.TryPickBashCodeExecutionResultBlock(out var result))
          continue;
      foreach (var output in result.Content)
      {
          fileIds.Add(output.FileID);
      }
  }

  // Baixa cada arquivo criado
  foreach (var fileId in fileIds)
  {
      var fileMetadata = await client.Files.RetrieveMetadata(fileId);
      using var download = await client.Files.Download(fileId);
      var downloadStream = await download.ReadAsStream();
      await using var target = File.Create(fileMetadata.Filename);
      await downloadStream.CopyToAsync(target);
      Console.WriteLine($"Downloaded: {fileMetadata.Filename}");
  }
  ```

  ```go Go
  	client := anthropic.NewClient()
  	ctx := context.Background()

  	response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  		Model:     anthropic.ModelClaudeOpus5_5,
  		MaxTokens: 4096,
  		Messages: []anthropic.MessageParam{
  			anthropic.NewUserMessage(anthropic.NewTextBlock("Create a matplotlib visualization and save it as output.png")),
  		},
  		Tools: []anthropic.ToolUnionParam{
  			{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
  		},
  	})
  	if err != nil {
  		log.Fatal(err)
  	}

  	fileIDs := extractFileIDs(response)

  	for _, fileID := range fileIDs {
  		fileMetadata, err := client.Files.GetMetadata(ctx, fileID, anthropic.FileGetMetadataParams{})
  		if err != nil {
  			log.Fatal(err)
  		}

  		fileContent, err := client.Files.Download(ctx, fileID, anthropic.FileDownloadParams{})
  		if err != nil {
  			log.Fatal(err)
  		}

  		outFile, err := os.Create(fileMetadata.Filename)
  		if err != nil {
  			log.Fatal(err)
  		}

  		_, err = io.Copy(outFile, fileContent.Body)
  		if err != nil {
  			log.Fatal(err)
  		}
  		outFile.Close()
  		fileContent.Body.Close()

  		fmt.Printf("Downloaded: %s\n", fileMetadata.Filename)
  	}
  // ...

  func extractFileIDs(response *anthropic.Message) []string {
  	var fileIDs []string
  	for _, item := range response.Content {
  		switch variant := item.AsAny().(type) {
  		case anthropic.BashCodeExecutionToolResultBlock:
  			// Coleta os IDs de arquivo do resultado da ferramenta
  			for _, file := range variant.Content.Content {
  				if file.FileID != "" {
  					fileIDs = append(fileIDs, file.FileID)
  				}
  			}
  		}
  	}
  	return fileIDs
  }
  ```

  ```java Java
  void main() throws Exception {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(4096L)
          .addUserMessage("Create a matplotlib visualization and save it as output.png")
          .addTool(CodeExecutionTool20250825.builder().build())
          .build();

      Message response = client.messages().create(params);

      List<String> fileIds = extractFileIds(response);

      for (String fileId : fileIds) {
          FileMetadata fileMetadata = client.files().retrieveMetadata(fileId);
          try (HttpResponse fileContent = client.files().download(fileId)) {
              Files.copy(
                  fileContent.body(),
                  Path.of(fileMetadata.filename()),
                  StandardCopyOption.REPLACE_EXISTING);
          }
          IO.println("Downloaded: " + fileMetadata.filename());
      }
  }

  List<String> extractFileIds(Message response) {
      List<String> fileIds = new ArrayList<>();
      // Coleta os IDs de arquivo dos resultados da ferramenta
      for (ContentBlock item : response.content()) {
          item.bashCodeExecutionToolResult().ifPresent(toolResult -> {
              if (toolResult.content().isBashCodeExecutionResultBlock()) {
                  BashCodeExecutionResultBlock result =
                      toolResult.content().asBashCodeExecutionResultBlock();
                  for (BashCodeExecutionOutputBlock output : result.content()) {
                      fileIds.add(output.fileId());
                  }
              }
          });
      }
      return fileIds;
  }
  ```

  ```php PHP
  $client = new Client();

  // Solicita execução de código que cria arquivos
  $response = $client->messages->create(
      maxTokens: 4096,
      messages: [
          [
              'role' => 'user',
              'content' => 'Create a matplotlib visualization and save it as output.png',
          ],
      ],
      model: Model::CLAUDE_OPUS_5_5,
      tools: [new CodeExecutionTool20250825()],
  );

  /**
   * Extract file IDs from the response.
   *
   * @return list<string>
   */
  function extractFileIds(Message $response): array
  {
      $fileIds = [];
      foreach ($response->content as $block) {
          if ($block->type !== 'bash_code_execution_tool_result') {
              continue;
          }
          $resultBlock = $block->content;
          if ($resultBlock->type !== 'bash_code_execution_result') {
              continue;
          }
          foreach ($resultBlock->content as $outputBlock) {
              $fileIds[] = $outputBlock->fileID;
          }
      }
      return $fileIds;
  }

  // Baixa os arquivos criados
  foreach (extractFileIds($response) as $fileId) {
      $fileMetadata = $client->files->retrieveMetadata($fileId);
      $fileContent = $client->files->download($fileId);

      file_put_contents($fileMetadata->filename, $fileContent);
      echo "Downloaded: {$fileMetadata->filename}\n";
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    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"
      }
    ]
  )

  def extract_file_ids(response)
    file_ids = []
    response.content.each do |item|
      if item.type == :bash_code_execution_tool_result
        # SOLUÇÃO ALTERNATIVA para bug de coerção de union no anthropic-sdk-ruby (SDK-636): item.content é uma
        # union de conteúdo aninhada, então os acessores tipados em `item.content` não são confiáveis.
        # Em vez disso, leia os dados brutos da resposta pela API pública `BaseModel#[]`.
        content_item = item.content
        if content_item[:type].to_s == "bash_code_execution_result"
          Array(content_item[:content]).each do |output_block|
            file_ids << output_block[:file_id]
          end
        end
      end
    end
    file_ids
  end

  extract_file_ids(response).each do |file_id|
    file_metadata = client.files.retrieve_metadata(file_id)
    file_content = client.files.download(file_id)

    File.open(file_metadata.filename, "wb") do |f|
      f.write(file_content.read)
    end

    puts "Downloaded: #{file_metadata.filename}"
  end
  ```
</CodeGroup>

#### Como os arquivos gerados são capturados

Cada chamada `bash_code_execution` recebe um diretório novo e vazio, disponível para o comando como `$OUTPUT_DIR`. Quando o comando termina, os arquivos no nível superior desse diretório são capturados e retornados como as entradas `file_id` na lista `content` do resultado. Arquivos gravados em qualquer outro lugar permanecem no contêiner e não são retornados.

A descrição da ferramenta instrui Claude a compartilhar arquivos copiando-os para `$OUTPUT_DIR`. Se sua aplicação depende de receber um arquivo, peça a Claude que o copie para `$OUTPUT_DIR` e liste o diretório no mesmo comando, para que a saída do `ls` confirme a captura (Claude não vê a lista `content`):

```bash
python /tmp/make_report.py && cp /tmp/report.pdf "$OUTPUT_DIR/" && ls "$OUTPUT_DIR"
```

Um arquivo que Claude gravou em outro lugar ainda está no contêiner, então você pode [reutilizar o contêiner](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#container-reuse) e pedir a Claude que o copie para `$OUTPUT_DIR`.

### Content Credentials em arquivos gerados

Na Claude API, os arquivos de imagem, vídeo e áudio compatíveis que Claude produz no sandbox de execução de código carregam "Content Credentials" (credenciais de conteúdo) [C2PA](https://c2pa.org/) quando você os baixa pela [Files API](https://platform.claude.com/docs/pt-BR/build-with-claude/files). Os [formatos compatíveis](https://opensource.contentauthenticity.org/docs/sdk-repos/c2pa-python/docs/supported-formats/) incluem PNG, JPEG, GIF, WebP, TIFF, HEIC, AVIF, SVG, MP4, MOV, MP3, WAV, FLAC e M4A. A credencial é um manifesto assinado criptograficamente e incorporado aos metadados do arquivo. Ela identifica a Anthropic como emissora, carrega um carimbo de data/hora e registra a descrição de ação "Claude provided this file at the request of a user and may have created or modified the file contents."

A assinatura não exige alterações nas suas solicitações nem no tratamento das respostas, e o manifesto não registra nada sobre você, sua organização ou sua solicitação. O conteúdo visível do arquivo não é alterado. O manifesto adiciona alguns kilobytes, então o tamanho e o checksum do arquivo baixado diferem do arquivo como ele existe dentro do contêiner. Arquivos de texto, PDFs e documentos de escritório não são assinados porque não são formatos compatíveis com assinatura. Os arquivos que você envia são armazenados como estão, incluindo quaisquer Content Credentials que já carreguem.

Para verificar uma credencial, inspecione o arquivo com qualquer ferramenta compatível com C2PA, como o [utilitário de linha de comando c2patool](https://github.com/contentauth/c2pa-rs) de código aberto. Recodificação, conversão de formato, capturas de tela e ferramentas que removem metadados eliminam a credencial, então a ausência de uma credencial não significa que um arquivo não foi produzido com Claude. Para saber mais sobre por que uma credencial pode estar ausente, consulte [How Claude marks AI-generated content](https://support.claude.com/en/articles/16266773-how-claude-marks-ai-generated-content).

## Definição da ferramenta

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

```json JSON
{
  "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 esta ferramenta, Claude obtém automaticamente acesso a duas subferramentas:

* `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 carimbo de data/hora `expires_at`. Passe esse ID de volta no parâmetro de solicitação `container` de nível superior para continuar usando o mesmo contêiner. Consulte [Reutilização de contêiner](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#container-reuse).

## Formato da resposta

A ferramenta de execução de código pode retornar dois tipos de resultados, dependendo da operação:

### Resposta de comando Bash

```json Output
{
  "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ções de arquivo

**Visualizar arquivo:**

```json Output
{
  "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:**

```json Output
{
  "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):**

```json Output
{
  "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 comandos 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 deixou em `$OUTPUT_DIR` (consulte [Como os arquivos gerados são capturados](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#how-generated-files-are-captured)). Cada entrada carrega o `file_id` para [recuperar o arquivo](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files) com a Files API

Os resultados de operações 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):**

```json Output
{
  "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 invocação da ferramenta excedeu o tempo máximo de execução |
| Todas as ferramentas | `invalid_tool_input`      | Parâmetros inválidos fornecidos à ferramenta                 |
| Todas as ferramentas | `too_many_requests`       | Limite de taxa excedido para o uso da ferramenta             |
| bash                 | `output_file_too_large`   | A saída do comando excedeu o tamanho máximo                  |
| text\_editor         | `file_not_found`          | O arquivo não existe (para operações de visualização/edição) |

Um contêiner expirado não pode ser reutilizado: solicitações que fazem referência a ele retornam um erro em vez de restaurá-lo. Envie a solicitaçã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 solicitaçã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 no espaço de trabalho
* **CPU:** 1 CPU
* **Tempo de execução:** Uma invocação da ferramenta que ultrapassa o tempo máximo de execução retorna um [erro](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#errors) `execution_time_exceeded`. Com a [chamada programática de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling), cada célula do REPL também tem um limite de tempo real de 90 segundos

### Rede e segurança

* **Acesso à internet:** Completamente desativado por segurança
* **Conexões externas:** Nenhuma solicitação de rede de saída é permitida
* **Isolamento do sandbox:** Isolamento total do sistema host e de outros contêineres
* **Acesso a arquivos:** Limitado apenas ao diretório do espaço de trabalho
* **Escopo do workspace:** Assim como a [Files API](https://platform.claude.com/docs/pt-BR/build-with-claude/files), os contêineres têm como escopo o workspace da solicitação
* **Expiração:** Os 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 nem 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 solicitações de API fornecendo o ID do contêiner de uma resposta anterior. Isso permite manter os arquivos criados entre as solicitações. Com `code_execution_20260120` ou posterior e a [chamada programática de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling), o estado do interpretador Python também persiste.

Os contêineres expiram 30 dias após a criação. Após cerca de 5 minutos de inatividade, é criado um checkpoint do contêiner, e enviar uma solicitação com seu ID dentro da janela de 30 dias o restaura. O carimbo de data/hora `expires_at` no objeto `container` da resposta é um valor contínuo mais curto e não informa o limite de 30 dias. Um contêiner que expirou não pode ser reutilizado. Envie a solicitação novamente sem o parâmetro `container` para obter um novo contêiner.

### Exemplo

<CodeGroup>
  ```bash cURL
  # Primeira requisição: cria um arquivo com um número aleatório e captura o ID do contêiner (usando jq)
  CONTAINER_ID=$(curl -s https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-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"
      }]
    }' | jq -r '.container.id')

  # Segunda requisição: reutiliza o contêiner para ler o arquivo
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "container": "'"$CONTAINER_ID"'",
      "model": "claude-opus-5-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"
      }]
    }'
  ```

  ```bash CLI
  # Primeira requisição: cria um arquivo com um número aleatório
  CONTAINER_ID=$(ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 4096 \
    --message '{role: user, content: Write a file with a random number and save it to "/tmp/number.txt"}' \
    --tool '{type: code_execution_20250825, name: code_execution}' \
    --transform container.id --raw-output)

  # Segunda requisição: reutiliza o contêiner para ler o arquivo
  ant messages create \
    --container "$CONTAINER_ID" \
    --model claude-opus-5-5 \
    --max-tokens 4096 \
    --message '{role: user, content: Read the number from "/tmp/number.txt" and calculate its square}' \
    --tool '{type: code_execution_20250825, name: code_execution}'
  ```

  ```python Python
  client = anthropic.Anthropic()

  # Primeira requisição: cria um arquivo com um número aleatório em um novo contêiner
  response1 = client.messages.create(
      model="claude-opus-5-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: envia de volta o ID do contêiner para que Claude reutilize o mesmo contêiner
  response2 = client.messages.create(
      container=response1.container.id,
      model="claude-opus-5-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())
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  // Primeira requisição: Claude cria um arquivo dentro de um novo contêiner de execução de código
  const response1 = await client.messages.create({
    model: "claude-opus-5-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" }]
  });

  // A resposta inclui o contêiner depois que a ferramenta de execução de código é executada
  if (!response1.container) {
    throw new Error("Expected the first response to include a container");
  }

  // Segunda requisição: envie o ID do contêiner de volta para reutilizar o mesmo contêiner
  const response2 = await client.messages.create({
    container: response1.container.id,
    model: "claude-opus-5-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" }]
  });

  console.log(JSON.stringify(response2));
  ```

  ```csharp C#
  AnthropicClient client = new();

  // Primeira requisição: Claude cria um arquivo dentro de um novo contêiner de execução de código
  var response1 = await client.Messages.Create(new()
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [new() { Role = Role.User, Content = "Write a file with a random number and save it to '/tmp/number.txt'" }],
      Tools = [new CodeExecutionTool20250825()]
  });

  // Segunda requisição: passe o ID do contêiner de volta para que Claude reutilize o mesmo contêiner
  var response2 = await client.Messages.Create(new()
  {
      Container = response1.Container!.ID,
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [new() { Role = Role.User, Content = "Read the number from '/tmp/number.txt' and calculate its square" }],
      Tools = [new CodeExecutionTool20250825()]
  });

  Console.WriteLine(response2);
  ```

  ```go Go
  client := anthropic.NewClient()
  ctx := context.Background()

  codeExecution := []anthropic.ToolUnionParam{
  	{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
  }

  // Primeira requisição: cria um arquivo com um número aleatório em um novo contêiner
  response1, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Write a file with a random number and save it to '/tmp/number.txt'")),
  	},
  	Tools: codeExecution,
  })
  if err != nil {
  	log.Fatal(err)
  }

  // Reutiliza o contêiner da primeira requisição para que o arquivo ainda esteja lá.
  response2, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  	Container: anthropic.MessageCreateParamsContainerUnion{
  		OfString: anthropic.String(response1.Container.ID),
  	},
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Read the number from '/tmp/number.txt' and calculate its square")),
  	},
  	Tools: codeExecution,
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(response2.RawJSON())
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  // Primeira requisição: cria um arquivo com um número aleatório em um novo contêiner
  MessageCreateParams params1 = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(4096L)
      .addUserMessage("Write a file with a random number and save it to '/tmp/number.txt'")
      .addTool(CodeExecutionTool20250825.builder().build())
      .build();

  Message response1 = client.messages().create(params1);

  // Segunda requisição: passa o ID do contêiner de volta para reutilizar o mesmo contêiner
  MessageCreateParams params2 = MessageCreateParams.builder()
      .container(response1.container().orElseThrow().id())
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(4096L)
      .addUserMessage("Read the number from '/tmp/number.txt' and calculate its square")
      .addTool(CodeExecutionTool20250825.builder().build())
      .build();

  Message response2 = client.messages().create(params2);
  IO.println(ObjectMappers.jsonMapper().valueToTree(response2));
  ```

  ```php PHP
  $client = new Client();

  // Primeira requisição: Claude grava o arquivo em um novo contêiner de execução de código
  $response1 = $client->messages->create(
      maxTokens: 4096,
      messages: [
          [
              'role' => 'user',
              'content' => "Write a file with a random number and save it to '/tmp/number.txt'",
          ],
      ],
      model: Model::CLAUDE_OPUS_5_5,
      tools: [new CodeExecutionTool20250825()],
  );

  // Segunda requisição: reutiliza o contêiner para que '/tmp/number.txt' ainda esteja lá
  $response2 = $client->messages->create(
      container: $response1->container->id,
      maxTokens: 4096,
      messages: [
          [
              'role' => 'user',
              'content' => "Read the number from '/tmp/number.txt' and calculate its square",
          ],
      ],
      model: Model::CLAUDE_OPUS_5_5,
      tools: [new CodeExecutionTool20250825()],
  );

  echo json_encode($response2), PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # Primeira requisição: Claude cria o arquivo dentro de um novo contêiner de execução de código
  response1 = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Write a file with a random number and save it to '/tmp/number.txt'"
      }
    ],
    tools: [Anthropic::CodeExecutionTool20250825.new]
  )

  # Segunda requisição: envie o ID do contêiner de volta para que Claude reutilize o mesmo contêiner
  response2 = client.messages.create(
    container: response1.container.id,
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Read the number from '/tmp/number.txt' and calculate its square"
      }
    ],
    tools: [Anthropic::CodeExecutionTool20250825.new]
  )

  puts response2.to_json
  ```
</CodeGroup>

## Usando a 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/bash-tool) ou um REPL personalizado), Claude está operando em um ambiente com múltiplos computadores. 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. Às vezes, Claude pode confundir esses ambientes, tentando usar a ferramenta errada ou presumindo que o estado é compartilhado entre eles.

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

```text wrap
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 a execução de código com [web search](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool) ou [web fetch](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-fetch-tool), que ativam a execução de código automaticamente. Se sua aplicação já fornece uma ferramenta de shell no 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 de 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 o [streaming](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming) ativado (`"stream": true`), você receberá os eventos de execução de código à medida que ocorrem. A entrada da subferramenta é transmitida como eventos `input_json_delta`, e cada bloco de resultado chega inteiro em um único evento `content_block_start`:

```sse
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": []}}}
```

## Solicitações em lote

Você pode incluir a ferramenta de execução de código na [Messages Batches API](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing). As chamadas da ferramenta de execução de código pela Messages Batches API têm o mesmo preço que as das solicitações regulares da Messages API.

## Uso e preços

**A execução de código é gratuita quando usada com web search ou web fetch.** Quando `web_search_20260209` (ou posterior) ou `web_fetch_20260209` (ou posterior) está incluído na sua requisição de API, não há cobranças adicionais por 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 **$0,05 USD por hora, por contêiner**
* Se arquivos forem incluídos na requisiçã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:

```json
{
  "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 solicitação: as três retornam os blocos de resposta documentados em [Formato da resposta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#response-format). Consulte [Versões da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#tool-versions) para saber o que cada versão adiciona e [Compatibilidade](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#compatibility) para ver os modelos que as suportam.

O restante desta seção aborda a migração do legado `code_execution_20250522`, somente Python, para as versões atuais da ferramenta.

### O que mudou

| Componente         | Legado                      | Atual                                                               |
| ------------------ | --------------------------- | ------------------------------------------------------------------- |
| Cabeçalho beta     | `code-execution-2025-05-22` | Nenhum necessário                                                   |
| Tipo de ferramenta | `code_execution_20250522`   | `code_execution_20250825` ou posterior                              |
| Recursos           | Somente 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 a execução de código Python existente continua funcionando exatamente como antes
* Nenhuma alteração é necessária nos fluxos de trabalho existentes somente com Python

### Etapas de atualização

Para atualizar, altere o tipo de ferramenta nas suas solicitações de API:

```diff
- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"
```

**Revise o tratamento das respostas** (se você analisa as 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 operações Bash e de arquivo (consulte [Formato da resposta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#response-format))

## Retenção de dados

A execução de código é executada em contêineres sandbox no 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. Os arquivos que a execução de código cria na [Files API](https://platform.claude.com/docs/pt-BR/build-with-claude/files) (recuperáveis com `client.files.download()` (csharp, go: `client.Files.Download()`; java: `client.files().download()`; php: `$client->files->download()`)) persistem até serem excluídos explicitamente.

Para a elegibilidade de ZDR em todos os recursos, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Ferramenta advisor" icon="compass" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool">
    Combine um modelo executor mais rápido com um modelo consultor de maior inteligência que fornece orientação estratégica durante a geração.
  </Card>

  <Card title="Chamada programática de ferramentas" icon="code" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling">
    Chame suas próprias ferramentas a partir de código executado dentro do contêiner de execução de código.
  </Card>

  <Card title="Files API" icon="file" href="https://platform.claude.com/docs/pt-BR/build-with-claude/files">
    Envie arquivos para análise e baixe os arquivos que a execução de código cria.
  </Card>

  <Card title="Usando Agent Skills com a API" icon="book" href="https://platform.claude.com/docs/pt-BR/build-with-claude/skills-guide">
    Aprenda a usar Agent Skills para estender os recursos de Claude por meio da API.
  </Card>
</CardGroup>