Claude 3.7 Sonnet e Claude 3.5 Sonnet (nuovo) sono in grado di interagire con strumenti che possono manipolare un ambiente desktop del computer. Claude 3.7 Sonnet introduce strumenti aggiuntivi e permette di abilitare il pensiero, dandoti maggiore visibilità sul processo di ragionamento del modello.

L’uso del computer è una funzionalità beta. Si prega di essere consapevoli che l’uso del computer comporta rischi unici che sono distinti dalle funzionalità API standard o dalle interfacce di chat. Questi rischi sono maggiori quando si utilizza il computer per interagire con internet. Per minimizzare i rischi, considera di prendere precauzioni come:

  1. Utilizzare una macchina virtuale dedicata o un container con privilegi minimi per prevenire attacchi diretti al sistema o incidenti.
  2. Evitare di dare al modello accesso a dati sensibili, come informazioni di login dell’account, per prevenire il furto di informazioni.
  3. Limitare l’accesso a internet a una lista di domini consentiti per ridurre l’esposizione a contenuti dannosi.
  4. Chiedere a un umano di confermare decisioni che potrebbero avere conseguenze significative nel mondo reale e qualsiasi attività che richieda un consenso affermativo, come accettare i cookie, eseguire transazioni finanziarie o accettare termini di servizio.

In alcune circostanze, Claude seguirà i comandi trovati nei contenuti anche se sono in conflitto con le istruzioni dell’utente. Per esempio, le istruzioni di Claude sulle pagine web o contenute nelle immagini potrebbero sovrascrivere le istruzioni o causare errori da parte di Claude. Suggeriamo di prendere precauzioni per isolare Claude da dati e azioni sensibili per evitare rischi relativi all’iniezione di prompt.

Infine, si prega di informare gli utenti finali dei rischi rilevanti e ottenere il loro consenso prima di abilitare l’uso del computer nei propri prodotti.

Implementazione di riferimento per l'uso del computer

Inizia rapidamente con la nostra implementazione di riferimento per l’uso del computer che include un’interfaccia web, container Docker, implementazioni di esempio degli strumenti e un loop dell’agente.

Nota: L’implementazione è stata aggiornata per includere nuovi strumenti per Claude 3.7 Sonnet. Assicurati di scaricare l’ultima versione del repository per accedere a queste nuove funzionalità.

Si prega di utilizzare questo modulo per fornire feedback sulla qualità delle risposte del modello, l’API stessa o la qualità della documentazione - non vediamo l’ora di ricevere il tuo feedback!

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


Come funziona l’uso del computer

1. Fornisci a Claude gli strumenti per l'uso del computer e un prompt utente

  • Aggiungi gli strumenti per l’uso del computer definiti da Anthropic alla tua richiesta API.
  • Includi un prompt utente che potrebbe richiedere questi strumenti, ad esempio “Salva una foto di un gatto sul mio desktop.”

2. Claude decide di utilizzare uno strumento

  • Claude carica le definizioni degli strumenti per l’uso del computer memorizzate e valuta se qualche strumento può aiutare con la query dell’utente.
  • In caso affermativo, Claude costruisce una richiesta di utilizzo dello strumento correttamente formattata.
  • La risposta API ha un stop_reason di tool_use, segnalando l’intenzione di Claude.

3. Estrai l'input dello strumento, valuta lo strumento su un computer e restituisci i risultati

  • Dal tuo lato, estrai il nome dello strumento e l’input dalla richiesta di Claude.
  • Usa lo strumento su un container o una Macchina Virtuale.
  • Continua la conversazione con un nuovo messaggio user contenente un blocco tool_result.

4. Claude continua a chiamare gli strumenti per l'uso del computer finché non ha completato l'attività

  • Claude analizza i risultati dello strumento per determinare se è necessario un ulteriore utilizzo dello strumento o se l’attività è stata completata.
  • Se Claude decide che ha bisogno di un altro strumento, risponde con un altro stop_reason di tool_use e dovresti tornare al punto 3.
  • Altrimenti, elabora una risposta testuale per l’utente.

Ci riferiamo alla ripetizione dei passaggi 3 e 4 senza input dell’utente come “loop 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’uso del computer richiede un ambiente di calcolo sandbox dove Claude può interagire in modo sicuro con applicazioni e web. Questo ambiente include:

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

  2. Ambiente desktop: Una UI leggera con window manager (Mutter) e pannello (Tint2) in esecuzione su Linux, che fornisce un’interfaccia grafica consistente con cui Claude può interagire.

  3. Applicazioni: Applicazioni Linux preinstallate come Firefox, LibreOffice, editor di testo e file manager che Claude può utilizzare per completare le attività.

  4. Implementazioni degli strumenti: Codice di integrazione che traduce le richieste di strumenti astratte di Claude (come “sposta mouse” o “fai screenshot”) in operazioni effettive nell’ambiente virtuale.

  5. Loop 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 usi l’uso 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 appropriate mappature delle porte per visualizzare e interagire con l’ambiente.


Come implementare l’uso 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’uso del computer:

Comprendere il loop multi-agente

Il nucleo dell’uso del computer è il “loop 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 loop infiniti
):
    """
    Un semplice loop dell'agente per le interazioni di uso del computer di Claude.
    
    Questa funzione gestisce il botta e risposta tra:
    1. Invio di messaggi utente a Claude
    2. Claude che richiede di usare 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"}
    ]
    
    # Loop principale dell'agente (con limite di iterazioni per prevenire costi API incontrollati)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Configura parametro thinking opzionale (per Claude 3.7 Sonnet)
        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 usato strumenti
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # In un'app reale, eseguiresti lo strumento qui
                # Per 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 usati 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 loop continua finché Claude non risponde senza richiedere alcuno strumento (completamento dell’attività) o viene raggiunto il limite massimo di iterazioni. Questa salvaguardia previene potenziali loop infiniti che potrebbero risultare in costi API inaspettati.

Per ogni versione degli strumenti, devi usare il flag beta corrispondente nella tua richiesta API:

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. Claude a volte assume i risultati delle sue azioni senza verificarli esplicitamente. Per prevenire questo puoi sollecitare Claude con Dopo ogni passaggio, fai uno screenshot e valuta attentamente se hai ottenuto il risultato giusto. 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 tendina e barre di scorrimento) potrebbero essere difficili da manipolare per Claude usando i movimenti del mouse. Se riscontri questo problema, prova a sollecitare il modello a utilizzare le scorciatoie da tastiera.
  4. Per attività ripetitive o interazioni con l’interfaccia utente, includi screenshot ed esempi di chiamate agli strumenti di risultati positivi nel tuo prompt.
  5. Se hai bisogno che il modello effettui l’accesso, fornigli nome utente e password nel tuo prompt all’interno di tag xml come <robot_credentials>. L’uso 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.

Se incontri ripetutamente un insieme chiaro di problemi o sai in anticipo le attività che Claude dovrà completare, usa il prompt di sistema per fornire a Claude suggerimenti o istruzioni esplicite su come svolgere le attività con successo.

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’uso del computer. È simile al prompt di sistema per l’uso degli strumenti ma inizia con:

Hai accesso a un set di funzioni che puoi utilizzare per rispondere alla domanda dell’utente. Questo include l’accesso a un ambiente di calcolo sandbox. NON hai attualmente la capacità di ispezionare file o interagire con risorse esterne, se non invocando le funzioni sottostanti.

Come con il normale uso 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

Essendo in beta, queste definizioni degli strumenti sono soggette a modifiche.

Abbiamo fornito un set di strumenti che permettono 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.

Gli strumenti definiti da Anthropic sono eseguiti dall’utente

Gli strumenti definiti da Anthropic sono definiti da Anthropic ma devi valutare esplicitamente i risultati dello strumento e restituire i tool_results a Claude. Come con qualsiasi strumento, il modello non esegue automaticamente lo strumento.

Forniamo un set di strumenti definiti da Anthropic, con ogni strumento che ha versioni ottimizzate sia per Claude 3.5 Sonnet (nuovo) che per Claude 3.7 Sonnet:

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

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

Non consigliamo di definire strumenti con i nomi degli strumenti definiti da Anthropic. Anche se puoi ancora ridefinire strumenti con questi nomi (purché il nome dello strumento sia unico nel tuo blocco tools), farlo potrebbe risultare in prestazioni degradate del modello.

Abilita la capacità di pensiero in Claude 3.7 Sonnet

Claude 3.7 Sonnet introduce una nuova capacità di “pensiero” che ti permette di vedere il processo di ragionamento del modello mentre lavora su attività complesse. Questa funzionalità ti aiuta a capire come Claude sta affrontando un problema e può essere particolarmente preziosa per il debugging 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ò usare 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 una foto di un gatto sul desktop. Analizziamo 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’uso del computer con altri strumenti

Puoi combinare l’uso regolare degli strumenti con gli strumenti definiti da Anthropic per l’uso del computer.

Costruisci 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 per far usare un computer a Claude. Tuttavia, puoi costruire il tuo ambiente per l’uso del computer per soddisfare le tue esigenze. Avrai bisogno di:

  • Un ambiente virtualizzato o containerizzato adatto per l’uso del computer con Claude
  • Un’implementazione di almeno uno degli strumenti definiti da Anthropic per l’uso del computer
  • Un loop dell’agente che interagisce con l’API Anthropic ed esegue i risultati tool_use usando le tue implementazioni degli strumenti
  • Un’API o UI che permette l’input dell’utente per avviare il loop dell’agente

Comprendere i limiti dell’uso del computer

La funzionalità di uso 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 dell’uso del computer per le interazioni uomo-IA potrebbe essere troppo lenta rispetto alle normali azioni al computer dirette dall’uomo. Raccomandiamo di concentrarsi su casi d’uso dove la velocità non è critica (es., raccolta di informazioni in background, test automatizzato del software) in ambienti fidati.
  2. Accuratezza e affidabilità della visione computerizzata: Claude potrebbe fare errori o allucinare quando produce coordinate specifiche mentre genera azioni. Claude 3.7 Sonnet introduce la capacità di pensiero che può aiutarti a capire il ragionamento del modello e identificare potenziali problemi.
  3. Accuratezza e affidabilità nella selezione degli strumenti: Claude potrebbe fare errori o allucinare quando seleziona strumenti mentre genera azioni o intraprendere azioni inaspettate per risolvere problemi. Inoltre, l’affidabilità potrebbe essere inferiore quando interagisce con applicazioni di nicchia o più applicazioni contemporaneamente. Raccomandiamo che gli utenti sollecitino il modello con attenzione quando richiedono attività complesse.
  4. Affidabilità dello scorrimento: Mentre Claude 3.5 Sonnet (nuovo) aveva limitazioni con lo scorrimento, Claude 3.7 Sonnet 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 click del mouse per l’interazione con i fogli di calcolo sono migliorati in Claude 3.7 Sonnet 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 usando questi controlli granulari e combinando i tasti modificatori con i click.
  6. Creazione di account e generazione di contenuti su piattaforme sociali e di comunicazione: Mentre Claude visiterà siti web, stiamo limitando la sua capacità di creare account o generare e condividere contenuti o altrimenti impersonare umani 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 attraverso i sistemi di IA di frontiera, inclusa l’API beta per l’uso del computer. In alcune circostanze, Claude seguirà i comandi trovati nei contenuti, a volte anche in conflitto con le istruzioni dell’utente. Per esempio, le istruzioni di Claude sulle pagine web o contenute nelle immagini potrebbero sovrascrivere le istruzioni o causare errori da parte di Claude. Raccomandiamo: a. Limitare l’uso del computer ad ambienti fidati come macchine virtuali o container con privilegi minimi b. Evitare di dare accesso all’uso del computer ad account o dati sensibili senza una stretta supervisione c. Informare gli utenti finali dei rischi rilevanti e ottenere il loro consenso prima di abilitare o richiedere permessi necessari 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 alcuna legge o la nostra Politica di Uso Accettabile.

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


Prezzi

Vedi la documentazione sui prezzi dell’uso degli strumenti per una spiegazione dettagliata di come vengono prezzate le richieste API di Claude Tool Use.

Come sottoinsieme delle richieste di uso degli strumenti, le richieste di uso del computer sono prezzate allo stesso modo di qualsiasi altra richiesta API Claude.

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

ModelloScelta strumentoConteggio token prompt di sistema
Claude 3.5 Sonnet (nuovo)auto
any, tool
466 token
499 token
Claude 3.7 Sonnetauto
any, tool
466 token
499 token

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

StrumentoToken di input aggiuntivi
computer_20241022 (Claude 3.5 Sonnet)683 token
computer_20250124 (Claude 3.7 Sonnet)735 token
text_editor_20241022 (Claude 3.5 Sonnet)700 token
text_editor_20250124 (Claude 3.7 Sonnet)700 token
bash_20241022 (Claude 3.5 Sonnet)245 token
bash_20250124 (Claude 3.7 Sonnet)245 token

Se abiliti il pensiero con Claude 3.7 Sonnet, i token usati per il pensiero verranno conteggiati nel tuo budget max_tokens in base ai budget_tokens che specifichi nel parametro thinking.