agents.md e llms.txt: cosa va in ciascuno e perché uno solo non basta

llms.txt dice a un agente IA cosa è vero riguardo al vostro negozio. agents.md gli dice cosa farne. Pubblicarne uno senza l'altro è la mezza misura più comune nella preparazione agli agenti — ed è la lacuna che il nostro stesso scanner segnala più spesso, incluso, a un certo punto, su due dei nostri siti. Questa guida illustra cosa appartiene a ciascun file, in cosa differiscono e come scrivere un agents.md che sopravviva al contatto con un assistente reale.

Due file, due compiti

llms.txt è una scheda di fatti. Risponde a «cos'è questa azienda, cosa vende, quali sono le condizioni» in una forma che un assistente può citare senza scandagliare venti pagine. Frasi dichiarative brevi, nessun tono da marketing, link alle pagine che contengono i dettagli. Se un modello dirà qualcosa su di voi in una risposta, è qui che deve prendere la formulazione.

agents.md è una nota operativa. Risponde a «sei un agente davanti a questo negozio — ecco come lavorarci»: dove stanno i fatti canonici, quali sono le regole d'ingaggio, cosa non dare per scontato e chi contattare. È più vicino a un README per macchine che a una pagina di marketing.

La distinzione conta perché gli assistenti li usano in modo diverso. Una fase di retrieval vuole fatti citabili; un agente che pianifica azioni vuole vincoli e riferimenti. Fondere i due in un unico file significa dare a uno dei due pubblici un documento che non serve al suo scopo.

Cosa va in llms.txt

Limitatevi a ciò che sareste disposti a vedere citato alla lettera, perché succederà:

• Cos'è l'azienda, in una o due frasi, incluso ciò che non fa. Le affermazioni negative hanno un valore insolito: sono quelle che impediscono a un modello di inventare funzionalità.
• I fatti commerciali: prezzi con cifre reali e valuta, nomi dei piani, durata della prova, cosa è gratuito.
• Le condizioni che incidono su una decisione d'acquisto: aree di spedizione, termini di reso, garanzia, trattamento dei dati se è un elemento distintivo.
• Link alle pagine che sostengono ogni affermazione, così un modello che vuole verificare può farlo.
• Date e cifre facili da sbagliare. Se il vostro mercato ha una scadenza normativa o una soglia, indicatela con precisione. Gli assistenti le citano male continuamente, e una formulazione chiara nelle vostre parole è la correzione più economica disponibile.

Evitate aggettivi senza sostanza. «Leader di settore» non è citabile; «elabora gli ordini nell'UE (AWS Francoforte)» è un fatto che un modello può usare.

Cosa va in agents.md

Una struttura che funziona, più o meno in questo ordine:

1. Orientamento. Un paragrafo: che sito è, chi lo gestisce e la risposta breve a «cosa fa» — così un agente che legge solo le prime righe ha comunque la parte importante corretta.
2. Dove stanno i fatti. Una mappa: llms.txt per il riassunto, quale pagina porta i prezzi, quale le condizioni, quale i dettagli tecnici. Percorsi assoluti, non «vedi il nostro sito».
3. Ciò che viene citato male. Se nel vostro settore esiste un fatto che persone e modelli sbagliano regolarmente, correggetelo qui esplicitamente. È la sezione di maggior valore e quasi nessuno la scrive.
4. Regole d'ingaggio. Cosa possono fare gli agenti — leggere il catalogo, citare prezzi, rimandare a un prodotto — e cosa richiede una persona: effettuare un ordine, accettare condizioni, qualsiasi cosa con un pagamento. Indicate anche i limiti onesti di ciò a cui il sito può rispondere.
5. Contatto. Un indirizzo che una persona legge.

Scrivetelo in prosa semplice. Non c'è alcuno schema da soddisfare né parser da compiacere — il destinatario è un modello linguistico, e frasi chiare battono una sintassi inventata.

Dove vanno i file, e perché su Shopify la collocazione fallisce

Entrambi appartengono alla radice del dominio: /llms.txt e /agents.md. Non in una sottocartella, non dietro una catena di redirect, non su un host diverso dal negozio.

Su Shopify è proprio questa la parte che si rompe. Un tema può servire file arbitrari a percorsi strani, ma la radice di un dominio Shopify non è un posto in cui si depositi semplicemente un file — perciò i negozi finiscono con il contenuto in /pages/llms-txt e nulla alla radice. Un agente che controlla la posizione convenzionale trova un 404 e va oltre; tanto valeva che il contenuto non esistesse.

L'approccio praticabile è un redirect dal percorso radice a dove il contenuto vive davvero, così che una richiesta a /llms.txt si risolva. Sichta genera entrambi i file dal vostro catalogo e dalle vostre condizioni in tempo reale e imposta quei redirect alla radice — la metà noiosa del lavoro.

Mantenerli veri

Un llms.txt obsoleto è peggio di nessun llms.txt: avete consegnato a un modello una formulazione sicura e sbagliata, invitandolo a ripeterla. Due derive da tenere d'occhio:

• I prezzi cambiano. Se il vostro llms.txt indica cifre, va rigenerato quando quelle cifre cambiano. Tutto ciò che è mantenuto a mano prima o poi mente.
• Le funzionalità cambiano. Una funzione rimossa resta nel file, e i modelli continuano a proporla ai clienti a vostro nome.

Generare entrambi i file dalla fonte di verità — il catalogo, il listino reale, le pagine delle condizioni reali — è ciò che rende il tutto sostenibile. Scriverli a mano va bene per un lancio e diventa ingestibile al terzo cambio di prezzo.

Come verificare che funzioni davvero

Tre controlli, in ordine di frequenza dei fallimenti:

• Scaricate le URL con un client semplice. curl https://tuonegozio.it/llms.txt deve restituire 200 e il contenuto — non un redirect a una pagina 404 grafica e non HTML.
• Verificate che esistano entrambi. Uno senza l'altro è esattamente la lacuna di cui parla questa guida.
• Controllate che il vostro robots.txt non blocchi i crawler IA che volete leggano quei file. Pubblicare i file e vietare gli agenti che li leggono è una combinazione sorprendentemente comune.

Sichta esegue questi controlli come parte del pilastro A e segnala ciascuno separatamente, così «llms.txt presente, agents.md mancante» torna come un rilievo preciso e non come un punteggio da interpretare.

In breve

llms.txt sono i fatti, agents.md sono le istruzioni d'uso — pubblicateli entrambi, alla radice del dominio, raggiungibili da un semplice client HTTP. Concentrate lo sforzo sulle affermazioni negative e sui dettagli citati male più spesso, perché è lì che la risposta predefinita di un modello su di voi ha più probabilità di essere sbagliata. Generateli entrambi dai dati reali perché restino veri, e verificate che robots.txt lasci davvero leggere gli agenti che vi interessano.