Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Claude può interagire con ambienti informatici attraverso lo strumento di utilizzo del computer, che fornisce funzionalità di screenshot e controllo di mouse/tastiera per l'interazione autonoma con il desktop.
L'utilizzo del computer è una funzionalità beta che consente a Claude di interagire con ambienti desktop. Questo strumento fornisce:
Sebbene l'utilizzo del computer possa essere potenziato con altri strumenti come bash e text editor 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.
Per il supporto dei modelli, consulta il Riferimento degli strumenti.
L'utilizzo 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à comandi trovati nei contenuti anche quando sono in conflitto con le tue istruzioni. Ad esempio, istruzioni su pagine web o contenute in immagini potrebbero sovrascrivere le tue 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 utilizzo del computer, dei 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'utilizzo del computer nei tuoi prodotti.
Inizia con l'implementazione di riferimento per l'utilizzo del computer che include un'interfaccia web, un container Docker, implementazioni di esempio degli strumenti e un agent loop.
Ecco come iniziare con l'utilizzo del computer:
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5", # 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)Fornisci a Claude lo strumento di utilizzo del computer e un prompt utente
Claude seleziona lo strumento di utilizzo del computer
stop_reason di tool_use, che segnala una richiesta di uso degli strumenti.Estrai l'input dello strumento, valuta lo strumento su un computer e restituisci i risultati
user contenente un blocco di contenuto tool_result.Claude continua a chiamare gli strumenti di utilizzo del computer finché non ha completato l'attività
stop_reason tool_use e dovresti tornare al passaggio 3.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'utilizzo del computer richiede un ambiente di calcolo sandbox in cui Claude possa interagire in sicurezza con applicazioni e web. Questo ambiente include:
Display virtuale: Un server di display virtuale X11 (utilizzando Xvfb) che renderizza l'interfaccia desktop che Claude vedrà attraverso gli screenshot e controllerà con azioni di mouse/tastiera.
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.
Applicazioni: Applicazioni Linux preinstallate come Firefox, LibreOffice, editor di testo e file manager che Claude può utilizzare per completare le attività.
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.
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 l'utilizzo del computer, Claude non si connette direttamente a questo ambiente. Invece, la tua applicazione:
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.
È disponibile un'implementazione di riferimento che include tutto ciò di cui hai bisogno per iniziare con l'utilizzo del computer:
Il cuore dell'utilizzo 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. Il loop utilizza il client che hai creato nell'Avvio rapido, un elenco di strumenti strutturato come l'array tools dell'Avvio rapido e l'helper di elaborazione delle chiamate agli strumenti definito in Elabora le chiamate agli strumenti di Claude. Ecco un esempio semplificato:
def sampling_loop(model, messages, max_iterations=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.beta.messages.create(
model=model,
max_tokens=4096,
messages=messages,
tools=TOOLS,
betas=["computer-use-2025-11-24"],
)
# Aggiungi la risposta di Claude alla cronologia della conversazione
messages.append({"role": "assistant", "content": response.content})
# Esegui gli strumenti richiesti da Claude e raccogli i risultati
tool_results = process_tool_calls(response)
if not tool_results:
return messages # No more tool use; task complete
# Invia i risultati degli strumenti a Claude per l'iterazione successiva
messages.append({"role": "user", "content": tool_results})
return messagesIl loop 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.
Ecco alcuni suggerimenti su come ottenere output della migliore qualità:
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.<robot_credentials>. L'utilizzo del computer all'interno di applicazioni che richiedono l'accesso aumenta il rischio di risultati negativi a causa della prompt injection. Consulta Mitigare jailbreak e prompt injection prima di fornire al modello credenziali di accesso.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.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.Quando uno degli strumenti con schema Anthropic viene richiesto tramite l'API di Claude, viene generato un prompt di sistema specifico per l'utilizzo 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 parametro system fornito dall'utente è comunque rispettato e utilizzato nella costruzione del prompt di sistema combinato.
Lo strumento di utilizzo del computer supporta queste azioni:
Azioni di base (tutte le versioni)
[x, y]Azioni avanzate (computer_20250124 e successive)
Disponibili in computer_20250124 e computer_20251124:
Azioni avanzate (computer_20251124)
Disponibili in Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 e Claude Opus 4.5:
computer_20250124enable_zoom: true nella definizione dello strumento. Accetta un parametro region con coordinate [x1, y1, x2, y2] che definiscono gli angoli in alto a sinistra e in basso a destra dell'area da ispezionare.| Parametro | Obbligatorio | Descrizione |
|---|---|---|
type | Sì | Versione dello strumento (computer_20251124 o computer_20250124) |
name | Sì | Deve essere "computer" |
display_width_px | Sì | Larghezza del display in pixel |
display_height_px | Sì | Altezza del display in pixel |
display_number | No | Numero del display per ambienti X11 |
enable_zoom | No | Abilita l'azione zoom (solo computer_20251124). Imposta su true per consentire a Claude di ingrandire regioni specifiche dello schermo. Predefinito: false |
Per combinare l'utilizzo del computer con il pensiero, consulta Pensiero.
Per aggiungere altri strumenti insieme all'utilizzo del computer, includili nello stesso array tools. La sezione Avvio rapido mostra questo pattern con lo strumento bash e lo strumento text editor. Puoi aggiungere le tue definizioni di strumenti personalizzati allo stesso modo.
L'implementazione di riferimento è pensata per aiutarti a iniziare con l'utilizzo del computer. Include tutti i componenti necessari per far usare un computer a Claude. Tuttavia, puoi costruire il tuo ambiente per l'utilizzo del computer in base alle tue esigenze. Avrai bisogno di:
tool_use utilizzando le tue implementazioni degli strumentiLo strumento di utilizzo del computer è implementato come strumento senza schema. Quando usi questo strumento, non devi 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 di calcolo
Crea un display virtuale o connettiti a un display esistente con cui Claude interagirà. Questo in genere comporta la configurazione di Xvfb (X Virtual Framebuffer) o tecnologia simile.
Implementa i gestori delle azioni
Crea funzioni per gestire ogni tipo di azione che Claude potrebbe richiedere:
def capture_screenshot():
return "<screenshot data>"
def click_at(x, y):
return f"clicked at ({x}, {y})"
def type_text(text):
return f"typed: {text}"
def handle_computer_action(action_type, params):
if action_type == "screenshot":
return capture_screenshot()
elif action_type == "left_click":
x, y = params["coordinate"]
return click_at(x, y)
elif action_type == "type":
return type_text(params["text"])
# Gestisci altre azioni secondo necessità
return f"unhandled action: {action_type}"Elabora le chiamate agli strumenti di Claude
Estrai ed esegui le chiamate agli strumenti dalle risposte di Claude:
def process_tool_calls(response):
tool_results = []
for block in response.content:
if block.type == "tool_use":
action = block.input["action"]
result = handle_computer_action(action, block.input)
tool_results.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": result,
}
)
return tool_resultsImplementa l'agent loop
Crea un loop che continua finché Claude non completa l'attività:
def sampling_loop(model, messages, max_iterations=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.beta.messages.create(
model=model,
max_tokens=4096,
messages=messages,
tools=TOOLS,
betas=["computer-use-2025-11-24"],
)
# Aggiungi la risposta di Claude alla cronologia della conversazione
messages.append({"role": "assistant", "content": response.content})
# Esegui gli strumenti richiesti da Claude e raccogli i risultati
tool_results = process_tool_calls(response)
if not tool_results:
return messages # No more tool use; task complete
# Invia i risultati degli strumenti a Claude per l'iterazione successiva
messages.append({"role": "user", "content": tool_results})
return messagesDurante l'implementazione dello strumento di utilizzo del computer, potrebbero verificarsi vari errori. Ecco come gestirli:
Gli screenshot inviati allo strumento computer dovrebbero rientrare nei limiti di dimensione delle immagini di Claude (consulta limiti di dimensione delle immagini). L'API ridimensiona le immagini troppo grandi prima che Claude le veda, e Claude restituisce coordinate per l'immagine che vede, quindi affidarsi al ridimensionamento lato server ti lascia senza il fattore di scala necessario per mappare quelle coordinate sul tuo schermo. Solo le immagini che superano i limiti di richiesta separati dell'API (ad esempio, più di 8.000 px su un lato) vengono rifiutate con un errore di validazione anziché ridimensionate.
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:
import math
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)
# Quando si cattura lo 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 si gestiscono 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)Se i clic mancano i loro target, la causa è solitamente una delle seguenti:
| Sintomo | Causa probabile | Prova |
|---|---|---|
| Clic costantemente spostati in una direzione | display_width_px/display_height_px non corrispondono alle dimensioni dell'immagine effettivamente inviata | Assicurati che le dimensioni del display corrispondano esattamente allo screenshot che invii |
| I clic arrivano nell'area giusta ma mancano il target | Il target è molto piccolo, i dettagli sono stati persi ridimensionando una sorgente 4K+, o le proporzioni sono state distorte | Imposta enable_zoom: true; cattura a DPI inferiore o ritaglia alla regione rilevante; preserva le proporzioni durante il ridimensionamento |
| Claude clicca completamente l'elemento sbagliato | Istruzione ambigua, o elementi visivamente simili nelle vicinanze | Usa prompt posizionali ("il pulsante blu Invia in basso a destra"); suddividi l'interazione in passaggi più piccoli |
| La precisione è costantemente scarsa | Risoluzione troppo bassa | Prova 1280x720 come baseline |
L'utilizzo del computer è in beta. Tieni presenti le seguenti limitazioni:
Latency (latenza): L'attuale latenza dell'utilizzo del computer per le interazioni umano-IA potrebbe essere troppo lenta rispetto alle normali azioni del computer dirette dall'uomo. 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.
Precisione e affidabilità della visione artificiale: 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.
Precisione e affidabilità nella selezione degli strumenti: Claude potrebbe commettere errori o allucinare quando seleziona strumenti durante la generazione di azioni o intraprendere azioni inaspettate per risolvere problemi. Inoltre, l'affidabilità potrebbe essere inferiore quando si interagisce con applicazioni di nicchia o più applicazioni contemporaneamente. Fornisci prompt accurati al modello quando richiedi attività complesse.
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 Page Down possono aiutare.
Interazione con fogli di calcolo: Usa le azioni di controllo granulare del mouse (left_mouse_down, left_mouse_up) e le combinazioni di tasti modificatori per selezionare singole celle. Operazioni complesse sui fogli di calcolo potrebbero comunque richiedere più tentativi.
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 altrimenti impegnarsi nell'impersonificazione umana su siti web e piattaforme di social media è limitata. Questa capacità potrebbe essere aggiornata in futuro.
Vulnerabilità: Vulnerabilità come jailbreak o prompt injection potrebbero persistere nei sistemi di IA di frontiera, inclusa l'API beta di utilizzo del computer. In alcune circostanze, Claude seguirà comandi trovati nei contenuti, a volte anche quando sono in conflitto con le tue istruzioni. Ad esempio, istruzioni su pagine web o contenute in immagini potrebbero sovrascrivere le tue istruzioni o causare errori da parte di Claude. Considera quanto segue:
Azioni inappropriate o illegali: Secondo i Termini di servizio di Anthropic, non devi utilizzare l'utilizzo del computer per violare leggi o la Politica di utilizzo accettabile.
Rivedi e verifica sempre attentamente le azioni e i log di utilizzo del computer di Claude. Non usare Claude per attività che richiedono precisione perfetta o informazioni sensibili degli utenti senza supervisione umana.
L'utilizzo del computer è uno strumento lato client. Tutti gli screenshot, le azioni del mouse, gli input da tastiera e qualsiasi file coinvolto in una sessione vengono catturati e archiviati nel tuo ambiente, non da Anthropic. Anthropic elabora le immagini degli screenshot e le richieste di azioni in tempo reale come parte della chiamata API. La conservazione per tali richieste API è regolata da API e conservazione dei dati.
Poiché la tua applicazione controlla dove e come vengono archiviati i dati di utilizzo del computer, l'utilizzo del computer è idoneo per ZDR. Per l'idoneità ZDR su tutte le funzionalità, consulta API e conservazione dei dati.
L'uso del computer segue i prezzi standard dell'uso degli strumenti. Quando usi 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:
| Modello | Token di input per definizione dello strumento |
|---|---|
| Modelli Claude 4.x | 735 token |
Consumo aggiuntivo di token:
Risolvi gli errori più comuni dell'uso degli strumenti con tabelle diagnostiche sintomo-soluzione.
Inizia con l'implementazione completa basata su Docker
Connetti Claude a strumenti e API esterni. Scopri dove vengono eseguiti gli strumenti, quando Claude li chiama e quale strumento si adatta alla tua attività.
Raccomandazioni basate su benchmark per risoluzione, thinking effort e gestione del contesto
| Supported models |
|
|---|---|
| Supported platforms |
|
Was this page helpful?