---
title: Strumento computer use
url: https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool
description: Offri a Claude il controllo di screenshot, mouse e tastiera di un ambiente desktop con lo strumento per l'uso del computer, il toolset client computer_toolset_20260801.
featureMetadata:
status: ga
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements).
supportedModels:
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-opus-4-8
- claude-haiku-5-5
supportedPlatforms:
Claude API: ga
Claude Platform on AWS: beta
Amazon Bedrock: beta
Google Cloud: ga
Microsoft Foundry: beta
details:
- Sulla Claude API e su Google Cloud, i modelli Claude 5.5 e successivi supportano il computer use solo tramite il toolset `computer_toolset_20260801` e restituiscono un errore per le versioni precedenti dello strumento `computer_20251124` e `computer_20250124`. Per spostare un'integrazione esistente, consulta [Migrare da `computer_20251124`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124). Per passare da `computer_20250124`, consulta [Sposta il computer use sul 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.
- Su Amazon Bedrock, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 accettano la versione precedente dello strumento `computer_20251124` come fanno Claude Opus 5 e Claude Sonnet 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 precedente 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).
- Le piattaforme diverse dalla Claude API e da Google Cloud offrono attualmente solo le [versioni beta precedenti dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions).
---
**Inizia con i toolset dell'SDK:** per `computer_toolset_20260801`, gli SDK Python e TypeScript dispongono di una classe per il toolset del 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 del 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, oppure quando gestisci tu stesso le chiamate agli strumenti.
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 l'interazione autonoma con il desktop.
Lo strumento computer use è un [client toolset](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets) (set di strumenti client) 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 tu. Non è attualmente 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 per turno (una [azione batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#batch-actions)).
Per le attività che restano all'interno di 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.
Computer use è disponibile sulla Claude API e su [Google Cloud](https://platform.claude.com/docs/it/build-with-claude/claude-on-vertex-ai) come toolset `computer_toolset_20260801`; consulta [Compatibilità](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#compatibility) per i modelli supportati.
Le integrazioni esistenti con `computer_20251124` continuano a funzionare sui modelli elencati per tale versione in [Versioni precedenti dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions), e le versioni precedenti dello strumento restano disponibili in beta per i modelli e le piattaforme che non supportano il 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 eseguire l'aggiornamento, oppure [Versioni precedenti dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions) per gli header beta.
## Considerazioni sulla sicurezza
Computer use presenta rischi specifici, distinti dalle funzionalità standard dell'API. Questi rischi aumentano quando si interagisce con internet.
Per ridurre al minimo i rischi, valuta di adottare 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 credenziali 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 una persona 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.
In alcune circostanze, Claude seguirà comandi trovati nei contenuti anche quando sono in conflitto con le tue istruzioni. Ad esempio, istruzioni presenti su pagine web o contenute in immagini potrebbero prevalere sulle tue istruzioni o indurre Claude a commettere errori. Adotta precauzioni per isolare Claude da dati e azioni sensibili, così da 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 gli strumenti per l'uso del computer, dei classificatori analizzeranno automaticamente ciò che gli strumenti restituiscono, come gli screenshot, per segnalare potenziali prompt injection. Quando questi classificatori identificano una potenziale prompt injection, indirizzeranno automaticamente il modello a verificare se l'istruzione provenga davvero da te prima di agire di conseguenza.
Questa protezione aggiuntiva non sarà ideale per ogni caso d'uso (ad esempio, i casi d'uso senza una persona nel ciclo), quindi se desideri rinunciarvi e disattivarla, [contatta il supporto](https://support.claude.com/en/). Le precauzioni sopra indicate restano importanti anche con questi classificatori attivi.
Informa gli utenti finali dei rischi rilevanti e ottieni il loro consenso prima di abilitare 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 header beta. 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 a computer use:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-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 MessageParam
{
Role = Role.User,
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: '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: "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
```
Quando Claude agisce sul desktop, la risposta ha uno `stop_reason` pari a `tool_use` e contiene uno o più blocchi `tool_use` membri, ciascuno dei quali nomina uno strumento membro e riporta `"toolset_name": "computer"`. A metà di questa attività, dopo che Claude ha visto 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 nuovamente l'API; [Come funziona 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 computer use
* 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."
* 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` di membri, come `screenshot`, `left_click` o `type`, ciascuno con `"toolset_name": "computer"`. Una risposta con diversi di questi blocchi è una [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.
* Itera su ogni blocco `tool_use` della 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 macchina virtuale.
* Continua 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 `"toolset_name": "computer"`. Restituisci un'immagine per `screenshot` e `zoom`; per le altre azioni è sufficiente 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).
* 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` e dovresti tornare al passaggio 3.
* Altrimenti, restituisce una risposta testuale all'utente.
La ripetizione dei passaggi 3 e 4 senza input dell'utente è chiamata "agent loop" (ciclo dell'agente), ovvero Claude che risponde con una richiesta di uso degli strumenti e la tua applicazione che risponde a Claude con i risultati della valutazione di quella richiesta.
### Azioni batch
Claude può pianificare una breve sequenza di azioni, come cliccare, digitare e poi acquisire uno screenshot, e restituirle insieme in un'unica risposta. Questa è chiamata "batch action" (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` richiedono un'immagine; per gli altri membri è sufficiente una breve conferma 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 dipendono solitamente da quelle precedenti: il `type` in questo esempio inserisce 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` richiede comunque 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 cosa è andato storto.
* Per ogni azione successiva nel batch, restituisci `is_error: true` con esattamente questo testo (lo strumento browser use usa il proprio [testo di arresto](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 vede quindi quali azioni sono riuscite, quale è fallita e quali sono state saltate, e ripianifica al turno successivo. Una richiesta che lascia senza risposta un qualsiasi blocco `tool_use` del batch viene rifiutata con un `invalid_request_error`, quindi un agent loop che legge solo il primo blocco fallisce alla chiamata successiva. Se la tua applicazione chiede a una persona di confermare le azioni con conseguenze rilevanti, esegui quel controllo prima dell'esecuzione di ogni blocco, perché un batch può completare un'azione a più passaggi all'interno di un singolo turno.
Claude di solito termina un batch con `screenshot` per 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, in modo che Claude veda sempre lo stato attuale dello schermo; questo fa risparmiare un round trip rispetto all'attesa che sia Claude a chiederlo. Puoi anche chiedere a Claude tramite prompt di terminare ogni batch con uno screenshot (consulta [Ottimizza 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 elaborazione
Computer use richiede un ambiente di elaborazione in sandbox in cui Claude possa interagire in sicurezza con le applicazioni e il web. Questo ambiente include:
1. **Display virtuale:** un server di display X11 virtuale (tramite Xvfb) che esegue il rendering dell'interfaccia desktop che Claude vedrà tramite screenshot e controllerà con azioni di mouse/tastiera.
2. **Ambiente desktop:** un'interfaccia utente 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. **Agent loop:** 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 computer use, Claude non si connette direttamente a questo ambiente. Invece, la tua applicazione:
1. Riceve le richieste di uso degli strumenti di Claude
2. Le traduce in azioni nel tuo ambiente di elaborazione
3. Acquisisce i risultati (come screenshot e output dei comandi)
4. Restituisce questi risultati a Claude
Per sicurezza e isolamento, l'implementazione di riferimento esegue tutto questo all'interno di un container Docker con le opportune mappature delle porte per visualizzare e interagire con l'ambiente.
***
## Come implementare computer use
Stai aggiornando un'integrazione `computer_20251124` esistente? 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.
L'[implementazione di riferimento di computer use](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo) è un esempio completo e funzionante: un [ambiente containerizzato](https://github.com/anthropics/anthropic-quickstarts/blob/main/computer-use-demo/Dockerfile) adatto a computer use, implementazioni degli [strumenti computer use](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo/computer_use_demo/tools), un [agent loop](https://github.com/anthropics/anthropic-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.
### Comprendere l'agent loop
Il cuore di computer use è l'"agent loop": un ciclo in cui Claude richiede azioni degli strumenti, la tua applicazione le esegue e restituisce i risultati a Claude. Il ciclo usa il client 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 l'helper di elaborazione delle chiamate agli strumenti descritto in [Implementa 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, effettua il dispatch dei loro blocchi `tool_use` nello stesso passaggio; l'helper risponde solo alle chiamate ai membri di computer use, e il ciclo considera concluso un turno senza chiamate a cui è stata data risposta. Ecco un esempio semplificato:
```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,
)
# Aggiungi la risposta di Claude alla cronologia della conversazione
messages.append({"role": "assistant", "content": response.content})
# Esegui le azioni richieste da Claude, in ordine, e raccogli i risultati
tool_results = process_tool_calls(response)
if not tool_results:
return messages # No more tool use; task complete
# Invia tutti i risultati a Claude in un unico messaggio utente
messages.append({"role": "user", "content": tool_results})
return messages
```
```typescript TypeScript
async function samplingLoop(
model: string,
messages: Anthropic.MessageParam[],
maxIterations = 10
): Promise {
// Esegui il ciclo dell'agente computer-use finché Claude smette di richiedere strumenti
// o viene raggiunto il limite di iterazioni.
for (let i = 0; i < maxIterations; i++) {
const response = await client.messages.create({
model,
max_tokens: 4096,
messages,
tools
});
// Aggiungi la risposta di Claude alla cronologia della conversazione
messages.push({ role: "assistant", content: response.content });
// Esegui gli strumenti richiesti da Claude e raccogli i risultati
const toolResults = processToolCalls(response);
if (toolResults.length === 0) {
return messages; // No more tool use; task complete
}
// Invia i risultati degli strumenti a Claude per l'iterazione successiva
messages.push({ role: "user", content: toolResults });
}
return messages;
}
```
```csharp C#
async Task> SamplingLoop(
Model model,
List messages,
int maxIterations = 10
)
{
// Esegui il ciclo dell'agente computer-use finché Claude smette di richiedere strumenti
// o viene raggiunto il limite di iterazioni.
for (var i = 0; i < maxIterations; i++)
{
var response = await client.Messages.Create(
new MessageCreateParams
{
Model = model,
MaxTokens = 4096,
Messages = messages,
Tools = tools,
}
);
// Aggiungi la risposta di Claude alla cronologia della conversazione
messages.Add(
new()
{
Role = Role.Assistant,
Content = response
.Content.Select(block => new ContentBlockParam(block.Json))
.ToList(),
}
);
// Esegui gli strumenti richiesti da Claude e raccogli i risultati
var toolResults = ProcessToolCalls(response);
if (toolResults.Count == 0)
{
return messages; // No more tool use; task complete
}
// Invia i risultati degli strumenti a Claude per l'iterazione successiva
messages.Add(new() { Role = Role.User, Content = toolResults });
}
return messages;
}
```
```go Go
// samplingLoop esegue il ciclo dell'agente computer-use finché Claude smette
// di richiedere strumenti o viene raggiunto il limite di iterazioni.
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
}
// Aggiungi la risposta di Claude alla cronologia della conversazione
messages = append(messages, response.ToParam())
// Esegui in ordine le azioni richieste da Claude e raccogli i risultati
toolResults := processToolCalls(response)
if len(toolResults) == 0 {
return messages, nil // No more tool use; task complete
}
// Invia tutti i risultati a Claude in un unico messaggio utente
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 samplingLoop(Model model, List messages, int maxIterations) {
for (int i = 0; i < maxIterations; i++) {
Message response = client.messages().create(MessageCreateParams.builder()
.model(model)
.maxTokens(4096)
.messages(messages)
.addTool(COMPUTER_TOOLSET)
.build());
// Aggiungi la risposta di Claude alla cronologia della conversazione
messages.add(MessageParam.builder()
.role(MessageParam.Role.ASSISTANT)
.contentOfBlockParams(response.content().stream().map(ContentBlock::toParam).toList())
.build());
// Esegui gli strumenti richiesti da Claude e raccogli i risultati
List toolResults = processToolCalls(response);
if (toolResults.isEmpty()) {
return messages; // No more tool use; task complete
}
// Invia i risultati degli strumenti a Claude per l'iterazione successiva
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(toolResults)
.build());
}
return messages;
}
```
```php PHP
/**
* Run the computer-use agent loop until Claude stops requesting tools
* or the iteration limit is reached.
*/
function samplingLoop(string $model, array $messages, int $maxIterations = 10): array
{
global $client, $tools;
for ($i = 0; $i < $maxIterations; $i++) {
$response = $client->messages->create(
model: $model,
maxTokens: 4096,
messages: $messages,
tools: $tools,
);
// Aggiungi la risposta di Claude alla cronologia della conversazione
$messages[] = MessageParam::with(role: Role::ASSISTANT, content: $response->content);
// Esegui gli strumenti richiesti da Claude e raccogli i risultati
$toolResults = processToolCalls($response);
if ($toolResults === []) {
return $messages; // No more tool use; task complete
}
// Invia i risultati degli strumenti a Claude per l'iterazione successiva
$messages[] = MessageParam::with(role: Role::USER, content: $toolResults);
}
return $messages;
}
```
```ruby Ruby
# Esegui il ciclo dell'agente computer-use finché Claude smette di richiedere strumenti
# o viene raggiunto il limite di iterazioni.
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
)
# Aggiungi la risposta di Claude alla cronologia della conversazione
messages << { role: "assistant", content: response.content }
# Esegui in ordine le azioni richieste da Claude e raccogli i risultati
tool_results = process_tool_calls(response)
return messages if tool_results.empty? # No more tool use; task complete
# Invia tutti i risultati a Claude in un unico messaggio utente
messages << { role: "user", content: tool_results }
end
messages
end
```
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 protezione previene potenziali cicli infiniti che potrebbero comportare costi API imprevisti.
### Ottimizza le prestazioni del modello con il prompting
1. Specifica attività semplici e ben definite e fornisci istruzioni esplicite per ogni passaggio.
2. Claude a volte presume gli esiti delle proprie azioni 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 tendina e barre di scorrimento) potrebbero essere difficili da manipolare per Claude tramite movimenti del mouse. Se riscontri questo problema, prova a istruire il modello a usare le scorciatoie da tastiera.
4. Per attività o interazioni con l'interfaccia ripetibili, includi nel prompt screenshot di esempio e chiamate agli strumenti di esiti riusciti.
5. Se hai bisogno che il modello effettui l'accesso, forniscigli nome utente e password nel prompt all'interno di tag XML come ``. Usare computer use all'interno di applicazioni che richiedono l'accesso aumenta il rischio di esiti negativi dovuti a 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 viene chiesto di testo piccolo o di elementi specifici dell'interfaccia non leggibili alla risoluzione predefinita dello screenshot, come nomi di file in una barra laterale, titoli di schede, testo della barra di stato, numeri di riga o etichette di pulsanti. Se Claude non esegue lo zoom quando te lo aspetti, chiedi di una regione o di un elemento specifico anziché dello 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 riscontri ripetutamente un insieme chiaro di problemi o conosci in anticipo le attività che Claude dovrà completare, usa il prompt di sistema per fornire a Claude suggerimenti o istruzioni esplicite su come svolgere le attività con successo.
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 del 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 "system prompt" (prompt di sistema) specifico per 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 usato 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 in alto a sinistra e in basso a destra 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 mantenendo le proporzioni. Questo permette a Claude di leggere testo piccolo o interfacce dense non leggibili in uno screenshot completo ridotto. |
| `left_click` | `coordinate` (facoltativo): `[x, y]`; `text` (facoltativo): tasti modificatori da tenere premuti durante il clic: `shift`, `ctrl`, `alt`, `super` (il tasto Command o Windows), oppure una combinazione unita da `+` come `ctrl+shift` | Clicca con il pulsante sinistro del mouse su `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 su `start_coordinate`, trascina fino a `coordinate` e rilascia. |
| `mouse_move` | `coordinate`: `[x, y]` | Sposta il cursore senza cliccare, ad esempio per passare sopra un elemento (hover). |
| `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 su `coordinate`, oppure nella posizione corrente del cursore. |
| `type` | `text`: la stringa da digitare | Digita testo letterale nel punto di focus corrente della tastiera. |
| `key` | `text`: un tasto o una combinazione unita da `+` come `"Return"`, `"ctrl+s"` o `"alt+Tab"`; `repeat` (facoltativo): da 1 a 100, 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 | Fa una pausa 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 `coordinate`, `start_coordinate` e `region`, e la posizione riportata da `cursor_position`, è nello spazio di pixel degli screenshot dell'intero display che restituisci, con l'origine in alto a sinistra. Le immagini di zoom non cambiano questo: dopo uno `zoom`, Claude esprime comunque le coordinate nello spazio dello screenshot completo, mai relative 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.
* **Effettua il dispatch sulla coppia (`toolset_name`, `name`).** `toolset_name` è ciò che contrassegna un blocco come azione sul computer: uno strumento personalizzato nella stessa richiesta può condividere il nome di un membro, e una versione successiva del toolset può aggiungere membri (consulta [Client toolset](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets)).
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" }
}
```
Trascina 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]
}
}
```
Scorri 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
}
}
```
Premi Tab quattro volte:
```json
{
"type": "tool_use",
"id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
"name": "key",
"toolset_name": "computer",
"input": { "text": "Tab", "repeat": 4 }
}
```
Esegui 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] }
}
```
Riporta 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": {}
}
```
### Parametri dello strumento
La voce del toolset nell'array `tools` accetta quattro parametri; le regole che condivide con il toolset browser use sono elencate in [Client toolset](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` (predefinito `true` per tutti i 17, incluso `zoom`) e `defer_loading` (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) sulla 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 sulla definizione del toolset:
```json
{
"type": "computer_toolset_20260801",
"configs": {
"zoom": { "enabled": false }
},
"cache_control": { "type": "ephemeral" }
}
```
Se il tuo agent loop può eseguire solo un'azione per round trip, imposta `disable_parallel_tool_use` su `true` in `tool_choice`; Claude restituirà quindi al massimo un blocco `tool_use` membro per 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 di 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 [Client toolset](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets).
### Combinazione con il thinking
Per combinare computer use con il thinking, consulta [Thinking](https://platform.claude.com/docs/it/build-with-claude/thinking).
Per lo strumento precedente `computer_20251124`, i benchmark interni sui modelli che lo usano suggeriscono queste impostazioni di `effort`:
* **Claude Opus 4.7:** usa `high` come predefinito; 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 predefinito (miglior rapporto precisione/costo). Evita `max`, che aggiunge 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 thinking (meno errori significano meno tentativi ripetuti), rendendolo un'ottima opzione per cicli sensibili ai costi.
### Potenziare computer use con altri strumenti
Per aggiungere altri strumenti insieme a 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 di 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, e le chiamate a membri che condividono un nome, come `screenshot` o `key`, si distinguono tramite `toolset_name`.
### Costruisci un ambiente computer use personalizzato
L'[implementazione di riferimento](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo) è pensata per aiutarti a iniziare con computer use. Include tutti i componenti necessari per far usare un computer a Claude. Tuttavia, puoi costruire il tuo ambiente per computer use in base alle tue esigenze. Avrai bisogno di:
* Un ambiente virtualizzato o containerizzato adatto a computer use con Claude
* Un'implementazione delle azioni dello strumento computer use
* Un agent loop 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 l'agent loop
### Implementa lo strumento computer use
Lo strumento computer use è implementato come strumento senza schema. Quando usi questo strumento, non devi fornire uno schema di input come per gli altri strumenti; lo schema è integrato nel modello di Claude e non può essere modificato.
Crea un display virtuale o connettiti a un display esistente con cui Claude interagirà. Questo comporta tipicamente la configurazione di Xvfb (X Virtual Framebuffer) o di una tecnologia simile.
Crea funzioni per gestire ogni tipo di azione che Claude potrebbe richiedere:
```python Python
# Dati immagine segnaposto; un executor reale cattura lo schermo e restituisce i byte PNG
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
def capture_screenshot() -> list[ImageBlockParam]:
# screenshot risponde con un blocco immagine anziché testo: restituisci la lista dei contenuti del risultato
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 è facoltativo; senza di esso, fai clic dove si trova già il cursore
return click(tool_input.get("coordinate"))
case "type":
return type_text(tool_input["text"])
# Gestisci le altre azioni secondo necessità
raise ValueError(f"Unknown or unimplemented member: {name}")
```
```typescript TypeScript
// Dati immagine segnaposto; un executor reale cattura lo schermo come byte PNG
const PLACEHOLDER_PNG =
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
function captureScreenshot(): Anthropic.ImageBlockParam[] {
// screenshot risponde con un blocco immagine anziché testo
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 è facoltativo nel toolset; se assente, fai clic sulla posizione del cursore
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;
}
// Gestisci altre azioni secondo necessità
throw new Error(`Unknown or unimplemented member: ${action}`);
}
```
```csharp C#
// Dati immagine segnaposto; un executor reale cattura lo schermo e restituisce i byte PNG
const string PlaceholderPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
// screenshot risponde con un blocco immagine anziché testo: restituisci la lista dei contenuti del risultato
List 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 input
) =>
action switch
{
"screenshot" => CaptureScreenshot(),
// coordinate è opzionale nei membri click; senza di essa, fai clic dove si trova il cursore
"left_click" when input.TryGetValue("coordinate", out var xy) => ClickAt(
xy[0].GetInt32(),
xy[1].GetInt32()
),
"left_click" => ClickAtCursor(),
"type" => TypeText(input["text"].GetString()!),
// Gestisci altre azioni secondo necessità
_ => throw new NotSupportedException($"Unknown or unimplemented member: {action}"),
};
```
```go Go
// placeholderPNG sostituisce una cattura reale: un executor restituisce lo
// schermo come dati PNG codificati in base64.
const placeholderPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
// captureScreenshot restituisce un blocco immagine anziché testo.
func captureScreenshot() []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{{
OfImage: &anthropic.ImageBlockParam{
Source: anthropic.ImageBlockParamSourceUnion{
OfBase64: &anthropic.Base64ImageSourceParam{
MediaType: anthropic.Base64ImageSourceMediaTypeImagePNG,
Data: placeholderPNG,
},
},
},
}}
}
// textContent racchiude il testo come contenuto tool_result.
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 è opzionale; senza di essa, fai clic dove si trova già il cursore
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
}
// Gestisci le altre azioni secondo necessità
default:
return nil, fmt.Errorf("unknown or unimplemented member: %s", action)
}
// Raggiunto quando nell'input di un membro manca un campo o un campo ha il tipo errato
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 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 point = (List) 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());
// Gestisci altre azioni secondo necessità
default -> throw new UnsupportedOperationException("Unknown or unimplemented member: " + action);
};
return ToolResultBlockParam.Content.ofString(output);
}
```
```php PHP
// Segnaposto per i byte PNG reali; un executor reale cattura lo schermo
const PLACEHOLDER_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
function captureScreenshot(): array
{
// screenshot risponde con un blocco immagine anziché testo, quindi restituisci la lista dei contenuti del risultato
$image = [
'type' => 'image',
'source' => ['type' => 'base64', 'media_type' => 'image/png', 'data' => PLACEHOLDER_PNG],
];
return [$image];
}
function clickAt(?array $coordinate): string
{
// left_click può omettere coordinate, nel qual caso il clic avviene dove si trova già il cursore
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']),
// Gestisci le altre azioni secondo necessità
default => throw new \RuntimeException("Unknown or unimplemented member: {$name}"),
};
}
```
```ruby Ruby
# Dati immagine segnaposto; un executor reale cattura lo schermo come PNG.
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
# screenshot risponde con un blocco immagine anziché testo
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 è opzionale; senza di esso, fai clic dove si trova già il cursore
click(input[:coordinate])
when "type"
type_text(input[:text])
# Gestisci le altre azioni secondo necessità
else
raise ArgumentError, "Unknown or unimplemented member: #{name}"
end
end
```
Estrai ed esegui le chiamate agli strumenti dalle risposte di Claude:
```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:
# È dichiarato solo il toolset computer; instrada qui altri strumenti se li aggiungi
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:
# Una stringa, o una lista di blocchi di contenuto come l'immagine dello screenshot
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") {
// Questo esempio dichiara solo il toolset computer; instrada qui altri strumenti
// se li aggiungi.
continue;
}
if (failed) {
// Un batch si ferma al primo errore; rispondi alle azioni successive come non eseguite
toolResults.push(computerResult(block.id, HALT_TEXT, true));
continue;
}
try {
// Una stringa, o la lista di blocchi immagine restituita da screenshot
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 ProcessToolCalls(Message response)
{
List toolResults = [];
var failed = false;
foreach (var block in response.Content)
{
if (!block.TryPickToolUse(out var toolUse))
{
continue;
}
if (toolUse.ToolsetName != "computer")
{
// Questo esempio dichiara solo il toolset computer; instrada qui altri strumenti
// se li aggiungi.
continue;
}
if (failed)
{
// Un batch si ferma al primo errore; rispondi alle azioni successive senza eseguirle
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = HaltText,
IsError = true,
ToolsetName = "computer",
}
);
continue;
}
try
{
// Una stringa, o la lista di blocchi immagine restituita da screenshot
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 costruisce il risultato per una singola azione computer. A differenza di un
// normale risultato di strumento, deve ripetere il nome del toolset.
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 esegue in ordine le azioni computer nella risposta di Claude e
// costruisce un tool_result per ogni blocco tool_use. Dopo il primo errore salta
// il resto: Claude le ha pianificate presumendo che le azioni precedenti fossero riuscite.
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:
// Questo esempio dichiara solo il toolset computer; instrada qui altri strumenti se li aggiungi.
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 {
// Testo, oppure il blocco immagine restituito da screenshot
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 per tool_use block. After the first failure, skip the rest:
* Claude planned them assuming the earlier actions succeeded.
*/
List processToolCalls(Message response) {
List toolResults = new ArrayList<>();
boolean failed = false;
for (ContentBlock block : response.content()) {
// Questo esempio dichiara solo il toolset computer; instrada qui altri strumenti se li aggiungi.
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 input =
(Map) toolUse._input().asObject().get();
// Una stringa, o il blocco immagine restituito da screenshot
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) {
// Questo esempio dichiara solo il toolset computer; instrada qui altri strumenti se li aggiungi.
if (!($block instanceof \Anthropic\Messages\ToolUseBlock) || $block->toolsetName !== 'computer') {
continue;
}
$result = ['type' => 'tool_result', 'tool_use_id' => $block->id, 'toolset_name' => 'computer'];
if ($failed) {
// Un batch si ferma al primo errore; le azioni rimanenti ricevono risposta senza essere eseguite
$toolResults[] = [...$result, 'content' => HALT_TEXT, 'is_error' => true];
continue;
}
try {
// Una stringa, oppure la lista di blocchi immagine restituita da screenshot
$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."
# Esegui in ordine le azioni del computer nella risposta di Claude e crea un
# tool_result per ogni blocco tool_use. Dopo il primo errore, salta il resto:
# Claude le ha pianificate presumendo che le azioni precedenti fossero riuscite.
def process_tool_calls(response)
tool_results = []
failed = false
response.content.each do |block|
# Questo esempio dichiara solo il toolset computer; instrada qui gli altri strumenti
# se li aggiungi.
next unless block.type == :tool_use && 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
# Una String, oppure i blocchi di contenuto immagine restituiti da screenshot
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
```
Racchiudi i due passaggi precedenti in un ciclo che rimanda indietro i risultati e si ripete finché Claude non restituisce più chiamate a strumenti membri; [Comprendere l'agent loop](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#understanding-the-agentic-loop) mostra questo ciclo in ogni linguaggio.
### Gestisci gli errori
Segnala a Claude un'azione fallita come `tool_result` con `is_error: true` e una breve descrizione, e includi `"toolset_name": "computer"` come in qualsiasi altro risultato di un membro. Se l'azione fallita faceva parte di una [azione batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#batch-actions), rispondi ai blocchi rimanenti del batch con il testo di arresto mostrato lì 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 coordinate al di fuori dei limiti del display e per 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 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 di pixel dell'immagine che vede, conserva il fattore di scala usato in modo da poter riportare quelle coordinate al tuo schermo.
I limiti variano in base al modello. Claude Opus 4.7 e i modelli successivi, incluso ogni modello che supporta `computer_toolset_20260801`, accettano fino a 2576 pixel sul lato lungo e 4784 token visivi in totale (`⌈width / 28⌉ × ⌈height / 28⌉`, circa 3,75 megapixel); i modelli precedenti accettano fino a 1568 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 il livello di ciascun modello). L'esempio seguente usa i limiti dei modelli precedenti di 1568 px / 1,15 MP. Per un modello del livello 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).
Se il tuo schermo è più grande del 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 serve:
```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 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) }
```
I **display Retina di macOS** acquisiscono gli screenshot con un device pixel ratio 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.
Quando scegli una risoluzione del display e restituisci gli screenshot:
* Per attività desktop generiche, usa 1024x768 o 1280x720; per 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 cicli agentici lunghi accumulano screenshot rapidamente (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 conserva la propria cronologia degli screenshot raggiunge quel numero entro poche decine di turni, quindi ridimensiona ogni screenshot in modo che nessun lato superi i 2000 px 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. Aggiungine fino ad altri tre sull'ultimo blocco `tool_result` di ciascuno dei turni più recenti, spostandoli in avanti a ogni turno. All'interno di un'[azione in 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 ai fini del limite di quattro, quindi usane uno per turno.
* Elimina i vecchi screenshot *in blocco*, non uno a ogni turno. Rimuovere uno screenshot a ogni turno modifica il prefisso a ogni turno e invalida la cache. Un valore predefinito ragionevole è conservare gli ultimi tre screenshot ed eseguire l'eliminazione ogni 25 turni, così il prefisso rimane identico byte per byte tra un'eliminazione e l'altra. Se i tuoi screenshot superano i 2000 px su uno dei lati, scegli un intervallo che mantenga ogni richiesta a 20 immagini o meno.
* Su Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5, evita di eliminare screenshot lato client: rimuovere uno screenshot precedente [invalida ogni blocco di ragionamento successivo](https://platform.claude.com/docs/it/build-with-claude/thinking#preserved-in-conversation) in ogni richiesta che contiene ancora quei turni. Ridimensiona invece gli screenshot a 2000 px o meno per lato e usa la [cancellazione dei risultati degli strumenti](https://platform.claude.com/docs/it/build-with-claude/context-editing#tool-result-clearing) lato server per rimuovere quelli vecchi dal contesto. Se devi eliminarli, mantieni impostato [`prefix_mismatch_behavior: "drop_block"`](https://platform.claude.com/docs/it/build-with-claude/thinking#preserved-thinking-controls) da quel momento in poi; dopo ogni eliminazione, Claude prosegue senza il ragionamento prodotto a partire dallo screenshot eliminato, in quella richiesta e in tutte quelle successive. Su Claude Sonnet 5.5, `block_binding` funziona solo con `thinking: {"type": "adaptive"}`. Con `between_tools`, mantieni la cronologia in sola aggiunta, oppure rimuovi i blocchi di ragionamento dal turno modificato in poi. Su Claude Haiku 5.5, `block_binding` funziona solo con `thinking: {"type": "adaptive"}`; con `thinking: {"type": "disabled"}`, mantieni la cronologia in sola aggiunta, oppure rimuovi i blocchi di ragionamento dal turno modificato in poi.
### Diagnostica i problemi di clic
Se i clic mancano i loro bersagli, la causa è solitamente una delle seguenti:
| Sintomo | Causa probabile | Prova |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Clic costantemente spostati in una direzione | Le coordinate di Claude, che sono nello spazio dei pixel degli screenshot che restituisci, vengono applicate a un display di dimensioni diverse senza ridimensionamento | Scala ogni coordinata in base al rapporto tra la dimensione del tuo schermo e la dimensione del tuo screenshot prima di fare clic (vedi [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 arrivano nell'area giusta ma mancano il bersaglio | Il bersaglio è molto piccolo, il dettaglio è andato perso 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 alla regione rilevante; preserva le proporzioni durante il ridimensionamento |
| Claude fa clic su un elemento completamente sbagliato | Istruzione ambigua, oppure 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 di base |
**La scelta del modello influisce sulla precisione dei clic.** Tra i modelli che usano lo strumento precedente `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 è all'incirca paragonabile a quella di Sonnet 4.6, e il suo limite di risoluzione più elevato significa che è necessaria una riduzione minore.
### Segui le best practice di implementazione
Alcune applicazioni hanno bisogno di tempo per rispondere alle azioni:
```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 {
clickAt(x, y);
await setTimeout(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
```
Verifica che le azioni richieste siano sicure e valide:
```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 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 params) {
if (actionType.equals("left_click") && params.containsKey("coordinate")) {
List coord = (List) 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
```
Mantieni un registro di tutte le azioni per la risoluzione dei problemi:
```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
```
***
## Migra da `computer_20251124`
L'aggiornamento da `computer_20251124` al toolset è facoltativo: i modelli elencati per `computer_20251124` in [Versioni precedenti dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions) continuano ad accettarlo con il relativo header beta, quindi un'integrazione esistente continua a funzionare finché non la modifichi. Claude 5.5 e i modelli successivi fanno eccezione sulla Claude API e su Google Cloud: lì accettano solo il toolset. Aggiorna un'integrazione prima di spostarla su uno di essi. Su Amazon Bedrock, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 accettano `computer_20251124`. 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é tramite 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 (vedi [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 tuo ciclo agentico in modo che iteri su ogni blocco `tool_use` in una risposta anziché leggere solo il primo, e che effettui il dispatch in base al `name` del blocco insieme a `toolset_name` invece che 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 arresto.** 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 può ancora 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 contenuti `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 invece di 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 del 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 lasciare che Claude esegua 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 si sposta 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 rimangono disponibili in beta per le integrazioni esistenti, per i modelli che non supportano il toolset e sulle piattaforme in cui il toolset non è attualmente disponibile. 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; su Amazon Bedrock, anche Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.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 Bedrock e Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations)), Claude Sonnet 4 ([ritirato, tranne su Bedrock e Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations)) e Claude Opus 4 ([ritirato, tranne su Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations)) | [Riferimento API](https://platform.claude.com/docs/it/api/beta/messages/create) |
***
## Limitazioni
1. **Latenza:** L'attuale "latency" (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 su casi d'uso in cui la velocità non è critica (ad esempio, raccolta di informazioni in background, test automatizzati del software) in ambienti affidabili.
2. **Precisione e affidabilità della visione artificiale:** Claude potrebbe commettere errori o allucinare quando produce 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à della selezione degli strumenti:** Claude potrebbe commettere errori o allucinare nella selezione degli strumenti durante la generazione delle azioni oppure intraprendere azioni inaspettate 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 per il 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, alternative da tastiera come Pagina giù possono aiutare.
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 altrimenti impersonare esseri umani su siti web e piattaforme di social media è limitata.
7. **Vulnerabilità:** I jailbreak e la 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 impiegare il computer use per violare alcuna legge o la Acceptable Use Policy.
Esamina e verifica sempre con attenzione 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 qualsiasi file coinvolto 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 di computer use, il computer use è idoneo per ZDR. Per l'idoneità ZDR di tutte le funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
## 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
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.
## Passaggi successivi
Parti dal driver di un partner, oppure scrivi il tuo in Python o TypeScript. L'SDK esegue il loop e la callback di approvazione che passi.
Correggi gli errori più comuni nell'uso degli strumenti con tabelle diagnostiche dal sintomo alla soluzione.
Inizia con l'implementazione completa basata su Docker
Collega Claude a strumenti e API esterni. Scopri dove vengono eseguiti gli strumenti, quando Claude li chiama e quale strumento è adatto alla tua attività.
Raccomandazioni basate su benchmark per risoluzione, impegno di ragionamento e gestione del contesto
Consenti a Claude di navigare, leggere e interagire con le pagine web nel tuo ambiente browser, per attività che restano all'interno del browser.