Strumento di uso del computer

Claude può interagire con ambienti informatici attraverso lo strumento di uso del computer, che fornisce funzionalità di screenshot e controllo di mouse/tastiera per l'interazione autonoma con il desktop. Su WebArena, un benchmark per la navigazione web autonoma su siti web reali, Claude ottiene risultati all'avanguardia tra i sistemi a singolo agente, dimostrando una forte capacità di completare attività del browser multi-step dall'inizio alla fine.



Panoramica

L'uso del computer è una funzionalità beta che consente a Claude di interagire con ambienti desktop. Questo strumento fornisce:

• Cattura di screenshot: Vedere cosa è attualmente visualizzato sullo schermo
• Controllo del mouse: Fare clic, trascinare e spostare il cursore
• Input da tastiera: Digitare testo e utilizzare scorciatoie da tastiera
• Automazione del desktop: Interagire con qualsiasi applicazione o interfaccia

Sebbene l'uso del computer possa essere potenziato con altri strumenti come bash e l'editor di testo per flussi di lavoro di automazione più completi, l'uso del computer si riferisce specificamente alla capacità dello strumento di uso del computer di vedere e controllare ambienti desktop.

Per il supporto dei modelli, consulta il Riferimento degli strumenti.



Considerazioni sulla sicurezza

L'uso del computer è una funzionalità beta con rischi unici distinti dalle funzionalità API standard. Questi rischi sono amplificati quando si interagisce con internet.

In alcune circostanze, Claude seguirà i comandi trovati nei contenuti anche se sono in conflitto con le istruzioni dell'utente. Ad esempio, istruzioni per Claude presenti su pagine web o contenute in immagini potrebbero sovrascrivere le istruzioni o causare errori da parte di Claude. Adotta precauzioni per isolare Claude da dati e azioni sensibili per evitare rischi legati alla prompt injection.

Anthropic ha addestrato il modello a resistere a queste prompt injection e ha aggiunto un ulteriore livello di difesa. Se utilizzi gli strumenti di uso del computer, i classificatori verranno eseguiti automaticamente sui tuoi prompt per segnalare potenziali casi di prompt injection. Quando questi classificatori identificano potenziali prompt injection negli screenshot, guideranno automaticamente il modello a chiedere conferma all'utente prima di procedere con l'azione successiva. Questa protezione aggiuntiva non sarà ideale per ogni caso d'uso (ad esempio, casi d'uso senza un essere umano nel loop), quindi se desideri disattivarla, contatta il supporto.

Queste precauzioni rimangono importanti anche con il livello di difesa dei classificatori attivo.

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



Avvio rapido

Ecco come iniziare con l'uso del computer:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",  # or another compatible model
    max_tokens=1024,
    tools=[
        {
            "type": "computer_20251124",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
            "display_number": 1,
        },
        {"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."}],
    betas=["computer-use-2025-11-24"],
)
print(response)



Come funziona l'uso del computer

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



L'ambiente di calcolo

L'uso del computer richiede un ambiente di calcolo sandbox in cui Claude possa interagire in sicurezza con applicazioni e web. Questo ambiente include:

1. Display virtuale: Un server di display X11 virtuale (utilizzando Xvfb) che renderizza l'interfaccia desktop che Claude vedrà attraverso gli 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ò utilizzare per completare le attività.

4. Implementazioni degli strumenti: Codice di integrazione che traduce le richieste astratte degli strumenti di Claude (come "sposta il mouse" o "fai 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 utilizzi l'uso del computer, 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 calcolo
3. Cattura 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 mappature delle porte appropriate per visualizzare e interagire con l'ambiente.



Come implementare l'uso del computer



Inizia con l'implementazione di riferimento

È disponibile un'implementazione di riferimento che include tutto il necessario per iniziare con l'uso del computer:

• Un ambiente containerizzato adatto all'uso del computer con Claude
• Implementazioni degli strumenti di uso del computer
• Un agent loop che interagisce con l'API di Claude ed esegue gli strumenti di uso del computer
• Un'interfaccia web per interagire con il container, l'agent loop e gli strumenti.



Comprendere il ciclo agentico

Il cuore dell'uso del computer è l'"agent loop": un ciclo in cui Claude richiede azioni degli strumenti, la tua applicazione le esegue e restituisce i risultati a Claude. Ecco un esempio semplificato:

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

Prova l'implementazione di riferimento prima di leggere il resto di questa documentazione.



Ottimizza le prestazioni del modello con il prompting

Ecco alcuni suggerimenti su come ottenere output della migliore qualità:

1. Specifica attività semplici e ben definite e fornisci istruzioni esplicite per ogni passaggio.
2. Claude a volte presume i risultati delle sue azioni senza verificarli esplicitamente. Per prevenire questo puoi fornire a Claude un prompt come 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 utente (come menu a discesa e barre di scorrimento) potrebbero essere difficili da manipolare per Claude utilizzando i movimenti del mouse. Se riscontri questo problema, prova a suggerire al modello di utilizzare scorciatoie da tastiera.
4. Per attività ripetibili o interazioni con l'interfaccia utente, includi nel tuo prompt screenshot di esempio e chiamate agli strumenti di risultati riusciti.
5. Se hai bisogno che il modello effettui l'accesso, forniscigli nome utente e password nel tuo prompt all'interno di tag XML come <robot_credentials>. L'utilizzo dell'uso del computer 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 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. Quando utilizzi computer_20251124 con enable_zoom: true impostato, Claude ingrandisce una regione quando gli viene chiesto di testo piccolo o elementi specifici dell'interfaccia utente che non sono 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 ingrandisce quando te lo aspetti, chiedi di una regione o elemento specifico piuttosto che dello schermo nel suo complesso.



Prompt di sistema

Quando uno degli strumenti con schema Anthropic viene richiesto tramite l'API di Claude, viene generato un prompt di sistema specifico per l'uso del computer. È 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 con l'uso degli strumenti regolare, il campo system_prompt fornito dall'utente è comunque rispettato e utilizzato nella costruzione del prompt di sistema combinato.



Azioni disponibili

Lo strumento di uso del computer supporta queste azioni:

Azioni di base (tutte le versioni)

• screenshot: Cattura il display corrente
• left_click: Fai clic alle coordinate [x, y]
• type: Digita una stringa di testo
• key: Premi un tasto o una combinazione di tasti (ad esempio, "ctrl+s")
• mouse_move: Sposta il cursore alle coordinate

Azioni avanzate (computer_20250124) Disponibili su tutti i modelli che supportano l'uso del computer:

• scroll: Scorri in qualsiasi direzione con controllo della quantità
• left_click_drag: Fai clic e trascina tra coordinate
• right_click, middle_click: Pulsanti del mouse aggiuntivi
• double_click, triple_click: Clic multipli
• left_mouse_down, left_mouse_up: Controllo granulare dei clic
• hold_key: Tieni premuto un tasto per una durata specificata (in secondi)
• wait: Pausa tra le azioni

Azioni avanzate (computer_20251124) Disponibili in Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 e Claude Opus 4.5:

• Tutte le azioni di computer_20250124
• zoom: Visualizza una regione specifica dello schermo a piena risoluzione. Richiede enable_zoom: true nella definizione dello strumento. Accetta un parametro region con coordinate [x1, y1, x2, y2] che definiscono gli angoli superiore sinistro e inferiore destro dell'area da ispezionare.



Parametri dello strumento



Combinazione con il pensiero esteso

Per combinare l'uso del computer con il pensiero esteso, consulta Pensiero esteso.



Potenziare l'uso del computer con altri strumenti

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



Costruisci un ambiente personalizzato per l'uso del computer

L'implementazione di riferimento è pensata per aiutarti a iniziare con l'uso del computer. Include tutti i componenti necessari per far utilizzare un computer a Claude. Tuttavia, puoi costruire il tuo ambiente per l'uso del computer in base alle tue esigenze. Avrai bisogno di:

• Un ambiente virtualizzato o containerizzato adatto all'uso del computer con Claude
• Un'implementazione di almeno uno degli strumenti di uso del computer con schema Anthropic
• Un agent loop che interagisce con l'API di Claude ed esegue i risultati tool_use utilizzando le tue implementazioni degli strumenti
• Un'API o interfaccia utente che consenta l'input dell'utente per avviare l'agent loop



Implementa lo strumento di uso del computer

Lo strumento di uso del computer è implementato come strumento senza schema. Quando utilizzi questo strumento, non è necessario fornire uno schema di input come con altri strumenti; lo schema è integrato nel modello di Claude e non può essere modificato.



Gestisci gli errori

Durante l'implementazione dello strumento di uso del computer, potrebbero verificarsi vari errori. Ecco come gestirli:



Dimensiona gli screenshot per rispettare i limiti delle immagini

Gli screenshot inviati allo strumento computer devono già rientrare nei limiti di dimensione delle immagini di Claude (consulta limiti di dimensione delle immagini). L'API non ridimensiona le immagini troppo grandi; uno screenshot che supera il limite viene rifiutato con un errore di validazione HTTP 400.

Se il tuo schermo è più grande del limite, ridimensiona lo screenshot prima di inviarlo, imposta display_width_px/display_height_px alle dimensioni ridimensionate e riscala le coordinate restituite da Claude allo spazio dello schermo originale:



Diagnostica i problemi di clic

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



Segui le best practice di implementazione



Comprendere le limitazioni del computer use

La funzionalità di "computer use" (uso del computer) è in beta. Sebbene le capacità di Claude siano allo stato dell'arte, gli sviluppatori dovrebbero essere consapevoli delle sue limitazioni:

1. Latency: 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. Accuratezza e affidabilità della computer vision: Claude potrebbe commettere errori o allucinare quando produce coordinate specifiche durante la generazione di azioni. Il pensiero esteso può aiutarti a comprendere il ragionamento del modello e identificare potenziali problemi.
3. Accuratezza e affidabilità nella selezione degli strumenti: Claude potrebbe commettere errori o allucinare quando seleziona gli strumenti durante la generazione di azioni, oppure intraprendere azioni inaspettate per risolvere problemi. Inoltre, l'affidabilità potrebbe essere inferiore quando si interagisce con applicazioni di nicchia o con più applicazioni contemporaneamente. Formula il prompt al modello con attenzione 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 essere d'aiuto.
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 capacità di Claude di creare account o generare e condividere contenuti, o comunque di impersonare esseri umani su siti web e piattaforme di social media, è limitata. Questa capacità potrebbe essere aggiornata in futuro.
7. Vulnerabilità: Vulnerabilità come il jailbreaking o la prompt injection potrebbero persistere nei sistemi di IA di frontiera, inclusa l'API beta di computer use. In alcune circostanze, Claude seguirà comandi trovati nei contenuti, a volte anche in conflitto con le istruzioni dell'utente. Ad esempio, istruzioni per Claude presenti su pagine web o contenute in immagini potrebbero sovrascrivere le istruzioni o indurre Claude a commettere errori. Considera quanto segue: a. Limitare il computer use ad ambienti affidabili come macchine virtuali o container con privilegi minimi b. Evitare di dare al computer use accesso ad account o dati sensibili senza una supervisione rigorosa c. Informare gli utenti finali dei rischi rilevanti e ottenere il loro consenso prima di abilitare o richiedere le autorizzazioni necessarie per le funzionalità di computer use nelle tue applicazioni
8. Azioni inappropriate o illegali: Secondo i Termini di Servizio di Anthropic, non devi utilizzare il computer use per violare alcuna legge o la Politica di Uso Accettabile.

Rivedi e verifica sempre attentamente le azioni e i log di computer use di Claude. Non usare Claude per attività che richiedono 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, ma non le conserva dopo che la risposta è stata restituita.

Poiché la tua applicazione controlla dove e come vengono archiviati i dati del computer use, il computer use è idoneo per ZDR. Per l'idoneità ZDR su tutte le funzionalità, consulta API e conservazione dei dati.



Prezzi

L'uso del computer segue la tariffazione standard per l'uso degli strumenti. Quando si utilizza lo strumento di uso del computer:

Overhead del prompt di sistema: la beta dell'uso del computer aggiunge 466-499 token al prompt di sistema

Utilizzo di token dello strumento di uso del computer:

Consumo aggiuntivo di token:

• Immagini di screenshot (consulta la tariffazione Vision)
• Risultati dell'esecuzione degli strumenti restituiti a Claude



Passaggi successivi