Snapshot

Snapshot è il modo in cui un agente AI legge una pagina web. Trasforma la pagina corrente in testo strutturato compatto e assegna numeri temporanei (@1, @2, ecc.) agli elementi utilizzabili: pulsanti, input e collegamenti. L'agente decide cosa fare dopo a partire dallo Snapshot, invece di leggere l'HTML grezzo o indovinare le coordinate dello schermo.

Cosa risolve

Per una persona, una pagina web è un'interfaccia visiva. Per un agente si tratta di decine di migliaia di token HTML, script, stili e stato live. Alimentarlo direttamente in un LLM ha due costi ricorrenti:

• Costo elevato in token. Una tipica pagina di amministrazione può contenere fino a 30.000 token, da rileggere prima di ogni azione.
• Annegamento nel rumore. La maggior parte di un DOM completo (stili, script, nodi nascosti) non ha nulla a che fare con la decisione e si limita a intralciare.

Uno snapshot viene creato dall'albero di accessibilità del browser, ovvero la vista semantica di una pagina che il browser conserva per gli screen reader, e comprime la pagina in poche centinaia di token:

• Titolo della pagina e URL corrente.
• Testo visibile e struttura principale.
• Elementi cliccabili, compilabili e selezionabili, con i relativi ruoli e nomi.
• Un @N temporaneo per ogni elemento interattivo.

Ciò è sufficiente affinché l'agente decida su quale pulsante fare clic e quale campo compilare, senza l'HTML grezzo o le coordinate dello schermo.

Come funzionano i riferimenti @N

Ogni elemento interattivo nell'istantanea riceve un numero temporaneo:

@1 [input]  "Search"
@2 [button] "Submit"
@3 [link]   "Next page"

L'agente agisce su quei numeri, ad es. await click('@2').

@N è valido solo per lo snapshot corrente. Dopo le modifiche della pagina (navigazione, aggiornamento, finestra di dialogo, invio di moduli, cambio di scheda, nuovo rendering dinamico), i vecchi numeri potrebbero smettere di puntare ovunque. L'abitudine affidabile è quella di scattare una nuova istantanea dopo ogni modifica invece di trattenere un @N.

Se hai bisogno di un riferimento stabile a un elemento in più passaggi, utilizza il selettore loc=... dall'output dello snapshot come selettore stabile oppure scrivi direttamente un selettore CSS. Vedi ego-browser.

Quando noterai l'istantanea

Nella maggior parte dei casi non si tocca affatto lo snapshot: l'agente lo legge da solo. Potresti vederlo emergere in due punti:

1. L'agente dice "re-snapshot" o "istantanea della pagina", il che significa che ha rilevato una modifica e sta rileggendo lo stato corrente.
2. Il risultato dell'attività include un estratto di un'istantanea come prova.

Scrittura di un'attività per l'agente

Un'istantanea aiuta l'agente a vedere chiaramente la pagina, ma i limiti dell'attività spettano a te. Una buona descrizione dell'attività dice all'agente:

• La pagina o il sito di destinazione.
• Cosa leggere, compilare, cliccare o scaricare.
• Cosa non deve fare (cancellare, pubblicare, pagare, inviare mail, ecc.).
• Se mettere in pausa sulle schermate captcha, pagamento o autorizzazione.
• La forma del risultato desiderato (tabella, riepilogo, screenshot, percorso del file locale).

Esempi:

Open my GitHub Notifications and list the PRs that need my review — repo name, title, URL.
Don't archive, don't mark anything as read.

Open the orders dashboard, filter yesterday's orders, and download the CSV.
Pause if you hit a login challenge or an export confirmation, and tell me where the file landed.

Rivedere ciò che ha fatto l'agente

Una volta terminato il compito, questi sono i segnali da controllare:

• L'agente ha dichiarato quali pagine ha visitato e le azioni chiave intraprese?
• Il risultato restituito include elementi che puoi verificare (titoli, ID, URL, importi, timestamp)?
• Per un download, ti ha fornito il percorso del file locale?
• Per tutto ciò che modifica o invia, è stata effettuata una pausa per la conferma prima del passaggio finale?
• Le pagine pertinenti sono ancora aperte in Space per poterle controllare?

Se qualcosa sembra strano, chiedi all'agente di ri-istantanare la pagina corrente invece di continuare a estrapolare dalla risposta precedente.

Domande comuni

Perché l'agente dice che un riferimento non è valido?

La pagina è cambiata dopo lo snapshot precedente. Chiedigli di prenderne uno nuovo.

Un'istantanea può leggere tutto?

Non sempre. I contenuti fuori schermo, il testo all'interno delle immagini, le tele complesse e gli iframe multiorigine sandbox potrebbero non essere visualizzati completamente. In questi casi l'agente potrebbe combinare istantanee con screenshot, estrazione di testo o conferma manuale.

Fare uno snapshot cambia qualcosa nella pagina?

No. Uno snapshot legge solo la struttura della pagina. I clic, i riempimenti, gli invii, i caricamenti e le eliminazioni che si verificano dopo sono ciò che effettivamente modifica lo stato.

Devo ricordare @1 o @2?

No. Trattali come numeri temporanei per la pagina corrente. L'agente li usa; sei tu a fissare l'obiettivo e i limiti.