Claude Platform Docs
MessaggiStrumenti

Strumento computer use

Dai a Claude il controllo di screenshot, mouse e tastiera di un ambiente desktop con lo strumento computer use, il toolset client computer_toolset_20260801.

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

Lo strumento computer use è un toolset client definito da Anthropic: una singola voce {"type": "computer_toolset_20260801"} in tools fornisce a Claude 17 strumenti membri come screenshot, left_click, type e zoom, e la tua applicazione esegue ogni chiamata in un ambiente che controlli. Al momento non è disponibile in Claude Managed Agents. Le chiamate di Claude sono blocchi tool_use il cui name è il membro e che riportano "toolset_name": "computer", spesso diversi in un unico turno (una batch action (azione in batch)).

Per le attività che restano all’interno delle 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.

Consulta Supporto API per i modelli e le piattaforme che supportano il toolset. Versioni precedenti dello strumento elenca l’header beta di ciascuna versione precedente e i modelli con cui utilizzarla.

Considerazioni sulla sicurezza

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

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

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

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

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

Avvio rapido

Aggiungi il toolset computer use all’array tools di una richiesta alla Messages APIAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) come {"type": "computer_toolset_20260801"}. La richiesta non necessita di alcun beta header. Questo esempio dichiara anche lo strumento editor di testo e lo strumento bash, che Claude usa tipicamente insieme al 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 dei membri, ciascuno dei quali nomina uno strumento membro e riporta "toolset_name": "computer". A metà di questa attività, dopo che Claude ha ricevuto uno screenshot del desktop, una risposta potrebbe apparire così:

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

La tua applicazione esegue ogni chiamata in ordine nel tuo ambiente, restituisce un blocco tool_result per ogni blocco tool_use e chiama di nuovo l’API; Come funziona il computer use descrive questo ciclo, e il resto di questa pagina mostra come implementarlo.


Come funziona il computer use

  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. Claude risponde con chiamate agli strumenti membri

    • Claude valuta se agire sul desktop possa aiutare a rispondere alla richiesta dell’utente.
    • In tal caso, Claude risponde con uno o più blocchi tool_use dei membri, come screenshot, left_click o type, ciascuno dei quali riporta "toolset_name": "computer". Una risposta con più blocchi di questo tipo è un’azione batch.
    • La risposta dell’API ha uno stop_reason pari a tool_use, che segnala una richiesta di uso degli strumenti.
  3. Esegui le chiamate in ordine e restituisci i risultati

    • Itera su ogni blocco tool_use nella risposta, in ordine. Per ciascuno, smista in base al name del membro insieme a toolset_name, ed esegui quell’azione con l’input del blocco sul tuo container o sulla tua macchina virtuale.
    • Prosegui la conversazione con un nuovo messaggio user che contenga un blocco tool_result per ogni blocco tool_use, abbinato tramite tool_use_id e ciascuno con la ripetizione di "toolset_name": "computer". Restituisci un’immagine per screenshot e zoom; per le altre azioni basta un breve testo come OK.
    • Se un’azione fallisce, restituisci is_error: true per quel blocco e rispondi al resto del batch come descritto in Azioni batch.
  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; torna al passaggio 3.
    • Altrimenti, restituisce una risposta testuale all’utente.

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

Azioni batch

Claude può pianificare una breve sequenza di azioni, ad esempio fare clic, digitare e poi acquisire uno screenshot, e restituirle insieme in un’unica risposta. Questa si chiama azione batch; usa la stessa forma di risposta dell’uso parallelo degli strumenti 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 necessitano di un’immagine; per gli altri membri basta un breve riscontro 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 di solito dipendono da quelle precedenti: il type in questo esempio inserisce il testo in qualunque elemento il clic precedente abbia messo a fuoco. Esegui i blocchi in sequenza nell’ordine in cui appaiono in content e, se uno fallisce, non eseguire i restanti. Ogni blocco tool_use necessita comunque di un tool_result, quindi rispondi al batch come segue:

  • Per ogni azione riuscita, restituisci il suo risultato normale.
  • Per l’azione fallita, restituisci is_error: true con una descrizione testuale di ciò che è andato storto.
  • Per ogni azione successiva nel batch, restituisci is_error: true esattamente con questo testo (lo strumento browser use usa il proprio testo di interruzione):
{
  "type": "tool_result",
  "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}

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

Claude termina tipicamente un batch con screenshot in modo da poter osservare il risultato prima di decidere cosa fare dopo. Quando un batch non termina con uno screenshot, la tua applicazione può allegare uno screenshot come blocco image aggiuntivo all’ultimo risultato del batch, così che Claude riceva sempre lo stato corrente dello schermo; questo consente di risparmiare un passaggio di andata e ritorno rispetto all’attesa che sia Claude a richiederlo. Puoi anche chiedere a Claude nel prompt di terminare ogni batch con uno screenshot (consulta Ottimizzare le prestazioni del modello con il prompting).

L’ambiente di calcolo

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

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

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

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

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

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

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

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

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


Come implementare il computer use

Stai aggiornando un’integrazione esistente con computer_20251124? Inizia da Migrare da computer_20251124; il resto di questa sezione si applica sia alle integrazioni nuove sia a quelle migrate.

Comprendere il ciclo dell’agente

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

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

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

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

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

    return messages

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

Ottimizzare le prestazioni del modello con il prompting

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

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

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

Prompt di sistema

Quando includi lo strumento computer use in una richiesta, l’API genera un prompt di sistema specifico per il computer use. È simile al prompt di sistema per l’uso degli strumenti ma inizia con:

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

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

Azioni disponibili

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

MembroInputDescrizione
screenshotNessuno ({})Acquisisce l’intero display e lo restituisce come immagine.
zoomregion: [x0, y0, x1, y1], gli angoli superiore sinistro e inferiore destro dell’area da ispezionareAcquisisce solo quella regione del display a piena risoluzione e la restituisce come immagine, ridimensionata per rientrare nelle dimensioni abituali dei tuoi screenshot mantenendone le proporzioni. Ciò consente a Claude di leggere testo piccolo o interfacce dense che non sono leggibili in uno screenshot completo ridimensionato.
left_clickcoordinate (facoltativo): [x, y]; text (facoltativo): tasti modificatori da tenere premuti durante il clic: shift, ctrl, alt, super (il tasto Comando o Windows), o una combinazione unita da + come ctrl+shiftFa clic con il pulsante sinistro del mouse in coordinate, oppure nella posizione corrente del cursore quando coordinate è omesso.
right_click, middle_click, double_click, triple_clickCome left_clickAltri pulsanti del mouse e clic multipli.
left_click_dragstart_coordinate: [x, y]; coordinate: [x, y]; text (facoltativo): tasti modificatoriPreme in start_coordinate, trascina fino a coordinate e rilascia.
mouse_movecoordinate: [x, y]Sposta il cursore senza fare clic, ad esempio per passare sopra un elemento.
left_mouse_down, left_mouse_upNessuno ({})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_positionNessuno ({})Riporta la posizione [x, y] corrente del cursore come testo.
scrollscroll_direction: "up", "down", "left" o "right"; scroll_amount: numero di scatti della rotellina; coordinate (facoltativo): [x, y]; text (facoltativo): tasti modificatoriScorre in coordinate, oppure nella posizione corrente del cursore.
typetext: la stringa da digitareDigita testo letterale nel punto in cui si trova il focus della tastiera.
keytext: un tasto o una combinazione unita da + come "Return", "ctrl+s" o "alt+Tab"; repeat (facoltativo): da 1 a 100, valore predefinito 1Preme un tasto o una combinazione di tasti, repeat volte.
hold_keytext: un tasto o una combinazione; duration: secondi, fino a 300Tiene premuto un tasto per la durata indicata.
waitduration: secondi, fino a 300Attende prima dell’azione successiva, ad esempio mentre un’applicazione si carica.

Tieni presente quanto segue quando implementi i membri:

  • Le coordinate sono in pixel dello screenshot. Ogni valore di coordinate, start_coordinate e region, e la posizione riportata da cursor_position, è nello spazio in pixel degli screenshot dell’intero display che restituisci, con l’origine in alto a sinistra. Le immagini di zoom non cambiano questo aspetto: dopo uno zoom, Claude esprime comunque le coordinate nello spazio dello screenshot completo, mai rispetto all’immagine ingrandita. Se riduci gli screenshot prima di restituirli, riporta le coordinate di Claude alla scala originale prima di applicarle al display reale (consulta Dimensiona gli screenshot per rispettare i limiti delle immagini).
  • 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.
  • Smista in base alla coppia (toolset_name, name). È toolset_name che contrassegna un blocco come azione del computer: uno strumento personalizzato nella stessa richiesta può condividere il nome di un membro, e una versione successiva del toolset può aggiungere membri (consulta Toolset client).

Parametri dello strumento

La voce del toolset nell’array tools accetta quattro parametri; le regole che condividono con il toolset browser use sono elencate in Toolset client.

ParametroObbligatorioDescrizione
typeSìcomputer_toolset_20260801
configsNoImpostazioni per membro indicizzate per nome del membro; ogni membro accetta enabled (valore predefinito true per tutti e 17, incluso zoom) e defer_loading (valore predefinito false, per la ricerca degli strumenti), e i membri che ometti mantengono i valori predefiniti.
cache_controlNoBreakpoint della cache dei prompt in corrispondenza della definizione del toolset; solo sulla voce. Un breakpoint su qualsiasi blocco tool_use o tool_result in un batch ha effetto alla fine di quel batch; consulta Uso degli strumenti con la cache dei prompt.
allowed_callersNoSolo ["direct"].

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

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

Se il tuo ciclo dell’agente può eseguire una sola azione per ogni passaggio di andata e ritorno, imposta disable_parallel_tool_use su true in tool_choice; Claude restituisce quindi al massimo un blocco tool_use di un membro per ogni turno (consulta Disabilitare l’uso parallelo degli strumenti).

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

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

Inoltre la voce non può essere dichiarata nella stessa richiesta di una voce computer_20251124 o di un altro strumento chiamato computer. Per strict, input_examples, il posizionamento di defer_loading, tool_choice, lo streaming e le restrizioni sui chiamanti, consulta Toolset client.

Combinazione con il ragionamento

Per combinare il computer use con il ragionamento, consulta Ragionamento.

Integrare il computer use con altri strumenti

Per aggiungere altri strumenti insieme al 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 delle 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. Il valore di toolset_name distingue le chiamate ai membri che condividono un nome, come screenshot o key.

Creare un ambiente di computer use personalizzato

L’implementazione di riferimento ha lo scopo di aiutarti a iniziare con il computer use. Include tutti i componenti necessari affinché Claude possa usare un computer. Tuttavia, puoi creare il tuo ambiente per il computer use in base alle tue esigenze. Ti servono:

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

Implementare lo strumento computer use

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

  1. Configura il tuo ambiente di calcolo

    Crea un display virtuale o connettiti a un display esistente con cui Claude interagisce. In genere ciò comporta la configurazione di Xvfb (X Virtual Framebuffer) o di una tecnologia simile.

  2. Implementa i gestori delle azioni

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

    # Placeholder image data; a real executor captures the screen and returns the PNG bytes
    PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
    
    
    def capture_screenshot() -> list[ImageBlockParam]:
        # screenshot answers with an image block rather than text: return the result content list
        return [
            {
                "type": "image",
                "source": {
                    "type": "base64",
                    "media_type": "image/png",
                    "data": PLACEHOLDER_PNG,
                },
            }
        ]
    
    
    def click(coordinate=None):
        if coordinate is None:
            return "clicked at current cursor"
        x, y = coordinate
        return f"clicked at ({x}, {y})"
    
    
    def type_text(text):
        return f"typed: {text}"
    
    
    def handle_computer_action(name, tool_input):
        match name:
            case "screenshot":
                return capture_screenshot()
            case "left_click":
                # coordinate is optional; without it, click where the cursor already is
                return click(tool_input.get("coordinate"))
            case "type":
                return type_text(tool_input["text"])
        # Handle other actions as needed
        raise ValueError(f"Unknown or unimplemented member: {name}")
  3. Elabora le chiamate agli strumenti di Claude

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

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

    Racchiudi i due passaggi precedenti in un ciclo che invia nuovamente i risultati e si ripete finché Claude non restituisce più chiamate agli strumenti membri; Comprendere il ciclo dell’agente mostra questo ciclo.

Gestire gli errori

Segnala un’azione fallita a Claude come tool_result con is_error: true e una breve descrizione, e includi "toolset_name": "computer" come per qualsiasi altro risultato di un membro. Se l’azione fallita faceva parte di un’azione batch, rispondi ai blocchi restanti del batch con il testo di interruzione mostrato in quella sezione anziché eseguirli.

Ad esempio, quando l’acquisizione dello screenshot fallisce:

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

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

Dimensiona gli screenshot per rispettare i limiti delle immagini

Gli screenshot e le immagini di zoom che restituisci al toolset di computer use devono già rientrare nei limiti di dimensione delle immagini del tuo modello: il toolset non accetta dimensioni del display e l’API non esegue il ridimensionamento per te, quindi un’immagine tool_result troppo grande viene rifiutata con un errore di validazione. Poiché Claude restituisce le coordinate nello spazio dei pixel dell’immagine che riceve, conserva il fattore di scala che hai usato in modo da poter rimappare quelle coordinate sul tuo schermo.

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

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

Gestisci la cronologia degli screenshot

I lunghi cicli dell’agente accumulano rapidamente screenshot (circa 1.000–1.800 token di input ciascuno). Si applicano anche i limiti delle richieste dell’API.

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

Per mantenere efficace il “prompt caching” (cache dei prompt) limitando al contempo il contesto:

  • Posiziona un breakpoint cache_control dopo il prompt di sistema e le definizioni degli strumenti, e fino a tre ulteriori sull’ultimo blocco tool_result di ciascuno dei turni più recenti, facendoli avanzare a ogni turno. All’interno di un’azione batch, i marcatori su più blocchi agiscono come un unico breakpoint, ma ciascuno conta comunque per il limite di quattro, quindi usane al massimo uno per turno.
  • Elimina i vecchi screenshot a blocchi, non uno per turno. Scartare uno screenshot a ogni turno modifica il prefisso a ogni turno e invalida la cache. Un valore predefinito ragionevole è mantenere gli ultimi tre screenshot ed eliminare ogni 25 turni, così il prefisso rimane identico byte per byte tra un’eliminazione e l’altra; se i tuoi screenshot superano il limite più restrittivo, scegli un intervallo che mantenga ogni richiesta a 20 immagini o meno.
  • Evita l’eliminazione lato client su Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1 e Claude Mythos 5.1. Lo stesso vale per Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5. Su questi modelli, rimuovere uno screenshot precedente da una richiesta invalida ogni “thinking block” (blocco di ragionamento) successivo già presente nella cronologia di quella richiesta e di ogni richiesta successiva.
    • In alternativa: Ridimensiona gli screenshot per non superare il limite più restrittivo. La “tool result clearing” (cancellazione dei risultati degli strumenti) fa risparmiare token, ma gli screenshot cancellati contano comunque per i limiti delle richieste, quindi usa la “on-demand compaction” (compattazione su richiesta) prima che un ciclo li raggiunga.
    • Se devi eliminare: Mantieni impostato prefix_mismatch_behavior: "drop_block" da quel momento in poi. Dopo ogni eliminazione, l’API scarta i blocchi di ragionamento invalidati, in quella richiesta e in ogni richiesta successiva. Claude prosegue quindi senza il ragionamento prodotto dopo lo screenshot eliminato.
    • Se devi eliminare su Claude Sonnet 5.5 o Claude Haiku 5.5: prefix_mismatch_behavior funziona solo con thinking: {"type": "adaptive"}. Con qualsiasi altra impostazione di ragionamento su quei modelli, mantieni la cronologia in sola aggiunta oppure rimuovi ogni blocco thinking e redacted_thinking successivo allo screenshot eliminato.

Diagnostica i problemi di clic

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

SintomoCausa probabileProva
I clic sono costantemente spostati in una direzioneLe coordinate di Claude, che si trovano nello spazio dei pixel degli screenshot che restituisci, vengono applicate a un display di dimensioni diverse senza scalaturaScala ogni coordinata in base al rapporto tra la dimensione del tuo schermo e quella del tuo screenshot prima di fare clic (consulta Dimensiona gli screenshot per rispettare i limiti delle immagini); sui display Retina di macOS, tieni conto del rapporto pixel del dispositivo 2x
I clic finiscono nell’area giusta ma mancano l’obiettivoL’obiettivo è molto piccolo, i dettagli sono andati persi riducendo una sorgente 4K+, oppure le proporzioni sono state distorteMantieni abilitato il membro zoom e implementalo in modo che Claude possa ispezionare la regione a piena risoluzione; acquisisci a DPI inferiori o ritaglia la regione rilevante; preserva le proporzioni durante il ridimensionamento
Claude fa clic su un elemento completamente sbagliatoIstruzione ambigua, o elementi visivamente simili nelle vicinanzeUsa prompt posizionali (“il pulsante blu Invia in basso a destra”); suddividi l’interazione in passaggi più piccoli
La precisione è costantemente scarsaRisoluzione troppo bassaProva 1280x720 come riferimento

Segui le best practice di implementazione


Migrazione da computer_20251124

Un’integrazione computer_20251124 funziona senza modifiche sui modelli elencati per quella versione in Versioni precedenti dello strumento. Aggiorna l’integrazione prima di spostarla su un modello che non accetta computer_20251124, come Claude Opus 5.5 sulla Claude API.

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

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

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 consentire a Claude di usare 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 passa 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 computer use sono disponibili in beta. Ciascuna richiede il proprio header beta in ogni richiesta, e i relativi parametri sono documentati nel riferimento della Messages API betaAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro). Con l’SDK, passa l’header tramite betas 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 strumentoHeader betaDa usare conParametri
computer_20251124computer-use-2025-11-24Claude 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.5Riferimento APIAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro)
computer_20250124computer-use-2025-01-24Claude Sonnet 4.5 (deprecato), Claude Haiku 4.5, Claude Opus 4.1 (ritirato, tranne su Claude Models on Google Cloud (Google managed) e Bedrock), Claude Sonnet 4 (ritirato, tranne su Claude Models on Google Cloud (Google managed) e Bedrock) e Claude Opus 4 (ritirato, tranne su Claude Models on Google Cloud (Google managed))Riferimento APIAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro)

Su Amazon Bedrock, anche Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 accettano lo strumento computer_20251124 con l’header beta computer-use-2025-11-24. Con l’API InvokeModel di Amazon Bedrock, invia computer-use-2025-11-24 nell’array anthropic_beta del corpo della richiesta anziché in un header. Per quell’API, consulta Claude su Amazon Bedrock (bedrock-runtime).


Limitazioni

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

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

Conservazione dei dati

Il computer use è uno strumento lato client. Tutti gli screenshot, le azioni del mouse, gli input da tastiera e gli eventuali file coinvolti in una sessione vengono acquisiti e archiviati nel tuo ambiente, non da Anthropic. Anthropic elabora le immagini degli screenshot e le richieste di azione in tempo reale come parte della chiamata API. La conservazione di tali richieste API è regolata da API e conservazione dei dati.

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

Prezzi

L’uso del computer segue i prezzi standard dell’uso degli strumenti. 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.

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

Parti dal driver di un partner o scrivi il tuo in Python o TypeScript. L’SDK esegue il ciclo e la callback di approvazione che passi.

Correggi gli errori più comuni di uso degli strumenti con tabelle diagnostiche sintomo-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, sforzo 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 rimangono all’interno del browser.

Disponibilità

Strumento computer use
API
  • Messages API
  • Managed Agents Non supportato
Modelli
  • Claude Fable 5.2, Fable 5.1, Fable 5
  • Claude Mythos 5.2, Mythos 5.1, Mythos 5, Mythos Preview
  • Claude Opus 5.5, Opus 5, Opus 4.8
  • Claude Opus 4.7, Opus 4.6, Opus 4.5 Beta richiede
  • Claude Sonnet 5.5, Sonnet 5
  • Claude Sonnet 4.6 Beta richiede
  • Claude Sonnet 4.5 Beta richiede
  • Claude Haiku 5.5
  • Claude Haiku 4.5 Beta richiede

Endpoint applicabili

  • /v1/messages con il toolset o lo strumento computer
Conservazione zero dei datiIdoneo

Esclude Modelli coperti

Strumento lato client in cui screenshot e file vengono acquisiti e archiviati nel tuo ambiente, non da Anthropic. Scopri di più

HIPAAIdoneo

Questa pagina ti è stata utile?