Utilizzo del computer (beta)

Claude 4 Opus e Sonnet, insieme a Claude Sonnet 3.7 e Claude Sonnet 3.5 (nuovo), sono in grado di interagire con strumenti che possono manipolare un ambiente desktop del computer. I modelli Claude 4 utilizzano versioni aggiornate degli strumenti ottimizzate per la nuova architettura. Claude Sonnet 3.7 introduce strumenti aggiuntivi e consente di abilitare il pensiero, fornendoti maggiori informazioni sul processo di ragionamento del modello.

Ecco un esempio di come fornire strumenti di utilizzo del computer a Claude utilizzando l’API Messages:

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-20250514",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250429",
        "name": "str_replace_based_edit_tool"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Save a picture of a cat to my desktop."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

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-20250514",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250429",
        "name": "str_replace_based_edit_tool"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Save a picture of a cat to my desktop."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

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-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Save a picture of a cat to my desktop."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

​

Come funziona l’utilizzo del computer

Ci riferiamo alla ripetizione dei passaggi 3 e 4 senza input dell’utente come “ciclo dell’agente” - 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 isolato in cui Claude può interagire in modo sicuro con le 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 screenshot e controllerà con 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 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 di strumenti astratti di Claude (come “sposta il mouse” o “fai uno screenshot”) in operazioni effettive nell’ambiente virtuale.

5. Ciclo dell’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 di calcolo
3. Cattura 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 di porte 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 dell’agente che interagisce con l’API Anthropic ed esegue gli strumenti di utilizzo del computer
• Un’interfaccia web per interagire con il container, il ciclo dell’agente e gli strumenti.

​

Comprendere il ciclo multi-agente

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

    Questa funzione gestisce il botta e risposta tra:
    1. Invio di messaggi utente a Claude
    2. Claude che richiede di utilizzare strumenti
    3. La tua app che esegue quegli strumenti
    4. Invio dei risultati degli strumenti a Claude
    """
    # Configura strumenti e 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 strumenti - dovresti averli già 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 dell'agente principale (con limite di iterazioni per prevenire costi API incontrollati)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Configura 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})

        # Controlla se Claude ha utilizzato 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": "Strumento eseguito con successo"}

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

        # Se non sono stati utilizzati strumenti, Claude ha finito - restituisci i messaggi finali
        if not tool_results:
            return messages

        # Aggiungi i risultati degli strumenti ai messaggi per la prossima iterazione con Claude
        messages.append({"role": "user", "content": tool_results})

Il ciclo continua fino a quando Claude 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.

Ti consigliamo 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à:

1. Specifica attività semplici e ben definite e fornisci istruzioni esplicite per ogni passaggio.
2. A volte Claude presuppone i risultati delle sue azioni senza verificarli esplicitamente. Per evitare questo, puoi sollecitare Claude con Dopo ogni passaggio, fai uno screenshot e valuta attentamente se hai ottenuto 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 al 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 sollecitare il modello a utilizzare scorciatoie da tastiera.
4. Per attività ripetibili o interazioni con l’interfaccia utente, includi screenshot di esempio e chiamate di strumenti di risultati positivi nel tuo prompt.
5. Se hai bisogno che il modello effettui l’accesso, forniscigli il nome utente e la 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. Si prega di consultare 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 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 di calcolo isolato. Attualmente NON hai la capacità di ispezionare file o interagire con risorse esterne, se non invocando le funzioni sottostanti.

Come per il normale utilizzo degli strumenti, il campo system_prompt fornito dall’utente viene comunque rispettato e utilizzato nella costruzione del prompt di sistema combinato.

​

Comprendere gli strumenti definiti da Anthropic

Abbiamo fornito un insieme di strumenti che consentono a Claude di utilizzare efficacemente i computer. Quando si specifica uno strumento definito da Anthropic, i campi description e tool_schema non sono necessari né consentiti.

Forniamo un insieme di strumenti definiti da Anthropic, con ogni strumento che ha versioni ottimizzate per Claude 4, Claude Sonnet 3.7 e Claude Sonnet 3.5:

Il campo type identifica lo strumento e i suoi parametri per scopi di convalida, il campo name è il nome dello strumento esposto al modello.

Se vuoi sollecitare il modello a utilizzare uno di questi strumenti, puoi fare riferimento esplicito allo strumento tramite il campo name. Il campo name deve essere unico all’interno dell’elenco degli strumenti; non puoi definire uno strumento con lo stesso nome di uno strumento definito da Anthropic nella stessa chiamata API.

​

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 affronta compiti complessi. Questa funzionalità ti aiuta a capire come Claude sta affrontando un problema e può essere particolarmente preziosa per il debug o per 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 incomprensioni
3. Imparare dall’approccio di Claude alla risoluzione dei problemi
4. Ottenere maggiore visibilità su operazioni complesse multi-step

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

[Thinking]
Devo salvare un'immagine di un gatto sul desktop. Suddividiamo questo in passaggi:

1. Prima, farò 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 facendo uno screenshot per vedere cosa è disponibile...

​

Combina l’utilizzo del computer con altri strumenti

Puoi combinare l’utilizzo regolare degli strumenti con gli strumenti definiti da Anthropic per 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-01-24" \
  -d '{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
      },
      {
        "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
    }
  }'

​

Costruisci un ambiente personalizzato per l’utilizzo del computer

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 in base alle 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 dell’agente che interagisce con l’API Anthropic ed esegue i risultati di tool_use utilizzando le tue implementazioni degli strumenti
• Un’API o un’interfaccia utente che consenta l’input dell’utente per avviare il ciclo dell’agente

​

Comprendere i limiti 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 dei suoi limiti:

1. Latenza: l’attuale latenza di utilizzo del computer per le interazioni uomo-IA potrebbe essere troppo lenta rispetto alle normali azioni del computer dirette dall’uomo. Consigliamo di concentrarsi su casi d’uso in cui la velocità non è critica (ad esempio, raccolta di informazioni in background, test automatizzati di software) in ambienti fidati.
2. Precisione e affidabilità della visione artificiale: Claude potrebbe 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. 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 interagisce con applicazioni di nicchia o più applicazioni contemporaneamente. Consigliamo agli utenti di sollecitare attentamente il modello quando richiedono attività complesse.
4. 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 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 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 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 sociali e di comunicazione: Sebbene Claude visiterà siti web, stiamo limitando la sua capacità di creare account o generare e condividere contenuti o altrimenti impegnarsi nell’impersonificazione umana attraverso siti web e piattaforme di social media. Potremmo aggiornare questa capacità in futuro.
7. Vulnerabilità: Vulnerabilità come il jailbreaking o l’iniezione di prompt potrebbero persistere nei sistemi di IA di frontiera, inclusa l’API beta di utilizzo del computer. 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 sulle pagine web o contenute nelle immagini potrebbero sovrascrivere le istruzioni o causare errori a Claude. Consigliamo: 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 una rigorosa supervisione c. Informare gli utenti finali dei rischi pertinenti e ottenere il loro consenso prima di abilitare o richiedere le autorizzazioni necessarie per le funzionalità di utilizzo del computer nelle tue applicazioni
8. Azioni inappropriate o illegali: Secondo i termini di servizio di Anthropic, non devi impiegare l’utilizzo del computer per violare leggi o la nostra Politica di Utilizzo Accettabile.

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

​

Prezzi

Come sottoinsieme delle richieste di utilizzo degli strumenti, le richieste di utilizzo del computer hanno lo stesso prezzo di qualsiasi altra richiesta API Claude.

Includiamo anche automaticamente un prompt di sistema speciale per il modello, che abilita l’utilizzo del computer.

Oltre ai token di base, sono necessari i seguenti token di input aggiuntivi per gli strumenti definiti da Anthropic:

Se abiliti il pensiero con Claude 4 o Claude Sonnet 3.7, i token utilizzati per il pensiero verranno conteggiati rispetto al tuo budget di max_tokens in base ai budget_tokens che specifichi nel parametro di pensiero.