agenthud-agui-a2ui

August 25, 2026 · View on GitHub

AG-UI event replay + A2UI component rendering in a static Vite/React app — a feasibility prototype for developers exploring how an agent composes safe, declarative UI from a standard catalog.

License Version CI CodeQL CodeFactor Lint Dependabot

What

agenthud demonstrates the AG-UI + A2UI loop end to end: an agent composes UI by referencing components from a fixed catalog — no arbitrary code runs on the client — streamed as AG-UI protocol events and rendered by @a2ui/react on a Vite/React surface. What you get: a Demo tier that replays pre-baked AG-UI events down a branching decision tree, where each path renders a different component mix from the same catalog (with a live event stream beside the surface) plus a Catalog Viewer of all 18 A2UI components; the qte77 EyeRest theme with a light/dark/system toggle; and a Live (BYOK) tier that swaps the replay for a real LLM in the browser — its render_ui tool (zod-validated) emits the same AG-UI events from your own OpenAI-compatible key. In Live, you step through prior turns with a ◀/▶ pager (one surface at a time; the latest stays interactive) and a free-text composer continues the conversation.

Screencast — Live: a prompt renders an A2UI surface, a composer drives a follow-up turn, and the prior turn freezes in the transcript agenthud — Live: a prompt renders an A2UI surface, a composer drives a follow-up turn, and the prior turn freezes in the transcript

How

Explore — open the live demo (zero setup), or run it locally:

cd ui
npm install
npm run dev

Pick a path from the decision tree or press Play All; click Catalog to browse the A2UI components.

Live (BYOK) — toggle Demo → Live in the header, pick an OpenAI-compatible provider (or Custom… for any base URL), paste your API key, and choose a model from the curated dropdown (Custom… accepts any id). Run a prompt, then continue the conversation with the composer below the surface — step through prior turns with ◀/▶ (one surface at a time; the latest stays interactive), and clicking a rendered button also drives the next turn. If a model is rate-limited or ignores the render tool, Live auto-tries the provider's other models (stopping cleanly on a bad key). Your API key is held in memory only (never stored — gone on reload); the base URL + model persist in sessionStorage. Google routes through the deployed edge proxy (worker/README.md); the dev prefill + proxy env vars are documented in ui/.env.example. The demo needs no key. Rationale: ADR-0001.

Build & develop — the local loop:

cd ui
npm run build      # tsc -b + vite build -> dist/ (deployable to GitHub Pages)
npm run typecheck  # tsc -b --noEmit
npm run lint       # eslint
npm test           # vitest

Why

Agents increasingly need to show things, not just say them — but server-rendered generative UI couples the agent to a frontend framework and risks executing arbitrary code on the client. A2UI keeps it safe: the agent only references components from a known catalog (no code runs), and AG-UI streams those choices as protocol events. agenthud is the smallest end-to-end demonstration of that loop — the same standard catalog producing different layouts per user intent — from pre-baked replay to a live BYOK agent. More in docs/UserStory.md and docs/protocols.md.

Refs

A static Vite/React app: pre-baked recordings — or a live Vercel AI SDK agent — emit AG-UI events through one applyA2UIEvent seam into the @a2ui/react surface; zod validates the A2UI payloads on both sides.

License

Apache-2.0 — see LICENSE. Bundled brand fonts (Inter, JetBrains Mono) are under the SIL OFL 1.1.