---
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: stable
  zdr:
    eligibility: not-eligible
    note: Dados do contêiner retidos por até 30 dias.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: stable
    Claude Platform on AWS: stable
    Claude Models on Google Cloud (Anthropic managed): stable
    Microsoft Foundry (hosted on Anthropic): stable
  details:
    - Todo modelo suportado aceita 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 novas se comportam como `code_execution_20250825` nele.
---

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 (“sandbox”).

**A execução de código é gratuita quando usada com pesquisa na web 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 [de pesquisa na web](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>
  Use o [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 todo [modelo suportado](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#availability-feature-support) aceita as três. Cada versão 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 “programmatic tool calling” ([chamada programática de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling)) 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 novas 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 chamada de ferramenta inteira excede o tempo máximo de execução.

Para o [Claude Mythos Preview](https://anthropic.com/glasswing), a execução de código é suportada na Claude API e no Microsoft Foundry.

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

Os exemplos desta 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 todo modelo suportado; 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 [pesquisa na web](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 [Suporte da API](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#availability-feature-support), 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` dele 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ê está usando o `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: 2026-10-21" \
    -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 UserMessageParam { 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 a estrutura 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 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 solicitaçã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](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` de volta 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 o resultado. O resultado chega em uma resposta posterior, depois que você envia de volta os blocos `tool_result` das 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
* Pedidos explícitos para “rodar”, “computar” ou “executar”

Claude responde diretamente, sem executar código, para:

* Aritmética simples e fatos matemáticos 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 referencie-os 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. **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 solicitação de API.

<CodeGroup>
  ```bash cURL
  # Primeiro, faça upload de um arquivo
  curl --fail-with-body -sS https://api.anthropic.com/v1/files \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -F "file=@data.csv"

  # Em seguida, use o arquivo com execução de código: FILE_ID é o ID da resposta do upload
  curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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 o upload de um arquivo
  ant files upload --file ./data.csv

  # Depois, use o arquivo com execução de código: FILE_ID é o ID da resposta do upload
  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();

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

  // Usar 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 UserMessageParam
          {
              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();

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

  // Usa o file_id com execução de código
  Message response = client.messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(4096L)
          .addUserMessageOfContentBlockParams(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();

  // Fazer 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 [Anthropic 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 [Anthropic 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 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 UserMessageParam { 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 a 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
        # Coleta os IDs dos arquivos do resultado da ferramenta
        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 recebe 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 suportados que Claude produz no sandbox de execução de código carregam Content Credentials [C2PA](https://c2pa.org/) quando você os baixa pela [Files API](https://platform.claude.com/docs/pt-BR/build-with-claude/files). Os [formatos suportados](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, incorporado aos metadados do arquivo. Ela identifica a Anthropic como emissora, contém um carimbo de data/hora e registra a descrição da 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 nenhuma alteração em suas solicitações ou 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 suportados para 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 [Como o Claude marca conteúdo gerado por IA](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 ganha 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 chamada 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 o referenciam 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.

Envie o ID do contêiner da resposta de volta com essa solicitação (consulte [Reutilização de contêiner](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#container-reuse)). Sem ele, a solicitação é executada em um novo contêiner, e os arquivos de etapas anteriores do turno são perdidos.

## Contêineres

A ferramenta de execução de código é executada em um ambiente conteinerizado e seguro, 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:** O contêiner tem 5 GiB de RAM.
* **Espaço em disco:** O contêiner tem 5 GiB de armazenamento de workspace.
* **CPU:** O contêiner tem 1 CPU.
* **Tempo de execução:** Uma chamada de 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 workspace
* **Escopo do workspace:** Com escopo no workspace da solicitação, como a [Files API](https://platform.claude.com/docs/pt-BR/build-with-claude/files)
* **Expiração:** 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, um contêiner recebe um checkpoint, e enviar uma solicitação com o ID dele dentro da janela de 30 dias o restaura. O carimbo de data/hora `expires_at` no objeto `container` da resposta é um valor móvel 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: criar um arquivo com um número aleatório
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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"
      }]
    }'

  # Segunda requisição: reutilizar o contêiner para ler o arquivo
  # CONTAINER_ID é o container.id da primeira resposta
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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: criar um arquivo com um número aleatório
  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}'

  # Segunda requisição: reutilizar o contêiner para ler o arquivo
  # CONTAINER_ID é o container.id da primeira resposta
  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: crie 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: passe 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-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 UserMessageParam { Content = "Write a file with a random number and save it to '/tmp/number.txt'" }],
      Tools = [new CodeExecutionTool20250825()]
  });

  // Segunda requisição: repasse o ID do contêiner 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 UserMessageParam { 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: repassa o ID do contêiner 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: o Claude grava o arquivo dentro de 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: passe 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 vários 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 usar a ferramenta errada ou agir como se o estado fosse compartilhado entre esses ambientes.

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 [pesquisa na web](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 do primeiro.

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 o resultado. O resultado chega em uma resposta posterior, depois que você envia de volta os blocos `tool_result` das suas ferramentas de cliente.

## Streaming

Com o [streaming](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming) ativado (`"stream": true`), você receberá 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 pesquisa na web 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 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:

```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 [Suporte da API](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#availability-feature-support) 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                              |
| Capacidades        | 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 é feita 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.

## 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">
    Saiba como usar Agent Skills para estender as capacidades de Claude por meio da API.
  </Card>
</CardGroup>

## Disponibilidade

Ferramenta de execução de código está disponível em todos os modelos.

### Suporte da API

#### [Messages API](https://platform.claude.com/docs/pt-BR/build-with-claude/working-with-messages)

* Disponibilidade: Disponível

| Status     | Plataformas de nuvem                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Disponível | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry) |

### Tratamento de dados

[Visão geral do tratamento de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#feature-eligibility)

| Item     | Retenção zero de dados                                                                                                                                        | HIPAA        |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| Status   | Não elegível                                                                                                                                                  | Não elegível |
| Detalhes | Dados do contêiner retidos por até 30 dias. [Saiba mais](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#data-retention) | —            |

Endpoints aplicáveis:

* `/v1/messages` com a ferramenta `code_execution`
