---
title: Strumento computer use
url: https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool
description: Dai a Claude il controllo di screenshot, mouse e tastiera di un ambiente desktop con lo strumento computer use, il toolset client computer_toolset_20260801.
featureMetadata:
  betaHeader: computer-use-2025-11-24, computer-use-2025-01-24
  zdr:
    eligibility: eligible
    note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Strumento lato client in cui screenshot e file vengono acquisiti e archiviati nel tuo ambiente, non da Anthropic.
  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
    Amazon Bedrock: stable
    Amazon Bedrock (bedrock-runtime): stable
    Claude Platform on AWS: stable
    Claude Models on Google Cloud (Anthropic managed): stable
    Claude Models on Google Cloud (Google managed): stable
    Microsoft Foundry: stable
  details:
    - Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 supportano il computer use tramite il toolset `computer_toolset_20260801`. Restituiscono un errore 400 per qualsiasi versione dello strumento computer use che non accettano, come `computer_20251124` sulla Claude API. Per spostare un'integrazione `computer_20251124` al toolset, consulta [Migrare da `computer_20251124`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124). Per spostarti da `computer_20250124`, consulta [Spostare il computer use al toolset](https://platform.claude.com/docs/it/models/haiku-5-5/migration-guide#computer-use-toolset) nella guida alla migrazione di Claude Haiku 5.5.
    - Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 e Claude Opus 4.5 supportano il computer use solo tramite la versione dello strumento `computer_20251124`, che richiede un header beta; consulta [Versioni precedenti dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions).
---

<Note>
  **Inizia con i toolset dell’SDK:** Per `computer_toolset_20260801`, gli SDK Python e TypeScript dispongono di una classe di toolset per il computer, in beta. Parti dall’[integrazione di un partner](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-sdk#partner-integrations), oppure consulta la sezione [toolset per il computer](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-sdk#computer-toolset) della pagina sui toolset dell’SDK. Usa questa pagina come riferimento dello strumento, o quando gestisci tu stesso le chiamate agli strumenti.
</Note>

Claude può interagire con ambienti informatici tramite lo strumento “computer use” (uso del computer), che fornisce funzionalità di screenshot e controllo di mouse/tastiera per un’interazione autonoma con il desktop.

Lo strumento computer use è un [toolset client](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets) definito da Anthropic: una singola voce `{"type": "computer_toolset_20260801"}` in `tools` fornisce a Claude 17 strumenti membri come `screenshot`, `left_click`, `type` e `zoom`, e la tua applicazione esegue ogni chiamata in un ambiente che controlli. Al momento non è disponibile in [Claude Managed Agents](https://platform.claude.com/docs/it/managed-agents/tools). Le chiamate di Claude sono blocchi `tool_use` il cui `name` è il membro e che riportano `"toolset_name": "computer"`, spesso diversi in un unico turno (una [batch action](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#batch-actions) (azione in batch)).

Per le attività che restano all’interno delle pagine web, lo [strumento browser use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool) è la scelta più adatta: i suoi strumenti membri leggono e agiscono sulla pagina stessa, e non richiede un ambiente desktop completo.

Consulta [Supporto API](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#availability-feature-support) per i modelli e le piattaforme che supportano il toolset. [Versioni precedenti dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions) elenca l’header beta di ciascuna versione precedente e i modelli con cui utilizzarla.

## Considerazioni sulla sicurezza

Il computer use presenta rischi unici, distinti dalle funzionalità API standard. Questi rischi aumentano quando si interagisce con internet.

<Warning>
  Per ridurre al minimo i rischi, valuta l’adozione di precauzioni come:

  1. Usare una macchina virtuale o un container dedicato con privilegi minimi per prevenire attacchi diretti al sistema o incidenti.
  2. Evitare di dare al modello accesso a dati sensibili, come le informazioni di accesso agli account, per prevenire il furto di informazioni.
  3. Limitare l’accesso a internet a una allowlist di domini per ridurre l’esposizione a contenuti dannosi.
  4. Chiedere a un essere umano di confermare le decisioni che potrebbero avere conseguenze significative nel mondo reale e qualsiasi attività che richieda un consenso esplicito, come accettare i cookie, completare transazioni finanziarie o accettare i termini di servizio.
</Warning>

In alcune circostanze, Claude segue comandi trovati nei contenuti anche quando sono in conflitto con le tue istruzioni. Ad esempio, le istruzioni presenti nelle pagine web o contenute nelle immagini potrebbero sovrascrivere le tue istruzioni o indurre Claude a commettere errori. Adotta precauzioni per isolare Claude da dati e azioni sensibili per evitare i rischi legati alla “prompt injection” (iniezione di prompt).

Anthropic ha addestrato il modello a resistere a queste prompt injection e ha aggiunto un ulteriore livello di difesa. Se usi lo strumento computer use, dei classificatori analizzano automaticamente ciò che lo strumento restituisce, come gli screenshot, per segnalare potenziali prompt injection. Quando questi classificatori identificano una potenziale prompt injection, indirizzano il modello a verificare se l’istruzione provenga davvero da te prima di agire di conseguenza.

Questa protezione aggiuntiva non è ideale per ogni caso d’uso (ad esempio, casi d’uso senza un essere umano nel ciclo), quindi se desideri escluderla e disattivarla, [contatta il supporto](https://support.claude.com/en/). Le precauzioni elencate in precedenza restano importanti anche con questi classificatori in funzione.

Informa gli utenti finali dei rischi rilevanti e ottieni il loro consenso prima di abilitare il computer use nei tuoi prodotti.

## Avvio rapido

Aggiungi il toolset computer use all’array `tools` di una richiesta alla [Messages API](https://platform.claude.com/docs/it/api/messages/create) come `{"type": "computer_toolset_20260801"}`. La richiesta non necessita di alcun beta header. Questo esempio dichiara anche lo [strumento editor di testo](https://platform.claude.com/docs/it/agents-and-tools/tool-use/text-editor-tool) e lo [strumento bash](https://platform.claude.com/docs/it/agents-and-tools/tool-use/bash-tool), che Claude usa tipicamente insieme al computer use:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "tools": [
        {
          "type": "computer_toolset_20260801"
        },
        {
          "type": "text_editor_20250728",
          "name": "str_replace_based_edit_tool"
        },
        {
          "type": "bash_20250124",
          "name": "bash"
        }
      ],
      "messages": [
        {
          "role": "user",
          "content": "Save a picture of a cat to my desktop."
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  tools:
    - type: computer_toolset_20260801
    - type: text_editor_20250728
      name: str_replace_based_edit_tool
    - type: bash_20250124
      name: bash
  messages:
    - role: user
      content: Save a picture of a cat to my desktop.
  YAML
  ```

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

  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      tools=[
          {"type": "computer_toolset_20260801"},
          {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"},
          {"type": "bash_20250124", "name": "bash"},
      ],
      messages=[{"role": "user", "content": "Save a picture of a cat to my desktop."}],
  )
  print(response)
  ```

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

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    tools: [
      {
        type: "computer_toolset_20260801"
      },
      {
        type: "text_editor_20250728",
        name: "str_replace_based_edit_tool"
      },
      {
        type: "bash_20250124",
        name: "bash"
      }
    ],
    messages: [{ role: "user", content: "Save a picture of a cat to my desktop." }]
  });

  console.log(response);
  ```

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

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Tools =
      [
          new ComputerToolset20260801(),
          new ToolTextEditor20250728(),
          new ToolBash20250124(),
      ],
      Messages = [new UserMessageParam { Content = "Save a picture of a cat to my desktop." }],
  };

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

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

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Tools: []anthropic.ToolUnionParam{
  		{OfComputerToolset20260801: &anthropic.ComputerToolset20260801Param{}},
  		{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
  		{OfBashTool20250124: &anthropic.ToolBash20250124Param{}},
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Save a picture of a cat to my desktop.")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.ComputerToolset20260801;
  // ...
  import com.anthropic.models.messages.ToolBash20250124;
  import com.anthropic.models.messages.ToolTextEditor20250728;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addTool(ComputerToolset20260801.builder().build())
          .addTool(ToolTextEditor20250728.builder().build())
          .addTool(ToolBash20250124.builder().build())
          .addUserMessage("Save a picture of a cat to my desktop.")
          .build();

      Message response = client.messages().create(params);
      IO.println(response);
  }
  ```

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

  $response = $client->messages->create(
      maxTokens: 1024,
      messages: [
          ['role' => 'user', 'content' => 'Save a picture of a cat to my desktop.'],
      ],
      model: Model::CLAUDE_OPUS_5_5,
      tools: [
          ['type' => 'computer_toolset_20260801'],
          [
              'type' => 'text_editor_20250728',
              'name' => 'str_replace_based_edit_tool',
          ],
          [
              'type' => 'bash_20250124',
              'name' => 'bash',
          ],
      ],
  );

  echo $response;
  ```

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

  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    tools: [
      { type: "computer_toolset_20260801" },
      {
        type: "text_editor_20250728",
        name: "str_replace_based_edit_tool"
      },
      {
        type: "bash_20250124",
        name: "bash"
      }
    ],
    messages: [
      { role: "user", content: "Save a picture of a cat to my desktop." }
    ]
  )

  puts response
  ```
</CodeGroup>

Quando Claude agisce sul desktop, la risposta ha uno `stop_reason` pari a `tool_use` e contiene uno o più blocchi `tool_use` dei membri, ciascuno dei quali nomina uno strumento membro e riporta `"toolset_name": "computer"`. A metà di questa attività, dopo che Claude ha ricevuto uno screenshot del desktop, una risposta potrebbe apparire così:

```json Output
{
  "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the web browser to find a picture of a cat."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [512, 742] }
    },
    {
      "type": "tool_use",
      "id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}
```

La tua applicazione esegue ogni chiamata in ordine nel tuo ambiente, restituisce un blocco `tool_result` per ogni blocco `tool_use` e chiama di nuovo l’API; [Come funziona il computer use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#how-computer-use-works) descrive questo ciclo, e il resto di questa pagina mostra come implementarlo.

***

## Come funziona il computer use

<Steps>
  <Step title="Fornisci a Claude lo strumento computer use e un prompt utente">
    * Aggiungi il toolset computer use (e facoltativamente altri strumenti) all’array `tools` della tua richiesta API.
    * Includi un prompt utente che richieda un’interazione con il desktop, ad esempio: “Salva un’immagine di un gatto sul mio desktop.”
  </Step>

  <Step title="Claude risponde con chiamate agli strumenti membri">
    * Claude valuta se agire sul desktop possa aiutare a rispondere alla richiesta dell’utente.
    * In tal caso, Claude risponde con uno o più blocchi `tool_use` dei membri, come `screenshot`, `left_click` o `type`, ciascuno dei quali riporta `"toolset_name": "computer"`. Una risposta con più blocchi di questo tipo è un’[azione batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#batch-actions).
    * La risposta dell’API ha uno `stop_reason` pari a `tool_use`, che segnala una richiesta di uso degli strumenti.
  </Step>

  <Step title="Esegui le chiamate in ordine e restituisci i risultati">
    * Itera su ogni blocco `tool_use` nella risposta, in ordine. Per ciascuno, smista in base al `name` del membro insieme a `toolset_name`, ed esegui quell’azione con l’`input` del blocco sul tuo container o sulla tua macchina virtuale.
    * Prosegui la conversazione con un nuovo messaggio `user` che contenga un blocco `tool_result` per ogni blocco `tool_use`, abbinato tramite `tool_use_id` e ciascuno con la ripetizione di `"toolset_name": "computer"`. Restituisci un’immagine per `screenshot` e `zoom`; per le altre azioni basta un breve testo come `OK`.
    * Se un’azione fallisce, restituisci `is_error: true` per quel blocco e rispondi al resto del batch come descritto in [Azioni batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#batch-actions).
  </Step>

  <Step title="Claude continua finché l’attività non è completata">
    * Claude analizza i risultati degli strumenti per determinare se sono necessarie altre azioni o se l’attività è stata completata.
    * Se Claude determina che sono necessarie altre azioni, risponde con un altro `stop_reason` `tool_use`; torna al passaggio 3.
    * Altrimenti, restituisce una risposta testuale all’utente.
  </Step>
</Steps>

I passaggi 3 e 4, ripetuti senza input dell’utente, formano l’“agent loop” (ciclo dell’agente): Claude risponde con una richiesta di uso degli strumenti e la tua applicazione risponde a Claude con i risultati della valutazione di tale richiesta.

### Azioni batch

Claude può pianificare una breve sequenza di azioni, ad esempio fare clic, digitare e poi acquisire uno screenshot, e restituirle insieme in un’unica risposta. Questa si chiama azione batch; usa la stessa forma di risposta dell’[uso parallelo degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/parallel-tool-use) con una differenza: esegui i blocchi in ordine anziché in modo concorrente.

Una risposta con un batch di tre azioni appare così:

```json
{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [640, 60] }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "name": "type",
      "toolset_name": "computer",
      "input": { "text": "pictures of cats" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ]
}
```

Restituisci un blocco `tool_result` per ogni blocco `tool_use`, abbinato tramite `tool_use_id`, tutti nel messaggio `user` successivo. Ogni risultato per uno strumento membro deve riportare `"toolset_name": "computer"`; un risultato che lo omette, o che nomina un toolset diverso da quello del suo blocco `tool_use`, viene rifiutato. Solo i risultati di `screenshot` e `zoom` necessitano di un’immagine; per gli altri membri basta un breve riscontro testuale come `OK` (`cursor_position` restituisce le coordinate come testo):

```json
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "toolset_name": "computer",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}
```

**Esegui i blocchi in ordine e fermati al primo errore.** Le azioni successive in un batch di solito dipendono da quelle precedenti: il `type` in questo esempio inserisce il testo in qualunque elemento il clic precedente abbia messo a fuoco. Esegui i blocchi in sequenza nell’ordine in cui appaiono in `content` e, se uno fallisce, non eseguire i restanti. Ogni blocco `tool_use` necessita comunque di un `tool_result`, quindi rispondi al batch come segue:

* Per ogni azione riuscita, restituisci il suo risultato normale.
* Per l’azione fallita, restituisci `is_error: true` con una descrizione testuale di ciò che è andato storto.
* Per ogni azione successiva nel batch, restituisci `is_error: true` esattamente con questo testo (lo strumento browser use usa il proprio [testo di interruzione](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#batch-actions)):

```json
{
  "type": "tool_result",
  "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}
```

Claude legge quindi quali azioni sono riuscite, quale è fallita e quali sono state saltate, e ripianifica al turno successivo. Una richiesta che lascia senza risposta qualsiasi blocco `tool_use` del batch viene rifiutata con un `invalid_request_error`, quindi un ciclo dell’agente che legge solo il primo blocco fallisce alla chiamata successiva. Se la tua applicazione chiede a un essere umano di confermare le azioni rilevanti, esegui tale verifica prima che venga eseguito ciascun blocco, perché un batch può completare un’azione in più passaggi all’interno di un singolo turno.

Claude termina tipicamente un batch con `screenshot` in modo da poter osservare il risultato prima di decidere cosa fare dopo. Quando un batch non termina con uno screenshot, la tua applicazione può allegare uno screenshot come blocco `image` aggiuntivo all’ultimo risultato del batch, così che Claude riceva sempre lo stato corrente dello schermo; questo consente di risparmiare un passaggio di andata e ritorno rispetto all’attesa che sia Claude a richiederlo. Puoi anche chiedere a Claude nel prompt di terminare ogni batch con uno screenshot (consulta [Ottimizzare le prestazioni del modello con il prompting](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#optimize-model-performance-with-prompting)).

### L’ambiente di calcolo

Il computer use richiede un ambiente di calcolo isolato (sandbox) in cui Claude possa interagire in sicurezza con applicazioni e con il web. Questo ambiente include:

1. **Display virtuale:** Un server di display X11 virtuale (che usa Xvfb) che esegue il rendering dell’interfaccia desktop che Claude riceve come screenshot e controlla con azioni di mouse/tastiera.

2. **Ambiente desktop:** Un’interfaccia leggera con window manager (Mutter) e pannello (Tint2) in esecuzione su Linux, che fornisce un’interfaccia grafica coerente con cui Claude può interagire.

3. **Applicazioni:** Applicazioni Linux preinstallate come Firefox, LibreOffice, editor di testo e file manager che Claude può usare per completare le attività.

4. **Implementazioni degli strumenti:** Codice di integrazione che traduce le richieste astratte di Claude agli strumenti (come “muovi il mouse” o “acquisisci uno screenshot”) in operazioni effettive nell’ambiente virtuale.

5. **Ciclo dell’agente:** Un programma che gestisce la comunicazione tra Claude e l’ambiente, inviando le azioni di Claude all’ambiente e restituendo i risultati (screenshot, output dei comandi) a Claude.

Quando usi il computer use, Claude non si connette direttamente a questo ambiente. La tua applicazione invece:

1. Riceve le richieste di uso degli strumenti di Claude.
2. Le traduce in azioni nel tuo ambiente di calcolo.
3. Acquisisce i risultati (come screenshot e output dei comandi).
4. Restituisce questi risultati a Claude.

Per garantire sicurezza e isolamento, l’implementazione di riferimento esegue tutto questo all’interno di un container Docker con mappature delle porte appropriate per visualizzare l’ambiente e interagire con esso.

***

## Come implementare il computer use

Stai aggiornando un’integrazione esistente con `computer_20251124`? Inizia da [Migrare da `computer_20251124`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124); il resto di questa sezione si applica sia alle integrazioni nuove sia a quelle migrate.

<Tip>
  L’[implementazione di riferimento del computer use](https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo) è un esempio funzionante completo: un [ambiente containerizzato](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/Dockerfile) adatto al computer use, implementazioni degli [strumenti di computer use](https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo/computer_use_demo/tools), un [ciclo dell’agente](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/computer_use_demo/loop.py) che chiama la Claude API ed esegue gli strumenti, e un’interfaccia web per il container, il ciclo e gli strumenti. Per usare `computer_toolset_20260801`, scegli un [modello che lo supporta](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#availability-feature-support), quindi seleziona il toolset in **Tool Versions** nella barra laterale dell’interfaccia web.
</Tip>

### Comprendere il ciclo dell’agente

Il cuore del computer use è il “ciclo dell’agente”: un ciclo in cui Claude richiede azioni agli strumenti e la tua applicazione le esegue e restituisce i risultati a Claude. Il ciclo usa il client che hai creato nell’[Avvio rapido](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#quick-start), un array `tools` che dichiara solo il toolset computer use, e la funzione di supporto per l’elaborazione delle chiamate agli strumenti descritta in [Implementare lo strumento computer use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#implement-the-computer-use-tool). Se dichiari anche altri strumenti, come gli strumenti bash ed editor di testo dell’Avvio rapido, smista i loro blocchi `tool_use` nello stesso passaggio; la funzione di supporto risponde solo alle chiamate ai membri del computer use, e il ciclo considera completato un turno senza chiamate a cui è stata data risposta. Ecco un esempio semplificato:

<CodeGroup exclude="shell">
  ```python Python
  def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 10):
      """
      Run the computer-use agent loop until Claude stops requesting tools
      or the iteration limit is reached.
      """
      for _ in range(max_iterations):
          response = client.messages.create(
              model=model,
              max_tokens=4096,
              messages=messages,
              tools=TOOLS,
          )

          # Add Claude's response to the conversation history
          messages.append({"role": "assistant", "content": response.content})

          # Run the actions Claude requested, in order, and collect the results
          tool_results = process_tool_calls(response)
          if not tool_results:
              return messages  # No more tool use; task complete

          # Send every result back to Claude in a single user message
          messages.append({"role": "user", "content": tool_results})

      return messages
  ```

  ```typescript TypeScript
  async function samplingLoop(
    model: string,
    messages: Anthropic.MessageParam[],
    maxIterations = 10
  ): Promise<Anthropic.MessageParam[]> {
    // Run the computer-use agent loop until Claude stops requesting tools
    // or the iteration limit is reached.
    for (let iteration = 0; iteration < maxIterations; iteration++) {
      const response = await client.messages.create({
        model,
        max_tokens: 4096,
        messages,
        tools
      });

      // Add Claude's response to the conversation history
      messages.push({ role: "assistant", content: response.content });

      // Run any tools Claude requested and collect results
      const toolResults = processToolCalls(response);
      if (toolResults.length === 0) {
        return messages; // No more tool use; task complete
      }

      // Send tool results back to Claude for the next iteration
      messages.push({ role: "user", content: toolResults });
    }

    return messages;
  }
  ```

  ```csharp C#
  async Task<List<MessageParam>> SamplingLoop(
      Model model,
      List<MessageParam> messages,
      int maxIterations = 10
  )
  {
      // Run the computer-use agent loop until Claude stops requesting tools
      // or the iteration limit is reached.
      for (var iteration = 0; iteration < maxIterations; iteration++)
      {
          var response = await client.Messages.Create(
              new MessageCreateParams
              {
                  Model = model,
                  MaxTokens = 4096,
                  Messages = messages,
                  Tools = tools,
              }
          );

          // Add Claude's response to the conversation history
          messages.Add(
              new AssistantMessageParam
              {
                  Content = response
                      .Content.Select(block => new ContentBlockParam(block.Json))
                      .ToList(),
              }
          );

          // Run any tools Claude requested and collect results
          var toolResults = ProcessToolCalls(response);
          if (toolResults.Count == 0)
          {
              return messages; // No more tool use; task complete
          }

          // Send tool results back to Claude for the next iteration
          messages.Add(new UserMessageParam { Content = toolResults });
      }

      return messages;
  }
  ```

  ```go Go
  // samplingLoop runs the computer-use agent loop until Claude stops
  // requesting tools or the iteration limit is reached.
  func samplingLoop(ctx context.Context, model anthropic.Model, messages []anthropic.MessageParam, maxIterations int) ([]anthropic.MessageParam, error) {
  	for range maxIterations {
  		response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  			Model:     model,
  			MaxTokens: 4096,
  			Messages:  messages,
  			Tools:     tools,
  		})
  		if err != nil {
  			return nil, err
  		}

  		// Add Claude's response to the conversation history
  		messages = append(messages, response.ToParam())

  		// Run the actions Claude requested, in order, and collect the results
  		toolResults := processToolCalls(response)
  		if len(toolResults) == 0 {
  			return messages, nil // No more tool use; task complete
  		}

  		// Send every result back to Claude in a single user message
  		messages = append(messages, anthropic.NewUserMessage(toolResults...))
  	}
  	return messages, nil
  }
  ```

  ```java Java
  /**
   * Run the computer-use agent loop until Claude stops requesting tools
   * or the iteration limit is reached.
   */
  List<MessageParam> samplingLoop(Model model, List<MessageParam> messages, int maxIterations) {
      for (int iteration = 0; iteration < maxIterations; iteration++) {
          Message response = client.messages().create(MessageCreateParams.builder()
              .model(model)
              .maxTokens(4096)
              .messages(messages)
              .addTool(COMPUTER_TOOLSET)
              .build());

          // Add Claude's response to the conversation history
          messages.add(response.toParam());

          // Run any tools Claude requested and collect results
          List<ContentBlockParam> toolResults = processToolCalls(response);
          if (toolResults.isEmpty()) {
              return messages; // No more tool use; task complete
          }

          // Send tool results back to Claude for the next iteration
          messages.add(MessageParam.ofUserOfContentBlockParams(toolResults));
      }
      return messages;
  }
  ```

  ```php PHP
  /**
   * Run the computer-use agent loop until Claude stops requesting tools
   * or the iteration limit is reached.
   */
  function samplingLoop(Model|string $model, array $messages, int $maxIterations = 10): array
  {
      global $client, $tools;

      for ($iteration = 0; $iteration < $maxIterations; $iteration++) {
          $response = $client->messages->create(
              model: $model,
              maxTokens: 4096,
              messages: $messages,
              tools: $tools,
          );

          // Add Claude's response to the conversation history
          $messages[] = MessageParam::with(role: Role::ASSISTANT, content: $response->content);

          // Run any tools Claude requested and collect results
          $toolResults = processToolCalls($response);
          if ($toolResults === []) {
              return $messages; // No more tool use; task complete
          }

          // Send tool results back to Claude for the next iteration
          $messages[] = MessageParam::with(role: Role::USER, content: $toolResults);
      }

      return $messages;
  }
  ```

  ```ruby Ruby
  # Run the computer-use agent loop until Claude stops requesting tools
  # or the iteration limit is reached.
  def sampling_loop(model, messages, max_iterations: 10)
    max_iterations.times do
      response = CLIENT.messages.create(
        model: model,
        max_tokens: 4096,
        messages: messages,
        tools: TOOLS
      )

      # Add Claude's response to the conversation history
      messages << { role: "assistant", content: response.content }

      # Run the actions Claude requested, in order, and collect the results
      tool_results = process_tool_calls(response)
      return messages if tool_results.empty? # No more tool use; task complete

      # Send every result back to Claude in a single user message
      messages << { role: "user", content: tool_results }
    end

    messages
  end
  ```
</CodeGroup>

Il ciclo continua finché Claude non risponde senza richiedere alcuno strumento (completamento dell’attività) oppure finché non viene raggiunto il limite massimo di iterazioni. Questa salvaguardia previene potenziali cicli infiniti che potrebbero comportare costi API imprevisti.

### Ottimizzare le prestazioni del modello con il prompting

1. Specifica attività ben definite e fornisci istruzioni esplicite per ogni passaggio.
2. A volte Claude si comporta come se le sue azioni fossero riuscite senza verificarne esplicitamente i risultati. Per evitarlo, puoi fornire a Claude il prompt `After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. State in one sentence what the screenshot shows and whether the step succeeded. If it didn't, try again. Only when you confirm a step was executed correctly should you move on to the next one.`
3. Alcuni elementi dell’interfaccia (come menu a discesa e barre di scorrimento) potrebbero essere difficili da manipolare per Claude con i movimenti del mouse. Se riscontri questo problema, prova a chiedere al modello di usare le scorciatoie da tastiera.
4. Per attività ripetibili o interazioni con l’interfaccia, includi nel prompt screenshot di esempio e chiamate agli strumenti relative a risultati positivi.
5. Se hai bisogno che il modello effettui l’accesso, forniscigli nome utente e password nel prompt all’interno di tag XML come `<robot_credentials>`. L’uso del computer use all’interno di applicazioni che richiedono l’accesso aumenta il rischio di esiti negativi a causa della prompt injection. Consulta [Mitigare jailbreak e prompt injection](https://platform.claude.com/docs/it/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks) prima di fornire al modello le credenziali di accesso.
6. Quando costruisci l’array `content` di un turno utente, posiziona il testo dell’istruzione *prima* dell’immagine dello screenshot. Fornire la descrizione del target prima che l’immagine venga elaborata migliora la precisione dei clic.
7. Claude usa l’azione `zoom` per ispezionare una regione a piena risoluzione quando gli vengono chiesti testi piccoli o elementi specifici dell’interfaccia che non sono leggibili alla risoluzione predefinita dello screenshot, come nomi di file in una barra laterale, titoli delle schede, testo della barra di stato, numeri di riga o etichette dei pulsanti. Se Claude non esegue lo zoom quando te lo aspetti, chiedi informazioni su una regione o un elemento specifico anziché sullo schermo nel suo insieme.
8. Se vuoi che ogni [azione batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#batch-actions) termini con uno screenshot, indicalo nel prompt di sistema, ad esempio `End each group of actions with a screenshot so you can verify the result before continuing.`

Se incontri ripetutamente un insieme chiaro di problemi, o conosci in anticipo le attività che Claude deve completare, fornisci a Claude suggerimenti o istruzioni espliciti al riguardo nel prompt di sistema.

Per gli agenti che si estendono su più sessioni, esegui una verifica end-to-end all’inizio di ogni sessione, non solo dopo l’implementazione. I controlli basati sul browser individuano regressioni delle sessioni precedenti che la sola revisione a livello di codice non rileva. Consulta [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) per i dettagli.

### Prompt di sistema

Quando includi lo strumento computer use in una richiesta, l’API genera un prompt di sistema specifico per il computer use. È simile al [prompt di sistema per l’uso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/define-tools#tool-use-system-prompt) ma inizia con:

> You have access to a set of functions you can use to answer the user’s question. This includes access to a sandboxed computing environment. You do NOT currently have the ability to inspect files or interact with external resources, except by invoking the below functions.

Come per il normale uso degli strumenti, il parametro `system` fornito dall’utente viene comunque rispettato e utilizzato nella costruzione del prompt di sistema combinato.

### Azioni disponibili

Ogni azione è uno strumento membro del toolset computer use: Claude nomina il membro in un blocco `tool_use` che riporta `"toolset_name": "computer"`, e l’`input` del blocco contiene solo i parametri di quel membro, senza alcun campo `action`. Il toolset ha 17 strumenti membri:

| Membro                                                        | Input                                                                                                                                                                                                                             | Descrizione                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `screenshot`                                                  | Nessuno (`{}`)                                                                                                                                                                                                                    | Acquisisce l’intero display e lo restituisce come immagine.                                                                                                                                                                                                                                                                                |
| `zoom`                                                        | `region`: `[x0, y0, x1, y1]`, gli angoli superiore sinistro e inferiore destro dell’area da ispezionare                                                                                                                           | Acquisisce solo quella regione del display a piena risoluzione e la restituisce come immagine, ridimensionata per rientrare nelle dimensioni abituali dei tuoi screenshot mantenendone le proporzioni. Ciò consente a Claude di leggere testo piccolo o interfacce dense che non sono leggibili in uno screenshot completo ridimensionato. |
| `left_click`                                                  | `coordinate` (facoltativo): `[x, y]`; `text` (facoltativo): tasti modificatori da tenere premuti durante il clic: `shift`, `ctrl`, `alt`, `super` (il tasto Comando o Windows), o una combinazione unita da `+` come `ctrl+shift` | Fa clic con il pulsante sinistro del mouse in `coordinate`, oppure nella posizione corrente del cursore quando `coordinate` è omesso.                                                                                                                                                                                                      |
| `right_click`, `middle_click`, `double_click`, `triple_click` | Come `left_click`                                                                                                                                                                                                                 | Altri pulsanti del mouse e clic multipli.                                                                                                                                                                                                                                                                                                  |
| `left_click_drag`                                             | `start_coordinate`: `[x, y]`; `coordinate`: `[x, y]`; `text` (facoltativo): tasti modificatori                                                                                                                                    | Preme in `start_coordinate`, trascina fino a `coordinate` e rilascia.                                                                                                                                                                                                                                                                      |
| `mouse_move`                                                  | `coordinate`: `[x, y]`                                                                                                                                                                                                            | Sposta il cursore senza fare clic, ad esempio per passare sopra un elemento.                                                                                                                                                                                                                                                               |
| `left_mouse_down`, `left_mouse_up`                            | Nessuno (`{}`)                                                                                                                                                                                                                    | Preme o rilascia il pulsante sinistro del mouse nella posizione corrente del cursore, per trascinamenti che `left_click_drag` non può esprimere. Sposta prima il cursore con `mouse_move`.                                                                                                                                                 |
| `cursor_position`                                             | Nessuno (`{}`)                                                                                                                                                                                                                    | Riporta la posizione `[x, y]` corrente del cursore come testo.                                                                                                                                                                                                                                                                             |
| `scroll`                                                      | `scroll_direction`: `"up"`, `"down"`, `"left"` o `"right"`; `scroll_amount`: numero di scatti della rotellina; `coordinate` (facoltativo): `[x, y]`; `text` (facoltativo): tasti modificatori                                     | Scorre in `coordinate`, oppure nella posizione corrente del cursore.                                                                                                                                                                                                                                                                       |
| `type`                                                        | `text`: la stringa da digitare                                                                                                                                                                                                    | Digita testo letterale nel punto in cui si trova il focus della tastiera.                                                                                                                                                                                                                                                                  |
| `key`                                                         | `text`: un tasto o una combinazione unita da `+` come `"Return"`, `"ctrl+s"` o `"alt+Tab"`; `repeat` (facoltativo): da 1 a 100, valore predefinito 1                                                                              | Preme un tasto o una combinazione di tasti, `repeat` volte.                                                                                                                                                                                                                                                                                |
| `hold_key`                                                    | `text`: un tasto o una combinazione; `duration`: secondi, fino a 300                                                                                                                                                              | Tiene premuto un tasto per la durata indicata.                                                                                                                                                                                                                                                                                             |
| `wait`                                                        | `duration`: secondi, fino a 300                                                                                                                                                                                                   | Attende prima dell’azione successiva, ad esempio mentre un’applicazione si carica.                                                                                                                                                                                                                                                         |

Tieni presente quanto segue quando implementi i membri:

* **Le coordinate sono in pixel dello screenshot.** Ogni valore di `coordinate`, `start_coordinate` e `region`, e la posizione riportata da `cursor_position`, è nello spazio in pixel degli screenshot dell’intero display che restituisci, con l’origine in alto a sinistra. Le immagini di zoom non cambiano questo aspetto: dopo uno `zoom`, Claude esprime comunque le coordinate nello spazio dello screenshot completo, mai rispetto all’immagine ingrandita. Se riduci gli screenshot prima di restituirli, riporta le coordinate di Claude alla scala originale prima di applicarle al display reale (consulta [Dimensiona gli screenshot per rispettare i limiti delle immagini](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)).
* **Tutti i membri sono abilitati per impostazione predefinita, incluso `zoom`.** Se il tuo ambiente non può produrre immagini di zoom, escludi il membro con `configs` (consulta [Parametri dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#tool-parameters)) anziché lasciarlo abilitato e restituire errori. Se Claude chiama un membro che hai escluso o che non implementi, restituisci un `tool_result` con `is_error: true` per quel blocco.
* **Smista in base alla coppia (`toolset_name`, `name`).** È `toolset_name` che contrassegna un blocco come azione del computer: uno strumento personalizzato nella stessa richiesta può condividere il nome di un membro, e una versione successiva del toolset può aggiungere membri (consulta [Toolset client](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets)).

<Accordion title="Azioni di esempio">
  Ogni esempio è un blocco `tool_use` completo così come appare nella risposta di Claude.

  Shift+clic in una posizione, ad esempio per estendere una selezione. A differenza di `hold_key`, `text` tiene premuti i modificatori solo per la durata di quel clic o scorrimento:

  ```json
  {
    "type": "tool_use",
    "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
    "name": "left_click",
    "toolset_name": "computer",
    "input": { "coordinate": [500, 300], "text": "shift" }
  }
  ```

  Trascinare da un punto a un altro:

  ```json
  {
    "type": "tool_use",
    "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
    "name": "left_click_drag",
    "toolset_name": "computer",
    "input": {
      "start_coordinate": [200, 300],
      "coordinate": [600, 300]
    }
  }
  ```

  Scorrere verso il basso di tre scatti della rotellina:

  ```json
  {
    "type": "tool_use",
    "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
    "name": "scroll",
    "toolset_name": "computer",
    "input": {
      "coordinate": [500, 400],
      "scroll_direction": "down",
      "scroll_amount": 3
    }
  }
  ```

  Premere Tab quattro volte:

  ```json
  {
    "type": "tool_use",
    "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
    "name": "key",
    "toolset_name": "computer",
    "input": { "text": "Tab", "repeat": 4 }
  }
  ```

  Eseguire lo zoom per ispezionare una regione a piena risoluzione:

  ```json
  {
    "type": "tool_use",
    "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
    "name": "zoom",
    "toolset_name": "computer",
    "input": { "region": [100, 200, 400, 350] }
  }
  ```

  Riportare la posizione del cursore. Rispondi a questa chiamata con un breve risultato testuale che indichi la posizione in pixel dello screenshot, ad esempio `X=512, Y=384`:

  ```json
  {
    "type": "tool_use",
    "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
    "name": "cursor_position",
    "toolset_name": "computer",
    "input": {}
  }
  ```
</Accordion>

### Parametri dello strumento

La voce del toolset nell’array `tools` accetta quattro parametri; le regole che condividono con il toolset browser use sono elencate in [Toolset client](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets).

| Parametro         | Obbligatorio | Descrizione                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`            | Sì           | `computer_toolset_20260801`                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `configs`         | No           | Impostazioni per membro indicizzate per nome del membro; ogni membro accetta `enabled` (valore predefinito `true` per tutti e 17, incluso `zoom`) e `defer_loading` (valore predefinito `false`, per la [ricerca degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-search-tool#deferred-tool-loading)), e i membri che ometti mantengono i valori predefiniti.                                                                               |
| `cache_control`   | No           | Breakpoint della [cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching) in corrispondenza della definizione del toolset; solo sulla voce. Un breakpoint su qualsiasi blocco `tool_use` o `tool_result` in un batch ha effetto alla fine di quel batch; consulta [Uso degli strumenti con la cache dei prompt](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions). |
| `allowed_callers` | No           | Solo `["direct"]`.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

Ad esempio, questa voce esclude `zoom` per un ambiente che non lo implementa e imposta un breakpoint di cache in corrispondenza della definizione del toolset:

```json
{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}
```

Se il tuo ciclo dell’agente può eseguire una sola azione per ogni passaggio di andata e ritorno, imposta `disable_parallel_tool_use` su `true` in `tool_choice`; Claude restituisce quindi al massimo un blocco `tool_use` di un membro per ogni turno (consulta [Disabilitare l’uso parallelo degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/parallel-tool-use#disable-parallel-tool-use)).

La voce rifiuta questi parametri delle versioni precedenti dello strumento, e una richiesta che ne include uno qualsiasi restituisce un `invalid_request_error`:

* `name`: i nomi dei membri sono fissati dalla versione del toolset.
* `display_width_px`, `display_height_px` e `display_number`: le coordinate sono sempre nello spazio in pixel degli screenshot che restituisci.
* `enable_zoom`: lo zoom è uno strumento membro che controlli tramite `configs`.

Inoltre la voce non può essere dichiarata nella stessa richiesta di una voce `computer_20251124` o di un altro strumento chiamato `computer`. Per `strict`, `input_examples`, il posizionamento di `defer_loading`, `tool_choice`, lo streaming e le restrizioni sui chiamanti, consulta [Toolset client](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets).

### Combinazione con il ragionamento

Per combinare il computer use con il ragionamento, consulta [Ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking).

<Tip>
  Per lo strumento `computer_20251124`, i benchmark interni sui modelli che lo usano suggeriscono queste impostazioni di `effort`:

  * **Claude Opus 4.7:** usa `high` come impostazione predefinita; usa `low` per carichi di lavoro ad alto throughput o sensibili ai costi.
  * **Claude Sonnet 4.6 e Claude Opus 4.6:** usa `medium` come impostazione predefinita (miglior rapporto tra precisione e costo). Evita `max`, che aumenta il costo in token senza migliorare la precisione nelle attività sull’interfaccia. Su questi modelli, `low` usa *meno* token di output rispetto alla disattivazione completa del ragionamento (meno errori significano meno tentativi), il che lo rende un’ottima opzione per i cicli sensibili ai costi.
</Tip>

### Integrare il computer use con altri strumenti

Per aggiungere altri strumenti insieme al computer use, includili nello stesso array `tools`. La sezione [Avvio rapido](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#quick-start) mostra questo schema con lo [strumento bash](https://platform.claude.com/docs/it/agents-and-tools/tool-use/bash-tool) e lo [strumento editor di testo](https://platform.claude.com/docs/it/agents-and-tools/tool-use/text-editor-tool). Puoi aggiungere le tue [definizioni di strumenti personalizzati](https://platform.claude.com/docs/it/agents-and-tools/tool-use/define-tools) allo stesso modo.

Per le attività che restano all’interno delle pagine web, puoi anche [dichiarare lo strumento browser use nella stessa richiesta](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#combine-with-other-tools). I due toolset funzionano in modo indipendente, ciascuno nel proprio sistema di coordinate. Il valore di `toolset_name` distingue le chiamate ai membri che condividono un nome, come `screenshot` o `key`.

### Creare un ambiente di computer use personalizzato

L’[implementazione di riferimento](https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo) ha lo scopo di aiutarti a iniziare con il computer use. Include tutti i componenti necessari affinché Claude possa usare un computer. Tuttavia, puoi creare il tuo ambiente per il computer use in base alle tue esigenze. Ti servono:

* Un ambiente virtualizzato o containerizzato adatto al computer use con Claude
* Un’implementazione delle azioni dello strumento computer use
* Un ciclo dell’agente che interagisca con la Claude API ed esegua i risultati `tool_use` usando le tue implementazioni degli strumenti
* Un’API o un’interfaccia utente che consenta l’input dell’utente per avviare il ciclo dell’agente

### Implementare lo strumento computer use

Lo strumento computer use è implementato come uno strumento senza schema. Quando usi questo strumento, non è necessario fornire uno schema di input come per gli altri strumenti; lo schema è integrato nel modello di Claude e non può essere modificato.

<Steps>
  <Step title="Configura il tuo ambiente di calcolo">
    Crea un display virtuale o connettiti a un display esistente con cui Claude interagisce. In genere ciò comporta la configurazione di Xvfb (X Virtual Framebuffer) o di una tecnologia simile.
  </Step>

  <Step title="Implementa i gestori delle azioni">
    Crea funzioni per gestire ogni tipo di azione che Claude potrebbe richiedere:

    <CodeGroup exclude="shell">
      ```python Python
      # Placeholder image data; a real executor captures the screen and returns the PNG bytes
      PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="


      def capture_screenshot() -> list[ImageBlockParam]:
          # screenshot answers with an image block rather than text: return the result content list
          return [
              {
                  "type": "image",
                  "source": {
                      "type": "base64",
                      "media_type": "image/png",
                      "data": PLACEHOLDER_PNG,
                  },
              }
          ]


      def click(coordinate=None):
          if coordinate is None:
              return "clicked at current cursor"
          x, y = coordinate
          return f"clicked at ({x}, {y})"


      def type_text(text):
          return f"typed: {text}"


      def handle_computer_action(name, tool_input):
          match name:
              case "screenshot":
                  return capture_screenshot()
              case "left_click":
                  # coordinate is optional; without it, click where the cursor already is
                  return click(tool_input.get("coordinate"))
              case "type":
                  return type_text(tool_input["text"])
          # Handle other actions as needed
          raise ValueError(f"Unknown or unimplemented member: {name}")
      ```

      ```typescript TypeScript
      // Placeholder image data; a real executor captures the screen as PNG bytes
      const PLACEHOLDER_PNG =
        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";

      function captureScreenshot(): Anthropic.ImageBlockParam[] {
        // screenshot answers with an image block rather than text
        return [
          {
            type: "image",
            source: {
              type: "base64",
              media_type: "image/png",
              data: PLACEHOLDER_PNG
            }
          }
        ];
      }

      function clickAt(x: number, y: number): string {
        return `clicked at (${x}, ${y})`;
      }

      function clickAtCursor(): string {
        return "clicked at the current cursor position";
      }

      function typeText(text: string): string {
        return `typed: ${text}`;
      }

      function handleComputerAction(
        action: string,
        input: unknown
      ): string | Anthropic.ImageBlockParam[] {
        const params: object = typeof input === "object" && input !== null ? input : {};
        switch (action) {
          case "screenshot":
            return captureScreenshot();
          case "left_click":
            // coordinate is optional on the toolset; without one, click at the cursor
            if ("coordinate" in params && Array.isArray(params.coordinate)) {
              const [x, y] = params.coordinate;
              return clickAt(x, y);
            }
            return clickAtCursor();
          case "type":
            if ("text" in params) {
              return typeText(String(params.text));
            }
            break;
        }
        // Handle other actions as needed
        throw new Error(`Unknown or unimplemented member: ${action}`);
      }
      ```

      ```csharp C#
      // Placeholder image data; a real executor captures the screen and returns the PNG bytes
      const string PlaceholderPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";

      // screenshot answers with an image block rather than text: return the result content list
      List<Block> CaptureScreenshot() =>
          [
              new ImageBlockParam(
                  new Base64ImageSource { Data = PlaceholderPng, MediaType = MediaType.ImagePng }
              ),
          ];

      string ClickAt(int x, int y) => $"clicked at ({x}, {y})";

      string ClickAtCursor() => "clicked at the current cursor position";

      string TypeText(string text) => $"typed: {text}";

      ToolResultBlockParamContent HandleComputerAction(
          string action,
          IReadOnlyDictionary<string, JsonElement> input
      ) =>
          action switch
          {
              "screenshot" => CaptureScreenshot(),
              // coordinate is optional on click members; without it, click where the cursor is
              "left_click" when input.TryGetValue("coordinate", out var xy) => ClickAt(
                  xy[0].GetInt32(),
                  xy[1].GetInt32()
              ),
              "left_click" => ClickAtCursor(),
              "type" => TypeText(input["text"].GetString()!),
              // Handle other actions as needed
              _ => throw new NotSupportedException($"Unknown or unimplemented member: {action}"),
          };
      ```

      ```go Go
      // placeholderPNG stands in for a real capture: an executor returns the
      // screen as base64-encoded PNG data.
      const placeholderPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="

      // captureScreenshot returns an image block rather than text.
      func captureScreenshot() []anthropic.ToolResultBlockParamContentUnion {
      	return []anthropic.ToolResultBlockParamContentUnion{{
      		OfImage: &anthropic.ImageBlockParam{
      			Source: anthropic.ImageBlockParamSourceUnion{
      				OfBase64: &anthropic.Base64ImageSourceParam{
      					MediaType: anthropic.Base64ImageSourceMediaTypeImagePNG,
      					Data:      placeholderPNG,
      				},
      			},
      		},
      	}}
      }

      // textContent wraps text as tool_result content.
      func textContent(text string) []anthropic.ToolResultBlockParamContentUnion {
      	return []anthropic.ToolResultBlockParamContentUnion{
      		{OfText: &anthropic.TextBlockParam{Text: text}},
      	}
      }

      func clickAt(x, y int) string {
      	return fmt.Sprintf("clicked at (%d, %d)", x, y)
      }

      func clickAtCursor() string {
      	return "clicked at the current cursor position"
      }

      func typeText(text string) string {
      	return fmt.Sprintf("typed: %s", text)
      }

      func handleComputerAction(action string, params map[string]any) ([]anthropic.ToolResultBlockParamContentUnion, error) {
      	switch action {
      	case "screenshot":
      		return captureScreenshot(), nil
      	case "left_click":
      		// coordinate is optional; without it, click where the cursor already is
      		coord, ok := params["coordinate"].([]any)
      		if !ok {
      			return textContent(clickAtCursor()), nil
      		}
      		if len(coord) == 2 {
      			x, xok := coord[0].(float64)
      			y, yok := coord[1].(float64)
      			if xok && yok {
      				return textContent(clickAt(int(x), int(y))), nil
      			}
      		}
      	case "type":
      		if text, ok := params["text"].(string); ok {
      			return textContent(typeText(text)), nil
      		}
      	// Handle other actions as needed
      	default:
      		return nil, fmt.Errorf("unknown or unimplemented member: %s", action)
      	}
      	// Reached when a member's input is missing a field or a field has the wrong type
      	return nil, fmt.Errorf("invalid input for %s", action)
      }
      ```

      ```java Java
      /** Placeholder pixels; a real executor captures the screen and base64-encodes the PNG. */
      static final String PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";

      ToolResultBlockParam.Content captureScreenshot() {
          ImageBlockParam image = ImageBlockParam.builder()
              .source(Base64ImageSource.builder()
                  .mediaType(Base64ImageSource.MediaType.IMAGE_PNG)
                  .data(PLACEHOLDER_PNG)
                  .build())
              .build();
          return ToolResultBlockParam.Content.ofBlocks(
              List.of(ToolResultBlockParam.Content.Block.ofImage(image)));
      }

      String clickAt(long x, long y) {
          return "clicked at (" + x + ", " + y + ")";
      }

      String clickAtCursor() {
          return "clicked at current cursor";
      }

      String typeText(String text) {
          return "typed: " + text;
      }

      /** Runs one computer toolset member; {@code action} is the tool_use block's name. */
      ToolResultBlockParam.Content handleComputerAction(String action, Map<String, JsonValue> input) {
          if (action.equals("screenshot")) {
              return captureScreenshot(); // the one member here that answers with an image block
          }
          String output = switch (action) {
              case "left_click" -> {
                  JsonValue coordinate = input.get("coordinate"); // optional on the toolset
                  if (coordinate == null) {
                      yield clickAtCursor();
                  }
                  List<JsonValue> point = (List<JsonValue>) coordinate.asArray().get();
                  long x = ((Number) point.get(0).asNumber().get()).longValue();
                  long y = ((Number) point.get(1).asNumber().get()).longValue();
                  yield clickAt(x, y);
              }
              case "type" -> typeText(input.get("text").asStringOrThrow());
              // Handle other actions as needed
              default -> throw new UnsupportedOperationException("Unknown or unimplemented member: " + action);
          };
          return ToolResultBlockParam.Content.ofString(output);
      }
      ```

      ```php PHP
      // Stand-in for real PNG bytes; a real executor captures the screen
      const PLACEHOLDER_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';

      function captureScreenshot(): array
      {
          // screenshot answers with an image block rather than text, so return the result content list
          $image = [
              'type' => 'image',
              'source' => ['type' => 'base64', 'media_type' => 'image/png', 'data' => PLACEHOLDER_PNG],
          ];

          return [$image];
      }

      function clickAt(?array $coordinate): string
      {
          // left_click may omit coordinate, in which case the click lands where the cursor already is
          if ($coordinate === null) {
              return 'clicked at current cursor';
          }
          [$x, $y] = $coordinate;

          return "clicked at ({$x}, {$y})";
      }

      function typeText(string $text): string
      {
          return "typed: {$text}";
      }

      function handleComputerAction(string $name, array $input): string|array
      {
          return match ($name) {
              'screenshot' => captureScreenshot(),
              'left_click' => clickAt($input['coordinate'] ?? null),
              'type' => typeText($input['text']),
              // Handle other actions as needed
              default => throw new \RuntimeException("Unknown or unimplemented member: {$name}"),
          };
      }
      ```

      ```ruby Ruby
      # Stand-in image data; a real executor captures the screen as a PNG.
      PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="

      # screenshot answers with an image block rather than text
      def capture_screenshot
        [
          {
            type: "image",
            source: { type: "base64", media_type: "image/png", data: PLACEHOLDER_PNG }
          }
        ]
      end

      def click(coordinate = nil)
        return "clicked at current cursor" if coordinate.nil?

        x, y = coordinate
        "clicked at (#{x}, #{y})"
      end

      def type_text(text)
        "typed: #{text}"
      end

      def handle_computer_action(name, input)
        case name
        when "screenshot"
          capture_screenshot
        when "left_click"
          # coordinate is optional; without it, click where the cursor already is
          click(input[:coordinate])
        when "type"
          type_text(input[:text])
        # Handle other actions as needed
        else
          raise ArgumentError, "Unknown or unimplemented member: #{name}"
        end
      end
      ```
    </CodeGroup>
  </Step>

  <Step title="Elabora le chiamate agli strumenti di Claude">
    Estrai ed esegui le chiamate agli strumenti dalle risposte di Claude:

    <CodeGroup exclude="shell">
      ```python Python
      NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."


      def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
          """
          Run the computer actions in Claude's response in order and answer each
          one. After the first failure the rest are skipped, because Claude planned
          them assuming the earlier actions succeeded.
          """
          tool_results: list[ToolResultBlockParam] = []
          failed = False
          for block in response.content:
              # Only the computer toolset is declared; route other tools here if you add them
              if block.type != "tool_use" or block.toolset_name != "computer":
                  continue
              result: ToolResultBlockParam = {
                  "type": "tool_result",
                  "tool_use_id": block.id,
                  "toolset_name": "computer",
              }
              if failed:
                  result["content"] = NOT_EXECUTED
                  result["is_error"] = True
              else:
                  try:
                      # A string, or a list of content blocks such as the screenshot image
                      result["content"] = handle_computer_action(block.name, block.input)
                  except Exception as err:
                      result["content"] = f"Error: {err}"
                      result["is_error"] = True
                      failed = True
              tool_results.append(result)
          return tool_results
      ```

      ```typescript TypeScript
      const HALT_TEXT = "Not executed: an earlier computer action in this turn failed.";

      function computerResult(
        toolUseId: string,
        content: string | Anthropic.ImageBlockParam[],
        isError?: boolean
      ): Anthropic.ToolResultBlockParam {
        return {
          type: "tool_result",
          tool_use_id: toolUseId,
          toolset_name: "computer",
          content,
          is_error: isError
        };
      }

      function processToolCalls(response: Anthropic.Message): Anthropic.ToolResultBlockParam[] {
        const toolResults: Anthropic.ToolResultBlockParam[] = [];
        let failed = false;
        for (const block of response.content) {
          if (block.type !== "tool_use") {
            continue;
          }
          if (block.toolset_name !== "computer") {
            // This example declares only the computer toolset; route other tools
            // here if you add them.
            continue;
          }
          if (failed) {
            // A batch stops at its first failure; answer later actions without running them
            toolResults.push(computerResult(block.id, HALT_TEXT, true));
            continue;
          }
          try {
            // A string, or the image block list that screenshot returns
            const result = handleComputerAction(block.name, block.input);
            toolResults.push(computerResult(block.id, result));
          } catch (error) {
            failed = true;
            const message = error instanceof Error ? error.message : String(error);
            toolResults.push(computerResult(block.id, `Error: ${message}`, true));
          }
        }
        return toolResults;
      }
      ```

      ```csharp C#
      const string HaltText = "Not executed: an earlier computer action in this turn failed.";

      List<ContentBlockParam> ProcessToolCalls(Message response)
      {
          List<ContentBlockParam> toolResults = [];
          var failed = false;
          foreach (var block in response.Content)
          {
              if (!block.TryPickToolUse(out var toolUse))
              {
                  continue;
              }

              if (toolUse.ToolsetName != "computer")
              {
                  // This example declares only the computer toolset; route other tools
                  // here if you add them.
                  continue;
              }

              if (failed)
              {
                  // A batch stops at its first failure; answer later actions without running them
                  toolResults.Add(
                      new ToolResultBlockParam(toolUse.ID)
                      {
                          Content = HaltText,
                          IsError = true,
                          ToolsetName = "computer",
                      }
                  );
                  continue;
              }

              try
              {
                  // A string, or the image block list that screenshot returns
                  var result = HandleComputerAction(toolUse.Name, toolUse.Input);
                  toolResults.Add(
                      new ToolResultBlockParam(toolUse.ID) { Content = result, ToolsetName = "computer" }
                  );
              }
              catch (Exception e)
              {
                  failed = true;
                  toolResults.Add(
                      new ToolResultBlockParam(toolUse.ID)
                      {
                          Content = $"Error: {e.Message}",
                          IsError = true,
                          ToolsetName = "computer",
                      }
                  );
              }
          }
          return toolResults;
      }
      ```

      ```go Go
      const notExecuted = "Not executed: an earlier computer action in this turn failed."

      // computerToolResult builds the result for one computer action. Unlike an
      // ordinary tool result, it must echo the toolset name.
      func computerToolResult(toolUseID string, content []anthropic.ToolResultBlockParamContentUnion, isError bool) anthropic.ContentBlockParamUnion {
      	result := anthropic.ToolResultBlockParam{
      		ToolUseID:   toolUseID,
      		ToolsetName: anthropic.String("computer"),
      		Content:     content,
      	}
      	if isError {
      		result.IsError = anthropic.Bool(true)
      	}
      	return anthropic.ContentBlockParamUnion{OfToolResult: &result}
      }

      // processToolCalls runs the computer actions in Claude's response in order and
      // builds one tool_result for each tool_use block. After the first failure it skips
      // the rest: Claude planned them assuming the earlier actions succeeded.
      func processToolCalls(response *anthropic.Message) []anthropic.ContentBlockParamUnion {
      	var toolResults []anthropic.ContentBlockParamUnion
      	failed := false
      	for _, block := range response.Content {
      		switch variant := block.AsAny().(type) {
      		case anthropic.ToolUseBlock:
      			// This example declares only the computer toolset; route other tools here if you add them.
      			if variant.ToolsetName != "computer" {
      				continue
      			}
      			if failed {
      				toolResults = append(toolResults, computerToolResult(variant.ID, textContent(notExecuted), true))
      				continue
      			}
      			var input map[string]any
      			var content []anthropic.ToolResultBlockParamContentUnion
      			err := json.Unmarshal(variant.Input, &input)
      			if err == nil {
      				// Text, or the image block that screenshot returns
      				content, err = handleComputerAction(variant.Name, input)
      			}
      			if err != nil {
      				failed = true
      				content = textContent("Error: " + err.Error())
      			}
      			toolResults = append(toolResults, computerToolResult(variant.ID, content, err != nil))
      		}
      	}
      	return toolResults
      }
      ```

      ```java Java
      /** The exact text the toolset contract prescribes for member calls skipped after a failure. */
      static final String HALT_TEXT = "Not executed: an earlier computer action in this turn failed.";

      /** Every result answering a computer toolset member echoes toolset_name. */
      ToolResultBlockParam.Builder computerResult(ToolUseBlock toolUse) {
          return ToolResultBlockParam.builder()
              .toolUseId(toolUse.id())
              .toolsetName("computer");
      }

      /**
       * Run the computer actions in Claude's response in order and build one
       * tool_result for each tool_use block. After the first failure, skip the rest:
       * Claude planned them assuming the earlier actions succeeded.
       */
      List<ContentBlockParam> processToolCalls(Message response) {
          List<ContentBlockParam> toolResults = new ArrayList<>();
          boolean failed = false;
          for (ContentBlock block : response.content()) {
              // This example declares only the computer toolset; route other tools here if you add them.
              if (!block.isToolUse() || !block.asToolUse().toolsetName().equals(Optional.of("computer"))) {
                  continue;
              }
              ToolUseBlock toolUse = block.asToolUse();
              ToolResultBlockParam result;
              if (failed) {
                  result = computerResult(toolUse)
                      .content(HALT_TEXT)
                      .isError(true)
                      .build();
              } else {
                  try {
                      Map<String, JsonValue> input =
                          (Map<String, JsonValue>) toolUse._input().asObject().get();
                      // A string, or the image block that screenshot returns
                      ToolResultBlockParam.Content output = handleComputerAction(toolUse.name(), input);
                      result = computerResult(toolUse)
                          .content(output)
                          .build();
                  } catch (RuntimeException e) {
                      failed = true;
                      result = computerResult(toolUse)
                          .content("Error: " + e.getMessage())
                          .isError(true)
                          .build();
                  }
              }
              toolResults.add(ContentBlockParam.ofToolResult(result));
          }
          return toolResults;
      }
      ```

      ```php PHP
      const HALT_TEXT = 'Not executed: an earlier computer action in this turn failed.';

      function processToolCalls(Message $response): array
      {
          $toolResults = [];
          $failed = false;
          foreach ($response->content as $block) {
              // This example declares only the computer toolset; route other tools here if you add them.
              if (!($block instanceof \Anthropic\Messages\ToolUseBlock) || $block->toolsetName !== 'computer') {
                  continue;
              }
              $result = ['type' => 'tool_result', 'tool_use_id' => $block->id, 'toolset_name' => 'computer'];
              if ($failed) {
                  // A batch stops at its first failure; the remaining actions are answered without running
                  $toolResults[] = [...$result, 'content' => HALT_TEXT, 'is_error' => true];
                  continue;
              }
              try {
                  // A string, or the image block list that screenshot returns
                  $toolResults[] = [...$result, 'content' => handleComputerAction($block->name, $block->input)];
              } catch (\Throwable $e) {
                  $failed = true;
                  $toolResults[] = [...$result, 'content' => 'Error: ' . $e->getMessage(), 'is_error' => true];
              }
          }

          return $toolResults;
      }
      ```

      ```ruby Ruby
      NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."

      # Run the computer actions in Claude's response in order and build one
      # tool_result for each tool_use block. After the first failure, skip the rest:
      # Claude planned them assuming the earlier actions succeeded.
      def process_tool_calls(response)
        tool_results = []
        failed = false
        response.content.each do |block|
          # This example declares only the computer toolset; route other tools here
          # if you add them.
          next unless block.is_a?(Anthropic::Models::ToolUseBlock) && block.toolset_name == "computer"

          result = { type: "tool_result", tool_use_id: block.id, toolset_name: "computer" }
          if failed
            result.update(content: NOT_EXECUTED, is_error: true)
          else
            begin
              # A String, or the image content blocks that screenshot returns
              result[:content] = handle_computer_action(block.name, block.input)
            rescue => e
              result.update(content: "Error: #{e.message}", is_error: true)
              failed = true
            end
          end
          tool_results << result
        end
        tool_results
      end
      ```
    </CodeGroup>
  </Step>

  <Step title="Implementa il ciclo dell’agente">
    Racchiudi i due passaggi precedenti in un ciclo che invia nuovamente i risultati e si ripete finché Claude non restituisce più chiamate agli strumenti membri; [Comprendere il ciclo dell’agente](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#understanding-the-agentic-loop) mostra questo ciclo.
  </Step>
</Steps>

### Gestire gli errori

Segnala un’azione fallita a Claude come `tool_result` con `is_error: true` e una breve descrizione, e includi `"toolset_name": "computer"` come per qualsiasi altro risultato di un membro. Se l’azione fallita faceva parte di un’[azione batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#batch-actions), rispondi ai blocchi restanti del batch con il testo di interruzione mostrato in quella sezione anziché eseguirli.

Ad esempio, quando l’acquisizione dello screenshot fallisce:

```json
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "toolset_name": "computer",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}
```

Usa la stessa forma per le coordinate al di fuori dei limiti del display e per le azioni che non riescono a essere eseguite, con un messaggio che indichi cosa è andato storto.

### Dimensiona gli screenshot per rispettare i limiti delle immagini

Gli screenshot e le immagini di zoom che restituisci al toolset di computer use devono già rientrare nei [limiti di dimensione delle immagini](https://platform.claude.com/docs/it/build-with-claude/vision#evaluate-image-size) del tuo modello: il toolset non accetta dimensioni del display e l’API non esegue il ridimensionamento per te, quindi un’immagine `tool_result` troppo grande viene rifiutata con un errore di validazione. Poiché Claude restituisce le coordinate nello spazio dei pixel dell’immagine che riceve, conserva il fattore di scala che hai usato in modo da poter rimappare quelle coordinate sul tuo schermo.

<Note>
  I limiti variano in base al modello. Claude Opus 4.7 e i modelli successivi, inclusi tutti i modelli che supportano `computer_toolset_20260801`, accettano fino a 2.576 pixel sul lato lungo e 4.784 token visivi in totale (`⌈width / 28⌉ × ⌈height / 28⌉`, circa 3,75 megapixel). I modelli precedenti accettano fino a 1.568 pixel sul lato lungo e circa 1,15 megapixel in totale. Consulta [Risoluzione e costo in token](https://platform.claude.com/docs/it/build-with-claude/vision#evaluate-image-size) per la fascia di ciascun modello. L’esempio seguente usa i limiti di 1.568 px / 1,15 MP dei modelli precedenti. Per un modello della fascia ad alta risoluzione, dimensiona in base al limite di token visivi anziché a un totale di pixel, ad esempio con l’helper di ridimensionamento in [Ridimensiona l’immagine prima del caricamento](https://platform.claude.com/docs/it/build-with-claude/vision-coordinates#resize-your-image-before-uploading).
</Note>

Se il tuo schermo supera il limite, ridimensiona ogni screenshot prima di restituirlo e riporta le coordinate restituite da Claude allo spazio dello schermo originale. Poiché il toolset non accetta dimensioni del display, il ridimensionamento e la scalatura delle coordinate nel codice della tua applicazione sono tutto ciò che ti serve:

<CodeGroup exclude="shell">
  ```python Python
  import math

  screen_width, screen_height = 1512, 982


  def get_scale_factor(width, height):
      """Calculate scale factor to meet API constraints."""
      long_edge = max(width, height)
      total_pixels = width * height

      long_edge_scale = 1568 / long_edge
      total_pixels_scale = math.sqrt(1_150_000 / total_pixels)

      return min(1.0, long_edge_scale, total_pixels_scale)


  # Durante l'acquisizione dello screenshot
  scale = get_scale_factor(screen_width, screen_height)
  scaled_width = int(screen_width * scale)
  scaled_height = int(screen_height * scale)

  # Ridimensiona l'immagine alle dimensioni scalate prima di inviarla a Claude
  screenshot = capture_and_resize(scaled_width, scaled_height)


  # Quando gestisci le coordinate di Claude, riportale alla scala originale
  def execute_click(x, y):
      screen_x = x / scale
      screen_y = y / scale
      perform_click(screen_x, screen_y)
  ```

  ```typescript TypeScript
  const screenWidth = 1512;
  const screenHeight = 982;
  const MAX_LONG_EDGE = 1568;
  const MAX_PIXELS = 1_150_000;

  function getScaleFactor(width: number, height: number): number {
    const longEdge = Math.max(width, height);
    const totalPixels = width * height;

    const longEdgeScale = MAX_LONG_EDGE / longEdge;
    const totalPixelsScale = Math.sqrt(MAX_PIXELS / totalPixels);

    return Math.min(1.0, longEdgeScale, totalPixelsScale);
  }

  // Durante l'acquisizione dello screenshot
  const scale = getScaleFactor(screenWidth, screenHeight);
  const scaledWidth = Math.floor(screenWidth * scale);
  const scaledHeight = Math.floor(screenHeight * scale);

  // Ridimensiona l'immagine alle dimensioni scalate prima di inviarla a Claude
  const screenshot = captureAndResize(scaledWidth, scaledHeight);

  // Quando gestisci le coordinate di Claude, riportale alla scala originale
  function executeClick(x: number, y: number): void {
    const screenX = x / scale;
    const screenY = y / scale;
    performClick(screenX, screenY);
  }
  ```

  ```csharp C#
  int screenWidth = 1512, screenHeight = 982;

  double GetScaleFactor(int width, int height)
  {
      // Calcola il fattore di scala per rispettare i vincoli dell'API.
      int longEdge = Math.Max(width, height);
      int totalPixels = width * height;

      double longEdgeScale = 1568.0 / longEdge;
      double totalPixelsScale = Math.Sqrt(1_150_000.0 / totalPixels);

      return Math.Min(1.0, Math.Min(longEdgeScale, totalPixelsScale));
  }

  // Durante l'acquisizione dello screenshot
  double scale = GetScaleFactor(screenWidth, screenHeight);
  int scaledWidth = (int)(screenWidth * scale);
  int scaledHeight = (int)(screenHeight * scale);

  // Ridimensiona l'immagine alle dimensioni scalate prima di inviarla a Claude
  var screenshot = CaptureAndResize(scaledWidth, scaledHeight);

  // Quando gestisci le coordinate di Claude, riportale alla scala originale
  void ExecuteClick(int x, int y)
  {
      double screenX = x / scale;
      double screenY = y / scale;
      PerformClick(screenX, screenY);
  }
  ```

  ```go Go
  func getScaleFactor(width, height int) float64 {
  	longest := float64(max(width, height))
  	area := float64(width * height)
  	return min(1.0, 1568/longest, math.Sqrt(1_150_000/area))
  }

  // ...
  	screenWidth, screenHeight := 1512, 982

  	// Durante l'acquisizione dello screenshot
  	scale := getScaleFactor(screenWidth, screenHeight)
  	scaledWidth := int(float64(screenWidth) * scale)
  	scaledHeight := int(float64(screenHeight) * scale)

  	// Ridimensiona l'immagine alle dimensioni scalate prima di inviarla a Claude
  	screenshot := captureAndResize(scaledWidth, scaledHeight)

  	// Quando gestisci le coordinate di Claude, riportale alla scala originale
  	executeClick := func(x, y int) {
  		performClick(float64(x)/scale, float64(y)/scale)
  	}
  ```

  ```java Java
  static double getScaleFactor(int width, int height) {
      return Math.min(
          1.0,
          Math.min(
              1568.0 / Math.max(width, height),
              Math.sqrt(1_150_000.0 / (width * height))
          )
      );
  }

  void main() {
      int screenWidth = 1512, screenHeight = 982;

      // Durante l'acquisizione dello screenshot
      double scale = getScaleFactor(screenWidth, screenHeight);
      int scaledWidth = (int)(screenWidth * scale);
      int scaledHeight = (int)(screenHeight * scale);

      // Ridimensiona l'immagine alle dimensioni scalate prima di inviarla a Claude
      var screenshot = captureAndResize(scaledWidth, scaledHeight);

      // Quando gestisci le coordinate di Claude, riportale alla scala originale
      BiConsumer<Integer, Integer> executeClick =
          (x, y) -> performClick(x / scale, y / scale);
      // ...
  }
  ```

  ```php PHP
  function getScaleFactor(int $width, int $height): float
  {
      return min(
          1.0,
          1568 / max($width, $height),
          sqrt(1_150_000 / ($width * $height)),
      );
  }

  $screenWidth = 1512;
  $screenHeight = 982;

  // Durante l'acquisizione dello screenshot
  $scale = getScaleFactor($screenWidth, $screenHeight);
  $scaledWidth = (int)($screenWidth * $scale);
  $scaledHeight = (int)($screenHeight * $scale);

  // Ridimensiona l'immagine alle dimensioni scalate prima di inviarla a Claude
  $screenshot = captureAndResize($scaledWidth, $scaledHeight);

  // Quando gestisci le coordinate di Claude, riportale alla scala originale
  $executeClick = fn(int $x, int $y) => performClick($x / $scale, $y / $scale);
  ```

  ```ruby Ruby
  def get_scale_factor(width, height)
    [1.0, 1568.0 / [width, height].max, Math.sqrt(1_150_000.0 / (width * height))].min
  end

  screen_width, screen_height = 1512, 982

  # Durante l'acquisizione dello screenshot
  scale = get_scale_factor(screen_width, screen_height)
  scaled_width = (screen_width * scale).to_i
  scaled_height = (screen_height * scale).to_i

  # Ridimensiona l'immagine alle dimensioni scalate prima di inviarla a Claude
  screenshot = capture_and_resize(scaled_width, scaled_height)

  # Quando gestisci le coordinate di Claude, riportale alla scala originale
  execute_click = ->(x, y) { perform_click(x / scale, y / scale) }
  ```
</CodeGroup>

<Note>
  **I display Retina di macOS** acquisiscono gli screenshot con un “device pixel ratio” (rapporto pixel del dispositivo) di 2, quindi l’immagine ha una risoluzione doppia rispetto alle coordinate logiche dello schermo. Riduci lo screenshot di 2x prima di inviarlo, oppure dimezza le coordinate restituite da Claude prima di eseguire il clic.
</Note>

Quando scegli una risoluzione del display e restituisci gli screenshot:

* Per le attività desktop generiche, usa 1024x768 o 1280x720; per le applicazioni web, usa 1280x800 o 1366x768.
* Evita risoluzioni superiori a 1920x1080 per prevenire problemi di prestazioni.
* Codifica gli screenshot come PNG o JPEG in base64 e valuta di comprimere gli screenshot di grandi dimensioni per migliorare le prestazioni.
* Includi metadati rilevanti come timestamp o stato del display.
* Se usi risoluzioni più elevate, assicurati che le coordinate siano scalate con precisione.

### Gestisci la cronologia degli screenshot

I lunghi cicli dell’agente accumulano rapidamente screenshot (circa 1.000–1.800 token di input ciascuno). Si applicano anche i [limiti delle richieste](https://platform.claude.com/docs/it/build-with-claude/vision#request-limits) dell’API.

Quando una singola richiesta contiene più di 20 immagini, ogni immagine al suo interno è soggetta a un limite per lato più restrittivo. Un ciclo che mantiene la cronologia degli screenshot può raggiungere quel numero. Ridimensiona ogni screenshot per non superare quel limite, oppure elimina gli screenshot più vecchi per mantenerne 20 o meno nella richiesta.

Per mantenere efficace il “prompt caching” ([cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching)) limitando al contempo il contesto:

* Posiziona un breakpoint `cache_control` dopo il prompt di sistema e le definizioni degli strumenti, e fino a tre ulteriori sull’ultimo blocco `tool_result` di ciascuno dei turni più recenti, facendoli avanzare a ogni turno. All’interno di un’[azione batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#batch-actions), i marcatori su più blocchi agiscono come un unico breakpoint, ma ciascuno conta comunque per il limite di quattro, quindi usane al massimo uno per turno.

* Elimina i vecchi screenshot *a blocchi*, non uno per turno. Scartare uno screenshot a ogni turno modifica il prefisso a ogni turno e invalida la cache. Un valore predefinito ragionevole è mantenere gli ultimi tre screenshot ed eliminare ogni 25 turni, così il prefisso rimane identico byte per byte tra un’eliminazione e l’altra; se i tuoi screenshot superano il limite più restrittivo, scegli un intervallo che mantenga ogni richiesta a 20 immagini o meno.

* Evita l’eliminazione lato client su Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1 e Claude Mythos 5.1. Lo stesso vale per Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5. Su questi modelli, rimuovere uno screenshot precedente da una richiesta [invalida ogni “thinking block” (blocco di ragionamento) successivo già presente nella cronologia](https://platform.claude.com/docs/it/build-with-claude/thinking#preserved-in-conversation) di quella richiesta e di ogni richiesta successiva.

  * **In alternativa:** Ridimensiona gli screenshot per non superare il limite più restrittivo. La [“tool result clearing” (cancellazione dei risultati degli strumenti)](https://platform.claude.com/docs/it/build-with-claude/context-editing#tool-result-clearing) fa risparmiare token, ma gli screenshot cancellati contano comunque per i [limiti delle richieste](https://platform.claude.com/docs/it/build-with-claude/vision#request-limits), quindi usa la [“on-demand compaction” (compattazione su richiesta)](https://platform.claude.com/docs/it/build-with-claude/compaction-on-demand) prima che un ciclo li raggiunga.
  * **Se devi eliminare:** Mantieni impostato [`prefix_mismatch_behavior: "drop_block"`](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking/prefix-checks#preserved-thinking-controls) da quel momento in poi. Dopo ogni eliminazione, l’API scarta i blocchi di ragionamento invalidati, in quella richiesta e in ogni richiesta successiva. Claude prosegue quindi senza il ragionamento prodotto dopo lo screenshot eliminato.
  * **Se devi eliminare su Claude Sonnet 5.5 o Claude Haiku 5.5:** `prefix_mismatch_behavior` funziona solo con `thinking: {"type": "adaptive"}`. Con qualsiasi altra impostazione di ragionamento su quei modelli, mantieni la cronologia in sola aggiunta oppure rimuovi ogni blocco `thinking` e `redacted_thinking` successivo allo screenshot eliminato.

### Diagnostica i problemi di clic

Se i clic mancano i loro obiettivi, la causa è solitamente una delle seguenti:

| Sintomo                                                  | Causa probabile                                                                                                                                                       | Prova                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| I clic sono costantemente spostati in una direzione      | Le coordinate di Claude, che si trovano nello spazio dei pixel degli screenshot che restituisci, vengono applicate a un display di dimensioni diverse senza scalatura | Scala ogni coordinata in base al rapporto tra la dimensione del tuo schermo e quella del tuo screenshot prima di fare clic (consulta [Dimensiona gli screenshot per rispettare i limiti delle immagini](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)); sui display Retina di macOS, tieni conto del rapporto pixel del dispositivo 2x |
| I clic finiscono nell’area giusta ma mancano l’obiettivo | L’obiettivo è molto piccolo, i dettagli sono andati persi riducendo una sorgente 4K+, oppure le proporzioni sono state distorte                                       | Mantieni abilitato il membro `zoom` e implementalo in modo che Claude possa ispezionare la regione a piena risoluzione; acquisisci a DPI inferiori o ritaglia la regione rilevante; preserva le proporzioni durante il ridimensionamento                                                                                                                                                                                   |
| Claude fa clic su un elemento completamente sbagliato    | Istruzione ambigua, o elementi visivamente simili nelle vicinanze                                                                                                     | Usa prompt posizionali (“il pulsante blu Invia in basso a destra”); suddividi l’interazione in passaggi più piccoli                                                                                                                                                                                                                                                                                                        |
| La precisione è costantemente scarsa                     | Risoluzione troppo bassa                                                                                                                                              | Prova 1280x720 come riferimento                                                                                                                                                                                                                                                                                                                                                                                            |

<Tip>
  **La scelta del modello influisce sulla precisione dei clic.** Tra i modelli che usano lo strumento `computer_20251124`, Claude Sonnet 4.6 è meccanicamente più preciso nei clic rispetto a Claude Opus 4.6 ed è più robusto quando gli screenshot richiedono una forte riduzione. Claude Opus 4.7 riduce questo divario: la sua precisione nei clic è più o meno paragonabile a quella di Sonnet 4.6, e il suo limite di risoluzione più elevato significa che è necessaria una riduzione minore.
</Tip>

### Segui le best practice di implementazione

<AccordionGroup>
  <Accordion title="Aggiungi ritardi alle azioni">
    Alcune applicazioni hanno bisogno di tempo per rispondere alle azioni:

    <CodeGroup exclude="shell">
      ```python Python
      def click_and_wait(x, y, wait_time=0.5):
          click_at(x, y)
          time.sleep(wait_time)  # Allow UI to update
      ```

      ```typescript TypeScript
      async function clickAndWait(x: number, y: number, waitMs = 500): Promise<void> {
        clickAt(x, y);
        await new Promise((resolve) => setTimeout(resolve, waitMs)); // Allow UI to update
      }
      ```

      ```csharp C#
      static void ClickAndWait(int x, int y, double waitSeconds = 0.5)
      {
          ClickAt(x, y);
          Thread.Sleep(TimeSpan.FromSeconds(waitSeconds));  // Allow UI to update
      }
      ```

      ```go Go
      func clickAndWaitFor(x, y int, wait time.Duration) {
      	clickAt(x, y)
      	time.Sleep(wait) // Allow UI to update
      }

      func clickAndWait(x, y int) {
      	clickAndWaitFor(x, y, 500*time.Millisecond)
      }
      ```

      ```java Java
      void clickAndWait(int x, int y) throws InterruptedException {
          clickAndWait(x, y, 500);
      }

      void clickAndWait(int x, int y, long waitTimeMillis) throws InterruptedException {
          clickAt(x, y);
          Thread.sleep(waitTimeMillis);  // Allow UI to update
      }
      ```

      ```php PHP
      function clickAndWait(int $x, int $y, float $waitSeconds = 0.5): void
      {
          clickAt($x, $y);
          usleep((int) ($waitSeconds * 1_000_000));  // Allow UI to update
      }
      ```

      ```ruby Ruby
      def click_and_wait(x, y, wait_time: 0.5)
        click_at(x, y)
        sleep(wait_time) # Allow UI to update
      end
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Convalida le azioni prima di eseguirle">
    Verifica che le azioni richieste siano sicure e valide:

    <CodeGroup exclude="shell">
      ```python Python
      display_width, display_height = 1024, 768


      def validate_action(action_type, params):
          if action_type == "left_click" and "coordinate" in params:
              x, y = params["coordinate"]
              if not (0 <= x < display_width and 0 <= y < display_height):
                  return False, "Coordinates out of bounds"
          return True, None
      ```

      ```typescript TypeScript
      const displayWidth = 1024;
      const displayHeight = 768;

      interface ActionParams {
        coordinate?: [number, number];
      }

      function validateAction(actionType: string, params: ActionParams): [boolean, string | null] {
        if (actionType === "left_click" && params.coordinate) {
          const [x, y] = params.coordinate;
          if (!(x >= 0 && x < displayWidth && y >= 0 && y < displayHeight)) {
            return [false, "Coordinates out of bounds"];
          }
        }
        return [true, null];
      }
      ```

      ```csharp C#
      const int DisplayWidth = 1024;
      const int DisplayHeight = 768;
      // ...
      static (bool IsValid, string? Error) ValidateAction(string actionType, IReadOnlyDictionary<string, JsonElement> parameters)
      {
          if (actionType == "left_click" && parameters.TryGetValue("coordinate", out JsonElement coordinate))
          {
              int x = coordinate[0].GetInt32();
              int y = coordinate[1].GetInt32();
              if (x is < 0 or >= DisplayWidth || y is < 0 or >= DisplayHeight)
              {
                  return (false, "Coordinates out of bounds");
              }
          }
          return (true, null);
      }
      ```

      ```go Go
      const (
      	displayWidth  = 1024
      	displayHeight = 768
      )

      func validateAction(actionType string, params map[string]any) (bool, string) {
      	raw, hasCoordinate := params["coordinate"]
      	if actionType == "left_click" && hasCoordinate {
      		coord, ok := raw.([]any)
      		if !ok || len(coord) != 2 {
      			return false, "Invalid coordinate"
      		}
      		x, y := int(coord[0].(float64)), int(coord[1].(float64))
      		if !(0 <= x && x < displayWidth && 0 <= y && y < displayHeight) {
      			return false, "Coordinates out of bounds"
      		}
      	}
      	return true, ""
      }
      ```

      ```java Java
      static final int DISPLAY_WIDTH = 1024;
      static final int DISPLAY_HEIGHT = 768;

      record Validation(boolean valid, String error) {}

      Validation validateAction(String actionType, Map<String, JsonValue> params) {
          if (actionType.equals("left_click") && params.containsKey("coordinate")) {
              List<JsonValue> coord = (List<JsonValue>) params.get("coordinate").asArray().get();
              long x = ((Number) coord.get(0).asNumber().get()).longValue();
              long y = ((Number) coord.get(1).asNumber().get()).longValue();
              if (!(0 <= x && x < DISPLAY_WIDTH && 0 <= y && y < DISPLAY_HEIGHT)) {
                  return new Validation(false, "Coordinates out of bounds");
              }
          }
          return new Validation(true, null);
      }
      ```

      ```php PHP
      const DISPLAY_WIDTH = 1024;
      const DISPLAY_HEIGHT = 768;

      /** @return array{bool, ?string} */
      function validateAction(string $actionType, array $params): array
      {
          if ($actionType === 'left_click' && isset($params['coordinate'])) {
              [$x, $y] = $params['coordinate'];
              if (!(0 <= $x && $x < DISPLAY_WIDTH && 0 <= $y && $y < DISPLAY_HEIGHT)) {
                  return [false, 'Coordinates out of bounds'];
              }
          }
          return [true, null];
      }
      ```

      ```ruby Ruby
      DISPLAY_WIDTH = 1024
      DISPLAY_HEIGHT = 768

      def validate_action(action_type, params)
        if action_type == "left_click" && params.key?(:coordinate)
          x, y = params[:coordinate]
          unless (0...DISPLAY_WIDTH).cover?(x) && (0...DISPLAY_HEIGHT).cover?(y)
            return [false, "Coordinates out of bounds"]
          end
        end
        [true, nil]
      end
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Registra le azioni per il debug">
    Mantieni un log di tutte le azioni per la risoluzione dei problemi:

    <CodeGroup exclude="shell">
      ```python Python
      import logging


      def log_action(action_type, params, result):
          logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")
      ```

      ```typescript TypeScript
      function logAction(actionType: string, params: unknown, result: unknown): void {
        console.error(
          `Action: ${actionType}, Params: ${JSON.stringify(params)}, Result: ${JSON.stringify(
            result
          )}`
        );
      }
      ```

      ```csharp C#
      static void LogAction(string actionType, object? parameters, object? result)
      {
          Console.Error.WriteLine($"Action: {actionType}, Params: {parameters}, Result: {result}");
      }
      ```

      ```go Go
      func logAction(actionType string, params map[string]any, result any) {
      	log.Printf("Action: %s, Params: %v, Result: %v", actionType, params, result)
      }
      ```

      ```java Java
      import static java.lang.System.Logger.Level.INFO;

      static final System.Logger LOGGER = System.getLogger("computer-use");

      void logAction(String actionType, Object params, Object result) {
          LOGGER.log(INFO, "Action: {0}, Params: {1}, Result: {2}", actionType, params, result);
      }
      ```

      ```php PHP
      function logAction(string $actionType, array $params, mixed $result): void
      {
          error_log(sprintf(
              'Action: %s, Params: %s, Result: %s',
              $actionType,
              json_encode($params),
              json_encode($result),
          ));
      }
      ```

      ```ruby Ruby
      require "logger"

      LOGGER = Logger.new($stderr)

      def log_action(action_type, params, result)
        LOGGER.info("Action: #{action_type}, Params: #{params}, Result: #{result}")
      end
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

## Migrazione da `computer_20251124`

Un’integrazione `computer_20251124` funziona senza modifiche sui modelli elencati per quella versione in [Versioni precedenti dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions). Aggiorna l’integrazione prima di spostarla su un modello che non accetta `computer_20251124`, come Claude Opus 5.5 sulla Claude API.

Per eseguire l’aggiornamento, apporta insieme le seguenti modifiche:

1. **Rimuovi l’header beta.** Elimina `anthropic-beta: computer-use-2025-11-24` dalle tue richieste. Con l’SDK, rimuovi `betas` (csharp, go: `Betas`; java: `.addBeta()`) e chiama la Messages API tramite il client standard anziché il namespace beta.
2. **Modifica la voce `tools`.** Imposta `type` su `computer_toolset_20260801` ed elimina `name`, `display_width_px`, `display_height_px`, `display_number` ed `enable_zoom`. Il toolset rifiuta ciascuno di questi campi.
3. **Scegli se mantenere lo zoom abilitato.** Lo zoom è abilitato per impostazione predefinita nel toolset, mentre `enable_zoom` ha come valore predefinito `false`. Se il tuo ambiente non implementa lo zoom, aggiungi `"configs": {"zoom": {"enabled": false}}` per mantenere il comportamento precedente; altrimenti implementalo (consulta [Azioni disponibili](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#available-actions)).
4. **Gestisci ogni blocco in un turno.** Aggiorna il ciclo del tuo agente in modo che iteri su ogni blocco `tool_use` di una risposta anziché leggere solo il primo, e che esegua il dispatch in base al `name` del blocco insieme a `toolset_name` anziché in base a `input.action`. Gli input dei membri non contengono più un campo `action`; i campi rimanenti sono invariati.
5. **Esegui i blocchi in ordine e usa il testo di interruzione.** Esegui i blocchi in sequenza, fermati al primo errore e rispondi ai blocchi rimanenti con `Not executed: an earlier computer action in this turn failed.` come descritto in [Azioni batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#batch-actions). Se il tuo ciclo non è ancora in grado di eseguire batch, [Parametri dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#tool-parameters) spiega come limitare Claude a un’azione per turno.
6. **Riporta `toolset_name` nei risultati.** Aggiungi `"toolset_name": "computer"` a ogni `tool_result` che risponde a una chiamata di un membro. I risultati possono contenere solo contenuto `text` e `image`.
7. **Supporta `repeat` su `key`.** Il membro `key` accetta un conteggio `repeat` facoltativo da 1 a 100. Un handler che ignora i campi non riconosciuti premerebbe il tasto una sola volta, quindi fai in modo che il tuo handler `key` rispetti `repeat`.
8. **Ridimensiona tu stesso gli screenshot.** Il toolset rifiuta uno screenshot o un’immagine di zoom che supera i limiti delle immagini del modello anziché ridurla. Ridimensiona prima di restituire l’immagine e continua a scalare le coordinate come descritto in [Dimensiona gli screenshot per rispettare i limiti delle immagini](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions).
9. **Rimuovi le opzioni non supportate.** Sposta qualsiasi `defer_loading` dalla voce in `configs`, con lo stesso valore su ogni membro abilitato. Le altre opzioni non supportate nelle voci dei toolset sono elencate in [Toolset client](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets).

Questa è la voce `tools` prima della modifica, inviata con l’header `anthropic-beta: computer-use-2025-11-24`:

```json
{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}
```

Questa è la voce `tools` dopo la modifica, inviata senza header beta. L’oggetto `configs` mantiene lo zoom disattivato per corrispondere alla voce precedente, che non imposta `enable_zoom`; ometti completamente `configs` per accettare il valore predefinito e consentire a Claude di usare lo zoom:

```json
{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  }
}
```

La coppia seguente mostra un blocco `tool_use` prima e dopo la modifica. Il nome dell’azione passa da `input.action` a `name`, e il blocco acquisisce `toolset_name`:

```json
{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "computer",
  "input": { "action": "left_click", "coordinate": [500, 300] }
}
```

```json
{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300] }
}
```

## Versioni precedenti dello strumento

Due versioni precedenti dello strumento computer use sono disponibili in beta. Ciascuna richiede il proprio [header beta](https://platform.claude.com/docs/it/api/beta-headers) in ogni richiesta, e i relativi parametri sono documentati nel [riferimento della Messages API beta](https://platform.claude.com/docs/it/api/beta/messages/create). Con l’SDK, passa l’header tramite `betas` (csharp, go: `Betas`; java: `.addBeta()`) e usa il namespace beta; solo lo strumento computer use necessita dell’header, non gli strumenti bash o editor di testo nella stessa richiesta.

| Versione dello strumento | Header beta               | Da usare con                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Parametri                                                                       |
| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `computer_20251124`      | `computer-use-2025-11-24` | Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 e Claude Opus 4.5                                                                                                                                                                                                                                                                                                                                                                                                                                     | [Riferimento API](https://platform.claude.com/docs/it/api/beta/messages/create) |
| `computer_20250124`      | `computer-use-2025-01-24` | Claude Sonnet 4.5 ([deprecato](https://platform.claude.com/docs/it/about-claude/model-deprecations)), Claude Haiku 4.5, Claude Opus 4.1 ([ritirato, tranne su Claude Models on Google Cloud (Google managed) e Bedrock](https://platform.claude.com/docs/it/about-claude/model-deprecations)), Claude Sonnet 4 ([ritirato, tranne su Claude Models on Google Cloud (Google managed) e Bedrock](https://platform.claude.com/docs/it/about-claude/model-deprecations)) e Claude Opus 4 ([ritirato, tranne su Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/it/about-claude/model-deprecations)) | [Riferimento API](https://platform.claude.com/docs/it/api/beta/messages/create) |

Su Amazon Bedrock, anche Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 accettano lo strumento `computer_20251124` con l’header beta `computer-use-2025-11-24`. Con l’API InvokeModel di Amazon Bedrock, invia `computer-use-2025-11-24` nell’array `anthropic_beta` del corpo della richiesta anziché in un header. Per quell’API, consulta [Claude su Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/it/build-with-claude/claude-on-amazon-bedrock-legacy).

***

## Limitazioni

1. **Latency (latenza):** La latenza del computer use per le interazioni uomo-IA potrebbe essere troppo lenta rispetto alle normali azioni al computer dirette da un essere umano. Concentrati sui casi d’uso in cui la velocità non è critica (ad esempio, raccolta di informazioni in background, test software automatizzati) in ambienti attendibili.
2. **Precisione e affidabilità della visione artificiale:** Claude potrebbe commettere errori o avere allucinazioni quando restituisce coordinate specifiche durante la generazione delle azioni. L’output del [ragionamento riassunto](https://platform.claude.com/docs/it/build-with-claude/thinking#summarized-thinking) di Claude può aiutarti a comprendere il ragionamento del modello e a identificare potenziali problemi; imposta `display: "summarized"` nella configurazione del ragionamento, perché i modelli che supportano il toolset omettono il testo del ragionamento per impostazione predefinita.
3. **Precisione e affidabilità nella selezione degli strumenti:** Claude potrebbe commettere errori o avere allucinazioni nella selezione degli strumenti durante la generazione delle azioni, oppure intraprendere azioni inattese per risolvere i problemi. Inoltre, l’affidabilità potrebbe essere inferiore quando interagisce con applicazioni di nicchia o con più applicazioni contemporaneamente. Formula con attenzione i prompt al modello quando richiedi attività complesse.
4. **Affidabilità dello scorrimento:** L’azione di scorrimento supporta il controllo della direzione (su, giù, sinistra, destra) e una quantità specificata. Nelle applicazioni in cui lo scorrimento non ha effetto, possono essere utili alternative da tastiera come Pagina giù.
5. **Interazione con i fogli di calcolo:** Usa le azioni di controllo fine del mouse (`left_mouse_down`, `left_mouse_up`) e le combinazioni con tasti modificatori per selezionare singole celle. Le operazioni complesse sui fogli di calcolo potrebbero comunque richiedere più tentativi.
6. **Creazione di account e generazione di contenuti su piattaforme social e di comunicazione:** Sebbene Claude visiti siti web, la sua capacità di creare account, generare e condividere contenuti o comunque impersonare esseri umani su siti web e piattaforme di social media è limitata.
7. **Vulnerabilità:** Jailbreak e prompt injection possono influire sul computer use come su qualsiasi sistema di IA di frontiera, anche tramite istruzioni incorporate in pagine web o immagini; applica le precauzioni descritte in [Considerazioni sulla sicurezza](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#security-considerations).
8. **Azioni inappropriate o illegali:** In base ai Termini di servizio di Anthropic, non devi utilizzare il computer use per violare alcuna legge o la Politica di utilizzo accettabile.

Esamina e verifica sempre attentamente le azioni e i log di computer use di Claude. Non usare Claude per attività che richiedono una precisione perfetta o informazioni sensibili degli utenti senza supervisione umana.

## Conservazione dei dati

Il computer use è uno strumento lato client. Tutti gli screenshot, le azioni del mouse, gli input da tastiera e gli eventuali file coinvolti in una sessione vengono acquisiti e archiviati nel tuo ambiente, non da Anthropic. Anthropic elabora le immagini degli screenshot e le richieste di azione in tempo reale come parte della chiamata API. La conservazione di tali richieste API è regolata da [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).

Poiché la tua applicazione controlla dove e come vengono archiviati i dati del computer use, il computer use è idoneo alla ZDR.

## Prezzi

L’uso del computer segue i [prezzi standard dell’uso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview#pricing). Quando usi lo strumento di uso del computer:

**Overhead della definizione del toolset:** Dichiarare `computer_toolset_20260801` con i suoi membri predefiniti aggiunge circa 4.500 token di input a una richiesta (circa 4.590 su Claude Sonnet 5 e circa 4.520 sugli altri modelli supportati), che coprono le definizioni degli strumenti membri e il prompt di sistema per l’uso degli strumenti. Disabilitare `zoom` con `configs` rimuove circa 410 di quei token. Il conteggio esatto per una richiesta è riportato nel campo `usage` della risposta, e puoi stimarlo in anticipo con l’[endpoint di conteggio dei token](https://platform.claude.com/docs/it/build-with-claude/token-counting).

**Versioni precedenti dello strumento:** Le seguenti cifre si applicano alle versioni dello strumento `computer_20251124` e `computer_20250124`, non a `computer_toolset_20260801`:

* Overhead del prompt di sistema: 466–499 token aggiunti al prompt di sistema
* Definizione dello strumento: circa 735 token di input per definizione dello strumento (misurati con `computer_20250124`)

**Consumo aggiuntivo di token:**

* Immagini di screenshot e zoom restituite nei risultati degli strumenti, fatturate come input di immagini (vedi [Prezzi della visione](https://platform.claude.com/docs/it/build-with-claude/vision#evaluate-image-size))
* Risultati dell’esecuzione degli strumenti restituiti a Claude

<Note>
  Se stai usando anche gli strumenti bash o editor di testo insieme all’uso del computer, tali strumenti hanno i propri costi in token come documentato nelle rispettive pagine.
</Note>

## Passaggi successivi

<CardGroup cols={2}>
  <Card title="Toolset computer negli SDK" icon="code" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-sdk#computer-toolset">
    Parti dal driver di un partner o scrivi il tuo in Python o TypeScript. L’SDK esegue il ciclo e la callback di approvazione che passi.
  </Card>

  <Card title="Risoluzione dei problemi di uso degli strumenti" icon="wrench" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/troubleshooting-tool-use">
    Correggi gli errori più comuni di uso degli strumenti con tabelle diagnostiche sintomo-soluzione.
  </Card>

  <Card title="Implementazione di riferimento" icon="github-logo" href="https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo">
    Inizia con l’implementazione completa basata su Docker.
  </Card>

  <Card title="Uso degli strumenti con Claude" icon="tool" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview">
    Collega Claude a strumenti e API esterni. Scopri dove vengono eseguiti gli strumenti, quando Claude li chiama e quale strumento è adatto alla tua attività.
  </Card>

  <Card title="Best practice in dettaglio" icon="book" href="https://claude.com/blog/best-practices-for-computer-and-browser-use-with-claude">
    Raccomandazioni basate su benchmark per risoluzione, sforzo di ragionamento e gestione del contesto.
  </Card>

  <Card title="Strumento di browser use" icon="browser" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool">
    Consenti a Claude di navigare, leggere e interagire con le pagine web nel tuo ambiente browser, per attività che rimangono all’interno del browser.
  </Card>
</CardGroup>

## Disponibilità

La funzionalità Strumento computer use è disponibile o in beta su alcuni modelli e idonea per conservazione zero dei dati e preparazione HIPAA.

### Supporto API

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

* Disponibilità: Disponibile

| Stato       | Piattaforme cloud                                                                                                                                                                                              | Modelli                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Disponibile | Claude API, [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/google-managed)                                               | [Claude Fable 5.2](https://platform.claude.com/docs/it/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/it/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/it/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/it/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/it/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/it/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/it/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/it/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/it/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/it/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/it/models/opus-4-8/overview) |
| Disponibile | [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed)                                                     | [Claude Fable 5.2](https://platform.claude.com/docs/it/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/it/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/it/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/it/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/it/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/it/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/it/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/it/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/it/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/it/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/it/models/opus-4-8/overview)                        |
| Disponibile | [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws), [Microsoft Foundry](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.2](https://platform.claude.com/docs/it/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/it/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/it/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/it/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/it/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/it/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/it/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/it/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/it/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/it/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/it/models/opus-4-8/overview)                        |
| Disponibile | [Amazon Bedrock](https://platform.claude.com/docs/it/build-with-claude/claude-in-amazon-bedrock)                                                                                                               | [Claude Fable 5.1](https://platform.claude.com/docs/it/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/it/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/it/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/it/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/it/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/it/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/it/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/it/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/it/models/opus-4-8/overview)                                                                                                                                                                                                |
| Disponibile | [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/it/build-with-claude/claude-on-amazon-bedrock-legacy)                                                                                      | [Claude Fable 5.2](https://platform.claude.com/docs/it/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/it/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/it/models/fable-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/it/models/fable-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/it/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/it/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/it/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/it/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/it/models/opus-4-8/overview)                                                                                                                                                                                              |
| Beta        | Tutte le piattaforme supportate                                                                                                                                                                                | [Claude Haiku 4.5](https://platform.claude.com/docs/it/models/haiku-4-5/overview), [Claude Opus 4.7](https://platform.claude.com/docs/it/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/it/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/it/models/sonnet-4-6/overview), [Claude Opus 4.5](https://platform.claude.com/docs/it/models/opus-4-5/overview), [Claude Sonnet 4.5](https://platform.claude.com/docs/it/models/sonnet-4-5/overview)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

#### [Managed Agents](https://platform.claude.com/docs/it/managed-agents/overview)

* Disponibilità: Non disponibile

### Header beta richiesti

[Panoramica degli header beta](https://platform.claude.com/docs/it/api/beta-headers)

Gli header beta consentono di accedere a funzionalità sperimentali e a nuove capacità dei modelli prima che entrino a far parte dell’API standard.

| Header                    | Modelli                                                                                                                                                                                                                                                                                                                                |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `computer-use-2025-11-24` | [Claude Opus 4.7](https://platform.claude.com/docs/it/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/it/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/it/models/sonnet-4-6/overview), [Claude Opus 4.5](https://platform.claude.com/docs/it/models/opus-4-5/overview) |
| `computer-use-2025-01-24` | [Claude Haiku 4.5](https://platform.claude.com/docs/it/models/haiku-4-5/overview), [Claude Sonnet 4.5](https://platform.claude.com/docs/it/models/sonnet-4-5/overview)                                                                                                                                                                 |

### 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    | Idoneo (esclude [Modelli coperti](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#model-specific-data-retention-requirements))                                                                           | Idoneo |
| Dettagli | Strumento lato client in cui screenshot e file vengono acquisiti e archiviati nel tuo ambiente, non da Anthropic. [Scopri di più](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#data-retention) | —      |

Endpoint applicabili:

* `/v1/messages` con il toolset o lo strumento `computer`
