Strumento di utilizzo del computer

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

Panoramica

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

• Acquisizione di screenshot: Visualizza ciò che è attualmente mostrato sullo schermo
• Controllo del mouse: Clic, trascinamento e spostamento del cursore
• Input da tastiera: Digitazione di testo e utilizzo di scorciatoie da tastiera
• Automazione del desktop: Interazione con qualsiasi applicazione o interfaccia

Sebbene l'utilizzo del computer possa essere integrato con altri strumenti come bash e l'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 gli ambienti desktop.

Compatibilità con i modelli

L'utilizzo del computer è disponibile per i seguenti modelli Claude:

Considerazioni sulla sicurezza

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à i comandi trovati nel contenuto anche se sono in conflitto con le istruzioni dell'utente. Ad esempio, le istruzioni di Claude nelle pagine web o contenute nelle immagini potrebbero sovrascrivere le istruzioni o causare errori a Claude. Adotta precauzioni per isolare Claude da dati e azioni sensibili per evitare rischi legati 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, indirizzeranno automaticamente il modello a richiedere 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 essere 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:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-11-24" \
  -d '{
    "model": "claude-opus-4-6",
    "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."
      }
    ]
  }'

Come funziona l'utilizzo del computer

La ripetizione dei passaggi 3 e 4 senza input dell'utente è denominata "ciclo agente" (ovvero, Claude risponde con una richiesta di utilizzo dello strumento e la tua applicazione risponde a Claude con i risultati della valutazione di tale richiesta).

L'ambiente informatico

L'utilizzo del computer richiede un ambiente informatico in sandbox in cui Claude possa interagire in modo sicuro con le applicazioni e il web. Questo ambiente include:

1. Display virtuale: Un server di display X11 virtuale (usando Xvfb) che renderizza l'interfaccia desktop che Claude vedrà tramite screenshot e controllerà con azioni mouse/tastiera.

2. Ambiente desktop: Un'interfaccia utente leggera con gestore di finestre (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 gestori di file 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 "acquisisci screenshot") in operazioni effettive nell'ambiente virtuale.

5. 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 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 degli strumenti di Claude
2. Le traduce in azioni nel tuo ambiente informatico
3. Acquisisce i risultati (screenshot, output dei comandi, ecc.)
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'utilizzo del computer

Inizia con l'implementazione di riferimento

È disponibile un'implementazione di riferimento che include tutto il necessario 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 ciclo agente che interagisce con l'API Claude ed esegue gli strumenti di utilizzo del computer
• Un'interfaccia web per interagire con il container, il ciclo agente e gli strumenti.

Comprendere il ciclo multi-agente

Il nucleo dell'utilizzo del computer è il "ciclo agente" - un ciclo in cui Claude richiede azioni degli strumenti, 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"
        if "20250124" in tool_version
        else "computer-use-2024-10-22"
    )

    # 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": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "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 finché Claude non risponde senza richiedere alcuno strumento (completamento dell'attività) o viene raggiunto il limite massimo di iterazioni. Questa salvaguardia previene potenziali cicli 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 di qualità migliore:

1. Specifica attività semplici e ben definite e fornisci istruzioni esplicite per ogni passaggio.
2. Claude a volte presuppone i risultati delle sue azioni senza verificarli esplicitamente. Per evitarlo, puoi istruire 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 tendina e barre di scorrimento) potrebbero essere difficili da manipolare per Claude usando i movimenti del mouse. Se riscontri questo problema, prova a istruire il modello a utilizzare le 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 del computer all'interno di applicazioni che richiedono l'accesso aumenta il rischio di risultati negativi a causa dell'iniezione di prompt. Consulta la guida sulla mitigazione delle iniezioni di prompt prima di fornire al modello le credenziali di accesso.

Prompt di sistema

Quando uno degli strumenti definiti da Anthropic viene richiesto tramite l'API Claude, 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 in sandbox. Al momento NON hai la capacità di ispezionare file o interagire con risorse esterne, tranne che invocando le funzioni seguenti.

Come per l'utilizzo regolare degli strumenti, il campo system_prompt fornito dall'utente viene comunque 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 - Acquisisce il display corrente
• left_click - 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 nei modelli Claude 4 e Claude Sonnet 3.7:

• scroll - Scorri in qualsiasi direzione con controllo della quantità
• left_click_drag - Clic e trascinamento tra coordinate
• right_click, middle_click - Pulsanti del mouse aggiuntivi
• double_click, triple_click - Clic multipli
• left_mouse_down, left_mouse_up - Controllo granulare del 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 Opus 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 in alto a sinistra e in basso a destra dell'area da ispezionare.

Parametri dello strumento

Abilita la capacità di pensiero nei modelli Claude 4 e Claude Sonnet 3.7

Claude Sonnet 3.7 ha introdotto una nuova capacità di "pensiero" che ti consente di vedere il processo di ragionamento del modello mentre lavora su attività complesse. Questa funzionalità ti aiuta a capire come Claude si avvicina a un problema e può essere particolarmente utile per il debug o a scopo didattico.

Per abilitare il pensiero, aggiungi un parametro thinking alla tua richiesta API:

"thinking": {
  "type": "enabled",
  "budget_tokens": 1024
}

Il parametro budget_tokens specifica quanti token Claude può utilizzare per il pensiero. Questo viene sottratto dal tuo budget complessivo di max_tokens.

Quando il pensiero è abilitato, Claude restituirà il suo processo di ragionamento come parte della risposta, il che può aiutarti a:

1. Comprendere il processo decisionale del modello
2. Identificare potenziali problemi o incomprensioni
3. Imparare dall'approccio di Claude alla risoluzione dei problemi
4. Ottenere maggiore visibilità nelle operazioni complesse multi-step

Ecco un esempio di come potrebbe apparire l'output del pensiero:

[Thinking]
I need to save a picture of a cat to the desktop. Let me break this down into steps:

1. First, I'll take a screenshot to see what's on the desktop
2. Then I'll look for a web browser to search for cat images
3. After finding a suitable image, I'll need to save it to the desktop

Let me start by taking a screenshot to see what's available...

Potenziare l'uso del computer con altri strumenti

Lo strumento di uso del computer può essere combinato con altri strumenti per creare flussi di lavoro di automazione più potenti. Questo è particolarmente utile quando è necessario:

• Eseguire comandi di sistema (strumento bash)
• Modificare file di configurazione o script (strumento editor di testo)
• Integrarsi con API o servizi personalizzati (strumenti personalizzati)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-11-24" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 2000,
    "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"
      },
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Find flights from San Francisco to a place with warmer weather."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

Costruire 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 affinché Claude utilizzi un computer. 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 definiti da Anthropic
• Un ciclo agente che interagisce con l'API di Claude ed esegue i risultati di tool_use utilizzando le tue implementazioni degli strumenti
• Un'API o un'interfaccia utente che consenta all'utente di avviare il ciclo agente

Implementare lo strumento di uso del computer

Lo strumento di uso del computer è implementato come uno strumento senza schema. Quando si utilizza 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.

Gestire gli errori

Quando si implementa lo strumento di uso del computer, possono verificarsi vari errori. Ecco come gestirli:

Gestire il ridimensionamento delle coordinate per risoluzioni più elevate

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

Questo può causare che le coordinate di clic di Claude manchino i loro obiettivi a meno che tu non gestisca la trasformazione delle coordinate.

Per risolvere questo problema, ridimensiona gli screenshot tu stesso e scala le coordinate di Claude verso l'alto:

import math


def get_scale_factor(width, height):
    """Calcola il fattore di scala per soddisfare i vincoli dell'API."""
    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 acquisisce 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, scalale verso l'alto
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

Seguire le best practice di implementazione

Comprendere i limiti dell'uso del computer

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

1. Latenza: l'attuale latenza dell'uso del computer per le interazioni uomo-AI può essere troppo lenta rispetto alle normali azioni al computer dirette dall'uomo. Concentrati sui 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 visione artificiale: Claude può commettere errori o allucinare quando genera coordinate specifiche durante la generazione di azioni. Claude Sonnet 3.7 introduce la capacità di pensiero che può aiutarti a comprendere il ragionamento del modello e identificare potenziali problemi.
3. Accuratezza e affidabilità nella selezione degli strumenti: Claude può commettere errori o allucinare quando seleziona gli strumenti durante la generazione di azioni o intraprendere azioni inaspettate per risolvere i problemi. Inoltre, l'affidabilità può essere inferiore quando si interagisce con applicazioni di nicchia o più applicazioni contemporaneamente. Istruisci il 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 i fogli di calcolo: I clic del mouse per l'interazione con i 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 il 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.
6. Creazione di account e generazione di contenuti su piattaforme social e di comunicazione: Sebbene Claude visiti i siti web, la capacità di Claude di creare account o generare e condividere contenuti o altrimenti impersonare esseri umani sui siti web e sulle piattaforme di social media è limitata. Questa capacità potrebbe essere aggiornata in futuro.
7. Vulnerabilità: Le vulnerabilità come il jailbreaking o l'iniezione di prompt possono persistere nei sistemi AI di frontiera, inclusa l'API beta di uso del computer. In alcune circostanze, Claude seguirà i comandi trovati nel contenuto, a volte anche in conflitto con le istruzioni dell'utente. Ad esempio, le istruzioni di Claude nelle pagine web o contenute nelle immagini possono sovrascrivere le istruzioni o causare errori a Claude. Considera quanto segue: a. Limitare l'uso del computer ad ambienti affidabili come macchine virtuali o container con privilegi minimi b. Evitare di dare accesso all'uso del computer 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 uso del computer nelle tue applicazioni
8. Azioni inappropriate o illegali: Secondo i termini di servizio di Anthropic, non devi impiegare l'uso del computer per violare leggi o la Policy sull'Uso Accettabile.

Rivedi e verifica sempre attentamente le azioni e i log di uso del computer di Claude. Non utilizzare Claude per attività che richiedono precisione assoluta o informazioni sensibili degli utenti senza supervisione umana.

Conservazione dei dati

L'uso 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 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 viene restituita.

Poiché la tua applicazione controlla dove e come vengono archiviati i dati di uso del computer, l'uso del computer è idoneo per ZDR. Per l'idoneità ZDR su tutte le funzionalità, consulta 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

Prossimi passi