Strumento di utilizzo del computer

​

Panoramica

• 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

​

Compatibilità del modello

​

Considerazioni sulla sicurezza

​

Avvio rapido

import anthropic

client = anthropic.Anthropic()

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

​

Come funziona l’utilizzo del computer

​

L’ambiente informatico

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 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 di strumenti: Codice di integrazione che traduce le richieste di strumenti astratti di Claude (come “sposta il mouse” o “acquisisci 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.

1. Riceve le richieste di utilizzo dello strumento 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

​

Come implementare l’utilizzo del computer

​

Inizia con la nostra implementazione di riferimento

• Un ambiente containerizzato adatto all’utilizzo del computer con Claude
• Implementazioni dei 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.

​

Comprendere il ciclo multi-agente

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 lo scambio tra:
    1. Invio di messaggi dell'utente a Claude
    2. Claude che richiede di utilizzare gli strumenti
    3. La tua app che esegue questi 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})

        # Controlla 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 non sono stati utilizzati strumenti, Claude ha finito - restituisci i messaggi finali
        if not tool_results:
            return messages

        # Aggiungi i risultati dello strumento ai messaggi per l'iterazione successiva con Claude
        messages.append({"role": "user", "content": tool_results})

"betas": ["computer-use-2025-01-24"]

"betas": ["computer-use-2025-01-24"]

​

Ottimizza le prestazioni del modello con i prompt

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 invitare Claude con Dopo ogni passaggio, acquisisci 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 hai confermato 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 invitare il modello a 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

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

​

Azioni disponibili

• screenshot - Acquisisci 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

• 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 granulare del clic
• hold_key - Tieni premuto un tasto mentre esegui altre azioni
• wait - Pausa tra le azioni

// Acquisisci uno screenshot
{
  "action": "screenshot"
}

// Fai clic alla posizione
{
  "action": "left_click",
  "coordinate": [500, 300]
}

// Digita testo
{
  "action": "type",
  "text": "Hello, world!"
}

// Scorri verso il basso (Claude 4/3.7)
{
  "action": "scroll",
  "coordinate": [500, 400],
  "scroll_direction": "down",
  "scroll_amount": 3
}

​

Parametri dello strumento

​

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

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

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

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

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

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

​

Aumentare l’utilizzo del computer con altri strumenti

• Eseguire comandi di sistema (strumento bash)
• Modificare file di configurazione o script (strumento editor di testo)
• Integrarsi 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-sonnet-4-5",
    "max_tokens": 2000,
    "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 di utilizzo del computer personalizzato

• Un ambiente virtualizzato o containerizzato adatto all’utilizzo del computer con Claude
• Un’implementazione di almeno uno degli strumenti di utilizzo del computer definiti da Anthropic
• Un ciclo di agenti che interagisce con l’API Claude ed esegue i risultati di tool_use utilizzando le tue implementazioni di strumenti
• Un’API o un’interfaccia utente che consenta l’input dell’utente per avviare il ciclo di agenti

​

Implementa lo strumento di utilizzo del computer

def handle_computer_action(action_type, params):
    if action_type == "screenshot":
        return capture_screenshot()
    elif action_type == "left_click":
        x, y = params["coordinate"]
        return click_at(x, y)
    elif action_type == "type":
        return type_text(params["text"])
    # ... gestisci altre azioni

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)
        
        # Restituisci il risultato a Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

while True:
    response = client.beta.messages.create(...)
    
    # Controlla se Claude ha utilizzato degli strumenti
    tool_results = process_tool_calls(response)
    
    if not tool_results:
        # Nessun ulteriore utilizzo dello strumento, attività completata
        break
        
    # Continua la conversazione con i risultati dello strumento
    messages.append({"role": "user", "content": tool_results})

​

Gestisci gli errori

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Coordinates (1200, 900) are outside display bounds (1024x768).",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Failed to perform click action. The application may be unresponsive.",
      "is_error": true
    }
  ]
}

​

Segui le migliori pratiche di implementazione

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Consenti all'interfaccia utente di aggiornarsi

def validate_action(action_type, params):
    if action_type == "left_click":
        x, y = params.get("coordinate", (0, 0))
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordinates out of bounds"
    return True, None

import logging

def log_action(action_type, params, result):
    logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")

​

Comprendi i limiti dell’utilizzo del computer

1. Latenza: la latenza attuale di utilizzo del computer per le interazioni uomo-IA potrebbe essere troppo lenta rispetto alle azioni del computer dirette regolari. 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 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à della selezione dello strumento: Claude potrebbe fare errori o allucinare quando seleziona gli strumenti 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 invitare il modello con attenzione 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 una quantità specificata.
5. Interazione con fogli di calcolo: I clic del mouse per l’interazione con fogli di calcolo sono stati 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 impegnarsi nell’imitazione umana su siti web e piattaforme di social media. Potremmo aggiornare questa capacità in futuro.
7. Vulnerabilità: Vulnerabilità come il jailbreaking o l’iniezione di prompt possono persistere nei sistemi di IA di frontiera, inclusa l’API beta di utilizzo 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 Claude su pagine web o contenute in immagini possono ignorare le istruzioni o causare errori di Claude. Consigliamo: a. Limitare l’utilizzo del computer ad ambienti affidabili come macchine virtuali o contenitori con privilegi minimi b. Evitare di dare accesso all’utilizzo del computer a account sensibili o dati 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 utilizzo del computer nelle tue applicazioni
8. Azioni inappropriate o illegali: Secondo i termini di servizio di Anthropic, non devi utilizzare l’utilizzo del computer per violare alcuna legge o la nostra Politica di utilizzo accettabile.

​

Prezzi

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

​

Passaggi successivi