Strumento di utilizzo del computer

Claude può interagire con ambienti desktop attraverso lo strumento di utilizzo del computer, che fornisce capacità di screenshot e controllo del mouse/tastiera per l'interazione autonoma del desktop. Su WebArena, un benchmark per la navigazione web autonoma su siti web reali, Claude raggiunge risultati all'avanguardia tra i sistemi single-agent, dimostrando una forte capacità di completare attività browser multi-step end to end.

Panoramica

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

• Cattura di screenshot: Vedi cosa è attualmente visualizzato sullo schermo
• Controllo del mouse: Fai clic, trascina e sposta il cursore
• Input da tastiera: Digita testo e usa scorciatoie da tastiera
• Automazione del desktop: Interagisci con qualsiasi applicazione o interfaccia

Sebbene l'utilizzo del computer possa essere aumentato 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.

Per il supporto del modello, vedi il Riferimento degli strumenti.

Considerazioni sulla sicurezza

L'utilizzo del computer è una funzione beta con rischi unici distinti dalle funzioni API standard. Questi rischi sono aumentati quando si interagisce con Internet.

In alcune circostanze, Claude seguirà i comandi trovati nel contenuto anche se entra in conflitto con le istruzioni dell'utente. Ad esempio, le istruzioni Claude su pagine web o contenute in immagini possono ignorare le istruzioni o causare a Claude di fare errori. Prendi precauzioni per isolare Claude da dati e azioni sensibili per evitare rischi correlati all'iniezione di prompt.

Il modello è stato addestrato per resistere a queste iniezioni di prompt, ed è stato aggiunto un ulteriore livello di difesa. Se utilizzi gli strumenti di utilizzo del computer, i classificatori verranno eseguiti automaticamente sui tuoi prompt per segnalare potenziali istanze di iniezioni di prompt. Quando questi classificatori identificano potenziali iniezioni di prompt negli screenshot, guideranno automaticamente il modello a chiedere la conferma dell'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 umano nel ciclo), quindi se desideri rinunciare e disattivarla, contatta il supporto.

Queste precauzioni rimangono importanti anche con il livello di difesa del classificatore in atto.

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

Avvio rapido

Ecco come iniziare con l'utilizzo del computer:

Come funziona l'utilizzo del computer

La ripetizione dei passaggi 3 e 4 senza input dell'utente è denominata "agent loop" (cioè Claude che risponde con una richiesta di utilizzo dello strumento e la tua applicazione che risponde a Claude con i risultati della valutazione di quella richiesta).

L'ambiente di calcolo

L'utilizzo del computer richiede un ambiente di calcolo sandbox in cui Claude può interagire in sicurezza con applicazioni e il 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 del mouse/tastiera.

2. Ambiente desktop: Un'interfaccia UI leggera con window manager (Mutter) e panel (Tint2) in esecuzione su Linux, che fornisce un'interfaccia grafica coerente per Claude per interagire.

3. Applicazioni: Applicazioni Linux pre-installate come Firefox, LibreOffice, editor di testo e gestori di file che Claude può utilizzare per completare attività.

4. Implementazioni di strumenti: Codice di integrazione che traduce le richieste di strumenti astratti di Claude (come "sposta il mouse" o "prendi 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'utilizzo del computer, Claude non si connette direttamente a questo ambiente. Invece, la tua applicazione:

1. Riceve le richieste di utilizzo dello strumento di Claude
2. Le traduce in azioni nel tuo ambiente di calcolo
3. Cattura i risultati (screenshot, output dei comandi, ecc.)
4. Restituisce questi risultati a Claude

Per la sicurezza e l'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 l'implementazione di riferimento

Un'implementazione di riferimento è disponibile che include tutto ciò di cui hai bisogno per iniziare rapidamente con l'utilizzo del computer:

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

Comprensione dell'agent loop

Il nucleo dell'utilizzo del computer è l'"agent loop" - un ciclo in cui Claude richiede azioni dello strumento, la tua applicazione le esegue e restituisce i risultati a Claude. Ecco un esempio semplificato:

async def sampling_loop(
    *,
    model: str,
    messages: list[dict],
    api_key: str,
    max_tokens: int = 4096,
    tool_version: str,
    thinking_budget: int | None = None,
    max_iterations: int = 10,  # Add iteration limit to prevent infinite loops
):
    """
    A simple agent loop for Claude computer use interactions.

    This function handles the back-and-forth between:
    1. Sending user messages to Claude
    2. Claude requesting to use tools
    3. Your app executing those tools
    4. Sending tool results back to Claude
    """
    # Set up tools and API parameters
    client = Anthropic(api_key=api_key)
    beta_flag = (
        "computer-use-2025-11-24"
        if "20251124" in tool_version
        else "computer-use-2025-01-24"
    )
    text_editor_type = (
        "text_editor_20250728"
        if "20251124" in tool_version
        else f"text_editor_{tool_version}"
    )

    # Configure tools - you should already have these initialized elsewhere
    tools = [
        {
            "type": f"computer_{tool_version}",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        },
        {"type": text_editor_type, "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "name": "bash"},
    ]

    # Main agent loop (with iteration limit to prevent runaway API costs)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Set up optional thinking parameter (for Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # Call the Claude API
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking,
        )

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

        # Check if Claude used any tools
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # In a real app, you would execute the tool here
                # For example: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Format the result for Claude
                tool_results.append(
                    {"type": "tool_result", "tool_use_id": block.id, "content": result}
                )

        # If no tools were used, Claude is done - return the final messages
        if not tool_results:
            return messages

        # Add tool results to messages for the next iteration with Claude
        messages.append({"role": "user", "content": tool_results})

Il ciclo continua fino a quando Claude non risponde senza richiedere alcuno strumento (completamento dell'attività) o fino al raggiungimento del limite massimo di iterazioni. Questo salvaguardia previene potenziali cicli infiniti che potrebbero causare 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 i migliori output di qualità:

1. Specifica attività semplici e ben definite e fornisci istruzioni esplicite per ogni passaggio.
2. Claude a volte assume i risultati delle sue azioni senza controllare esplicitamente i loro risultati. Per prevenire questo, puoi prompt Claude con After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. Explicitly show your thinking: "I have evaluated step X..." If not correct, try again. Only when you confirm a step was executed correctly should you move on to the next one.
3. Alcuni elementi dell'interfaccia utente (come menu a discesa e barre di scorrimento) potrebbero essere difficili per Claude da manipolare utilizzando i movimenti del mouse. Se riscontri questo problema, prova a prompt il modello per utilizzare scorciatoie da tastiera.
4. Per attività ripetibili o interazioni dell'interfaccia utente, includi screenshot di esempio e chiamate di strumenti di risultati riusciti nel tuo prompt.
5. Se hai bisogno che il modello acceda, forniscigli il nome utente e la password nel tuo prompt all'interno di tag xml come <robot_credentials>. L'utilizzo dell'utilizzo del computer all'interno di applicazioni che richiedono l'accesso aumenta il rischio di cattivi risultati a causa dell'iniezione di prompt. Rivedi la guida sulla mitigazione delle iniezioni di prompt prima di fornire al modello le credenziali di accesso.

System prompt

Quando uno degli strumenti dello schema Anthropic viene richiesto tramite l'API Claude, viene generato un system prompt specifico per l'utilizzo del computer. È simile al tool use system prompt 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 il tool use regolare, il campo system_prompt fornito dall'utente è ancora rispettato e utilizzato nella costruzione del system prompt 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 - 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 migliorate (computer_20250124) Disponibili nei modelli Claude 4 e Claude Sonnet 3.7:

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

Azioni migliorate (computer_20251124) Disponibili in Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 e Claude Opus 4.5:

• Tutte le azioni da computer_20250124
• zoom - Visualizza una regione specifica dello schermo a risoluzione completa. Richiede enable_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.

Parametri dello strumento

Combinazione con il pensiero esteso

Per combinare l'utilizzo del computer con il pensiero esteso, vedi Extended thinking.

Aumento dell'utilizzo del computer con altri strumenti

Per aggiungere altri strumenti insieme all'utilizzo del computer, includili nello stesso array tools. L'avvio rapido sopra mostra questo modello con lo strumento bash e lo strumento editor di testo. Puoi aggiungere le tue definizioni di strumenti personalizzati allo stesso modo.

Costruire un ambiente di computer use personalizzato

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

• Un ambiente virtualizzato o containerizzato adatto al computer use con Claude
• Un'implementazione di almeno uno dei tool di computer use dello schema Anthropic
• Un agent loop che interagisce con l'API Claude ed esegue i risultati di tool_use utilizzando le tue implementazioni di tool
• Un'API o un'interfaccia utente che consenta l'input dell'utente per avviare l'agent loop

Implementare il tool di computer use

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

Gestire gli errori

Quando implementi il tool di computer use, possono verificarsi vari errori. Ecco come gestirli:

Gestire il ridimensionamento delle coordinate per risoluzioni più elevate

L'API vincola le immagini a un massimo di 1568 pixel sul lato più lungo e circa 1,15 megapixel totali (vedi ridimensionamento dell'immagine per i dettagli). Ad esempio, uno schermo di 1512x982 viene sottocampionato a circa 1330x864. Claude analizza questa immagine più piccola e restituisce coordinate in quello spazio, ma il tuo tool esegue i clic nello spazio dello schermo originale.

Questo può causare il mancato raggiungimento dei target da parte delle coordinate di clic di Claude a meno che tu non gestisca la trasformazione delle coordinate.

Per risolvere questo problema, ridimensiona gli screenshot tu stesso e ridimensiona le coordinate di Claude:

Seguire le best practice di implementazione

Comprendere i limiti del computer use

La funzionalità di computer use è in beta. Sebbene le capacità di Claude siano all'avanguardia, gli sviluppatori dovrebbero essere consapevoli dei suoi limiti:

1. Latenza: la latenza attuale del computer use per le interazioni uomo-IA potrebbe essere troppo lenta rispetto alle normali azioni al computer dirette dall'uomo. Concentrati su casi d'uso in cui la velocità non è critica (ad esempio, raccolta di informazioni di background, test automatizzato del software) in ambienti affidabili.
2. Accuratezza e affidabilità della visione artificiale: Claude potrebbe fare errori o allucinare quando genera coordinate specifiche durante la generazione di azioni. Claude Sonnet 3.7 introduce la capacità di thinking che può aiutarti a comprendere il ragionamento del modello e identificare potenziali problemi.
3. Accuratezza e affidabilità della selezione dei tool: Claude potrebbe fare errori o allucinare quando seleziona i tool durante la generazione di azioni o intraprendere azioni inaspettate per risolvere i problemi. Inoltre, l'affidabilità potrebbe essere inferiore quando si interagisce con applicazioni di nicchia o più applicazioni contemporaneamente. Richiedi al modello con attenzione quando richiedi attività complesse.
4. Affidabilità dello scorrimento: Claude Sonnet 3.7 ha introdotto azioni di scorrimento dedicate con controllo della direzione che migliora l'affidabilità. Il modello può ora scorrere esplicitamente in qualsiasi direzione (su/giù/sinistra/destra) di una quantità specificata.
5. Interazione con fogli di calcolo: I clic del mouse per l'interazione con fogli di calcolo sono migliorati in Claude Sonnet 3.7 con l'aggiunta di azioni di controllo del mouse più precise come left_mouse_down, left_mouse_up e nuovo supporto per i tasti modificatori. La selezione delle celle può essere più affidabile utilizzando questi controlli granulari e combinando i tasti modificatori con i clic.

Rivedi e verifica sempre attentamente le azioni e i log del computer use di Claude. Non utilizzare Claude per attività che richiedono una precisione perfetta o informazioni utente sensibili senza supervisione umana.

Conservazione dei dati

Il computer use è uno strumento lato client. Tutti gli screenshot, le azioni del mouse, gli input della tastiera e tutti i 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 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à di ZDR in tutte le funzioni, vedi API e conservazione dei dati.

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:

Additional token consumption:

• Screenshot images (see Vision pricing)
• Tool execution results returned to Claude

Passaggi successivi