---
title: Strumento di esecuzione del codice
url: https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool
description: Esegui codice Python e Bash in un container isolato (sandbox) per analizzare dati, generare file e iterare sulle soluzioni.
featureMetadata:
  status: stable
  zdr:
    eligibility: not-eligible
    note: Dati del container conservati fino a 30 giorni.
  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:
    - Ogni modello supportato accetta tutte e tre le [versioni dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#tool-versions). Su Claude Haiku 4.5, la chiamata programmatica degli strumenti e la persistenza dello stato della REPL non sono disponibili, quindi le versioni più recenti si comportano lì come `code_execution_20250825`.
---

Claude può analizzare dati, creare visualizzazioni, eseguire calcoli complessi, eseguire comandi di sistema, creare e modificare file ed elaborare file caricati direttamente all’interno della conversazione API. Lo strumento di esecuzione del codice consente a Claude di eseguire comandi Bash e manipolare file, inclusa la scrittura di codice, in un ambiente sicuro e isolato (“sandbox”).

**L’esecuzione del codice è gratuita quando viene utilizzata con la ricerca web o il recupero web (`web_search_20260209`, `web_fetch_20260209` o successivi).** Quando uno di questi strumenti è presente nella tua richiesta, non ci sono costi aggiuntivi per l’esecuzione del codice in quella richiesta oltre ai costi standard dei token. Ciò copre sia l’esecuzione del codice alla base del “dynamic filtering” (filtraggio dinamico) sia qualsiasi codice che Claude esegue direttamente. Quando questi strumenti non sono inclusi, si applicano i prezzi standard dell’esecuzione del codice.

L’esecuzione del codice alimenta anche il filtraggio dinamico negli strumenti di [ricerca web](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool) e [recupero web](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-fetch-tool): Claude filtra i risultati all’interno dell’ambiente di esecuzione del codice prima che raggiungano la “context window” (finestra di contesto). Quando viene eseguito il filtraggio dinamico, l’API fornisce automaticamente l’esecuzione del codice di cui ha bisogno per la richiesta, quindi non è necessario aggiungere lo strumento di esecuzione del codice alla tua richiesta a tale scopo.

<Note>
  Usa il [modulo di feedback](https://forms.gle/LTAU6Xn2puCJMi1n6) per condividere il tuo feedback su questa funzionalità.
</Note>

## Versioni dello strumento

Lo strumento di esecuzione del codice ha tre versioni attuali, e ogni [modello supportato](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#availability-feature-support) le accetta tutte e tre. Ogni versione si basa sulla precedente:

* `code_execution_20250825` supporta comandi Bash e operazioni sui file.
* `code_execution_20260120` aggiunge la persistenza dello stato della REPL e la [chiamata programmatica degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/programmatic-tool-calling) dall’interno della sandbox. Claude Haiku 4.5 accetta i tipi di strumento `code_execution_20260120` e `code_execution_20260521`, ma la chiamata programmatica degli strumenti e la persistenza dello stato della REPL che da essa dipende non sono disponibili su di esso, quindi le versioni più recenti si comportano lì come `code_execution_20250825`.
* `code_execution_20260521` è lo stesso runtime di `code_execution_20260120`. La differenza è che la descrizione dello strumento informa Claude del limite di 90 secondi di tempo reale su ogni cella Python nella chiamata programmatica degli strumenti, così Claude può pianificare le celle a lunga esecuzione. Una cella che supera il limite restituisce un normale risultato di esecuzione del codice con un `return_code` diverso da zero e un messaggio di stato `detection_timeout` nel suo output. Questo è distinto dal [codice di errore](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#errors) `execution_time_exceeded`, che l’API restituisce quando un’intera chiamata allo strumento supera il tempo massimo di esecuzione.

Per [Claude Mythos Preview](https://anthropic.com/glasswing), l’esecuzione del codice è supportata sulla Claude API e su Microsoft Foundry.

Nessuna delle tre versioni dello strumento richiede un header `anthropic-beta`. Gli header beta legacy dell’esecuzione del codice rimangono opt-in validi.

Gli esempi in questa pagina utilizzano `code_execution_20250825`, che copre le operazioni Bash e sui file che dimostrano e si comporta allo stesso modo su ogni modello supportato; usa `code_execution_20260120` o successivo quando hai bisogno della chiamata programmatica degli strumenti o della persistenza dello stato della REPL. Gli strumenti attuali di [ricerca web](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool) e [recupero web](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-fetch-tool) (`web_search_20260209`, `web_fetch_20260209` e successivi) richiedono `code_execution_20260120` o successivo come versione di esecuzione del codice.

Non è garantito che le versioni precedenti dello strumento rimangano compatibili con i modelli più recenti. Quando adotti un nuovo modello, controlla [Versioni dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#tool-versions) e [Supporto API](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#availability-feature-support), e preferisci la versione dello strumento più recente supportata dalla tua integrazione.

Per verificare se un modello accetta lo strumento di esecuzione del codice prima di inviare una richiesta, leggi il suo valore `capabilities.server_tools.code_execution.supported` dalla Models API. Non usare a questo scopo il valore di primo livello `capabilities.code_execution`. Esso indica se il codice eseguito in questo strumento può chiamare gli altri strumenti della tua richiesta, come nella chiamata programmatica degli strumenti. [Utilizzo della Models API](https://platform.claude.com/docs/it/models/overview#using-the-models-api) descrive entrambi i campi.

<Note>
  Se stai utilizzando `code_execution_20250522` (solo Python), consulta [Aggiornamento all’ultima versione dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version) per migrare da esso.
</Note>

## Avvio rapido

Ecco un esempio che chiede a Claude di eseguire un calcolo:

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

La risposta alterna blocchi `server_tool_use` (i comandi eseguiti da Claude) con i relativi blocchi di risultato dello strumento, seguiti dal testo di Claude. Il livello superiore include anche un oggetto `container` il cui `id` puoi [riutilizzare tra le richieste](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#container-reuse). Consulta [Formato della risposta](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#response-format) per la struttura dei blocchi.

## Come funziona l’esecuzione del codice

Quando aggiungi lo strumento di esecuzione del codice alla tua richiesta API:

1. Claude valuta se l’esecuzione del codice aiuterebbe a rispondere alla tua domanda.

2. Lo strumento fornisce automaticamente a Claude le seguenti capacità:

   * **Comandi Bash:** Eseguire comandi shell per operazioni di sistema
   * **Operazioni sui file:** Creare, visualizzare e modificare file direttamente, inclusa la scrittura di codice

3. Claude può utilizzare qualsiasi combinazione di queste capacità in una singola richiesta.

4. Tutte le operazioni vengono eseguite in un container sicuro e isolato. Il container non ha accesso a internet, quindi Claude non può scaricare pacchetti durante l’esecuzione: sono disponibili solo le [librerie preinstallate](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#pre-installed-libraries).

5. L’API esegue ogni comando lato server e restituisce i risultati a Claude all’interno della stessa richiesta, quindi non devi mai eseguire codice né rinviare tu stesso blocchi `tool_result`. Un’eccezione si verifica quando Claude chiama uno dei tuoi strumenti client insieme all’esecuzione del codice: l’API restituisce la chiamata di esecuzione del codice senza il suo risultato. Il risultato arriva in una risposta successiva, dopo che hai rinviato i blocchi `tool_result` per i tuoi strumenti client.

6. Ogni richiesta viene eseguita in un nuovo container a meno che tu non rinvii l’ID del container di una risposta precedente (consulta [Riutilizzo del container](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#container-reuse)).

7. Claude fornisce i risultati con eventuali grafici, calcoli o analisi generati.

Il container ha Python preinstallato. Claude scrive codice Python con il sotto-strumento per le operazioni sui file e lo esegue con un comando Bash. Con `code_execution_20260120` o successivo e la [chiamata programmatica degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/programmatic-tool-calling), anche lo stato dell’interprete Python (come i binding delle variabili) persiste tra le richieste che riutilizzano il container.

### Quando Claude esegue codice

Claude esegue codice quando la richiesta trae vantaggio dal calcolo o dalla gestione di file:

* Matematica non banale (numeri grandi, molti passaggi, risultati sensibili alla precisione)
* Analisi di dati, parsing di file o visualizzazione
* Esecuzione di algoritmi o simulazioni
* Richieste esplicite di “eseguire”, “calcolare” o “lanciare”

Claude risponde direttamente senza eseguire codice per:

* Aritmetica semplice e fatti matematici ben noti
* Richieste fattuali, conversazionali o creative
* Semplici conversioni di unità o traduzioni

Se vuoi che Claude esegua codice per una richiesta al limite, chiedilo esplicitamente (ad esempio, “esegui codice per verificarlo”).

## Lavorare con i file

### Caricare e analizzare i tuoi file

Per analizzare i tuoi file di dati (come CSV, Excel o immagini), caricali tramite la Files API e fai riferimento ad essi nella tua richiesta.

L’ambiente Python può elaborare vari tipi di file caricati tramite la Files API, tra cui:

* CSV
* Excel (.xlsx, .xls)
* JSON
* XML
* Immagini (JPEG, PNG, GIF, WebP)
* File di testo (.txt, .md, .py e altri)

#### Caricare e analizzare file

1. **Carica il tuo file** utilizzando la [Files API](https://platform.claude.com/docs/it/build-with-claude/files).
2. **Fai riferimento al file** nel tuo messaggio utilizzando un blocco di contenuto `container_upload`.
3. **Includi lo strumento di esecuzione del codice** nella tua richiesta API.

<CodeGroup>
  ```bash cURL
  # Per prima cosa, carica un file
  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"

  # Poi usa il file con l'esecuzione del codice: FILE_ID è l'ID dalla risposta del caricamento
  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
  # Per prima cosa, carica un file
  ant files upload --file ./data.csv

  # Poi usa il file con l'esecuzione del codice: FILE_ID è l'ID dalla risposta del caricamento
  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()

  # Carica un file
  file_object = client.files.upload(file=Path("data.csv"))

  # Usa il file_id con l'esecuzione del codice
  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();

  // Carica un file
  const fileObject = await client.files.upload({
    file: createReadStream("data.csv")
  });

  // Usa il file_id con l'esecuzione del codice
  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();

  // Carica un file
  var fileObject = await client.Files.Upload(new FileUploadParams
  {
      File = File.OpenRead("data.csv")
  });

  // Usa il file_id con l'esecuzione del codice
  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()

  // Carica un file
  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)
  }

  // Usa il file_id con l'esecuzione del codice
  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();

  // Carica un file
  FileMetadata fileObject = client.files().upload(
      FileUploadParams.builder()
          .file(Path.of("data.csv"))
          .build()
  );

  // Usa il file_id con l'esecuzione del codice
  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();

  // Carica un file
  $fileObject = $client->files->upload(
      file: FileParam::fromResource(fopen('data.csv', 'r')),
  );

  // Usa il file_id con l'esecuzione del codice
  $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

  # Carica un file
  file_object = client.files.upload(
    file: Pathname("data.csv")
  )

  # Usa il file_id con l'esecuzione del codice
  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>

### Recuperare i file generati

Quando Claude salva file nella sua directory di output durante l’esecuzione del codice (consulta [Come vengono acquisiti i file generati](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#how-generated-files-are-captured)), l’ID di ciascun file appare nel risultato dello strumento di esecuzione del codice, e puoi scaricarlo con la [Files API](https://platform.claude.com/docs/it/build-with-claude/files):

<CodeGroup exclude="shell">
  <CodeGroupItem language="cURL">
    Scaricare ogni file generato richiede un ciclo sugli ID dei file nel risultato dello strumento, il che necessita di più logica di un singolo comando shell. Usa l’[Anthropic SDK](https://platform.claude.com/docs/it/cli-sdks-libraries/overview) per questo.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Scaricare ogni file generato richiede un ciclo sugli ID dei file nel risultato dello strumento, il che necessita di più logica di un singolo comando shell. Usa l’[Anthropic SDK](https://platform.claude.com/docs/it/cli-sdks-libraries/overview) per questo.
  </CodeGroupItem>

  ```python Python
  client = Anthropic()

  # Richiedi un'esecuzione di codice che crea file
  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"}],
  )


  # Estrai gli ID dei file dalla risposta
  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


  # Scarica i file creati
  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();

  // Richiedi un'esecuzione di codice che crea file
  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"
      }
    ]
  });

  // Estrai gli ID dei file dalla risposta e scarica ogni file creato
  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);

  // Raccogli gli ID dei file dai risultati degli strumenti
  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);
      }
  }

  // Scarica ciascun file creato
  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:
  			// Raccogli gli ID dei file dal risultato dello strumento
  			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<>();
      // Raccogli gli ID dei file dai risultati degli strumenti
      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();

  // Richiedi l'esecuzione di codice che crea file
  $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;
  }

  // Scarica i file creati
  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
        # Raccogli gli ID dei file dal risultato dello strumento
        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>

#### Come vengono acquisiti i file generati

Ogni chiamata `bash_code_execution` riceve una nuova directory vuota, disponibile al comando come `$OUTPUT_DIR`. Al termine del comando, i file al livello superiore di quella directory vengono acquisiti e restituiti come voci `file_id` nell’elenco `content` del risultato. I file scritti in qualsiasi altro punto rimangono nel container e non vengono restituiti.

La descrizione dello strumento indica a Claude di condividere i file copiandoli in `$OUTPUT_DIR`. Se la tua applicazione dipende dalla ricezione di un file, chiedi a Claude di copiarlo in `$OUTPUT_DIR` e di elencare il contenuto della directory nello stesso comando, in modo che l’output di `ls` confermi l’acquisizione (Claude non riceve l’elenco `content`):

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

Un file che Claude ha scritto altrove si trova ancora nel container, quindi puoi [riutilizzare il container](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#container-reuse) e chiedere a Claude di copiarlo in `$OUTPUT_DIR`.

### Content Credentials sui file generati

Sulla Claude API, i file immagine, video e audio supportati che Claude produce nella sandbox di esecuzione del codice includono le Content Credentials [C2PA](https://c2pa.org/) quando li scarichi tramite la [Files API](https://platform.claude.com/docs/it/build-with-claude/files). I [formati supportati](https://opensource.contentauthenticity.org/docs/sdk-repos/c2pa-python/docs/supported-formats/) includono PNG, JPEG, GIF, WebP, TIFF, HEIC, AVIF, SVG, MP4, MOV, MP3, WAV, FLAC e M4A. La credenziale è un manifest firmato crittograficamente e incorporato nei metadati del file. Identifica Anthropic come emittente, include un timestamp e registra la descrizione dell’azione “Claude provided this file at the request of a user and may have created or modified the file contents.”

La firma non richiede modifiche alle tue richieste o alla gestione delle risposte, e il manifest non registra nulla su di te, sulla tua organizzazione o sulla tua richiesta. Il contenuto visibile del file rimane invariato. Il manifest aggiunge alcuni kilobyte, quindi la dimensione e il checksum del file scaricato differiscono da quelli del file così come esiste all’interno del container. I file di testo, i PDF e i documenti d’ufficio non vengono firmati perché non sono formati supportati per la firma. I file che carichi vengono archiviati così come sono, incluse eventuali Content Credentials che già contengono.

Per verificare una credenziale, ispeziona il file con qualsiasi strumento compatibile con C2PA, come l’[utility a riga di comando c2patool](https://github.com/contentauth/c2pa-rs) open source. La ricodifica, la conversione di formato, gli screenshot e gli strumenti che rimuovono i metadati eliminano la credenziale, quindi l’assenza di una credenziale non significa che un file non sia stato prodotto con Claude. Per maggiori informazioni sul motivo per cui una credenziale può mancare, consulta [Come Claude contrassegna i contenuti generati dall’IA](https://support.claude.com/en/articles/16266773-how-claude-marks-ai-generated-content).

## Definizione dello strumento

Lo strumento di esecuzione del codice non richiede parametri aggiuntivi:

```json JSON
{
  "type": "code_execution_20250825",
  "name": "code_execution"
}
```

Entrambi i campi sono fissi: `type` seleziona la versione dello strumento, e `name` deve essere `code_execution`.

Quando fornisci questo strumento, Claude ottiene automaticamente l’accesso a due sotto-strumenti:

* `bash_code_execution`: Eseguire comandi shell
* `text_editor_code_execution`: Visualizzare, creare e modificare file, inclusa la scrittura di codice

Quando Claude esegue codice, la risposta include anche un oggetto `container` di primo livello con l’`id` del container e il timestamp `expires_at`. Rinvia quell’ID nel parametro di richiesta `container` di primo livello per continuare a utilizzare lo stesso container. Consulta [Riutilizzo del container](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#container-reuse).

## Formato della risposta

Lo strumento di esecuzione del codice può restituire due tipi di risultati a seconda dell’operazione:

### Risposta di un 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": []
  }
}
```

### Risposte delle operazioni sui file

**Visualizzare un file:**

```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
  }
}
```

**Creare un file:**

```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
  }
}
```

**Modificare un file (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"]
  }
}
```

### Risultati

I risultati dei comandi Bash (`bash_code_execution_result`) includono:

* `stdout`: Output dell’esecuzione riuscita
* `stderr`: Messaggi di errore se l’esecuzione fallisce
* `return_code`: 0 in caso di successo, diverso da zero in caso di errore
* `content`: Un elenco con una voce per ogni file che il comando ha lasciato in `$OUTPUT_DIR` (consulta [Come vengono acquisiti i file generati](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#how-generated-files-are-captured)). Ogni voce contiene il `file_id` per [recuperare il file](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files) con la Files API

I risultati delle operazioni sui file hanno i propri campi:

* **Visualizzazione** (`text_editor_code_execution_view_result`): `file_type`, `content`, `num_lines`, `start_line`, `total_lines`
* **Creazione** (`text_editor_code_execution_create_result`): `is_file_update` (se il file esisteva già)
* **Modifica** (`text_editor_code_execution_str_replace_result`): `old_start`, `old_lines`, `new_start`, `new_lines`, `lines` (formato diff)

### Errori

Ogni tipo di strumento può restituire errori specifici:

**Errori comuni (tutti gli strumenti):**

```json Output
{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}
```

**Codici di errore per tipo di strumento:**

| Strumento           | Codice di errore          | Descrizione                                                           |
| ------------------- | ------------------------- | --------------------------------------------------------------------- |
| Tutti gli strumenti | `unavailable`             | Lo strumento è temporaneamente non disponibile                        |
| Tutti gli strumenti | `execution_time_exceeded` | La chiamata allo strumento ha superato il tempo massimo di esecuzione |
| Tutti gli strumenti | `invalid_tool_input`      | Parametri non validi forniti allo strumento                           |
| Tutti gli strumenti | `too_many_requests`       | Limite di velocità superato per l’utilizzo dello strumento            |
| bash                | `output_file_too_large`   | L’output del comando ha superato la dimensione massima                |
| text\_editor        | `file_not_found`          | Il file non esiste (per le operazioni di visualizzazione/modifica)    |

Un container scaduto non può essere riutilizzato: le richieste che vi fanno riferimento restituiscono un errore invece di ripristinarlo. Invia di nuovo la richiesta senza il parametro `container` per ottenere un nuovo container.

### Motivo di arresto `pause_turn`

La risposta potrebbe includere un motivo di arresto `pause_turn`, che indica che l’API ha messo in pausa un turno di lunga durata. Puoi fornire la risposta così com’è in una richiesta successiva per consentire a Claude di continuare il suo turno, oppure modificare il contenuto se vuoi interrompere la conversazione.

Invia con quella richiesta l’ID del container restituito dalla risposta (vedi [Riutilizzo del container](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#container-reuse)). Senza di esso, la richiesta viene eseguita in un nuovo container e i file creati in precedenza nel turno vanno persi.

## Container

Lo strumento di esecuzione del codice viene eseguito in un ambiente sicuro e containerizzato progettato specificamente per l’esecuzione del codice, con una maggiore attenzione a Python.

### Ambiente di runtime

* **Versione di Python:** 3.11
* **Sistema operativo:** Container basato su Linux
* **Architettura:** x86\_64 (AMD64)

### Limiti delle risorse

* **Memoria:** Il container dispone di 5 GiB di RAM.
* **Spazio su disco:** Il container dispone di 5 GiB di spazio di archiviazione per l’area di lavoro.
* **CPU:** Il container dispone di 1 CPU.
* **Tempo di esecuzione:** Una chiamata allo strumento che supera il tempo massimo di esecuzione restituisce un [errore](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#errors) `execution_time_exceeded`. Con la [chiamata programmatica degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/programmatic-tool-calling), ogni cella della REPL ha anche un limite di 90 secondi di tempo reale.

### Rete e sicurezza

* **Accesso a internet:** Completamente disabilitato per motivi di sicurezza
* **Connessioni esterne:** Nessuna richiesta di rete in uscita consentita
* **Isolamento della sandbox:** Isolamento completo dal sistema host e dagli altri container
* **Accesso ai file:** Limitato alla sola directory dell’area di lavoro
* **Ambito del workspace:** Limitato al workspace della richiesta, come la [Files API](https://platform.claude.com/docs/it/build-with-claude/files)
* **Scadenza:** 30 giorni dopo la creazione

### Librerie preinstallate

L’ambiente Python isolato include queste librerie di uso comune:

* **Data science:** pandas, numpy, scipy, scikit-learn, statsmodels
* **Visualizzazione:** matplotlib, seaborn
* **Elaborazione di file:** pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab\[pycairo], Img2pdf
* **Matematica e calcolo:** sympy, mpmath
* **Utilità:** tqdm, python-dateutil, pytz, joblib

Il container include anche strumenti a riga di comando come unzip, unrar, 7zip, bc, rg (ripgrep), fd e sqlite.

Il container non ha accesso a internet, quindi Claude non può scaricare o installare pacchetti aggiuntivi durante l’esecuzione: sono disponibili solo le librerie preinstallate.

## Riutilizzo del container

Puoi riutilizzare un container esistente in più richieste API fornendo l’ID del container di una risposta precedente. Questo ti consente di mantenere i file creati tra una richiesta e l’altra. Con `code_execution_20260120` o successivo e la [chiamata programmatica degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/programmatic-tool-calling), persiste anche lo stato dell’interprete Python.

I container scadono 30 giorni dopo la creazione. Dopo circa 5 minuti di inattività viene creato un checkpoint del container, e l’invio di una richiesta con il suo ID entro la finestra di 30 giorni lo ripristina. Il timestamp `expires_at` nell’oggetto `container` della risposta è un valore mobile più breve e non riporta il limite di 30 giorni. Un container scaduto non può essere riutilizzato. Invia di nuovo la richiesta senza il parametro `container` per ottenere un nuovo container.

### Esempio

<CodeGroup>
  ```bash cURL
  # Prima richiesta: crea un file con un numero casuale
  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"
      }]
    }'

  # Seconda richiesta: riusa il container per leggere il file
  # CONTAINER_ID è il container.id della prima risposta
  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
  # Prima richiesta: crea un file con un numero casuale
  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}'

  # Seconda richiesta: riusa il container per leggere il file
  # CONTAINER_ID è il container.id della prima risposta
  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()

  # Prima richiesta: crea un file con un numero casuale in un nuovo container
  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"}],
  )

  # Seconda richiesta: ripassa l'ID del container affinché Claude riutilizzi lo stesso container
  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();

  // Prima richiesta: Claude crea un file in un nuovo container di esecuzione del codice
  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" }]
  });

  // La risposta include il container una volta eseguito lo strumento di esecuzione del codice
  if (!response1.container) {
    throw new Error("Expected the first response to include a container");
  }

  // Seconda richiesta: ripassa l'ID del container per riutilizzare lo stesso container
  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();

  // Prima richiesta: Claude crea un file in un nuovo container di esecuzione del codice
  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()]
  });

  // Seconda richiesta: ripassa l'ID del container affinché Claude riutilizzi lo stesso container
  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{}},
  }

  // Prima richiesta: crea un file con un numero casuale in un nuovo container
  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)
  }

  // Riusa il container della prima richiesta così il file è ancora presente.
  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();

  // Prima richiesta: crea un file con un numero casuale in un nuovo container
  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);

  // Seconda richiesta: ripassa l'ID del container così da riutilizzare lo stesso container
  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();

  // Prima richiesta: Claude scrive il file in un nuovo container di esecuzione del codice
  $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()],
  );

  // Seconda richiesta: riusa il container così '/tmp/number.txt' è ancora presente
  $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

  # Prima richiesta: Claude crea il file in un nuovo container di esecuzione del codice
  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]
  )

  # Seconda richiesta: ripassa l'ID del container così Claude riutilizza lo stesso container
  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>

## Utilizzo dell’esecuzione del codice con altri strumenti di esecuzione

Quando fornisci l’esecuzione del codice insieme a strumenti forniti dal client che eseguono anch’essi codice (come uno [strumento Bash](https://platform.claude.com/docs/it/agents-and-tools/tool-use/bash-tool) o una REPL personalizzata), Claude opera in un ambiente multi-computer. Lo strumento di esecuzione del codice viene eseguito nel container isolato di Anthropic, mentre i tuoi strumenti forniti dal client vengono eseguiti in un ambiente separato che controlli tu. A volte Claude può utilizzare lo strumento sbagliato o comportarsi come se lo stato fosse condiviso tra questi ambienti.

Per evitarlo, aggiungi istruzioni al tuo prompt di sistema che chiariscano la distinzione:

```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
```

Ciò è particolarmente importante quando si combina l’esecuzione del codice con la [ricerca web](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool) o il [recupero web](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-fetch-tool), che abilitano automaticamente l’esecuzione del codice. Se la tua applicazione fornisce già uno strumento shell lato client, l’esecuzione automatica del codice crea un secondo ambiente di esecuzione che Claude deve distinguere dal primo.

Quando Claude chiama uno dei tuoi strumenti client insieme all’esecuzione del codice, l’API restituisce la chiamata di esecuzione del codice senza il suo risultato. Il risultato arriva in una risposta successiva, dopo che hai rinviato i blocchi `tool_result` per i tuoi strumenti client.

## Streaming

Con lo [streaming](https://platform.claude.com/docs/it/build-with-claude/streaming) abilitato (`"stream": true`), riceverai gli eventi di esecuzione del codice man mano che si verificano. L’input del sotto-strumento viene trasmesso come eventi `input_json_delta`, e ogni blocco di risultato arriva per intero in un singolo 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": []}}}
```

## Richieste batch

Puoi includere lo strumento di esecuzione del codice nella [Messages Batches API](https://platform.claude.com/docs/it/build-with-claude/batch-processing). Le chiamate allo strumento di esecuzione del codice tramite la Messages Batches API hanno lo stesso prezzo di quelle nelle normali richieste della Messages API.

## Utilizzo e prezzi

**L’esecuzione del codice è gratuita quando utilizzata con ricerca web o web fetch.** Quando `web_search_20260209` (o successivo) o `web_fetch_20260209` (o successivo) è incluso nella tua richiesta API, non ci sono costi aggiuntivi per le chiamate allo strumento di esecuzione del codice oltre ai costi standard dei token di input e output.

Quando utilizzata senza questi strumenti, l’esecuzione del codice viene fatturata in base al tempo di esecuzione, tracciato separatamente dall’utilizzo dei token:

* Il tempo di esecuzione ha un minimo di 5 minuti.
* Ogni organizzazione riceve **1.550 ore gratuite** di utilizzo al mese.
* L’utilizzo aggiuntivo oltre le 1.550 ore viene fatturato a **$0,05 USD all’ora, per container**.
* Se nella richiesta sono inclusi dei file, il tempo di esecuzione viene fatturato anche se lo strumento non viene chiamato, perché i file vengono precaricati nel container.

L’utilizzo dell’esecuzione del codice viene tracciato nella risposta:

```json
{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 239,
    "server_tool_use": {
      "code_execution_requests": 1
    }
  }
}
```

## Aggiornamento all’ultima versione dello strumento

L’ultima versione dello strumento è `code_execution_20260521`. Per passare da una all’altra delle tre versioni attuali, aggiorna la stringa `type` nella tua richiesta: tutte e tre restituiscono i blocchi di risposta documentati in [Formato della risposta](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#response-format). Consulta [Versioni dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#tool-versions) per sapere cosa aggiunge ciascuna versione e [Supporto API](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#availability-feature-support) per i modelli che le supportano.

Il resto di questa sezione tratta la migrazione dal legacy `code_execution_20250522`, solo Python, alle versioni attuali dello strumento.

### Cosa è cambiato

| Componente        | Legacy                      | Attuale                                                             |
| ----------------- | --------------------------- | ------------------------------------------------------------------- |
| Header beta       | `code-execution-2025-05-22` | Nessuno richiesto                                                   |
| Tipo di strumento | `code_execution_20250522`   | `code_execution_20250825` o successivo                              |
| Capacità          | Solo Python                 | Comandi Bash, operazioni sui file                                   |
| Tipi di risposta  | `code_execution_result`     | `bash_code_execution_result`, `text_editor_code_execution_*_result` |

### Retrocompatibilità

* Tutta l’esecuzione di codice Python esistente continua a funzionare esattamente come prima
* Nessuna modifica richiesta ai flussi di lavoro esistenti solo Python

### Passaggi per l’aggiornamento

Per eseguire l’aggiornamento, aggiorna il tipo di strumento nelle tue richieste API:

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

**Rivedi la gestione delle risposte** (se analizzi le risposte in modo programmatico):

* L’API non invia più i blocchi precedenti per le risposte di esecuzione Python.
* L’API invia invece nuovi tipi di risposta per Bash e le operazioni sui file (consulta [Formato della risposta](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#response-format)).

## Conservazione dei dati

L’esecuzione del codice avviene in container sandbox lato server. I dati del container, inclusi artefatti di esecuzione, file caricati e output, vengono conservati per un massimo di 30 giorni. Questa conservazione si applica a tutti i dati elaborati all’interno dell’ambiente del container. I file che l’esecuzione del codice crea nella [Files API](https://platform.claude.com/docs/it/build-with-claude/files) (recuperabili con `client.files.download()` (csharp, go: `client.Files.Download()`; java: `client.files().download()`; php: `$client->files->download()`)) persistono finché non vengono eliminati esplicitamente.

## Passaggi successivi

<CardGroup cols={2}>
  <Card title="Strumento advisor" icon="compass" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool">
    Abbina un modello esecutore più veloce a un modello advisor di maggiore intelligenza che fornisce indicazioni strategiche durante la generazione.
  </Card>

  <Card title="Chiamata programmatica degli strumenti" icon="code" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/programmatic-tool-calling">
    Chiama i tuoi strumenti dal codice eseguito all’interno del container di esecuzione del codice.
  </Card>

  <Card title="Files API" icon="file" href="https://platform.claude.com/docs/it/build-with-claude/files">
    Carica file per l’analisi e scarica i file creati dall’esecuzione del codice.
  </Card>

  <Card title="Utilizzo degli Agent Skills con l’API" icon="book" href="https://platform.claude.com/docs/it/build-with-claude/skills-guide">
    Scopri come utilizzare gli Agent Skills per estendere le capacità di Claude tramite l’API.
  </Card>
</CardGroup>

## Disponibilità

La funzionalità Strumento di esecuzione del codice è disponibile su tutti i modelli.

### Supporto API

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

* Disponibilità: Disponibile

| Stato       | Piattaforme cloud                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Disponibile | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry) |

### Gestione dei dati

[Panoramica sulla gestione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#feature-eligibility)

| Elemento | Conservazione zero dei dati                                                                                                                                       | HIPAA      |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| Stato    | Non idoneo                                                                                                                                                        | Non idoneo |
| Dettagli | Dati del container conservati fino a 30 giorni. [Scopri di più](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#data-retention) | —          |

Endpoint applicabili:

* `/v1/messages` con lo strumento `code_execution`
