Strumento di utilizzo del computer

Claude può interagire con ambienti desktop attraverso lo strumento di utilizzo del computer, che fornisce funzionalità di screenshot e controllo del mouse/tastiera per l'interazione autonoma del desktop.

Panoramica

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

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

Sebbene l'utilizzo del computer possa 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 gli ambienti desktop.

Compatibilità del modello

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

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. Ti suggeriamo di prendere precauzioni per isolare Claude da dati e azioni sensibili per evitare rischi correlati all'iniezione di prompt.

Abbiamo addestrato il modello a resistere a queste iniezioni di prompt e abbiamo aggiunto un ulteriore livello 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, guideranno automaticamente il modello a chiedere la conferma dell'utente prima di procedere con l'azione successiva. Riconosciamo che questa protezione extra 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, contattaci.

Ti suggeriamo comunque di prendere precauzioni per isolare Claude da dati e azioni sensibili per evitare rischi correlati all'iniezione di prompt.

Infine, informi 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:

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",  # o un altro modello compatibile
    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": "Salva una foto di un gatto sul mio desktop."}],
    betas=["computer-use-2025-11-24"]
)
print(response)

Come funziona l'utilizzo del computer

Ci riferiamo alla ripetizione dei passaggi 3 e 4 senza input dell'utente come il "ciclo di agenti" - 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 le azioni del 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 per Claude per 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 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. Ciclo di agenti: 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. Acquisisce 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 contenitore 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 all'utilizzo del computer con Claude
• Implementazioni degli strumenti di utilizzo del computer
• Un ciclo di agenti che interagisce con l'API Claude ed esegue gli strumenti di utilizzo del computer
• Un'interfaccia web per interagire con il contenitore, il ciclo di agenti e gli strumenti.

Comprensione del ciclo multi-agente

Il nucleo dell'utilizzo del computer è il "ciclo di agenti" - 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,  # Aggiungi limite di iterazione per prevenire cicli infiniti
):
    """
    Un semplice ciclo di agenti per le interazioni di utilizzo del computer di Claude.

    Questa funzione gestisce il dialogo tra:
    1. Invio di messaggi dell'utente a Claude
    2. Claude che richiede di utilizzare gli strumenti
    3. La tua app che esegue quegli strumenti
    4. Invio dei risultati dello strumento a Claude
    """
    # Configura gli strumenti e i parametri API
    client = Anthropic(api_key=api_key)
    beta_flag = "computer-use-2025-01-24" if "20250124" in tool_version else "computer-use-2024-10-22"

    # Configura gli strumenti - dovresti già averli inizializzati altrove
    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"}
    ]

    # Ciclo di agenti principale (con limite di iterazione per prevenire costi API incontrollati)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Configura il parametro di pensiero opzionale (per Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

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

        # Aggiungi la risposta di Claude alla cronologia della conversazione
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Verifica se Claude ha utilizzato degli strumenti
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # In un'app reale, eseguiresti lo strumento qui
                # Ad esempio: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Formatta il risultato per Claude
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # Se nessuno strumento è stato utilizzato, Claude ha finito - restituisci i messaggi finali
        if not tool_results:
            return messages

        # Aggiungi i risultati dello strumento ai messaggi per la prossima iterazione con 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 iterazione. Questa salvaguardia previene potenziali cicli infiniti che potrebbero causare costi API inaspettati.

Ti consigliamo di provare l'implementazione di riferimento prima di leggere il resto di questa documentazione.

Ottimizza le prestazioni del modello con i prompt

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 verificarli esplicitamente. Per evitare questo, puoi richiedere a Claude con Dopo ogni passaggio, prendi uno screenshot e valuta attentamente se hai raggiunto il risultato corretto. Mostra esplicitamente il tuo ragionamento: "Ho valutato il passaggio X..." Se non è corretto, riprova. Solo quando confermi che un passaggio è stato eseguito correttamente dovresti passare a quello successivo.
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 richiedere al modello di 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. Consulta la nostra 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 di utilizzo dello strumento 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 di calcolo sandbox. Attualmente NON hai la capacità di ispezionare file o interagire con risorse esterne, se non invocando le funzioni sottostanti.

Come con l'utilizzo regolare dello strumento, 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 - Acquisisce 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 es. "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.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

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 funzione ti aiuta a capire come Claude sta affrontando un problema e può essere particolarmente preziosa per il debug o scopi educativi.

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, che può aiutarti a:

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

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

[Pensiero]
Devo salvare una foto di un gatto sul desktop. Scomponiamo questo in passaggi:

1. Per prima cosa, prenderò uno screenshot per vedere cosa c'è sul desktop
2. Poi cercherò un browser web per cercare immagini di gatti
3. Dopo aver trovato un'immagine adatta, dovrò salvarla sul desktop

Iniziamo prendendo uno screenshot per vedere cosa è disponibile...

Potenziamento dell'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)

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-01-24" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 2000,
    "tools": [
      {
        "type": "computer_20250124",
        "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": "Ottieni il meteo attuale in una determinata posizione",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "La città e lo stato, ad es. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "L'unità di temperatura, 'celsius' o 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Trova voli da San Francisco a un posto con meteo più caldo."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

Costruisci 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 definiti da 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

Implementa 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.

Gestisci gli errori

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

Gestisci 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 delle immagini per i dettagli). Ad esempio, uno schermo 1512x982 viene sottocampionato a circa 1330x864. Claude analizza questa immagine più piccola e restituisce le 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:

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 acquisisci uno 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 ridimensionate prima di inviarla a Claude
screenshot = capture_and_resize(scaled_width, scaled_height)

# Quando gestisci le coordinate di Claude, ridimensionale
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

Segui le best practice di implementazione

Comprendi le limitazioni del computer use

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

1. Latenza: la latenza attuale del computer use per le interazioni uomo-IA potrebbe essere troppo lenta rispetto alle normali azioni di computer dirette dall'uomo. Consigliamo di concentrarsi su casi d'uso in cui la velocità non è critica (ad es. 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 produce 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. Consigliamo agli utenti di richiedere attentamente il modello quando si richiedono 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 un importo specificato.
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 dei 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 di social media e comunicazioni: Sebbene Claude visiterà i siti web, stiamo limitando la sua capacità di creare account o generare e condividere contenuti o altrimenti impersonare persone su siti web e piattaforme di social media. Potremmo aggiornare questa capacità in futuro.
7. Vulnerabilità: Vulnerabilità come jailbreaking o prompt injection possono persistere nei sistemi di IA frontier, inclusa l'API beta di computer use. In alcune circostanze, Claude seguirà i comandi trovati nei contenuti, a volte anche in conflitto con le istruzioni dell'utente. Ad esempio, le istruzioni di Claude su pagine web o contenute in immagini possono ignorare le istruzioni o causare errori di Claude. Consigliamo: a. Limitare il computer use ad ambienti affidabili come macchine virtuali o container con privilegi minimi b. Evitare di dare accesso al computer use 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 autorizzazioni necessarie per le funzioni 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 leggi o la nostra Acceptable Use Policy.

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 sensibili dell'utente 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:

Additional token consumption:

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

Passaggi successivi