Sito AI-friendly: azioni chiare per gli agenti con WebMCP
Come rendere un sito usabile anche dagli agenti AI senza perdere il controllo? Azioni strutturate, conferme umane, sicurezza e un primo passo verso WebMCP.
Un sito oggi deve essere facile da usare per le persone e, sempre più spesso, anche per gli agenti AI. Qui vedi come scegliere le poche azioni giuste, descriverle in modo che un agente le capisca e proteggerle. Il primo passo, la mappa delle azioni, puoi farlo oggi con il prompt qui sotto.
Cos'è
Un sito AI-friendly tiene la sua normale interfaccia, ma le affianca un livello di azioni strutturate: cercare un prodotto, verificare una disponibilità, vedere lo stato di un ordine, preparare una richiesta. Ogni azione ha un nome chiaro, parametri descritti, risultati prevedibili, errori leggibili, permessi espliciti e, quando serve, una conferma umana.
WebMCP è una proposta nata nell'ecosistema Web Machine Learning per permettere alle pagine web di esporre strumenti che gli agenti possono scoprire e usare. Progetto e documentazione sono ancora in evoluzione. Non è una garanzia di compatibilità ovunque, e non sostituisce API, accessibilità e interfaccia normale.
Perché serve
Senza azioni dichiarate, un agente deve interpretare ogni elemento della pagina, cliccare alla cieca e sperare che il pulsante giusto non sia quello accanto.
Non vuol dire trasformare la homepage in un robot o aggiungere un chatbot perché "ce l'hanno tutti". Vuol dire rendere esplicito quello che un utente, o un agente autorizzato, deve poter fare.
C'è anche un vantaggio per le persone. Descrivere un'azione con input, output e permessi costringe il team a chiarire processi, stati, errori e responsabilità. Se un flusso di lavoro non si riesce a descrivere così, probabilmente non è chiaro nemmeno per l'azienda.
Il punto di partenza non è il modello. È il processo.
Come si fa
- Parti da un flusso reale. Non da "aggiungiamo WebMCP". Scegli un'azione frequente e misurabile: trovare un prodotto, rispondere a una richiesta. Guarda quali richieste arrivano, quali dati servono e dove il lavoro si blocca.
- Scegli poche azioni di valore. Non esporre tutto solo perché puoi.
- Disegna il contratto di ogni azione. Nome, descrizione, parametri obbligatori, errori e formato del risultato. Una funzione, uno scopo. Niente funzioni generiche tipo "fai_tutto".
- Separa lettura e scrittura. Consultare un ordine non è come modificarlo.
- Valida sul server. Lo schema aiuta l'agente, ma non è una misura di sicurezza. Ricontrolla tipi, permessi, proprietà del dato e limiti nel backend (la parte del sito che gira sul server).
- Registra e chiedi conferma. Per ogni azione importante registra chi l'ha fatta, con quale identità, su quali dati e con quale risultato. Ricerca e anteprima possono essere automatiche. Invio, acquisto, cancellazione e modifiche irreversibili hanno bisogno di una barriera chiara.
- Tieni il piano B. Se WebMCP non c'è, il sito deve funzionare lo stesso con l'interfaccia, le API o un'automazione compatibile.
- Prova il comportamento. Anche un agente molto sicuro di sé può sbagliare con grande entusiasmo.
Un esempio: e-commerce B2B. Oggi un operatore cerca un prodotto, controlla la disponibilità, verifica le condizioni riservate al cliente e prepara una bozza d'offerta. Il sito può esporre quattro azioni separate:
- search_products (query, categoria): cerca i prodotti, solo lettura.
- get_product_availability (id prodotto): controlla la disponibilità, solo lettura.
- get_customer_terms (id cliente): legge le condizioni del cliente, solo lettura.
- prepare_quote (articoli, id cliente): crea una bozza d'offerta. L'invio richiede la conferma dell'operatore.
Il vantaggio non è solo la velocità. Il processo diventa più esplicito, si può testare e si collega più facilmente ad altri strumenti.
Pronto da copiare, per fare la mappa delle azioni con Claude o ChatGPT:
Ti descrivo un processo della mia azienda che passa dal nostro sito: [descrivi in 5-10 righe chi lo fa, cosa cerca, quali dati usa, dove si blocca]. Aiutami a progettare le azioni che un agente AI autorizzato potrebbe usare. Regole: 1. Proponi al massimo 5 azioni, solo quelle con più valore. 2. Per ognuna scrivi: nome in inglese tipo verbo_oggetto, descrizione di una riga, parametri obbligatori con tipo, formato del risultato, errori possibili. 3. Segna ogni azione come LETTURA o SCRITTURA. 4. Per ogni azione di scrittura indica quale conferma umana serve prima di eseguirla. 5. Dimmi cosa va registrato nel log (chi, con quale identità, su quali dati, con quale risultato). 6. Se il processo non è abbastanza chiaro per descriverlo così, fammi le domande che mancano invece di inventare.
Per chi usa un agente di programmazione, un secondo prompt per il primo strumento:
Aggiungi al sito un solo strumento WebMCP: search_products, con parametro obbligatorio query di tipo stringa. Prima controlla la sintassi nella documentazione ufficiale (https://webmachinelearning.github.io/webmcp/) perché la proposta cambia. Registra lo strumento solo se il browser supporta navigator.modelContext, altrimenti non fare niente: il sito deve funzionare uguale. La funzione deve chiamare la ricerca che esiste già sul server, che resta l'unico posto dove si validano input, permessi e limiti. Non aggiungere azioni di scrittura. Alla fine dimmi come provarlo.
Questo strumento non sostituisce autenticazione, autorizzazione e validazione. È il bordo visibile di un sistema da progettare con la stessa cura di un'API pubblica.
Prova piccola
Dieci minuti. Prendi il processo più frequente che passa dal tuo sito e incolla il primo prompt. È riuscita se ottieni al massimo cinque azioni, ognuna con nome, parametri e risultato, e se sai dire per ognuna se legge o scrive. Se l'AI ti fa domande a cui non sai rispondere, hai trovato il punto del processo da chiarire prima di tutto il resto.
Attenzione a
- WebMCP è ancora una proposta. La sintassi esatta va verificata sulla versione supportata dal browser o dall'SDK che usi. Non promettere ai clienti una compatibilità che oggi non c'è.
- Lo schema non protegge niente. La sicurezza sta sul server: permessi, proprietà dei dati, limiti.
- Ogni azione di scrittura ha bisogno di una barriera. Invio, acquisto e cancellazione passano da una persona.
- Poche azioni, non tutte. La parte difficile non è aggiungere un altro strumento. È decidere quali azioni meritano davvero di essere semplici.
Fonti: WebMCP, progetto ufficiale, WebMCP, documentazione, OpenTiny WebMCP SDK, skill per webmcp-cli.
Passo successivo: prima di toccare il sito, verifica se il processo è pronto con l'audit AI per PMI. Per dare all'agente permessi e controlli giusti, leggi Workspace per agenti AI.
In breve: Un sito AI-friendly non lascia fare tutto a un agente: rende poche azioni utili chiare, strutturate e sicure, e lascia alle persone le decisioni che contano.
Newsletter
L'AI che funziona davvero, nella tua casella.
Le nuove pillole, gli strumenti che usiamo e quello che impariamo sui progetti. Poche mail, solo quando c’è qualcosa di utile.
