Strumento di utilizzo del computer
Claude può interagire con ambienti informatici attraverso lo strumento di utilizzo del computer, che fornisce capacità di screenshot e controllo di mouse/tastiera per l’interazione autonoma del desktop.
Claude può interagire con ambienti informatici attraverso lo strumento di utilizzo del computer, che fornisce capacità di screenshot e controllo di mouse/tastiera per l’interazione autonoma del desktop.
L’utilizzo del computer è attualmente in beta e richiede un header beta:
"computer-use-2025-01-24"
(modelli Claude 4 e 3.7)"computer-use-2024-10-22"
(Claude Sonnet 3.5)
Panoramica
L’utilizzo del computer è una funzionalità beta che consente a Claude di interagire con ambienti desktop. Questo strumento fornisce:
- Cattura screenshot: Vedere cosa è attualmente visualizzato sullo schermo
- Controllo del mouse: Cliccare, trascinare e muovere il cursore
- Input da tastiera: Digitare testo e utilizzare scorciatoie da tastiera
- Automazione desktop: Interagire con qualsiasi applicazione o interfaccia
Mentre l’utilizzo del computer può essere potenziato con altri strumenti come bash e editor di testo per flussi di lavoro di automazione più completi, l’utilizzo del computer si riferisce specificamente alla capacità dello strumento di utilizzo del computer di vedere e controllare ambienti desktop.
Compatibilità del modello
L’utilizzo del computer è disponibile per i seguenti modelli Claude:
Modello | Versione Strumento | Flag Beta |
---|---|---|
Claude 4 Opus & Sonnet | computer_20250124 | computer-use-2025-01-24 |
Claude Sonnet 3.7 | computer_20250124 | computer-use-2025-01-24 |
Claude Sonnet 3.5 (nuovo) | computer_20241022 | computer-use-2024-10-22 |
I modelli Claude 4 utilizzano versioni di strumenti aggiornate ottimizzate per la nuova architettura. Claude Sonnet 3.7 introduce capacità aggiuntive inclusa la funzionalità di pensiero per maggiore comprensione del processo di ragionamento del modello.
Considerazioni sulla sicurezza
L’utilizzo del computer è una funzionalità beta con rischi unici distinti dalle funzionalità API standard. Questi rischi sono aumentati quando si interagisce con internet. Per minimizzare i rischi, considera di prendere precauzioni come:
- Utilizzare una macchina virtuale dedicata o un container con privilegi minimi per prevenire attacchi diretti al sistema o incidenti.
- Evitare di dare al modello accesso a dati sensibili, come informazioni di login dell’account, per prevenire il furto di informazioni.
- Limitare l’accesso internet a una lista di domini consentiti per ridurre l’esposizione a contenuti dannosi.
- Chiedere a un umano di confermare decisioni che potrebbero risultare in conseguenze significative nel mondo reale così come qualsiasi compito che richiede consenso affermativo, come accettare cookie, eseguire transazioni finanziarie, o accettare termini di servizio.
In alcune circostanze, Claude seguirà comandi trovati nel contenuto anche se in conflitto con le istruzioni dell’utente. Per esempio, le istruzioni di Claude su pagine web o contenute in immagini potrebbero sovrascrivere le istruzioni o causare errori a Claude. Suggeriamo di prendere precauzioni per isolare Claude da dati e azioni sensibili per evitare rischi relativi all’iniezione di prompt.
Abbiamo addestrato il modello a resistere a queste iniezioni di prompt e abbiamo aggiunto un livello extra di difesa. Se utilizzi i nostri strumenti di utilizzo del computer, eseguiremo automaticamente classificatori sui tuoi prompt per segnalare potenziali istanze di iniezioni di prompt. Quando questi classificatori identificano potenziali iniezioni di prompt negli screenshot, indirizzeranno automaticamente il modello a chiedere conferma dell’utente prima di procedere con l’azione successiva. Riconosciamo che questa protezione extra non sarà ideale per ogni caso d’uso (per esempio, casi d’uso senza un umano nel ciclo), quindi se desideri rinunciare e disattivarla, per favore contattaci.
Suggeriamo ancora di prendere precauzioni per isolare Claude da dati e azioni sensibili per evitare rischi relativi all’iniezione di prompt.
Infine, per favore informa gli utenti finali dei rischi rilevanti e ottieni il loro consenso prima di abilitare l’utilizzo del computer nei tuoi prodotti.
Implementazione di riferimento per l'utilizzo del computer
Inizia rapidamente con la nostra implementazione di riferimento per l’utilizzo del computer che include un’interfaccia web, container Docker, implementazioni di strumenti di esempio, e un ciclo agente.
Nota: L’implementazione è stata aggiornata per includere nuovi strumenti sia per Claude 4 che per Claude Sonnet 3.7. Assicurati di scaricare l’ultima versione del repository per accedere a queste nuove funzionalità.
Per favore utilizza questo modulo per fornire feedback sulla qualità delle risposte del modello, l’API stessa, o la qualità della documentazione - non vediamo l’ora di sentirti!
Avvio rapido
Ecco come iniziare con l’utilizzo del computer:
Requisiti header beta:
- Claude 4 e Sonnet 3.7: Header beta richiesto solo per lo strumento di utilizzo del computer
- Claude Sonnet 3.5: Header beta richiesto per strumenti computer, bash, e editor di testo
L’esempio sopra mostra tutti e tre gli strumenti utilizzati insieme, il che richiede l’header beta per qualsiasi modello Claude poiché include lo strumento di utilizzo del computer.
Come funziona l’utilizzo del computer
1. Fornisci a Claude lo strumento di utilizzo del computer e un prompt utente
- Aggiungi lo strumento di utilizzo del computer (e opzionalmente altri strumenti) alla tua richiesta API.
- Includi un prompt utente che richiede interazione desktop, ad es., “Salva un’immagine di un gatto sul mio desktop.”
2. Claude decide di utilizzare lo strumento di utilizzo del computer
- Claude valuta se lo strumento di utilizzo del computer può aiutare con la query dell’utente.
- Se sì, Claude costruisce una richiesta di utilizzo strumento formattata correttamente.
- La risposta API ha un
stop_reason
ditool_use
, segnalando l’intenzione di Claude.
3. Estrai l'input dello strumento, valuta lo strumento su un computer, e restituisci i risultati
- Dal tuo lato, estrai il nome dello strumento e l’input dalla richiesta di Claude.
- Utilizza lo strumento su un container o Macchina Virtuale.
- Continua la conversazione con un nuovo messaggio
user
contenente un blocco di contenutotool_result
.
4. Claude continua a chiamare strumenti di utilizzo del computer finché non ha completato il compito
- Claude analizza i risultati dello strumento per determinare se è necessario più utilizzo di strumenti o se il compito è stato completato.
- Se Claude decide che ha bisogno di un altro strumento, risponde con un altro
stop_reason
tool_use
e dovresti tornare al passo 3. - Altrimenti, crea una risposta testuale per l’utente.
Ci riferiamo alla ripetizione dei passi 3 e 4 senza input dell’utente come il “ciclo agente” - cioè, Claude che risponde con una richiesta di utilizzo strumento e la tua applicazione che risponde a Claude con i risultati della valutazione di quella richiesta.
L’ambiente informatico
L’utilizzo del computer richiede un ambiente informatico sandboxed dove Claude può interagire in sicurezza con applicazioni e il web. Questo ambiente include:
-
Display virtuale: Un server display X11 virtuale (utilizzando Xvfb) che renderizza l’interfaccia desktop che Claude vedrà attraverso screenshot e controllerà con azioni mouse/tastiera.
-
Ambiente desktop: Una UI leggera con window manager (Mutter) e pannello (Tint2) in esecuzione su Linux, che fornisce un’interfaccia grafica consistente con cui Claude può interagire.
-
Applicazioni: Applicazioni Linux preinstallate come Firefox, LibreOffice, editor di testo, e gestori di file che Claude può utilizzare per completare compiti.
-
Implementazioni strumenti: Codice di integrazione che traduce le richieste di strumenti astratte di Claude (come “muovi mouse” o “fai screenshot”) in operazioni effettive nell’ambiente virtuale.
-
Ciclo 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 comandi) a Claude.
Quando utilizzi l’utilizzo del computer, Claude non si connette direttamente a questo ambiente. Invece, la tua applicazione:
- Riceve le richieste di utilizzo strumento di Claude
- Le traduce in azioni nel tuo ambiente informatico
- Cattura i risultati (screenshot, output comandi, ecc.)
- Restituisce questi risultati a Claude
Per sicurezza e isolamento, l’implementazione di riferimento esegue tutto questo all’interno di un container Docker con mappature di porta appropriate per visualizzare e interagire con l’ambiente.
Come implementare l’utilizzo del computer
Inizia con la nostra implementazione di riferimento
Abbiamo costruito un’implementazione di riferimento che include tutto ciò di cui hai bisogno per iniziare rapidamente con l’utilizzo del computer:
- Un ambiente containerizzato adatto per l’utilizzo del computer con Claude
- Implementazioni degli strumenti di utilizzo del computer
- Un ciclo agente che interagisce con l’API Anthropic ed esegue gli strumenti di utilizzo del computer
- Un’interfaccia web per interagire con il container, ciclo agente, e strumenti.
Comprendere il ciclo multi-agente
Il nucleo dell’utilizzo del computer è il “ciclo agente” - un ciclo dove Claude richiede azioni strumento, la tua applicazione le esegue, e restituisce risultati a Claude. Ecco un esempio semplificato:
Il ciclo continua finché Claude risponde senza richiedere strumenti (completamento compito) o viene raggiunto il limite massimo di iterazioni. Questa salvaguardia previene potenziali cicli infiniti che potrebbero risultare in costi API inaspettati.
Quando utilizzi lo strumento di utilizzo del computer, devi includere il flag beta appropriato per la tua versione del modello:
Nota: Per Claude 4 e Sonnet 3.7, il flag beta è richiesto solo per lo strumento di utilizzo del computer. Per Claude Sonnet 3.5, il flag beta è richiesto per strumenti computer, bash, e editor di testo.
Raccomandiamo di provare 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 di migliore qualità:
- Specifica compiti semplici e ben definiti e fornisci istruzioni esplicite per ogni passo.
- Claude a volte assume risultati delle sue azioni senza controllare esplicitamente i loro risultati. Per prevenire questo puoi fare prompt a Claude con
Dopo ogni passo, fai uno screenshot e valuta attentamente se hai raggiunto il risultato giusto. Mostra esplicitamente il tuo pensiero: "Ho valutato il passo X..." Se non corretto, riprova. Solo quando confermi che un passo è stato eseguito correttamente dovresti passare al successivo.
- Alcuni elementi UI (come dropdown e scrollbar) potrebbero essere difficili da manipolare per Claude utilizzando movimenti del mouse. Se sperimenti questo, prova a fare prompt al modello per utilizzare scorciatoie da tastiera.
- Per compiti ripetibili o interazioni UI, includi screenshot di esempio e chiamate strumento di risultati di successo nel tuo prompt.
- Se hai bisogno che il modello faccia login, forniscigli username e password nel tuo prompt all’interno di tag xml come
<robot_credentials>
. Utilizzare l’utilizzo del computer all’interno di applicazioni che richiedono login aumenta il rischio di risultati negativi come risultato di iniezione di prompt. Per favore rivedi la nostra guida sulla mitigazione delle iniezioni di prompt prima di fornire al modello credenziali di login.
Se incontri ripetutamente un insieme chiaro di problemi o conosci in anticipo i compiti che Claude dovrà completare, utilizza il prompt di sistema per fornire a Claude suggerimenti espliciti o istruzioni su come fare i compiti con successo.
Prompt di sistema
Quando uno degli strumenti definiti da Anthropic viene richiesto tramite l’API Anthropic, viene generato un prompt di sistema specifico per l’utilizzo del computer. È simile al prompt di sistema per l’utilizzo degli strumenti ma inizia con:
Hai accesso a un insieme di funzioni che puoi utilizzare per rispondere alla domanda dell’utente. Questo include l’accesso a un ambiente informatico sandboxed. NON hai attualmente la capacità di ispezionare file o interagire con risorse esterne, eccetto invocando le funzioni sottostanti.
Come con l’utilizzo regolare degli strumenti, il campo system_prompt
fornito dall’utente è ancora rispettato e utilizzato nella costruzione del prompt di sistema combinato.
Azioni disponibili
Lo strumento di utilizzo del computer supporta queste azioni:
Azioni di base (tutte le versioni)
- screenshot - Cattura il display corrente
- left_click - Clicca alle coordinate
[x, y]
- type - Digita stringa di testo
- key - Premi tasto o combinazione di tasti (ad es., “ctrl+s”)
- mouse_move - Muovi cursore alle coordinate
Azioni avanzate (computer_20250124
)
Disponibili in Claude 4 e Claude Sonnet 3.7:
- scroll - Scorri in qualsiasi direzione con controllo quantità
- left_click_drag - Clicca e trascina tra coordinate
- right_click, middle_click - Pulsanti mouse aggiuntivi
- double_click, triple_click - Click multipli
- left_mouse_down, left_mouse_up - Controllo click fine-grained
- hold_key - Tieni premuto un tasto mentre esegui altre azioni
- wait - Pausa tra azioni
Parametri strumento
Parametro | Richiesto | Descrizione |
---|---|---|
type | Sì | Versione strumento (computer_20250124 o computer_20241022 ) |
name | Sì | Deve essere “computer” |
display_width_px | Sì | Larghezza display in pixel |
display_height_px | Sì | Altezza display in pixel |
display_number | No | Numero display per ambienti X11 |
Mantieni la risoluzione del display a o sotto 1280x800 (WXGA) per le migliori prestazioni. Risoluzioni più alte potrebbero causare problemi di accuratezza a causa del ridimensionamento immagine.
Importante: Lo strumento di utilizzo del computer deve essere eseguito esplicitamente dalla tua applicazione - Claude non può eseguirlo direttamente. Sei responsabile dell’implementazione della cattura screenshot, movimenti mouse, input tastiera, e altre azioni basate sulle richieste di Claude.
Abilita la capacità di pensiero in Claude 4 e Claude Sonnet 3.7
Claude Sonnet 3.7 ha introdotto una nuova capacità di “pensiero” che ti permette di vedere il processo di ragionamento del modello mentre lavora attraverso compiti complessi. Questa funzionalità ti aiuta a capire come Claude sta approcciando un problema e può essere particolarmente preziosa per debugging o scopi educativi.
Per abilitare il pensiero, aggiungi un parametro thinking
alla tua richiesta API:
Il parametro budget_tokens
specifica quanti token Claude può utilizzare per il pensiero. Questo viene sottratto dal tuo budget max_tokens
complessivo.
Quando il pensiero è abilitato, Claude restituirà il suo processo di ragionamento come parte della risposta, che può aiutarti a:
- Capire il processo decisionale del modello
- Identificare potenziali problemi o misconcezioni
- Imparare dall’approccio di Claude alla risoluzione dei problemi
- Ottenere più visibilità in operazioni complesse multi-passo
Ecco un esempio di come potrebbe apparire l’output del pensiero:
Potenziare l’utilizzo del computer con altri strumenti
Lo strumento di utilizzo del computer può essere combinato con altri strumenti per creare flussi di lavoro di automazione più potenti. Questo è particolarmente utile quando hai bisogno di:
- Eseguire comandi di sistema (strumento bash)
- Modificare file di configurazione o script (strumento editor di testo)
- Integrare con API personalizzate o servizi (strumenti personalizzati)
Costruisci un ambiente di utilizzo del computer personalizzato
L’implementazione di riferimento è pensata per aiutarti a iniziare con l’utilizzo del computer. Include tutti i componenti necessari per far utilizzare un computer a Claude. Tuttavia, puoi costruire il tuo ambiente per l’utilizzo del computer per soddisfare le tue esigenze. Avrai bisogno di:
- Un ambiente virtualizzato o containerizzato adatto per l’utilizzo del computer con Claude
- Un’implementazione di almeno uno degli strumenti di utilizzo del computer definiti da Anthropic
- Un ciclo agente che interagisce con l’API Anthropic ed esegue i risultati
tool_use
utilizzando le tue implementazioni strumento - Un’API o UI che permette input utente per avviare il ciclo agente
Implementa lo strumento di utilizzo del computer
Lo strumento di utilizzo del computer è implementato come uno strumento senza schema. Quando utilizzi questo strumento, non hai bisogno di fornire uno schema di input come con altri strumenti; lo schema è integrato nel modello di Claude e non può essere modificato.
Configura il tuo ambiente informatico
Crea un display virtuale o connettiti a un display esistente con cui Claude interagirà. Questo tipicamente comporta la configurazione di Xvfb (X Virtual Framebuffer) o tecnologia simile.
Implementa gestori azioni
Crea funzioni per gestire ogni tipo di azione che Claude potrebbe richiedere:
Processa le chiamate strumento di Claude
Estrai ed esegui chiamate strumento dalle risposte di Claude:
Implementa il ciclo agente
Crea un ciclo che continua finché Claude completa il compito:
Gestisci errori
Quando implementi lo strumento di utilizzo del computer, possono verificarsi vari errori. Ecco come gestirli:
Segui le migliori pratiche di implementazione
Comprendi le limitazioni dell’utilizzo del computer
La funzionalità di utilizzo del computer è in beta. Mentre le capacità di Claude sono all’avanguardia, gli sviluppatori dovrebbero essere consapevoli delle sue limitazioni:
- Latenza: l’attuale latenza dell’utilizzo del computer per interazioni umano-AI potrebbe essere troppo lenta rispetto alle azioni regolari del computer dirette dall’umano. Raccomandiamo di concentrarsi su casi d’uso dove la velocità non è critica (ad es., raccolta informazioni in background, test software automatizzato) in ambienti fidati.
- Accuratezza e affidabilità della visione computerizzata: Claude potrebbe fare errori o allucinare quando produce coordinate specifiche mentre genera azioni. Claude Sonnet 3.7 introduce la capacità di pensiero che può aiutarti a capire il ragionamento del modello e identificare potenziali problemi.
- Accuratezza e affidabilità della selezione strumenti: Claude potrebbe fare errori o allucinare quando seleziona strumenti mentre genera azioni o prendere azioni inaspettate per risolvere problemi. Inoltre, l’affidabilità potrebbe essere più bassa quando interagisce con applicazioni di nicchia o applicazioni multiple contemporaneamente. Raccomandiamo che gli utenti facciano prompt al modello attentamente quando richiedono compiti complessi.
- Affidabilità dello scorrimento: Mentre Claude Sonnet 3.5 (nuovo) aveva limitazioni con lo scorrimento, Claude Sonnet 3.7 introduce azioni di scorrimento dedicate con controllo direzione che migliora l’affidabilità. Il modello ora può scorrere esplicitamente in qualsiasi direzione (su/giù/sinistra/destra) di una quantità specificata.
- Interazione foglio di calcolo: I click del mouse per l’interazione con fogli di calcolo sono migliorati in Claude Sonnet 3.7 con l’aggiunta di azioni di controllo mouse più precise come
left_mouse_down
,left_mouse_up
, e nuovo supporto tasti modificatori. La selezione celle può essere più affidabile utilizzando questi controlli fine-grained e combinando tasti modificatori con click. - Creazione account e generazione contenuti su piattaforme social e comunicazioni: Mentre Claude visiterà siti web, stiamo limitando la sua capacità di creare account o generare e condividere contenuti o altrimenti impegnarsi in impersonificazione umana attraverso siti web e piattaforme social media. Potremmo aggiornare questa capacità in futuro.
- Vulnerabilità: Vulnerabilità come jailbreaking o iniezione di prompt potrebbero persistere attraverso sistemi AI di frontiera, inclusa l’API beta di utilizzo del computer. In alcune circostanze, Claude seguirà comandi trovati nel contenuto, a volte anche in conflitto con le istruzioni dell’utente. Per esempio, le istruzioni di Claude su pagine web o contenute in immagini potrebbero sovrascrivere istruzioni o causare errori a Claude. Raccomandiamo: a. Limitare l’utilizzo del computer ad ambienti fidati come macchine virtuali o container con privilegi minimi b. Evitare di dare accesso all’utilizzo del computer ad account o dati sensibili senza supervisione rigorosa c. Informare gli utenti finali dei rischi rilevanti e ottenere il loro consenso prima di abilitare o richiedere permessi necessari per funzionalità di utilizzo del computer nelle tue applicazioni
- Azioni inappropriate o illegali: Secondo i termini di servizio di Anthropic, non devi utilizzare l’utilizzo del computer per violare leggi o la nostra Politica di Uso Accettabile.
Rivedi sempre attentamente e verifica le azioni e log di utilizzo del computer di Claude. Non utilizzare Claude per compiti che richiedono precisione perfetta o informazioni utente sensibili senza supervisione umana.
Prezzi
Computer use follows the standard tool use pricing. When using the computer use tool:
System prompt overhead: The computer use beta adds 466-499 tokens to the system prompt
Computer use tool token usage:
Model | Input tokens per tool definition |
---|---|
Claude 4 / Sonnet 3.7 | 735 tokens |
Claude Sonnet 3.5 | 683 tokens |
Additional token consumption:
- Screenshot images (see Vision pricing)
- Tool execution results returned to Claude
If you’re also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages.