Strumento computer use

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 (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. 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).

Per le attività che restano all'interno di pagine web, lo strumento browser use è la scelta più adatta: i suoi strumenti membri leggono e agiscono sulla pagina stessa, e non richiede un ambiente desktop completo.

Considerazioni sulla sicurezza

Computer use presenta rischi specifici, distinti dalle funzionalità standard dell'API. Questi rischi aumentano quando si interagisce con internet.

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. 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 come {"type": "computer_toolset_20260801"}. La richiesta non necessita di alcun header beta. Questo esempio dichiara anche lo strumento editor di testo e lo strumento bash, che Claude usa tipicamente insieme a computer use:

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)

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

{
  "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 descrive questo ciclo, e il resto di questa pagina mostra come implementarlo.

Come funziona computer use

1. 1

   Fornisci a Claude lo strumento computer use e un prompt utente

   • Aggiungi il toolset computer use (e facoltativamente altri strumenti) all'array tools della tua richiesta API.
   • Includi un prompt utente che richieda un'interazione con il desktop, ad esempio "Salva un'immagine di un gatto sul mio desktop."
2. 2

   Claude risponde con chiamate agli strumenti membri

   • Claude valuta se agire sul desktop può aiutare a rispondere alla richiesta dell'utente.
   • In tal caso, Claude risponde con uno o più blocchi tool_use membri, come screenshot, left_click o type, ciascuno con "toolset_name": "computer". Una risposta con diversi di questi blocchi è una azione batch.
   • La risposta dell'API ha uno stop_reason pari a tool_use, che segnala una richiesta di uso degli strumenti.
3. 3

   Esegui le chiamate in ordine e restituisci i risultati

   • Itera su ogni blocco tool_use nella risposta, in ordine. Per ciascuno, effettua il dispatch 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 contiene 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.
4. 4

   Claude continua finché l'attività non è completata

   • Claude analizza i risultati degli strumenti per determinare se sono necessarie altre azioni o se l'attività è stata completata.
   • Se Claude determina che sono necessarie altre azioni, risponde con un altro stop_reason tool_use e devi 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 con una differenza: esegui i blocchi in ordine anziché in modo concorrente.

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

{
  "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):

{
  "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):

{
  "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 tipicamente conclude 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ò allegarne uno come blocco image aggiuntivo sull'ultimo risultato del batch, così che Claude veda sempre lo stato corrente dello schermo, risparmiando un round trip rispetto ad attendere che Claude lo richieda. Puoi anche istruire Claude a terminare ogni batch con uno screenshot (consulta Ottimizza le prestazioni del modello con il 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; il resto di questa sezione si applica sia alle integrazioni nuove sia a quelle migrate.

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, 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. 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:

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

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 i risultati delle proprie azioni senza verificarli esplicitamente. Per evitarlo puoi istruire Claude con After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. Explicitly show your thinking: "I have evaluated step X..." If not correct, 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 <robot_credentials>. 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 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 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.

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

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).
• 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) 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).

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

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

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

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

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

{
  "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.

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

{
  "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).

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.

Combinazione con il thinking

Per combinare computer use con il thinking, consulta Thinking.

Potenziare computer use con altri strumenti

Per aggiungere altri strumenti insieme a computer use, includili nello stesso array tools. La sezione Avvio rapido mostra questo schema con lo strumento bash e lo strumento editor di testo. Puoi aggiungere le tue definizioni di strumenti personalizzati allo stesso modo.

Per le attività che restano all'interno di pagine web, puoi anche dichiarare lo strumento browser use nella stessa richiesta: 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 è 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.

1. 1

   Configura il tuo ambiente di elaborazione

   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.

2. 2

   Implementa i gestori delle azioni

   Crea funzioni per gestire ogni tipo di azione che Claude potrebbe richiedere:

   PythonTypeScriptC#GoJavaPHPRuby

   

   # 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}")

3. 3

   Elabora le chiamate agli strumenti di Claude

   Estrai ed esegui le chiamate agli strumenti dalle risposte di Claude:

   PythonTypeScriptC#GoJavaPHPRuby

   

   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

4. 4

   Implementa l'agent loop

   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 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, rispondi ai blocchi rimanenti del batch con il testo di arresto mostrato lì anziché eseguirli.

Ad esempio, quando l'acquisizione dello screenshot fallisce:

{
  "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 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.

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:

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)

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 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) 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, 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 e Claude Sonnet 5.5, evita di eliminare screenshot sul client. La rimozione di uno screenshot precedente invalida ogni blocco di ragionamento successivo 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 lato server per rimuovere quelli vecchi dal contesto. Se devi eliminarli, mantieni impostato prefix_mismatch_behavior: "drop_block" 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 le 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.

Diagnostica i problemi di clic

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

Segui le best practice di implementazione

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Allow UI to update

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

import logging


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

Migra da computer_20251124

L'aggiornamento da computer_20251124 al toolset è facoltativo: i modelli elencati per computer_20251124 in Versioni precedenti dello strumento continuano ad accettarlo con il relativo beta header, 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 e Claude Sonnet 5.5 continuano ad accettare 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. Negli SDK, rimuovi il parametro betas e chiama la Messages API tramite il client standard anziché il namespace beta.
2. Modifica la voce tools. Imposta type su computer_toolset_20260801 ed elimina name, display_width_px, display_height_px, display_number ed enable_zoom. Il toolset rifiuta ciascuno di questi campi.
3. Scegli se mantenere lo zoom abilitato. Lo zoom è abilitato per impostazione predefinita nel toolset, mentre enable_zoom ha come valore predefinito false. Se il tuo ambiente non implementa lo zoom, aggiungi "configs": {"zoom": {"enabled": false}} per mantenere il comportamento precedente; altrimenti implementalo (vedi Azioni disponibili).
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. Se il tuo ciclo non può ancora eseguire batch, Parametri dello strumento 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.
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.

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

{
  "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:

{
  "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:

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

{
  "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 di 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 in ogni richiesta, e i relativi parametri sono documentati nel riferimento della Messages API beta. Negli SDK, passa l'header tramite il parametro betas e usa il namespace beta; solo lo strumento di computer use necessita dell'header, non gli strumenti bash o editor di testo nella stessa richiesta.

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

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.

Prezzi

L'uso del computer segue i prezzi standard dell'uso degli strumenti. 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.520 su Claude Fable 5, Claude Mythos 5, Claude Opus 5 e Claude Opus 4.8, e circa 4.590 su Claude Sonnet 5), 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 questi 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.

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)
• Risultati dell'esecuzione degli strumenti restituiti a Claude

Passaggi successivi

Compatibility