L’architettura dei servizi web sta attraversando una fase di profonda ridefinizione guidata dall’emergere degli agenti autonomi basati su Modelli di Linguaggio di Grandi Dimensioni (LLM).
Per oltre due decenni, il principio HATEOAS (Hypermedia as the Engine of Application State), vincolo fondamentale dell’architettura REST formalizzato da Roy Fielding e posizionato al livello 3 del Modello di Maturità di Richardson, è stato ampiamente ignorato o considerato un esercizio teorico privo di risvolti pratici per la maggior parte delle applicazioni commerciali.
La maggioranza degli sviluppatori ha storicamente preferito architetture di tipo Remote Procedure Call (RPC) su HTTP, veicolando JSON statico guidato da documentazione esterna come le specifiche OpenAPI o Swagger.
L’adozione diffusa degli agenti di intelligenza artificiale capaci di effettuare chiamate a strumenti esterni (tool calling) ha tuttavia evidenziato i limiti strutturali delle API JSON tradizionali.
L’interazione tra sistemi AI e API rigide genera criticità legate alla saturazione delle finestre di contesto degli LLM, all’ambiguità nella selezione dei tool e all’incapacità di gestire transizioni di stato dinamiche.
In questo scenario, HATEOAS si rivela un’architettura ideale per consumatori software dotati di capacità cognitive e di ragionamento, trasformando le API in ambienti navigabili in modo autonomo e contestuale.
Principi Fondamentali di HATEOAS e la Loro Evoluzione Storica
Il principio HATEOAS impone che un client interagisca con un’applicazione di rete interamente attraverso i controlli ipertestuali forniti dinamicamente dal server ad ogni risposta HTTP.
A differenza delle architetture tradizionali basate su contratti fissi, un client REST conforme a HATEOAS necessita esclusivamente di un punto di ingresso iniziale e della comprensione semantica del formato hypermedia utilizzato.
{
"accountId": "ACC-98765",
"balance": 1250.00,
"currency": "EUR",
"_links": {
"self": { "href": "/accounts/ACC-98765" },
"deposit": { "href": "/accounts/ACC-98765/deposits", "method": "POST" },
"withdraw": { "href": "/accounts/ACC-98765/withdrawals", "method": "POST" },
"transfer": { "href": "/accounts/ACC-98765/transfers", "method": "POST" }
}
}
Nel modello tradizionale, se un account di credito dovesse andare in scoperto, il server modificherebbe lo stato interno ma continuerebbe a restituire una struttura dati statica.
Spetterebbe al programmatore lato client implementare una logica condizionale per disabilitare le opzioni di prelievo ed esporre endpoint specifici per il rientro dal debito.
Un’applicazione HATEOAS sposta invece la macchina a stati dall’applicazione client alla risposta HTTP inviata dal server. Se il conto è in scoperto, la risposta elimina automaticamente il link per il prelievo e introduce nuovi controlli ipertestuali, consentendo al client di interagire unicamente con le opzioni legalmente disponibili al momento della richiesta.
Le ragioni dell’abbandono storico di HATEOAS da parte degli sviluppatori umani risiedono nella complessità di sviluppo, nella scarsità di librerie client dinamiche e nell’abitudine di integrare percorsi e flussi applicativi direttamente nel codice sorgente delle interfacce utente.
Tuttavia, l’emergere degli agenti AI elimina questa barriera: un LLM non necessita di codice precompilato per navigare una risorsa, ma agisce come un browser intelligente capace di interpretare il significato di un collegamento e decidere l’azione successiva in base all’obiettivo assegnato.
Le Criticità degli Agenti AI con le API JSON Tradizionali
L’architettura standard per l’integrazione degli LLM con i sistemi esterni si basa sull’invio di schemi JSON dettagliati all’interno del prompt di sistema.
Questo approccio presenta limiti strutturali primari durante la fase di esecuzione. Quando a un agente viene data la possibilità di accedere a decine o centinaia di endpoint API, l’aggiunta di tutti gli schemi OpenAPI necessari satura rapidamente la finestra di contesto del modello.
Ciò comporta un aumento esponenziale dei costi di inferenza, un incremento della latenza delle risposte e un degrado delle capacità ragionative dell’LLM, che fatica a isolare le informazioni pertinenti all’interno di definizioni estese.
Inoltre, i modelli linguistici selezionano gli strumenti mediante calcoli probabilistici basati sulle descrizioni testuali delle funzioni. Presentare a un LLM un elenco statico di strumenti senza informazioni sul loro stato operativo porta inevitabilmente a tentativi di chiamata di endpoint non validi per la fase corrente del processo aziendale.
Nelle API JSON tradizionali, l’agente conosce gli endpoint disponibili ma ignora se l’azione sia consentita in quel preciso istante temporale. Se un agente deve elaborare il reso di un ordine, il modello cercherà di chiamare l’endpoint di rimborso anche se l’ordine si trova in stato non pagato o annullato, ricevendo come risposta un errore HTTP che richiede ulteriori cicli di elaborazione per essere interpretato e risolto.
L’Architettura HATEOAS per la Soluzione dei Problemi degli Agenti AI
L’adozione di HATEOAS trasforma la modalità con cui gli agenti software interagiscono con i servizi aziendali, introducendo vantaggi determinanti nell’architettura complessiva. Riducendo l’esposizione degli strumenti al solo stato corrente, l’API limita l’insieme dei collegamenti e delle azioni restituiti nell’output JSON unicamente a quelli validi per la risorsa nello stato attuale.
Un ordine nello stato di attesa pagamento restituirà esclusivamente i link per effettuare il pagamento o per annullare l’ordine, omettendo opzioni non pertinenti come la spedizione o il rimborso.
Di conseguenza, l’agente riceve a runtime un sottoinsieme ristretto di strumenti tra cui scegliere, eliminando le invocazioni errate legate a uno stato applicativo non idoneo.
Le interazioni complesse degli agenti richiedono inoltre il mantenimento di un contesto accurato lungo tutta la sequenza operativa. Poiché ogni risposta ipermediale contiene i riferimenti per i passi successivi, l’agente accumula il risultato delle scelte precedenti senza dover memorizzare complessi grafi di dipendenza all’interno della memoria a lungo termine o del prompt.
La risposta dell’API stessa guida l’agente verso l’obiettivo finale, muovendo lo stato dell’agente attraverso la navigazione ipermediale.
Anche la gestione della sicurezza e dei permessi trae beneficio da questa struttura. La profilazione degli accessi viene riflessa direttamente nella presenza o assenza dei controlli ipertestuali.
Se un agente opera con credenziali aventi diritti limitati, il server omette i link associati ad azioni privilegiate nella risorsa restituita. L’agente non deve valutare complesse regole di autorizzazione a livello di codice, poiché l’impossibilità di compiere un’azione è rappresentata dall’assenza della relativa opzione nel payload.
Un’ulteriore dimostrazione dell’efficacia di questo modello è fornita dal framework GRAIL (Goal-Resolution through Affordance-Informed Logic) ideato da Mike Amundsen.
GRAIL consente a un agente di partire da un obiettivo di alto livello e di raggiungerlo tramite un ciclo ricorsivo di tentativo, rilevamento delle precondizioni mancanti, risoluzione e riprovazione. Quando l’agente tenta un’azione senza aver soddisfatto i requisiti previsti, il server risponde bloccando l’operazione e indicando le azioni correttive necessarie.
L’agente gestisce le azioni mancanti tramite una pila operativa LIFO (Last-In, First-Out), risolve i passaggi intermedi come l’autenticazione o il caricamento dati e infine riesegue l’azione principale. Questo approccio basato sul feedback dinamico dell’ambiente sostituisce la necessità di pianificazioni rigide predeterminate con una navigazione adattiva ed estremamente resiliente agli errori.
Analisi Comparativa dei Formati Hypermedia e delle Architetture
Per rendere un’API fruibile dagli agenti AI, la scelta del formato di rappresentazione dati gioca un ruolo centrale. I diversi formati ipermediali variano in base alla ricchezza informativa fornita in merito alle azioni eseguibili, ai metodi supportati e alla struttura dei parametri richiesti.
| Formato Hypermedia | Media Type | Gestione di Link (rel) | Supporto per Azioni e Form (Metodi, Campi) | Idoneità per Agenti Autonomi LLM |
| HAL (Hypertext Application Language) | application/hal+json | Elevata (_links, _embedded) | Bassa (definisce prevalentemente link di navigazione in lettura) | Media: Ottimale per la scoperta di risorse, ma richiede contesto esterno per definire le mutazioni di stato. |
| Siren | application/vnd.siren+json | Elevata (links, entities) | Molto Elevata (struttura actions completa di metodi, URI, tipi e campi) | Massima: Fornisce all’agente tutte le istruzioni per formulare richieste di mutazione prive di ambiguità. |
| HAL-Forms | application/prs.hal-forms+json | Elevata (_links) | Elevata (estende HAL integrando i template dei form e la validazione dei dati) | Alta: Arricchisce il modello HAL fornendo i dettagli sui metodi HTTP e sui parametri richiesti. |
| JSON-LD | application/ld+json | Elevata (@id, @context) | Media (orientato al collegamento con ontologie semantiche globali) | Alta: Indicato per contesti che richiedono elevata interoperabilità semantica e architetture RAG. |
| Collection+JSON | application/vnd.collection+json | Elevata (links, items) | Media (focalizzato su collezioni di dati e template di inserimento) | Media: Efficace per la gestione di elenchi e paginazioni, meno flessibile per processi complessi. |
Il confronto tra il modello tradizionale a contratti fissi e il modello guidato da hypermedia evidenzia sostanziali differenze operative nell’interazione con gli agenti intelligenti.
| Dimensione Operativa | API JSON Tradizionali (REST Livello 2 / OpenAPI) | API HATEOAS (REST Livello 3 / Hypermedia) |
| Occupazione della Finestra di Contesto | Elevata: L’agente deve caricare in memoria l’intera specifica OpenAPI con tutti gli endpoint dell’applicazione. | Minima: L’agente elabora unicamente le opzioni ipermediali restituite nella risposta corrente. |
| Tasso di Errore nelle Invocazioni | Elevato: L’agente rischia di chiamare strumenti non validi per lo stato attuale della risorsa. | Trascurabile: Vengono esposte esclusivamente le transizioni di stato legalmente eseguibili dal server. |
| Resilienza ai Cambiamenti del Backend | Bassa: La modifica di un percorso URL richiede l’aggiornamento della documentazione e delle istruzioni dell’agente. | Elevata: L’agente segue la relazione ipertestuale indipendentemente dalle variazioni della struttura URI. |
| Isolamento della Sicurezza | Richiede valutazioni complesse a livello di codice lato client per stabilire quali azioni mostrare. | Le azioni non autorizzate vengono rimosse dal payload alla radice in fase di generazione della risposta. |
Un esempio di risposta in formato Siren mostra chiaramente come un agente possa estrarre ed eseguire un’azione senza la necessità di consultare una documentazione esterna.
{
"class": [ "order" ],
"properties": {
"orderNumber": 42,
"itemCount": 3,
"totalAmount": 149.99,
"status": "pending_payment"
},
"actions": [
{
"name": "pay-order",
"title": "Paga Ordine",
"method": "POST",
"href": "https://api.store.example/orders/42/payments",
"type": "application/json",
"fields": [
{ "name": "paymentMethod", "type": "string", "value": "credit_card" },
{ "name": "token", "type": "string" }
]
},
{
"name": "cancel-order",
"title": "Annulla Ordine",
"method": "DELETE",
"href": "https://api.store.example/orders/42"
}
],
"links": [
{ "rel": [ "self" ], "href": "https://api.store.example/orders/42" },
{ "rel": [ "customer" ], "href": "https://api.store.example/customers/1209" }
]
}
Analizzando questo payload, l’agente comprende lo stato dell’ordine e identifica in modo univoco i due soli strumenti utilizzabili (pay-order e cancel-order). La presenza dei dettagli sui campi e sul metodo HTTP fornisce le informazioni necessarie per formattare la successiva richiesta in modo corretto ed esecutivo.
Integrazione con il Model Context Protocol (MCP) e Scenari Futuri
L’evoluzione dell’architettura per agenti ha visto la nascita di standard come il Model Context Protocol (MCP), progettato per connettere modelli di intelligenza artificiale a fonti dati e strumenti remoti attraverso un’interfaccia unificata.
Mentre il protocollo MCP opera come uno strato di trasporto universale gestendo l’autenticazione, la scoperta dei server e l’infrastruttura di canale, l’architettura HATEOAS definisce la dinamica di navigazione applicativa all’interno dei dati trasferiti.
L’integrazione di server MCP che restituiscono risorse modellate secondo principi ipermediali consente di realizzare sistemi altamente efficienti.
In questo scenario a due livelli, MCP viene utilizzato per stabilire la connessione iniziale ed esporre l’entrypoint dell’applicazione, mentre HATEOAS gestisce le interazioni successive tramite il flusso di link e azioni contenuto nelle risposte.
Questo evita di dover registrare preventivamente centinaia di funzioni statiche nel registro di MCP, mantenendo l’infrastruttura snella e scalabile.
Per gli architetti software e i designer di API, l’emergere dell’ecosistema agentico impone un cambio di paradigma verso la progettazione orientata alle affordance. L’inclusione di metadata chiari, l’uso di standard di relazione per i link e la centralizzazione delle macchine a stati sul server rappresentano passaggi chiave per costruire servizi in grado di supportare l’autonomia operativa degli agenti di intelligenza artificiale nei prossimi anni.
Il vincolo HATEOAS, per lungo tempo relegato a dibattito accademico all’interno della comunità REST, ha trovato nella diffusione degli agenti basati su LLM il proprio ambito applicativo di maggior valore. La necessità di guidare i sistemi AI attraverso processi aziendali complessi, riducendo l’uso del contesto di memoria e garantendo l’esecuzione di sole operazioni valide rispetto allo stato corrente, rende i controlli ipertestuali uno strumento fondamentale per la progettazione dei servizi web del futuro.
L’adozione di architetture guidate da hypermedia permette di superare i limiti delle API rigide, realizzando un’infrastruttura pronta per l’interazione autonoma tra macchine.