Come dare agli agent AI un percorso strutturato attraverso la tua app

Perché gli agent AI hanno bisogno di un percorso diverso attraverso la tua app?

Una quota crescente delle richieste alla tua application arriva da agent AI: assistenti che recuperano documentazione per un utente, strumenti di ricerca che leggono pagine prodotto, workflow autonomi che chiamano la tua API. La maggior parte di loro opera attraverso interfacce progettate per le persone. Scaricano pagine HTML complete, analizzano i layout, seguono una navigazione pensata per il mouse e riprovano quando una pagina molto ricca di script non si rende come si aspettano.

Questo è inefficiente per tutti. Gli agent ricevono contenuti rumorosi e commettono errori. I tuoi server spendono risorse per renderizzare pagine che nessuno guarda. E il traffico è difficile da interpretare, perché sembra un browser che si comporta in modo anomalo. Se non sei ancora sicuro di quanta parte del tuo traffico sia questo, inizia con come capire se il traffico del sito web proviene da agent AI.

Un approccio migliore è dare agli agent un percorso strutturato: contenuti e azioni in formati costruiti per i programmi, individuabili in punti standard, con limiti che premiano i client che si identificano correttamente. Questa guida mostra come farlo senza costruire una seconda application.

Passo 1: Decidi cosa gli agent dovrebbero poter fare

Inizia dall'intento, non dalla tecnologia. Osserva le route in cui vedi già traffico di agent e raggruppale:

• Leggere contenuti: documentazione, informazioni di prodotto, pagine prezzi, articoli di supporto, profili pubblici.
• Interrogare dati: ricerca, consultazione di cataloghi, disponibilità, stato.
• Eseguire azioni: creare, aggiornare o eliminare qualcosa per conto di un utente.

La lettura e l'interrogazione sono buone candidate per un percorso strutturato aperto a qualsiasi client che si comporti correttamente. Le azioni richiedono autenticazione e autorizzazione indipendentemente da come il client si identifica, e sono trattate nella guida sulla protezione delle azioni sensibili.

Passo 2: Offri formati adatti alle macchine

Per le route di contenuto, offri le stesse informazioni senza la cornice della pagina. Due formati coprono la maggior parte delle esigenze:

• Markdown per contenuti discorsivi come documentazione e articoli, servito con il tipo MIME text/markdown registrato in RFC 7763. Mantiene titoli, elenchi, link e blocchi di codice, ed è compatto.
• JSON per record strutturati come prodotti, piani o stato.

Usa la content negotiation così l'URL resta lo stesso e il client chiede il formato che desidera:

import express from "express";

const app = express();

app.get("/docs/:slug", async (req, res) => {
  const doc = await loadDoc(req.params.slug);
  if (!doc) return res.status(404).end();

  res.vary("Accept");
  const preferred = req.accepts(["text/html", "text/markdown", "application/json"]);

  if (preferred === "text/markdown") {
    return res.type("text/markdown; charset=utf-8").send(doc.markdown);
  }
  if (preferred === "application/json") {
    return res.json({ title: doc.title, updatedAt: doc.updatedAt, body: doc.markdown });
  }
  return res.render("doc", { doc });
});

Invia un header Vary: Accept (RFC 9110 su Vary) in modo che le cache archivino ogni rappresentazione separatamente. Molti team espongono anche un URL alternativo esplicito, per esempio aggiungendo .md a un percorso di documentazione, perché per alcuni client questo è più semplice della negoziazione. Collegalo dalla pagina HTML con <link rel="alternate" type="text/markdown" href="..."> così può essere individuato. Link tipizzati come questo seguono il modello Web Linking.

Passo 3: Come fanno gli agent a scoprire il tuo percorso strutturato?

Gli agent non possono usare ciò che non riescono a trovare. Pubblica i punti di ingresso nei luoghi in cui i client automatizzati già guardano:

1. /llms.txt alla root del sito: un breve riepilogo in Markdown di ciò che offre il tuo sito con i link alle pagine più utili e alle loro versioni strutturate, seguendo la proposta llms.txt.
2. Una descrizione della API come un documento OpenAPI, collegato dalla tua documentazione per sviluppatori e da /llms.txt.
3. Link alternativi nelle pagine HTML che puntano alle versioni Markdown o JSON.
4. Una sitemap che elenca i tuoi URL di contenuto canonici, nel formato definito dal protocollo Sitemaps.

Un llms.txt minimo:

# Example App

> Example App helps teams plan projects. This file lists the best entry points for automated clients.

## Docs
- [Getting started](https://example.com/docs/getting-started.md): setup in five steps
- [API reference](https://example.com/openapi.json): OpenAPI description of the public API

## Policies
- [Automated access](https://example.com/docs/automated-access.md): limits and how to sign requests

Mantieni una pagina che spieghi le tue regole per i client automatizzati: quali route sono aperte, quali limiti si applicano e come un client può identificarsi con richieste firmate per ricevere un trattamento migliore. Regole chiare trasformano l'ipotesi in cooperazione.

Passo 4: Instrada per classe di attore, non per user agent string

Una volta che hai risposte strutturate, decidi chi le riceve per default. Usa la classe di attore e la sua base invece di analizzare ad hoc le user agent string. Gli operatori AI pubblicano i loro user agent, come fanno OpenAI e Anthropic per i loro crawler e fetcher, ma una corrispondenza di stringa è comunque solo una dichiarazione.

type ActorClass = "human" | "human_ai" | "agent" | "unknown";
type Basis = "verified" | "declared" | "inferred" | "unknown";

function preferStructured(actor: ActorClass, basis: Basis, accept: string): boolean {
  if (accept.includes("text/markdown") || accept.includes("application/json")) return true;
  return actor === "agent" && (basis === "verified" || basis === "declared");
}

Due principi mantengono questo approccio sicuro:

• Le richieste esplicite vincono sempre. Se un client chiede Markdown o JSON, servilo, qualunque sia la classe.
• I default non tolgono nulla. Un visitatore Human o Unknown riceve sempre la pagina completa. Scegliere un default strutturato per gli agent cambia il formato, non ciò che sono autorizzati a vedere.

Passo 5: Quali limiti di velocità dovrebbero avere gli agent AI?

I limiti di velocità sono il punto in cui il contesto dell'attore dà il massimo vantaggio in modo visibile. Invece di un solo limite per tutti, assegna a ogni combinazione di classe e base un budget sensato:

Associa il limite all'identificatore più stabile disponibile. Per gli agent verificati, questo è l'origine dell'operatore e l'identificatore della chiave. Per gli altri, usa il credential o un key a livello di rete.

function limitKey(actor: { actor: ActorClass; basis: Basis; operator?: string }, ip: string, apiKey?: string) {
  if (actor.actor === "agent" && actor.basis === "verified" && actor.operator) return `op:${actor.operator}`;
  if (apiKey) return `key:${apiKey}`;
  return `ip:${ip}`;
}

function limitFor(actor: { actor: ActorClass; basis: Basis }): number {
  if (actor.actor === "agent" && actor.basis === "verified") return 600;
  return 120;
}

I numeri sono segnaposto. Imposta i tuoi a partire dalla baseline che hai osservato. Quando un client supera un limite, restituisci 429 Too Many Requests con un header Retry-After e un link alla tua pagina di accesso automatizzato. Gli agent ben costruiti rallentano e lo leggono.

Passo 6: Tieni le azioni dietro l'autorizzazione

Un percorso strutturato per la lettura non è un percorso che aggira il tuo modello di sicurezza. Qualsiasi azione che modifica i dati richiede ancora:

1. autenticazione con un credential emesso dalla tua application,
2. autorizzazione per quella specifica azione, e
3. eventuali controlli aggiuntivi richiesti dalla fascia di rischio della route.

Una firma verificata ti dice quale client sta chiamando. Non ti dice che il client possa agire per conto di un determinato utente. Tieni separate queste domande. Il nostro post su cosa dimostrano le richieste firmate degli agent AI spiega la differenza.

Passo 7: Misura l'effetto

Esegui il percorso strutturato prima in modalità di osservazione, poi confronta:

• la quota di richieste degli agent che usa formati strutturati,
• il costo del server e la latenza per il traffico degli agent prima e dopo,
• i tassi di errore e di retry per i client agent,
• quanti client automatizzati passano da Declared a Verified una volta pubblicate le tue indicazioni sulla firma.

Questi numeri mostrano se il percorso strutturato sta facendo il suo lavoro e dove estenderlo in seguito.

Passo 8: Versiona e documenta il percorso strutturato

Tratta il percorso strutturato come un'interfaccia pubblica, perché gli agent costruiranno su di esso. Alcune abitudini lo rendono affidabile:

1. Mantieni stabili gli URL. Se un agent ha imparato che /docs/getting-started.md esiste, dovrebbe continuare a funzionare. Quando un contenuto si sposta, restituisci un 301 verso la nuova posizione invece di un 404.
2. Includi gli orari di aggiornamento. Inserisci un campo updatedAt nelle risposte JSON e un header Last-Modified sul Markdown, così gli agent possono fare caching in modo sensato e aggiornare solo quando qualcosa cambia.
3. Supporta le conditional requests. Rispondi a If-None-Match e If-Modified-Since con 304 Not Modified. Gli agent che interrogano periodicamente i tuoi contenuti costano molto meno quando possono fare revalidazione invece di riscaricare tutto da capo.
4. Versiona i cambiamenti che rompono la compatibilità. Se una forma JSON deve cambiare, aggiungi un nuovo percorso di versione o un nuovo media type e mantieni quello vecchio per un periodo pubblicato.
5. Pubblica un changelog per la pagina di accesso automatizzato. Gli operatori di agent ben comportati lo leggono, e ti offre uno spazio per annunciare nuove route strutturate.

app.get("/api/plans", async (req, res) => {
  const plans = await loadPlans();
  const etag = `"${plans.version}"`;
  res.set("ETag", etag);
  res.set("Cache-Control", "public, max-age=300");
  if (req.get("if-none-match") === etag) return res.status(304).end();
  return res.json({ updatedAt: plans.updatedAt, plans: plans.items });
});

Queste pratiche beneficiano anche il tuo frontend e le integrazioni con partner. Un percorso strutturato stabile, cacheable e documentato diventa rapidamente il modo più semplice per qualsiasi programma di lavorare con la tua application.

Errori comuni

• Servire fatti diversi agli agent e alle persone. La versione strutturata dovrebbe contenere le stesse informazioni della pagina. Contenuti divergenti confondono gli utenti che chiedono a un assistente informazioni sul tuo prodotto.
• Nascondere il percorso strutturato. Se non è collegato da /llms.txt, dai tuoi API docs o dalle pagine stesse, gli agent continueranno a fare scraping dell'HTML.
• Premiare le dichiarazioni. Limiti più alti spettano ai client verificati. Una user agent string copiata non dovrebbe ottenere un budget maggiore.
• Dimenticare le cache. Senza Vary: Accept, una cache può servire Markdown a un browser.

Dove si inserisce Proof of Actor

Proof of Actor ti fornisce la classe di attore e la base di cui hai bisogno per instradare gli agent verso contenuti strutturati e impostare limiti equi. Rileva agent firmati, dichiarati e inferiti, ti aiuta a capire come usano le tue route e lascia la decisione di routing nel tuo codice.

Per progettare un percorso strutturato per la tua application con il nostro team, richiedi l'accesso anticipato. Per scenari API e MCP in particolare, vedi APIs e MCP Servers, e leggi chi sta chiamando il tuo MCP server? per capire come il contesto dell'attore si applica alle chiamate tool di Model Context Protocol.

Fonti

• RFC 9110: HTTP Semantics: content negotiation (Sezione 12), Vary (Sezione 12.5.5), conditional requests (Sezione 13) e Retry-After (Sezione 10.2.3)
• RFC 7763: The text/markdown Media Type: serving Markdown representations
• RFC 8288: Web Linking: link alternate tipizzati
• RFC 6585: Additional HTTP Status Codes, Section 4: 429 Too Many Requests
• proposta llms.txt: il formato file /llms.txt
• OpenAPI Specification: descrizioni API leggibili dalle macchine
• protocollo Sitemaps: formato file sitemap
• OpenAI: Overview of OpenAI Crawlers: user agent e intervalli IP pubblicati da OpenAI
• Anthropic: crawler and fetcher documentation: ClaudeBot, Claude-User e Claude-SearchBot
• Model Context Protocol specification (2026-07-28): la revisione corrente di MCP a novembre 2026