Publié le 19 décembre 2025 à 22h09. Les agents d’intelligence artificielle (IA) sont de plus en plus présents, mais leur communication avec les interfaces utilisateur reste un défi. De nouveaux outils, comme CopilotKit et AG-UI, promettent de simplifier cette interaction et de rendre les agents IA plus intuitifs.
- AG-UI standardise la communication entre les agents IA et les interfaces utilisateur, permettant une expérience plus fluide et réactive.
- CopilotKit facilite l’implémentation d’AG-UI en fournissant des composants d’interface utilisateur préconstruits et des outils de débogage.
- La combinaison de ces technologies permet de visualiser le processus de réflexion d’un agent IA, transformant une « boîte noire » en un système transparent.
Pour les développeurs travaillant avec des agents d’IA, la communication entre l’agent et l’interface utilisateur (UI) a longtemps été un point de friction. Se retrouver face à des termes comme CopilotKit et AG-UI, sans comprendre leur utilité, est une expérience courante. Récemment, un développeur a exploré ces outils pour créer une interface utilisateur connectée à un agent développé avec l’ADK (Agent Development Kit) de Google. Il a rapidement réalisé qu’AG-UI est bien plus qu’un simple protocole : c’est ce qui permet aux agents IA de se comporter comme de véritables applications, et non de simples zones de texte.
Imaginez la construction d’une maison. L’ADK représente l’architecte et les ouvriers, le cerveau qui décide de ce qui doit être construit et comment. CopilotKit est la maison finie, visible et tangible. AG-UI, quant à lui, est le système de communication qui relie les deux. Sans AG-UI, les ouvriers travailleraient en silence, et vous ne verriez le résultat qu’une fois terminé. Avec AG-UI, ils communiquent en permanence : « Je pose la première brique », « Je peins le mur en bleu », ou encore « Où souhaitez-vous cette fenêtre ? »
Qu’est-ce qu’AG-UI exactement ?
AG-UI (Agent-User Interaction) est un protocole standard ouvert conçu pour unifier la manière dont les agents IA communiquent avec les interfaces utilisateur. Bien que le nombre d’événements pris en charge évolue rapidement (on parle de « 17 événements » ou de « 30+ »), le protocole de base couvre l’essentiel : la diffusion de texte, les appels d’outils et les mises à jour d’état. À mesure que les agents deviennent plus sophistiqués, le protocole s’étend pour inclure des éléments tels que les « propositions de projets », les interruptions « Human-in-the-loop » et les « instantanés d’activité ».
Quelle est la place de CopilotKit ?
CopilotKit est un framework construit sur AG-UI. Il prend ce flux d’événements bruts et offre :
- Des composants d’interface utilisateur riches : des bulles de discussion prédéfinies (
- Des hooks sans tête : des hooks de bas niveau (comme
useCopilotChatouuseAgent) qui donnent un accès direct aux données, permettant de créer des outils personnalisés, comme le débogueur présenté ici.
Il est possible d’expérimenter avec ce framework d’interaction de manière interactive sur AG-UI Dojo.
Avant de découvrir cette combinaison d’outils, l’application ADK en cours de développement semblait maladroite. Les utilisateurs posaient une question, attendaient dix secondes devant une icône de chargement, puis recevaient un mur de texte. L’objectif était d’afficher les réflexions intermédiaires et l’utilisation des outils, mais la cartographie des événements ADK bruts sur le frontend s’avérait complexe. AG-UI a permis de résoudre ce problème en fournissant un ensemble standard de signaux que n’importe quel backend peut émettre et n’importe quel frontend peut écouter. CopilotKit facilite cette communication.
Commencer : la méthode rapide
Il n’est pas nécessaire de créer une interface utilisateur complète à partir de zéro. La CLI CopilotKit permet de créer un projet full-stack avec un backend ADK (ou un autre framework agentique) et une interface Next.js connectés :
npx create-copilotkit-app@latest my-copilot-app --adkPour reproduire l’environnement de travail utilisé, suivez les instructions du Guide de démarrage rapide ADK de CopilotKit. À partir de là, le code des fichiers page.tsx, layout.tsx et de l’agent backend a été modifié pour créer l’expérience personnalisée décrite ci-dessous.
Comprendre l’architecture
Pour faire fonctionner une interface utilisateur qui communique avec un agent personnalisé, il est nécessaire d’utiliser un ensemble d’outils spécifiques pour combler le fossé entre l’ADK de Google et une interface React :
- Le backend : l’agent Python ADK natif, encapsulé dans une couche de traduction (
ag_ui_adk). - Le middleware : une route API Next.js agissant comme Copilot Runtime.
- Le frontend : une application React utilisant CopilotKit pour consommer le flux d’événements.
1. Le backend : encapsuler l’agent ADK
Un package appelé ag_ui_adk agit comme un adaptateur de protocole. Il intercepte les comportements natifs de l’agent ADK (comme démarrer une exécution ou émettre un jeton) et les traduit en événements AG-UI standard.
from fastapi import FastAPI
from ag_ui_adk import ADKAgent, add_adk_fastapi_endpoint
from data_science_agent.agent import root_agent
import uvicorn
import os
app = FastAPI(title="Data Science Agent - AG-UI Compatible")
Wrap the existing native ADK agent
This adapter translates ADK behaviors into AG-UI protocol events
adk_agent_wrapper = ADKAgent(
adk_agent=root_agent,
user_id="demo_user",
session_timeout_seconds=3600,
use_in_memory_services=True,
)
Expose the wrapped agent on the root path
add_adk_fastapi_endpoint(app, adk_agent_wrapper, path="https://discuss.google.dev/")
if name == "main":
port = int(os.getenv("PORT", 8080))
uvicorn.run(app, host="0.0.0.0", port=port)
2. Le middleware : la route API
Une route API Next.js (src/app/api/copilotkit/route.ts) est mise en place pour faire office de passerelle et gérer la connexion sécurisée au backend Python.
import { CopilotRuntime, ExperimentalEmptyAdapter, copilotRuntimeNextJSAppRouterEndpoint } from "@copilotkit/runtime";
import { HttpAgent } from "@ag-ui/client";
import { NextRequest } from "next/server";
const runtime = new CopilotRuntime({
agents: {
// We register our python agent here using the HttpAgent adapter
"data_science_agent": new HttpAgent({ url: "http://localhost:8080/" }),
}
});
export const POST = async (req: NextRequest) => {
const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
runtime,
serviceAdapter: new ExperimentalEmptyAdapter(),
endpoint: "/api/copilotkit",
});
return handleRequest(req);
};
3. Le frontend : contexte global
L’application est enveloppée dans le src/app/layout.tsx, exposant l’agent à chaque composant.
{children}
Visualisation de la « matrice » : création d’un débogueur d’agent
L’objectif était de visualiser exactement ce qui se passait sous le capot, au-delà des bulles de discussion. Un débogueur d’agent personnalisé a été créé pour visualiser le flux d’événements brut. Avec CopilotKit v1.5+, le hook useAgent permet de s’abonner directement à ces événements.
Le GIF ci-dessus montre deux vues de la même session d’agent. En bas, la console développeur personnalisée capture et affiche les événements AG-UI bruts en temps réel. Cette console a été créée pour démontrer l’accès complet aux signaux que CopilotKit reçoit. Ces événements peuvent être utilisés pour déclencher des comportements d’interface utilisateur personnalisés, comme la mise à jour d’un tableau de bord en direct. En haut, les outils de développement natifs de CopilotKit montrent que l’agent reçoit bien les événements AG-UI en temps réel.
Une précision technique : Lors de l’implémentation, il a été constaté que les événements sont des objets plats, et non enveloppés dans un objet payload. Les données nécessaires, comme delta ou toolCallId, se trouvent directement sur l’objet événement.
L’implémentation du débogueur personnalisé
Voici le code du composant AgentDebugger.tsx :
"use client";import React, { useState, useEffect } from "react"; import { useAgent } from "@copilotkitnext/react";
export function AgentDebugger() { const [events, setEvents] = useState<any>([]);
const { agent } = useAgent({ agentId: "data_science_agent" });
useEffect(() => { if (agent) { const subscriber = { // Catch-all handler for the raw stream onEvent: ({ event }: { event: any }) => { // Enrich with local timestamp if missing const enrichedEvent = { ...event, _receivedAt: Date.now() }; setEvents((prev) => [enrichedEvent, ...prev]); } };
const subscription = agent.subscribe(subscriber); return () => subscription.unsubscribe(); }}, [agent]);
return (
<p>
{events.map((event, idx) => (
<genericeventcard key="{event.id" idx="" event="{event}"/>
))}
</p>
);
}
Rendu de la carte d’événement
Le composant
GenericEventCardcode les événements par couleur (bleu pour le texte, violet pour les outils, vert pour l’état) pour une meilleure visualisation.function GenericEventCard({ event }: { event: any }) { // Note: Data is accessed DIRECTLY on the event object. There is no 'payload' wrapper! const { type, agentId } = event; const timestamp = event.timestamp || event._receivedAt;// ... (styling logic omitted for brevity)
return ( <div classname="border border-gray-200 rounded p-3 text-sm bg-white font-mono"> {/ Event Header /} <p> <span classname="{`font-bold" uppercase="">{type}</span> <span classname="text-xs text-gray-500">{agentId}</span> </p>
<div classname="text-xs text-gray-700 overflow-x-auto break-all"> {/* Text Streaming */} {type === "TEXT_MESSAGE_CONTENT" && ( <p><span classname="font-bold text-blue-400">Delta: </span>"{event.delta}"</p> )} {/* Tool Args */} {type === "TOOL_CALL_ARGS" && ( <p><span classname="font-bold text-purple-600">Arg Delta: </span>{event.delta}</p> )} {/* Raw View */} <details classname="mt-2 text-[10px] text-gray-400"> <summary classname="cursor-pointer">Raw Event</summary> <pre classname="bg-slate-50 p-2 mt-1">{JSON.stringify(event, null, 2)}</pre> </details> </div> </div>);
}
Points clés à retenir
- Découplage : L’utilisation d’AG-UI permet de changer la logique du backend sans casser le frontend. Les « signaux de communication » restent les mêmes.
- Le streaming est essentiel : Le backend doit émettre les événements au fur et à mesure. La réactivité de l’interface utilisateur dépend de la gestion immédiate des événements
RUN_STARTEDetTOOL_CALL_START.L’apprentissage de ces outils est un processus continu, mais la visibilité accrue sur le fonctionnement interne de l’agent grâce à ces événements standardisés a transformé la façon dont l’application est construite. Cela transforme une « boîte noire » en un système transparent et interactif.
Vous voulez en savoir plus ?
Voici les ressources utilisées pour se familiariser avec ces outils :
Connectons-nous !
J’espère que ce guide vous aidera à explorer vos propres agents et à créer des interfaces utilisateur intéressantes de manière plus simple. Si vous avez trouvé cela utile, ou si vous créez quelque chose d’intéressant avec cette pile, j’aimerais en entendre parler. N’hésitez pas à me contacter ou à me faire part de vos commentaires sur LinkedIn. Bon codage !
Pour aller plus loin
