Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Architettura: Screenshot, Azioni e il Ciclo di Interazione

Lezione 2 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Il ciclo percezione-azione
  2. Il punto di partenza: lo screenshot
  3. Analisi e decisione
  4. Il repertorio delle azioni
  5. Il flusso completo
  6. Quanto costa un turno del ciclo
  7. Punti chiave

Lezione riscritta il 3 novembre 2026 sulla base della guida Computer use di OpenAI e delle ricette di integrazione per Computer use: questo corso si basava in precedenza sulle API di Anthropic (import anthropic, strumento computer_20241022). Ora utilizza lo strumento computer delle API Responses di OpenAI, con le azioni raggruppate in una computer_call e gli screenshot restituiti tramite computer_call_output. Abbiamo rimosso i conteggi di token e le stime di durata privi di fonte presenti nella versione precedente. Fonti: Computer use · Ricette di integrazione.

Il ciclo percezione-azione

Tutta l’architettura del Computer Use si riduce a un singolo ciclo: osserva → decidi → agisci → osserva. Finché questo ciclo non ti sarà chiaro nella mente, le tue automazioni rimarranno erratiche; non appena farà clic, il resto sarà solo infrastruttura.

La differenza rispetto a uno script Selenium risiede nel luogo in cui risiede la conoscenza. Selenium esegue ciecamente una sequenza predeterminata: clicca qui, poi lì, poi digita questo. Il Computer Use sceglie il passo successivo solo dopo aver visto il risultato di quello precedente. Appare un popup, una pagina impiega più tempo a caricarsi o l’etichetta di un pulsante cambia da un giorno all’altro: in tutti e tre i casi, il modello vede la situazione reale e si adatta, mentre lo script continua a recitare nel vuoto.

Con lo strumento computer di OpenAI, lo scambio avviene in tre passaggi: invii il compito, esegui le azioni restituite dal modello e poi rimandi uno screenshot. La tua applicazione gestisce mouse e tastiera; il modello prende solo le decisioni.

Il punto di partenza: lo screenshot

Ogni turno si basa su un’immagine dello stato corrente dello schermo. Questo screenshot proviene da un browser controllato da Playwright (il caso più comune per l’automazione web), da un desktop virtuale quando si automatizza un’applicazione desktop o da un container Docker che isola l’agente. OpenAI raccomanda di utilizzare in tutti i casi un browser isolato o una macchina virtuale.

import base64

def capture_screen(page) -> str:
    """Cattura lo schermo con Playwright e restituisce l'immagine PNG in base64."""
    return base64.b64encode(page.screenshot()).decode("utf-8")

Lo screenshot torna al modello come URL dati PNG. Conta come input immagine, quindi influisce sul costo di ogni turno: la dimensione della finestra che catturi è un vero parametro di progettazione.

Analisi e decisione

Il modello riceve il compito, la cronologia della conversazione e l’ultimo screenshot. La sua risposta non è una frase, ma un elemento computer_call, che contiene una lista ordinata di azioni da eseguire. Ecco un esempio dalla documentazione di OpenAI che seleziona un campo di ricerca e poi digita una parola:

{
  "type": "computer_call",
  "call_id": "call_002",
  "actions": [
    { "type": "click", "button": "left", "x": 405, "y": 157 },
    { "type": "type", "text": "penguin" }
  ],
  "status": "completed"
}

Due dettagli sono importanti. La prima chiamata potrebbe contenere solo un’azione screenshot: il modello chiede di vedere lo schermo prima di agire e tu restituisci uno screenshot senza cambiare nulla. Inoltre, status: "completed" significa che il modello ha finito di generare la chiamata, non che le azioni sono state eseguite: spetta a te eseguirle.

Il repertorio delle azioni

Il vocabolario disponibile per il modello è intenzionalmente limitato; combinati, questi primitivi coprono la maggior parte di ciò che un umano fa con mouse e tastiera.

AzioneDescrizioneCampi
clickClicca in una posizionex, y, button (left, right, wheel, back, forward)
double_clickDoppio clicx, y
dragTrascina lungo un percorsopath (lista di punti)
moveSposta il puntatorex, y
scrollScorrix, y, scroll_x, scroll_y
keypressTasto o combinazionekeys (es. ["CTRL", "A"])
typeDigita testotext
waitAttendi il caricamento della pagina—
screenshotRichiedi un nuovo screenshot—

Il flusso completo

Messi insieme, questi elementi creano il seguente ciclo, modellato sulla documentazione di OpenAI. Finché la risposta contiene una computer_call, esegui le sue azioni, catturi lo schermo e restituisci lo screenshot in una computer_call_output che riutilizza lo stesso call_id; previous_response_id collega ogni turno a quello precedente.

from openai import OpenAI

client = OpenAI()

def computer_use_loop(page, task: str):
    """Ciclo Computer Use con lo strumento computer dalle API Responses."""
    response = client.responses.create(
        model="gpt-6.1-sol",
        tools=[{"type": "computer"}],
        input=task,
    )

    while True:
        call = next(
            (item for item in response.output if item.type == "computer_call"),
            None,
        )
        if call is None:
            return response.output_text  # nessuna altra azione richiesta: compito finito

        execute_actions(page, call.actions)  # il tuo gestore azioni (Lezione 4)
        screenshot = capture_screen(page)

        response = client.responses.create(
            model="gpt-6.1-sol",
            tools=[{"type": "computer"}],
            previous_response_id=response.id,
            input=[{
                "type": "computer_call_output",
                "call_id": call.call_id,
                "output": {
                    "type": "computer_screenshot",
                    "image_url": f"data:image/png;base64,{screenshot}",
                    "detail": "original",
                },
            }],
        )

Questo ciclo non ha ancora protezioni: in produzione, limita il numero di turni, la durata e il costo; fermati se una chiamata include controlli di sicurezza in sospeso (pending_safety_checks); e verifica il risultato effettivo invece di fidarti solo del messaggio finale del modello. Queste sono le linee guida di sicurezza di OpenAI, trattate nella Lezione 12.

Quanto costa un turno del ciclo

Ogni richiesta alle API Responses addebita token di input e output, e ogni screenshot conta come input immagine; un ambiente ospitato potrebbe essere fatturato separatamente. Il costo di un compito dipende quindi dal numero di turni, dalla dimensione dello screenshot e dal modello, e cresce più velocemente del numero di turni, perché anche con previous_response_id, tutti i token di input dalle risposte precedenti nella catena vengono riaddebitati come input su ogni richiesta. OpenAI fornisce un calcolatore dei costi per le immagini ed espone l’utilizzo per ogni richiesta: misura sui tuoi flussi di lavoro prima di fare preventivi. Uno script Selenium farà sempre la stessa cosa più velocemente e a minor costo, ma dovrai riscriverlo la prossima volta che il modulo cambierà, cosa che l’agente non richiede.

Punti chiave

  • Il ciclo compito → azioni → screenshot è il cuore del Computer Use; la tua applicazione esegue le azioni
  • Con OpenAI, dichiara lo strumento con tools=[{"type": "computer"}] nelle API Responses
  • Una computer_call contiene una lista ordinata di azioni (click, type, scroll, keypress, ecc.) da eseguire in sequenza
  • Lo screenshot torna al modello in una computer_call_output con lo stesso call_id, concatenato tramite previous_response_id
  • Ogni turno costa token e un’immagine: limita i turni e misura prima di fare preventivi