AG-UI: un protocollo leggero per l’interazione agente-utente

Perché le app agentiche hanno bisogno di AG-UI

Prima di guardare il codice, spiego perché serviva un nuovo protocollo. Tutto nasce dalla differenza fondamentale tra una funzione e un agente.

Il limite della richiesta/risposta

Nello sviluppo web tradizionale, le interazioni sono transazionali. Chiedi un profilo utente e il server lo invia. È uno scambio "una tantum".

Gli agenti, invece, sono imprevedibili e richiedono tempo. Se chiedi a un agente di "debuggare perché la tua pipeline CI ha iniziato all’improvviso a fallire dopo il merge di un collega", non ti restituisce subito un oggetto JSON. Potrebbe invece:

1. Recuperare gli ultimi 50 commit log da GitHub (Azione).
2. Notare che è stata aggiunta una nuova dipendenza senza aggiornare il lockfile (Osservazione).
3. Confrontare quella versione del pacchetto con CVE noti (Ragionamento).
4. Chiederti se vuoi fare il rollback del merge o applicare una patch in avanti (Human-in-the-loop).

Lo spiegherò più avanti nella sezione "Tipi di evento", ma per ora sappi solo che una richiesta HTTP standard andrebbe in timeout in attesa di tutto questo. Ti serve un modo per trasmettere questi aggiornamenti parziali, così l’utente non guarda uno schermo congelato.

Le esigenze specifiche degli agenti

Gli agenti richiedono un flusso bidirezionale di informazioni che vada oltre il testo. Devono sincronizzare lo Stato.

Immagina un agente che ti aiuta a scrivere un report. Non è solo una chat; sta modificando un documento. Sia tu sia l’agente potreste digitare contemporaneamente. AG-UI gestisce questo trattando il "documento" come uno stato condiviso, usando aggiornamenti efficienti per mantenere sincronizzati il tuo schermo e la memoria dell’agente senza sovrascrivere il lavoro dell’altro.

Come comunicano agenti e UI

AG-UI sostituisce il vecchio modello RPC (Remote Procedure Call) con un modello Event-Sourcing. Invece di attendere una risposta finale, l’agente invia un flusso costante di eventi che descrivono cosa sta facendo.

Il flusso di eventi

Pensa allo stream AG-UI come a un notiziario in tempo reale del cervello del tuo agente. L’applicazione client (il tuo frontend) si iscrive a questo ticker e aggiorna la UI in base a ciò che riceve. Questo approccio disaccoppia la logica: il tuo frontend React non ha bisogno di sapere come pensa l’agente, ma solo cosa mostrare.

AG-UI evita il vuoto di attesa. Immagine dell’autore.

Tipi di evento core

Il protocollo definisce tipi di evento standard che coprono quasi ogni scenario d’interazione. Ecco i principali che incontrerai:

1. TEXT_MESSAGE_*: Eventi che trasmettono testo generato a pezzi. Tipicamente includono _START, _CONTENT (lo stream di token) e _END, che insieme creano il familiare effetto "digitazione".

2. TOOL_CALL: Segnala che l’agente vuole fare qualcosa, come controllare il meteo o interrogare un database. Fondamentalmente, AG-UI può trasmettere in streaming gli argomenti della chiamata allo strumento, permettendo alla tua UI di precompilare i moduli prima ancora che l’agente finisca di "parlare".

3.  STATE_DELTA: È il motore della collaborazione. Invece di rimandare l’intero documento ogni volta che cambia una lettera, l’agente invia un piccolo "diff" (tipo "aggiungi 'ciao' all’indice 5").

4. INTERRUPT: La valvola di sicurezza. Se un agente raggiunge un’azione sensibile (come "Elimina database"), emette un evento di interruzione. Il flusso si ferma finché l’utente non invia un evento di approvazione.

Multimodalità e passi di ragionamento

Il protocollo non si limita al testo. Gestisce la multimodalità, ovvero trasmette immagini, audio e allegati insieme alla conversazione. Standardizza anche i Thinking Steps, separando i pensieri interni dell’agente (tracce di ragionamento) dalla risposta pubblica finale. Potresti aver notato un modello simile usando strumenti come ChatGPT, dove gli indicatori di avanzamento o i passaggi intermedi vengono mostrati separatamente dalla risposta finale. Questo ti permette di decidere se mostrare agli utenti l’avanzamento dell’esecuzione o solo il risultato finale.

I blocchi costitutivi di AG-UI

Ora che hai compreso il flusso, vediamo le caratteristiche specifiche che rendono AG-UI potente per gli sviluppatori.

UI generativa

Il testo va benissimo, ma a volte un grafico è meglio. La UI generativa consente a un agente di decidere a runtime di mostrarti un componente UI invece del testo.

AG-UI trasmette eventi; A2UI definisce i componenti. Immagine dell’autore.

C’è una distinzione che spesso trae in inganno (ne parlerò di nuovo nella sezione sui framework): AG-UI è il meccanismo di consegna (livello di trasporto) e A2UI (Agent-to-User Interface) è la definizione della UI (payload). Un agente può usare un evento TOOL_CALL di AG-UI per trasportare un payload A2UI, un albero JSON dichiarativo che descrive un componente UI (come una "Scheda prezzo azione"). Il tuo frontend lo riceve e renderizza il grafico vero e proprio.

Stato condiviso con JSON Patch

Gestire lo stato condiviso è complicato. Se l’agente invia ogni secondo un enorme oggetto di contesto da 5 MB, la tua app rallenta.

AG-UI risolve questo con JSON Patch (RFC 6902). Come accennato prima riguardo alla sincronizzazione dello stato, quando l’agente cambia un valore nella sua memoria, calcola la differenza e invia un evento STATE_DELTA.

[
  {
    "op": "replace",
    "path": "/user/status",
    "value": "active"
  }
]Offerto da

Il client riceve questa istruzione leggera e la applica al suo stato locale. Questa efficienza è ciò che rende possibile la collaborazione in tempo reale con gli agenti.

AG-UI nel panorama dei protocolli

Potresti aver sentito parlare di altri protocolli come MCP (Model Context Protocol). È importante capire dove si colloca AG-UI nello stack per non usare lo strumento sbagliato.

Lo stack agentico

Mi piace pensarci come a un triangolo della comunicazione:

1. MCP (Agente ↔ Strumenti): collega l’agente al mondo backend: database, repo GitHub e API interne. Serve a ottenere informazioni.
2. A2A (Agente ↔ Agente): consente agli agenti di parlarsi, delegando compiti a sottoagenti.
3. AG-UI (Agente ↔ Utente): è il "Last Mile". Collega l’intelligenza dell’agente all’utente umano.

La Trinità dei protocolli che connette gli agenti. Immagine dell’autore.

AG-UI non si interessa a come l’agente ha ottenuto i dati (è il lavoro di MCP, come detto sopra); si interessa solo a come mostrarli a te.

Implementare AG-UI

Vediamo come appare in pratica. Gli sviluppatori di solito interagiscono con AG-UI in tre modi: costruendo 1) app agentiche (collegare un frontend a un agente), 2) integrazioni (rendere compatibile un framework) o 3) client (creare nuovi frontend). La maggior parte di voi rientrerà nella prima categoria.

Spiegherò il codice tra poco, ma sappi che di solito non scriverai tu a mano gli handler del protocollo grezzo. Le librerie si occupano dell’incapsulamento. Capire il flusso però serve per il debugging.

Stabilire il canale di eventi

La maggior parte delle implementazioni usa i Server-Sent Events (SSE) perché sono semplici, compatibili con i firewall e perfetti per lo streaming unidirezionale dal server al client. L’ho accennato prima: gli SSE sono la chiave che rende questo protocollo così leggero rispetto ai WebSocket.

In un setup tipico (come con Microsoft Agent Framework o CopilotKit), il tuo server espone un endpoint che aggiorna la connessione a uno stream.

Sottoscrizione semplice agli eventi

Ecco un esempio concettuale di come un client frontend ascolta lo stream. Nota come gestiamo i diversi tipi di evento per aggiornare la UI.

// Connect to the AG-UI stream
const eventSource = new EventSource('/api/agent/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'TEXT_MESSAGE_CONTENT':
      // Append text to the chat window
      updateChatLog(data.content);
      break;

    case 'TOOL_CALL_START':
      // Show a "Processing..." indicator or the specific tool UI
      showToolIndicator(data.tool_name);
      break;

    case 'STATE_DELTA':
      // Apply the JSON patch to our local state store
      applyPatch(localState, data.patch);
      break;

    case 'INTERRUPT':
      // Prompt the user for permission
      showApprovalModal(data.message);
      break;
  }
};Offerto da

Questo pattern nasconde la complessità della logica interna dell’agente. Il tuo frontend è solo un "player" per gli eventi inviati dall’agente.

Integrazioni e supporto dell’ecosistema

Non devi costruire tutto da zero. L’ecosistema sta maturando rapidamente: le principali piattaforme e i framework stanno convergendo su pattern di interazione basati su eventi molto simili.

Il "Triangolo d’oro" degli strumenti

Microsoft descrive un "Triangolo d’oro" per lo sviluppo di agenti:

1. DevUI: per visualizzare il processo di pensiero dell’agente (debugging).
2. OpenTelemetry: per misurare prestazioni e costi.
3. AG-UI: per connettersi all’utente.

Framework supportati

L’ecosistema si sta espandendo rapidamente. Oltre ai grandi nomi, il supporto sta crescendo ovunque:

1. Microsoft Agent Framework: ha middleware nativo per ASP.NET Core (Microsoft.Agents.AI.Hosting.AGUI).

2. CopilotKit: funge da "Browser" per AG-UI, fornendo un frontend React completo che sa renderizzare questi eventi pronti all’uso.

3. Ecosistema Python: framework come LangGraph, CrewAI, Mastra, Pydantic AI, Agno e LlamaIndex possono tutti essere esposti come endpoint AG-UI.

4. SDK: Anche se TypeScript e Python dominano, sono attivi o in sviluppo SDK per Kotlin, Go, Dart, Java e Rust.

Affidabilità, debugging e sicurezza

Aprire una linea diretta di comunicazione tra un’AI e un browser introduce dei rischi. Ecco come mantenere la tua applicazione sicura.

Il trusted frontend server

Non permettere mai a un client di connettersi direttamente al runtime grezzo del tuo agente. Come sottolineato nella sezione "Perché le app agentiche hanno bisogno di AG-UI", usa sempre un Trusted Frontend Server (pattern BFF). Questo server funge da guardiano. Aggiunge autenticazione, rate limiting e validazione degli input prima di passare il messaggio dell’utente all’agente.

Considerazioni sulla sicurezza

Prompt injection

Utenti malevoli potrebbero cercare di sovrascrivere le istruzioni del tuo agente tramite attacchi di prompt injection. Come accennato, il tuo middleware dovrebbe sanificare gli input.

Chiamate a strumenti non autorizzate

Il fatto che un agente possa eliminare un file non significa che l’utente corrente debba essere autorizzato a farlo. Il tuo server di fiducia deve filtrare gli strumenti a disposizione dell’agente in base ai permessi dell’utente.

Sicurezza dello stato

Poiché lo stato è condiviso tramite patch JSON, fai attenzione alla prototype pollution. Assicurati che la tua libreria di patch impedisca modifiche a proprietà protette come __proto__.

Debugging con il Dojo

Se il tuo agente si comporta in modo strano, usa l’AG-UI Dojo. È una suite di test che ti permette di visualizzare lo stream di eventi grezzi. Ti aiuta a individuare problemi come JSON patch malformate o chiamate a strumenti che partono ma non restituiscono risultati.

Conclusione

Abbiamo coperto l’architettura, i tipi di evento e i pattern di implementazione di AG-UI.

Riconosco che lo sviluppatore singolo medio o chi lavora in una piccola azienda difficilmente "adotterà AG-UI" e all’improvviso "disaccoppierà il frontend dal backend". Tutto questo richiederebbe decisioni architetturali importanti, il coinvolgimento di più team e risorse che molti non hanno.

Ma capire AG-UI è utile anche se non lo implementi. Quando valuti framework per agenti o decidi se costruire in-house o usare una piattaforma, sapere come dovrebbe apparire una buona comunicazione agente-UI migliora il tuo giudizio. Riconoscerai quando uno strumento ti costringe in pattern fragili.

Se vuoi approfondire la costruzione di questi sistemi, dai un’occhiata ai corsi Introduzione agli agenti AI e Costruire sistemi agentici scalabili per portare le tue competenze al livello successivo.