One UI, Any Agent: Proving Framework Independence with AG-UI, Mastra, and React

A developer built a single Vite + React client that renders both a real Mastra agent and a roughly 50-line hand-rolled emitter without any client-side changes, using the AG-UI event protocol as the interface between frontends and agents. Both backends funnel through one shared runPipeline() function that emits standard AG-UI events such as RUN_STARTED, TEXT_MESSAGE_CONTENT and TOOL_CALL_START, with a pure reducer folding the raw event log into the view. The project also documents a cancellation bug that nearly broke the demo.

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. 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 the client. That defeats the purpose of having a protocol. AG-UI https://docs.ag-ui.com Agent-User Interaction Protocol fixes this by defining a standard event contract between agents and frontends: RUN STARTED , TEXT MESSAGE CONTENT , TOOL CALL START/ARGS/END , STATE DELTA , RUN FINISHED , RUN ERROR . If every backend speaks AG-UI, the frontend only needs to speak AG-UI too — and becomes framework-independent. This post walks through a project that proves it: one Vite + React client, two backends a real Mastra agent and a ~50-line hand-rolled emitter , one unchanged component tree. Along the way I'll show the exact code, the ┌─────────────────────────────┐ POST /api/run/:backend SSE ┌──────────────────────────────┐ │ CLIENT :5173 │ ───────────────────────────────────▶ │ SERVER :3101 │ │ App.tsx → useAgui → agui │ │ /mastra ──┐ │ │ tabs, SSE reader, reducer │ ◀─────────────────────────────────── │ /minimal ─┴─▶ runPipeline │ └─────────────────────────────┘ data: {type: RUN STARTED…} └──────────────┬───────────────┘ │ fetch streaming ┌──────▼──────┐ │ Ollama / LM │ │ Studio / … │ └─────────────┘ The invariant that makes the whole demo honest: both routes funnel through a single runPipeline function. The Mastra route constructs a genuine Agent — name, instructions, model — but the AG-UI byte sequence comes from the shared pipeline. Conformance is structural, not aspirational. The client is equally strict: a pure reducer folds the raw event log into the view. There is no if backend === "mastra" anywhere in client/src . server/src/pipeline.ts is the heart of the project. Every run opens the same way: js const send = e: Omit<AguiEvent, "runId" | "timestamp" | "backend" = sseSend res, { ...e, runId, timestamp: now , backend } as AguiEvent ; send { type: "RUN STARTED", message: frameworkNote } as any ; send { type: "STATE SNAPSHOT", snapshot: { task, backend, plan: , results: } } as any ; const messageId = randomUUID ; send { type: "TEXT MESSAGE START", messageId } as any ; for await const chunk of streamLLMText settings, task, isAborted { full += chunk; send { type: "TEXT MESSAGE CONTENT", messageId, delta: chunk } as any ; } send { type: "TEXT MESSAGE END", messageId } as any ; streamLLMText server/src/llm.ts calls any OpenAI-compatible /chat/completions endpoint with stream: true and yields real token chunks . If the provider doesn't support SSE, it falls back to a non-streaming call and re-chunks the genuine response text — the UI still shows real model output arriving incrementally, never canned strings. The planning agent's system prompt in shared/defaults.json , shared by both backends demands strict JSON: { "plan": "step1", "step2", "step3" , "steps": { "tool": "<tool-name ", "args": {...} }, ... } Models disobey. The pipeline's guardrail: strip code fences, JSON.parse , verify plan / steps — and if anything fails, show the parse error instead of inventing a plan : if doc { send { type: "STATE DELTA", deltaState: { op: "add", path: "/parseError", value: parseError } } as any ; send { type: "RUN ERROR", code: "PLAN PARSE ERROR", message: Model did not return valid plan JSON ${parseError} . ... } as any ; return; } Each validated step then becomes real TOOL CALL START → two chunked TOOL CALL ARGS → TOOL CALL END with a deterministically executed toy-tool result → STATE DELTA sequence, before the final RUN FINISHED . Different tasks produce different plans, hence visibly different tool cards — acceptance criteria without a single fixture file. My first implementation checked the abort flag between stream chunks. Testing against a stalled upstream revealed the flaw: when the LLM fetch hangs, no chunks arrive, so the flag is never checked — Stop left the spinner running forever well, until the client's own timeout . The fix has two halves. Server-side, the upstream fetch gets an AbortController driven by a 100 ms poll of the abort registry: js // server/src/llm.ts const ctrl = new AbortController ; const poll = setInterval = { if isAborted ctrl.abort ; }, 100 ; and the pipeline maps the resulting AbortError to a first-class protocol event: } catch e: any { send { type: "TEXT MESSAGE END", messageId } as any ; if isAborted || e?.name === "AbortError" { send { type: "RUN ERROR", code: "ABORTED", message: "Run cancelled by user interrupt ." } as any ; } ... } Client-side, Stop tells the server first and only aborts local transport as a backstop 800 ms later — so the genuine server event arrives down the still-open stream: // client/src/useAgui.ts await fetch "/api/run/abort", { method: "POST", body: JSON.stringify { runId: activeRunId } } ; setTimeout = abortRef.current?.abort , 800 ; I verified this end-to-end against a black-hole HTTP server: the stream closed with TEXT MESSAGE END → RUN ERROR code: "ABORTED" , and the canvas rendered "aborted". The lesson generalizes: cancellation in streaming systems must be tested against a hung upstream, not just a slow one. client/src/agui.ts holds reduceRun — ~80 lines folding an event log into a RunView text + tool cards + state tree + status . useAgui.ts reads SSE-over-POST frames data: {...} split on \n\n , stamps each with a wall-clock timestamp and inter-event latency, and feeds the log. panes.tsx renders the two panes from that single state. Conformance is a type-sequence diff ignoring ids and timestamps: js export function diffSequences a: string , b: string : string { const out: string = ; const n = Math.max a.length, b.length ; for let i = 0; i < n; i++ if a i == b i out.push ${i} mastra=${a i ?? "∅"} minimal=${b i ?? "∅"} ; return out; } Empty diff → green badge. It's a small thing, but it turns "framework independence" from a slide into a widget you can watch go green. The Settings panel base URL / API key / model + Particle.ai, LM Studio, Ollama, Gemini presets, persisted to localStorage flows into every run request body — the server holds no keys. Test connection does a live GET {baseURL}/models and prints the true status and body. Pointing the demo at Ollama http://localhost:11434/v1 , llama3.1 , empty key requires zero code changes, as the acceptance criteria demand. runPipeline — the badge should stay green with zero client changes. reduceRun with no server. Protocols only matter if you prove the independence they promise. Two backends, one shared emitter, one pure client reducer, and a badge that stays red until the event streams actually match — that's the whole demo, and that's the point: build to the event contract, and the framework becomes an implementation detail. Code & more: https://www.dailybuild.xyz/project/269-marionette https://www.dailybuild.xyz/project/269-marionette