Dalla leggibilità per modelli vision al WebMCP: passi pratici per rendere le interazioni più veloci, affidabili e debuggabili.
Perché “agent-ready” non significa “web separato”
Quando si parla di agentic web è facile immaginare un “nuovo web”. In realtà è più utile vederla come un’evoluzione del web attuale: le persone continuano a leggere contenuti, acquistare, prenotare, gestire account… ma sempre più spesso lo fanno delegando parti del flusso a un agente AI.
Gli agenti possono presentarsi in varie forme:
- On-site: integrati direttamente nell’esperienza del sito.
- Browser agent: nativi del browser o forniti tramite estensioni.
- Off-browser: tool esterni (anche CLI) che guidano il browser tramite protocolli come CDP.
Qui ci concentriamo sul caso più “vicino” al frontend quotidiano: agenti che operano nel browser e devono capire rapidamente cosa mostra la pagina e quali azioni sono possibili.
Come un agente “vede” davvero il tuo sito
Un agente non interpreta una pagina come un umano in modo magico: raccoglie segnali e li combina. In pratica, i canali principali sono tre.
1) Screenshot + modello vision
L’agente può acquisire screenshot della pagina renderizzata e usare un modello multimodale per interpretare layout e contenuti visivi. Questo funziona, ma è costoso (in contesto e computazione) e può essere fragile con UI dense o poco consistenti.
2) DOM renderizzato
Il DOM fornisce struttura: gerarchie, nesting, vicinanze. Un bottone dentro una sezione o un form con campi etichettati correttamente “racconta” molto più di una griglia di div.
In più, il testo reale è un segnale chiave:
- il contenuto di un
<button>suggerisce l’azione - titoli e label aiutano a capire cosa è primario/secondario
3) Accessibility Tree
È la distillazione semantica che il browser espone (ruoli, nomi accessibili, stati). È anche ciò che usano gli screen reader.
Qui c’è un punto importante: migliorare accessibilità e semantica aiuta contemporaneamente umani e agenti. Non è un compromesso, è un allineamento.
Il problema: più complesso è il journey, più cresce il “contesto”
Nei flussi reali (prenotazioni, e-commerce, configuratori, onboarding) l’agente deve:
- mantenere memoria di scelte precedenti
- interpretare passaggi intermedi e stati UI
- distinguere varianti simili (es. “modifica testo” vs “cambia stato”)
Più cresce la complessità, più l’agente deve sintetizzare screenshot, DOM e accessibility tree. Questo comporta:
- maggiore latenza (più contesto, più ragionamento)
- maggiore probabilità di errore (segnali ambigui → svolte sbagliate)
Serve quindi un modo per rendere l’interazione più diretta e meno ambigua.
WebMCP: esporre “tool” strutturati direttamente dalle pagine
L’idea chiave di WebMCP (proposta di standard) è semplice: oltre a “capire” la UI, un agente dovrebbe poter invocare azioni strutturate esposte dal sito.
Esempio concettuale:
- invece di dedurre quale campo compilare e quale bottone premere per “prenotare un tavolo”,
- l’agente può chiamare un tool tipo
bookTable({name, date, time, partySize, notes}).
Risultato: flussi più veloci, più affidabili, più debuggabili.
Il punto interessante è che questi tool non “sostituiscono” la UI: la affiancano come API di intent per gli agenti.
Definire tool: approccio imperativo (JavaScript)
Nel modello imperativo registri un tool via API, fornendo:
- name: nome stabile e specifico
- description: quando usarlo
- input schema: parametri in JSON Schema
- execute: funzione che esegue davvero l’azione
Un aspetto spesso sottovalutato: il valore di ritorno di execute è un canale di comunicazione verso l’agente, non verso l’utente. Puoi usarlo per:
- segnalare errori di validazione sui parametri
- indicare success/failure
- suggerire “next step” (es. “serve conferma utente”)
Lifecycle e cleanup
Se l’esistenza del tool dipende dallo stato della pagina o dal ciclo di vita di un componente, puoi gestirne la rimozione con un AbortController. Questo è particolarmente utile nei framework (es. cleanup su onDestroy).
Definire tool: approccio dichiarativo (HTML form)
Se hai già form “classici”, l’approccio dichiarativo è spesso il più economico.
Bastano due attributi richiesti sul form:
toolnametooldescription
In più, puoi aggiungere descrizioni per i parametri (opzionale ma molto utile) per chiarire cosa inserire nei campi.
Tool description = contesto operativo (non “commenti”)
Naming e descrizioni non sono un dettaglio: sono parte dell’informazione che l’agente usa per decidere quale tool invocare e con quali parametri. In pratica è una forma di “prompting strutturato” incorporato nel markup.
Autosubmit e controllo utente
Per default, un tool basato su form tende a:
- far compilare i campi all’agente
- richiedere il click dell’utente per il submit
Se vuoi consentire il submit automatico, entra in gioco un attributo tipo toolautosubmit.
Riconoscere submit invocati da agente
Nel submit event compare un nuovo membro come agentInvoked per distinguere:
- submit dell’utente
- submit attivato dall’agente
Questo ti permette di:
- applicare validazioni e regole dedicate
- rispondere con messaggi mirati verso l’agente (es. spiegare perché un input è invalido)
Debug: DevTools e strumenti come per qualunque JS
Un vantaggio pratico dei tool WebMCP è che si debuggano come codice web normale:
- puoi vedere quali tool vengono chiamati
- con quali input
- e cosa viene restituito come output
E se un tool è implementato in JavaScript, puoi:
- saltare al punto di registrazione
- mettere breakpoint
- ispezionare stato e parametri
Questo sposta l’esperienza da “l’agente ha sbagliato qualcosa” a “ho una traccia riproducibile di input/output e posso correggere tool, schema o descrizioni”.
Linee guida concrete per rendere un sito più “agent-ready”
1) Parti dai fondamentali: UI leggibile, HTML semantico, accessibilità solida. Migliora subito anche l’esperienza umana.
2) Individua i punti ad alto attrito nei journey (ricerche complesse, configuratori, checkout, prenotazioni) e valuta dove un tool riduce ambiguità.
3) Progetta tool piccoli e specifici: “toggle status” non è “edit text”. Evita tool “fai tutto” che aumentano errori.
4) Scrivi descrizioni operative (name/description/param description): devono aiutare un agente a scegliere correttamente, non essere marketing.
5) Usa JSON Schema con cura: tipi, enum, required, vincoli. Più lo schema è preciso, meno l’agente deve indovinare.
6) Restituisci output utili: messaggi di errore strutturati, motivazioni, suggerimenti di correzione.
Sintesi: la via più breve verso interazioni affidabili
Rendere un sito “agent-ready” non significa inseguire un trend: significa ridurre ambiguità e rendere esplicite le azioni. Prima ancora dei tool, vincono semantica e accessibilità perché migliorano i tre canali chiave (visivo, DOM, accessibility tree). Quando i flussi diventano complessi, però, i tool strutturati stile WebMCP possono fare la differenza: meno contesto da interpretare, meno errori, più controllo e debugging.
L’implicazione pratica per chi fa frontend oggi è chiara: progettare UI e API di intent insieme, dove la UI serve l’utente e i tool aiutano l’agente a non “indovinare”.
Articolo originale: https://frontendfacile.it/blog/siti-agent-ready-come-preparare-il-frontend-a-browser-agent-e-strumenti-struttur
Top comments (0)