Snapshot

Snapshot, c'est la façon dont un agent lit une page web. Il transforme la page courante en texte structuré compact et attribue des numéros temporaires (@1, @2…) aux éléments actionnables — boutons, champs, liens. L'agent décide ensuite quoi faire à partir de ce snapshot, sans lire le HTML brut ni deviner des coordonnées d'écran.

Ce que ça résout

Pour une personne, une page web est une interface visuelle. Pour un agent, c'est des dizaines de milliers de tokens de HTML, de scripts, de styles et d'état dynamique. Refiler tout ça à un LLM coûte deux choses :

• Un coût en tokens élevé. Une page d'administration typique pèse 30 000 tokens, à relire avant chaque action.
• Trop de bruit. La plus grande partie du DOM (styles, scripts, nœuds cachés) n'a rien à voir avec la décision et brouille l'analyse.

Le snapshot s'appuie sur l'accessibility tree du navigateur — la vue sémantique que le navigateur tient à jour pour les lecteurs d'écran — et comprime la page en quelques centaines de tokens :

• Le titre de la page et l'URL courante.
• Le texte visible et la structure principale.
• Les éléments cliquables, remplissables et sélectionnables, avec leurs rôles et leurs noms.
• Un @N temporaire par élément interactif.

C'est largement assez pour décider quel bouton cliquer et quel champ remplir, sans HTML brut ni coordonnées d'écran.

Fonctionnement des refs @N

Chaque élément interactif du snapshot reçoit un numéro temporaire :

@1 [input]  "Rechercher"
@2 [button] "Envoyer"
@3 [link]   "Page suivante"

L'agent agit sur ces numéros, par exemple await click('@2').

@N n'est valable que pour le snapshot courant. Dès que la page change (navigation, rafraîchissement, dialogue, soumission de formulaire, changement d'onglet, re-render dynamique), les anciens numéros risquent de ne plus pointer nulle part. La règle saine : reprendre un snapshot après chaque changement, plutôt que de conserver un @N.

Si vous avez besoin d'une référence stable sur plusieurs étapes, utilisez le sélecteur loc=... que renvoie le snapshot, ou un sélecteur CSS direct. Voir ego-browser.

Quand vous croisez le snapshot

Dans la majorité des cas, vous n'y touchez pas — l'agent le lit tout seul. Vous le verrez surgir dans deux situations :

1. L'agent dit « nouveau snapshot » ou « snapshot de la page » : il a détecté un changement et veut relire l'état courant.
2. Le résultat de la tâche inclut un extrait de snapshot à titre de preuve.

Décrire une tâche à l'agent

Le snapshot aide l'agent à voir la page ; les limites de la tâche, c'est vous qui les posez. Une bonne description précise :

• La page ou le site cible.
• Ce qu'il faut lire, remplir, cliquer ou télécharger.
• Ce qu'il ne doit pas faire (supprimer, publier, payer, envoyer un e-mail…).
• S'il doit s'arrêter face à un captcha, un paiement ou une autorisation.
• La forme de la sortie attendue (tableau, résumé, capture d'écran, chemin local).

Exemples :

Ouvre mes GitHub Notifications, sors les PR qui attendent ma review : nom du dépôt, titre, lien.
Ne pas archiver, ne pas marquer comme lu.

Ouvre la page d'administration des commandes, filtre celles d'hier, télécharge le CSV.
Si tu tombes sur un login ou une confirmation d'export, arrête-toi et dis-moi où est le fichier.

Vérifier ce qu'a fait l'agent

Une fois la tâche terminée, ces signaux aident à juger :

• A-t-il indiqué les pages visitées et les actions clés ?
• Le résultat contient-il des éléments vérifiables (titres, identifiants, liens, montants, dates) ?
• Pour un téléchargement, donne-t-il le chemin local du fichier ?
• Pour une modification ou un envoi, s'est-il arrêté avant la confirmation finale ?
• La page reste-t-elle ouverte dans le Space pour qu'on puisse la consulter ?

Si le résultat ne sonne pas juste, demandez à l'agent de reprendre un snapshot de la page courante plutôt que de continuer à supposer à partir de sa réponse précédente.

Questions fréquentes

Pourquoi l'agent dit-il qu'une ref est invalide ?

La page a changé depuis le snapshot précédent. Demandez-lui d'en reprendre un.

Le snapshot lit-il tout le contenu ?

Pas toujours. Le contenu hors écran, le texte dans des images, les canvas complexes, les iframes cross-origin restreintes peuvent ne pas apparaître complètement. Dans ces cas, l'agent peut combiner snapshot et capture d'écran, extraction texte ou confirmation manuelle.

Le snapshot modifie-t-il quelque chose ?

Non. Le snapshot ne fait que lire la structure de la page. Ce sont les clics, remplissages, envois, uploads, suppressions qui suivent qui changent réellement l'état.

Dois-je retenir @1, @2 ?

Non. Considérez-les comme des numéros temporaires pour la page courante. L'agent s'en sert ; vous fixez l'objectif et les limites.