One UI, Any Agent: Proving Framework Independence with AG-UI, Mastra, and React
How I built a single React client that renders a Mastra agent and a hand-rolled emitter with zero client changes — and the cancellation bug that almost broke the demo. The problem with agent demos Almost every agent-framework demo hard-wires the UI to one framework. The frontend knows about Mastra's (or LangChain's, or the Vercel AI SDK's) response shapes, so swapping the agent means rewriting…
Building a single React client that renders both a Mastra agent and a hand-rolled emitter, with zero client changes, requires adhering to a protocol that defines a standard event contract between agents and frontends. This protocol, called AG-UI (Agent-User Interaction Protocol), ensures framework independence by defining a common set of events such as RUN_STARTED, TEXT_MESSAGE_CONTENT, TOOL_CALL_START/ARGS/END, STATE_DELTA, RUN_FINISHED, and RUN_ERROR.
The demo uses a single Vite + React client, two backends (a real Mastra agent and a hand-rolled emitter), and an unchanged component tree to prove that any agent framework can be used interchangeably. The communication between the client and server happens over Server-Sent Events (SSE) at the endpoint POST /api/run/:backend (SSE). The client sends events to the server using the `sseSend` function, which emits the events as per the AG-UI specification.
The server-side code, located in `server/src/pipeline.ts`, handles the construction of a genuine Agent for the Mastra backend while using the shared pipeline for both backends. The server sends events to the client using the `send` function, which formats the event according to the AG-UI specification.
The client-side code, located in `client/src`, uses the `useAgui` hook to manage the AG-UI event stream. The client has a single `runPipeline` function that handles all the logic for sending and receiving events, regardless of the backend. This function constructs the plan, sends the initial messages, and processes the tokens returned by the language model, sending them in chunks as TEXT_MESSAGE_CONTENT events.
The cancellation bug encountered in the project occurred when the server-side cancellation did not correctly signal the client. This bug could have resulted in the client not handling the cancellation event properly, leading to potential issues with the user experience. The bug was addressed by ensuring that the server sends a RUN_ERROR event with the appropriate code and message when the cancellation occurs, allowing the client to handle the cancellation event correctly.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
