AG-UI : Un protocole léger pour l'interaction agent-utilisateur

Pourquoi les applications agencées nécessitent une interface utilisateur AG

Avant d'examiner le code, permettez-moi d'expliquer pourquoi nous avions besoin d'un nouveau protocole. Cela revient à la différence fondamentale entre une fonction et un agent.

La limitation des requêtes/réponses

Dans le développement web traditionnel, les interactions sont transactionnelles. Vous demandez un profil utilisateur, et le serveur vous l'envoie. Il s'agit d'un échange unique.

Les agents, cependant, sont imprévisibles et prennent du temps. Lorsque vous demandez à un agent de « déboguer pourquoi votre pipeline CI a soudainement commencé à échouer après la fusion d'un collègue », il ne renvoie pas immédiatement un objet JSON. Au lieu de cela, il pourrait :

1. Veuillez récupérer les 50 derniers journaux de commit depuis GitHub (Action).
2. Veuillez noter qu'une nouvelle dépendance a été ajoutée sans mise à jour du fichier de verrouillage (observation).
3. Veuillez comparer la version de ce paquet avec les CVE connus (justification).
4. Veuillez indiquer si vous souhaitez annuler la fusion ou l'appliquer (intervention humaine).

Je vous expliquerai cela plus en détail dans la section « Types d'événements », mais pour l'instant, sachez simplement qu'une requête HTTP standard expirerait en attendant que tout cela se produise. Il est nécessaire de trouver un moyen de diffuser ces mises à jour partielles afin que l'utilisateur ne soit pas confronté à un écran figé.

Les besoins spécifiques des agents

Les agents ont besoin d'un flux d'informations bidirectionnel qui va au-delà du texte. Ils doivent synchroniser l'État.

Imaginez un agent qui vous assiste dans la rédaction d'un rapport. Il ne s'agit pas seulement de discuter, mais également de modifier un document. Il est possible que vous et l'agent tapiez simultanément. AG-UI gère cela en considérant le « document » comme un état partagé, en utilisant des mises à jour efficaces pour synchroniser votre écran et la mémoire de l'agent sans écraser le travail de l'autre.

Comment les agents et les interfaces utilisateur communiquent

AG-UI remplace l'ancien modèle RPC (Remote Procedure Call) par un modèle Event-Sourcing. Au lieu d'attendre une réponse définitive, l'agent envoie un flux continu d'événements qui décrivent ce qu'il est en train de faire.

Le flux d'événements

Considérez le flux AG-UI comme un téléscripteur d'actualités pour le cerveau de votre agent. L'application cliente (votre interface utilisateur) s'abonne à ce téléscripteur et met à jour l'interface utilisateur en fonction des informations qu'elle reçoit. Cette approche dissocie la logique : votre interface React n'a pas besoin de connaître le fonctionnement de l'agent, elle doit simplement savoir ce qu'elle doit afficher.

AG-UI élimine le délai d'attente. Image fournie par l'auteur.

Types d'événements principaux

Le protocole définit des types d'événements standard qui couvrent presque tous les scénarios d'interaction. Voici les principaux éléments que vous rencontrerez :

1. TEXT_MESSAGE_*: Événements générant du texte au fur et à mesure. Cela implique généralement les événements _START, _CONTENT (le flux de jetons) et _END, qui, ensemble, créent l'effet familier de « saisie ».

2. TOOL_CALL: Signaux indiquant que l'agent souhaite effectuer une action, telle que vérifier la météo ou interroger une base de données. Il est important de noter qu'AG-UI peut diffuser lesarguments d' s de l'appel de l'outil, ce qui permet à votre interface utilisateur de préremplir les formulaires avant même que l'agent ait fini de « parler ».

3.  STATE_DELTA: Il s'agit d'un outil essentiel pour la collaboration. Au lieu de renvoyer l'intégralité du document à chaque modification d'une lettre, l'agent envoie une petite « différence » (par exemple « ajouter « bonjour » à l'index 5 »).

4. INTERRUPT: La soupape de sécurité. Si un agent effectue une action sensible (telle que « Supprimer la base de données »), il émet un événement d'interruption. Le flux est interrompu jusqu'à ce que l'utilisateur renvoie un événement d'approbation.

Multimodalité et étapes de réflexion

Le protocole ne se limite pas au texte. Il prend en charge la multimodalité, c'est-à-dire la diffusion en continu d'images, de fichiers audio et de pièces jointes parallèlement à la conversation. Il normalise également les étapes de réflexion, en séparant les pensées internes de l'agent (traces de raisonnement) de la réponse publique finale. Vous avez peut-être remarqué un schéma similaire lorsque vous utilisez des outils tels que chatGPT, où les indicateurs de progression ou les étapes intermédiaires apparaissent séparément de la réponse finale. Cela vous permet de décider si vous souhaitez montrer aux utilisateurs la progression de l'exécution ou simplement le résultat final.

Éléments constitutifs de l'interface utilisateur AG

Maintenant que vous comprenez le fonctionnement, examinons les fonctionnalités spécifiques qui rendent AG-UI si performant pour les développeurs.

Interface utilisateur générative

Le texte est excellent, mais parfois un graphique est plus efficace. L'interface utilisateur générative permet à un agent de décider, au moment de l'exécution, qu'il est préférable de vous présenter un composant de l'interface utilisateur plutôt que du texte.

AG-UI diffuse les événements ; A2UI définit les composants. Image fournie par l'auteur.

Il existe ici une distinction qui peut souvent prêter à confusion (j'y reviendrai dans la section consacrée au cadre) : AG-UI est le mécanisme de transmission (couche transport), et A2UI (Agent-to-User Interface) est la définition de l'interface utilisateur (charge utile). Un agent peut utiliser un événement AG-UI TOOL_CALL pour transporter une charge utile A2UI, une arborescence JSON déclarative qui décrit un composant d'interface utilisateur (tel qu'une « fiche de cours boursiers »). Votre interface utilisateur reçoit ces informations et affiche le graphique correspondant.

État partagé avec JSON Patch

La gestion de l'état partagé est délicate. Si l'agent envoie un objet contextuel volumineux de 5 Mo toutes les secondes, votre application fonctionnera au ralenti.

AG-UI résoutce problème grâce à JSON Patch (RFC 6902). Comme jel'ai mentionné précédemment à propos de la synchronisation d'état, lorsque l'agent modifie une valeur dans sa mémoire, il calcule la différence et envoie un événement d'STATE_DELTA.

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

Le client reçoit cette instruction légère et l'applique à son état local. Cette efficacité est ce qui rend possible la collaboration en temps réel avec les agents.

AG-UI dans le paysage protocolaire

Vous avez peut-être entendu parler d'autres protocoles tels que le MCP (Model Context Protocol). Il est essentiel de comprendre où AG-UI s'intègre dans la pile afin d'éviter d'utiliser un outil inapproprié pour la tâche à accomplir.

La pile agentique

Je préfère le considérer comme un triangle de communication :

1. MCP (Agent ↔ Outils) : Ceci permet de connecter l'agent au monde backend : bases de données, dépôts GitHub et API internes. Il s'agit d'obtenir des informations.
2. A2A (Agent ↔ Agent) : Cela permet aux agents de communiquer entre eux et de déléguer des tâches à des sous-agents.
3. AG-UI (Agent ↔ Utilisateur) : Il s'agit du « dernier kilomètre ». Il relie l'intelligence de l'agent à l'utilisateur humain.

Le Protocole Trinity connectant les agents. Image fournie par l'auteur.

AG-UI ne se préoccupe pas de la manière dont l'agent a obtenu les données (c'est le rôle de MCP, comme je l'ai mentionné précédemment) ; il se concentre uniquement sur la manière de vous présenter ces données.

Mise en œuvre de l'AG-UI

Examinons comment cela se présente concrètement. Les développeurs interagissent généralement avec AG-UI de trois manières différentes : en créant 1) des applications agencées (connectant une interface utilisateur à un agent), en créant 2) des intégrations (rendant un cadre compatible) ou en créant 3) des clients (créant de nouvelles interfaces utilisateur). La plupart d'entre vous se trouveront dans la première catégorie.

Je vais vous expliquer le code dans un instant, mais avant cela, il est important de comprendre que vous n'écrirez généralement pas vous-même les gestionnaires de protocole bruts. Les bibliothèques gèrent le packaging. Cependant, il est nécessaire de comprendre le flux pour le débogage.

Création du canal événementiel

La plupart des implémentations utilisent les événements envoyés par le serveur (SSE) car ils sont simples, compatibles avec les pare-feu et parfaitement adaptés au streaming unidirectionnel du serveur vers le client. J'ai déjà évoqué ce point précédemment, mais SSE est l'élément clé qui rend ce protocole si léger par rapport aux WebSockets.

Dans une configuration standard (telle que Microsoft Agent Framework ou CopilotKit), votre serveur expose un point de terminaison qui met à niveau la connexion vers un flux.

Abonnement simple à un événement

Voici un exemple conceptuel illustrant comment un client frontal écoute le flux. Veuillez noter comment nous gérons différents types d'événements pour mettre à jour l'interface utilisateur.

// 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;
  }
};

Ce modèle masque la complexité de la logique interne de l'agent. Votre interface utilisateur n'est qu'un « lecteur » pour les événements envoyés par l'agent.

Intégrations et assistance pour l'écosystème

Il n'est pas nécessaire de tout créer à partir de zéro. L'écosystème évolue rapidement, les principales plateformes et infrastructures convergeant vers des modèles d'interaction similaires, basés sur les événements.

Le « triangle d'or » des outils

Microsoft décrit un « triangle d'or » pour le développement d'agents :

1. DevUI: Pour visualiser le processus de réflexion de l'agent (débogage).
2. OpenTelemetry: Pour mesurer les performances et les coûts.
3. AG-UI: Pour établir une connexion avec l'utilisateur.

Cadres pris en charge

L'écosystème connaît une expansion rapide. Au-delà des principaux acteurs, le soutien s'intensifie à tous les niveaux :

1. Cadre Microsoft Agent: Dispose d'un middleware natif pour ASP.NET Core (Microsoft.Agents.AI.Hosting.AGUI).

2. CopilotKit: Fait office de « navigateur » pour AG-UI, fournissant une interface React complète qui sait comment afficher ces événements dès son installation.

3. Écosystème Python: Les frameworks d'tels que LangGraph, CrewAI, Mastra, Pydantic AI, Agno et LlamaIndex peuvent tous être exposés en tant que points de terminaison AG-UI.

4. SDK: Bien qu', TypeScript et Python soient prédominants, des SDK sont actifs ou en cours de développement pour Kotlin, Go, Dart, Java etRust.

Fiabilité, débogage et sécurité

L'établissement d'une ligne de communication directe entre une IA et un navigateur comporte des risques. Voici comment assurer la sécurité de votre application.

Le serveur frontal de confiance

Veuillez ne jamais autoriser un client à se connecter directement à votre environnement d'exécution d'agent brut. Comme je l'ai souligné dans la section « Pourquoi les applications agentiques ont besoin d'AG-UI », il est recommandé de toujours utiliser un serveur frontal de confiance (modèle BFF). Ce serveur agit en tant que contrôleur d'accès. Il ajoute l'authentification, la limitation du débit et la validation des entrées avant de transmettre le message de l'utilisateur à l'agent.

Considérations relatives à la sécurité

Injection immédiate

Des utilisateurs malveillants pourraient tenter de contourner les instructions de votre agentpar le biais d'attaques par injection de prompt. Comme je l'ai mentionnéprécédemment, votre middleware devrait assainir les entrées.

Appels d'outils non autorisés

Le fait qu'un agent puisse supprimer un fichier ne signifie pas que l'utilisateur actuel devrait être autorisé à le faire. Votre serveur de confiance doit filtrer les outils disponibles pour l'agent en fonction des autorisations de l'utilisateur.

Sécurité nationale

Étant donné que l'état est partagé via des correctifs JSON, veuillez faire attention à la pollution des prototypes. Veuillez vous assurer que votre bibliothèque de correctifs empêche toute modification des propriétés protégées telles que __proto__.

Débogage avec Dojo

Si votre agent se comporte de manière inhabituelle, veuillez utiliserl'AG-UI Dojo. Il s'agit d'un site de testqui vous permet de visualiser le flux d'événements bruts. Il vous aide à détecter des problèmes tels que des correctifs JSON mal formés ou des appels d'outils qui s'exécutent mais ne renvoient pas de résultats.

Conclusion

Nous avons abordé l'architecture, les types d'événements et les modèles d'implémentation d'AG-UI.

Je reconnais qu'il n'est pas réaliste de s'attendre à ce qu'un développeur indépendant moyen ou un employé d'une petite entreprise « adopte AG-UI » et « découple soudainement son front-end de son back-end ». Tout cela nécessiterait des décisions architecturales importantes, l'adhésion de plusieurs équipes et des ressources dont la plupart des gens ne disposent pas.

Cependant, il est important de comprendre l'AG-UI même si vous ne l'implémentez pas. Lorsque vous évaluez des frameworks d'agent ou que vous décidez de développer en interne ou d'utiliser une plateforme, il est important de savoir à quoi ressemble une « bonne » communication entre l'agent et l'interface utilisateur afin de pouvoir prendre une décision éclairée. Vous saurez reconnaître quand un outil vous contraint à adopter des modèles rigides.

Si vous souhaitez approfondir vos connaissances sur la création de ces systèmes, nous vous invitons à consulter nos cours « Introduction aux agents IA » et « Création de systèmes agents évolutifs » afin de perfectionner vos compétences.