Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Primo flusso di lavoro: navigare e interagire

Lezione 4 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Assemblare i pezzi
  2. Il gestore di azioni
  3. Il ciclo completo
  4. Avvio del flusso di lavoro
  5. Una funzione riutilizzabile per il resto del corso
  6. Tre fallimenti che incontrerai
  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: l’agente utilizza lo strumento computer dalle API Responses, un gestore di azioni modellato sulla documentazione (azioni raggruppate, keypress, scroll_x/scroll_y, percorsi drag) e il concatenamento tramite previous_response_id, sostituendo il codice scritto per le API di Anthropic. Fonti: Computer use · Ricette di integrazione.

Assemblare i pezzi

Hai il ciclo in mente e l’ambiente configurato. Ora devi unirli in un programma funzionante: un agente che apre un’enciclopedia online, cerca un termine, apre il primo risultato e ti riporta il titolo della pagina raggiunta. Lo scenario sembra modesto, ma coinvolge i gesti fondamentali—navigazione, digitazione, clic, lettura delle informazioni—e tutto ciò che costruirai in seguito sarà solo una variazione più lunga di questo.

Il gestore di azioni

Il modello decide, ma non esegue nulla di per sé: restituisce una lista di azioni e il tuo codice le traduce in gesti di Playwright, in ordine. Questa funzione segue il gestore pubblicato da OpenAI nelle sue ricette di integrazione, semplificato per un browser.

import time

KEYS = {
    "ENTER": "Enter", "RETURN": "Enter", "ESC": "Escape", "ESCAPE": "Escape",
    "TAB": "Tab", "SPACE": "Space", "BACKSPACE": "Backspace", "DELETE": "Delete",
    "UP": "ArrowUp", "DOWN": "ArrowDown", "LEFT": "ArrowLeft", "RIGHT": "ArrowRight",
    "CTRL": "Control", "CONTROL": "Control", "SHIFT": "Shift", "ALT": "Alt",
    "CMD": "Meta", "META": "Meta",
}
BUTTONS = {"left": "left", "right": "right", "wheel": "middle"}

def execute_actions(page, actions):
    """Esegue le azioni da una computer_call in ordine."""
    for action in actions:
        if action.type in ("click", "double_click", "drag", "move", "scroll") and getattr(action, "keys", None):
            raise ValueError("Azione del mouse con tasto modificatore: non gestita qui")
        match action.type:
            case "click":
                button = getattr(action, "button", "left")
                if button not in BUTTONS:  # indietro e avanti non esistono in Playwright
                    raise ValueError(f"Pulsante non supportato: {button}")
                page.mouse.click(action.x, action.y, button=BUTTONS[button])
            case "double_click":
                page.mouse.dblclick(action.x, action.y)
            case "drag":
                points = [(p.x, p.y) for p in action.path]
                page.mouse.move(*points[0])
                page.mouse.down()
                for x, y in points[1:]:
                    page.mouse.move(x, y)
                page.mouse.up()
            case "move":
                page.mouse.move(action.x, action.y)
            case "scroll":
                page.mouse.move(action.x, action.y)
                page.mouse.wheel(action.scroll_x, action.scroll_y)
            case "keypress":
                page.keyboard.press("+".join(KEYS.get(k, k) for k in action.keys))
            case "type":
                page.keyboard.type(action.text)
            case "wait":
                time.sleep(2)
            case "screenshot":
                continue  # lo screenshot viene catturato dopo ogni batch di azioni
            case _:
                raise ValueError(f"Azione non supportata: {action.type}")

Due scelte meritano una spiegazione. I nomi dei tasti e dei pulsanti restituiti dal modello (ENTER, CTRL, wheel…) non sono quelli che Playwright si aspetta (Enter, Control, middle…): le tabelle di mappatura, tratte dalla documentazione, colmano il divario, e i pulsanti back e forward, che l’API può anche richiedere, vengono rifiutati come nel gestore di OpenAI. Inoltre, un’azione sconosciuta genera un errore invece di essere ignorata silenziosamente: un arresto netto è preferibile a un agente che crede di aver agito quando non l’ha fatto.

Il ciclo completo

L’agente orchestra quindi il ciclo. La prima chiamata invia il compito; se contiene solo una richiesta di screenshot, restituisci semplicemente lo schermo. Ogni screenshot torna al modello come risultato della chiamata che lo ha richiesto, referenziato dal suo call_id, e previous_response_id collega i vari turni.

import base64

from openai import OpenAI
from playwright.sync_api import sync_playwright

client = OpenAI()
MODEL = "gpt-6.1-sol"
MAX_TURNS = 15

def launch_agent(task: str, start_url: str = "https://en.wikipedia.org"):
    """Avvia un agente Computer Use su un dato compito."""
    pw = sync_playwright().start()
    browser = pw.chromium.launch(headless=False)  # False per osservare
    page = browser.new_page(viewport={"width": 1280, "height": 720})
    page.goto(start_url)
    page.wait_for_load_state("networkidle")

    try:
        response = client.responses.create(
            model=MODEL, tools=[{"type": "computer"}], input=task,
        )
        for turn in range(MAX_TURNS):
            call = next((i for i in response.output if i.type == "computer_call"), None)
            if call is None:
                print(f"Compito completato: {response.output_text}")
                return response.output_text

            if call.pending_safety_checks:  # vedi lezione 12
                raise RuntimeError("Controlli di sicurezza in sospeso: richiesto intervento umano")
            for action in call.actions:
                print(f"  Azione: {action.type}")
            execute_actions(page, call.actions)
            screenshot = base64.b64encode(page.screenshot()).decode("utf-8")

            response = client.responses.create(
                model=MODEL,
                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",
                    },
                }],
            )
        raise RuntimeError("Raggiunto il numero massimo di turni: controlla lo stato della pagina")
    finally:
        browser.close()
        pw.stop()

Tre salvaguardie sono già in atto. MAX_TURNS delimita il ciclo: senza questo limite, un agente disorientato consumerebbe il tuo budget fino all’esaurimento. Una chiamata con controlli di sicurezza in sospeso (pending_safety_checks) blocca tutto, come nell’esempio ufficiale di OpenAI: la lezione 12 mostra come farli validare da un umano. E il completamento normale è segnalato dall’assenza di una computer_call: il modello ha smesso di agire e ti sta rispondendo, e recuperi il titolo della pagina da output_text.

Avvio del flusso di lavoro

if __name__ == "__main__":
    launch_agent(
        "Cerca 'Computer Use' nel motore di ricerca di Wikipedia, "
        "apri il primo risultato e dammi il titolo della pagina. "
        "Usa lo strumento computer per agire sull'interfaccia."
    )

Con headless=False, lo spettacolo è istruttivo: la finestra si apre, il clic atterra nel campo di ricerca, il testo appare, il primo link si apre e il titolo torna nella tua console. Osservalo eseguire due o tre volte prima di passare a compiti più ambiziosi; vedrai precisamente dove l’agente esita e cosa le tue istruzioni dovrebbero affrontare.

Una funzione riutilizzabile per il resto del corso

Le lezioni successive lavorano su una pagina già aperta—dopo un login, nel mezzo di un flusso di lavoro. Si basano su run_agent(task, page=page): lo stesso ciclo, estratto da launch_agent, con instructions opzionali restituite a ogni turno (la lezione 5 spiega perché).

def run_agent(task: str, page, instructions: str | None = None, max_turns: int = MAX_TURNS) -> str:
    """Ciclo Computer Use su una pagina già aperta; restituisce il messaggio finale."""
    request = {"model": MODEL, "tools": [{"type": "computer"}]}
    if instructions:
        request["instructions"] = instructions  # da restituire a ogni richiesta

    response = client.responses.create(**request, input=task)
    for turn in range(max_turns):
        call = next((i for i in response.output if i.type == "computer_call"), None)
        if call is None:
            return response.output_text
        if call.pending_safety_checks:
            raise RuntimeError("Controlli di sicurezza in sospeso: richiesto intervento umano")

        execute_actions(page, call.actions)
        screenshot = base64.b64encode(page.screenshot()).decode("utf-8")
        response = client.responses.create(
            **request,
            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",
                },
            }],
        )
    raise RuntimeError("Raggiunto il numero massimo di turni: controlla lo stato della pagina")

Tre fallimenti che incontrerai

L’agente clicca sistematicamente accanto al suo obiettivo? Il colpevole è quasi sempre una discrepanza di scala tra lo screenshot inviato e la pagina su cui stai cliccando: screenshot ridimensionato, zoom del browser, schermo ad alta densità. Le coordinate del modello si riferiscono all’immagine che ha ricevuto; se la rimpicciolisci, converti le sue coordinate nella direzione opposta.

L’agente gira in tondo e ripete lo stesso gesto? Il limite di turni alla fine lo fermerà, ma è meglio rilevare il loop prima: se lo stesso screenshot torna più volte di fila, l’agente non sta facendo progressi e interromperlo ti risparmia chiamate inutili.

L’agente agisce su una pagina ancora vuota? Su un sito pesante, page.goto() torna prima che il rendering sia finito e il primo screenshot mostra solo uno sfondo bianco. Attendi l’inattività della rete prima di scattare la foto:

page.goto(url)
page.wait_for_load_state("networkidle")

Punti chiave

  • Un agente Computer Use combina un gestore di azioni, un ciclo di controllo e il concatenamento delle risposte
  • La prima chiamata invia il compito; ogni screenshot torna in un computer_call_output con lo stesso call_id
  • Il gestore esegue le azioni in ordine e rifiuta ciò che non sa come fare
  • Limita sempre il numero di turni, fermati su pending_safety_checks e usa headless=False durante lo sviluppo
  • run_agent(task, page=page) riutilizza questo ciclo per una pagina già aperta; è ciò che useranno le lezioni successive