Skip to content
ggui

ggui vs AG-UI

AG-UI and ggui both sit in the “agent ↔ user interface” lane, but they solve adjacent problems. If you’re deciding which to adopt — or whether to run both — this page gives you the framing without pretending one is a replacement for the other.

One-line positioning

Section titled “One-line positioning”
ProtocolWhat it isWhat the user ships
AG-UIA typed event protocol between an agent and a BYO UI. You ship the UI; the agent streams events to update it.Your UI (React / Vue / whatever) + a thin adapter.
gguiA generation + display protocol. Agents describe what UI they need; ggui renders it on demand through MCP + an ephemeral viewer.No UI. You write a system prompt and your agent calls ggui_push.

Different defaults, different center of gravity. Both are open protocols.

The decision tree

Section titled “The decision tree”

Pick AG-UI when:

  • You already have a product with a designed UI and you’re adding an agent to drive it.
  • The UI shape is stable and your differentiation is in the chrome (branding, domain-specific components, pixel-level control).
  • Your users are already trained on your UI surface — novelty is a liability, not a feature.
  • The agent’s job is to update screens, not invent them. Fill forms, update charts, move kanban cards.

Pick ggui when:

  • You’re building an agent-first product where the UI is a byproduct of the agent’s reasoning, not the main deliverable.
  • You want to ship zero agent code beyond a system prompt — MCP config + prompt, no event-handling loop, no component wiring.
  • You need UI shape to vary by intent (“show me a weather card” vs “show me a login form”) without writing a component for every case.
  • You’re OK with the trade-off: generated UIs are bounded by the primitive catalog, not the designer’s imagination.

Run both when:

  • Your agent has a stable product UI (AG-UI) AND ephemeral ad-hoc UI requirements (ggui). Example: a SaaS app where the main dashboard is AG-UI-driven, but support flows or edge cases pop up as ggui-generated modals.
  • The protocols are compositional. AG-UI lives in your app code; ggui lives at ggui_push call sites the agent reaches via MCP.

How they differ in structure

Section titled “How they differ in structure”

AG-UI

Section titled “AG-UI”
┌─────────┐       AG-UI events        ┌──────────────────┐
│  Agent  │ ────────────────────────→ │   Your UI app    │
└─────────┘                            │ (BYO components) │
                                       └──────────────────┘

The agent emits typed events (message, tool_call, state_delta, …) onto a stream. Your UI subscribes and renders whatever the events imply. Components, layouts, styling — all yours. The protocol is the wire, not the look.

ggui

Section titled “ggui”
┌─────────┐   ggui_push (MCP tool)    ┌────────────────┐
│  Agent  │ ────────────────────────→ │  ggui server   │ ──→ /s/<shortCode> viewer
└─────────┘                            │ (generates UI) │        ▲
                                       └────────────────┘        │
                                                   same-origin WebSocket (channel-3)
                                                   │
                                                   ▼
                                          ┌─────────────────┐
                                          │ Guuey app / any │
                                          │  embed surface  │
                                          └─────────────────┘

The agent calls one of a handful of MCP tools (ggui_push, ggui_consume, ggui_close). ggui_push produces a shortCode URL that renders the generated UI in any browser surface — the Guuey app, an iframe in your product, a standalone viewer. The surface re-subscribes to live updates via channel-3 WebSocket.

Overlapping concerns, different answers

Section titled “Overlapping concerns, different answers”
ConcernAG-UI answerggui answer
Agent ↔ UI transportYour server streams AG-UI events (SSE, WebSocket, whatever you pick).MCP transport (SSE / HTTP / stdio) + channel-3 WebSocket for client updates.
UI component libraryBring your own.Generated against the shipped primitive catalog (open) or your declared primitives.
State shapeYour UI owns it; agent emits deltas.Server-managed session; agent pushes stack items + emits actions on declared contracts.
Component invention at runtimeNot the model.Core capability.
Type-safety of eventsStrong — you typecheck the AG-UI event envelope.Strong — defineContract() infers types from JSON schema.
Mobile clientWhatever you ship.Guuey app (paired via /pair — see Pairing guide).
Self-hosting storyRun your own server, serve your own UI. No protocol authority.ggui serve — open-source server, protocol authority for the ggui wire.

Why we built ggui instead of adopting AG-UI

Section titled “Why we built ggui instead of adopting AG-UI”

Short answer: the design center is different.

AG-UI assumes the UI exists and the agent’s job is to drive it. That’s a correct call when the product is a UI and the agent is a feature. We were building for the inverse case: products where the agent is the product and the UI is a function of what the agent needs to show this time. Rendering is ephemeral by design; the agent shouldn’t have to ship a component library to handle “show me a weather card at 10am and a signup form at noon.”

That led to a protocol where:

  • Agents describe intent, not components. ggui_push takes a stack item with a contract; the server generates a component that satisfies the contract.
  • The viewer is generic. Any browser at /s/<shortCode> renders the session — the Guuey app, an iframe, your own embed. No UI shipping required on the agent side.
  • Zero agent code is the default. An MCP config + a system prompt is the full integration. The agent’s runtime tool-calling loop drives everything.

AG-UI and ggui can both be right, for different products. If the product you’re building looks more like a stateful UI your agent happens to animate, AG-UI is the better fit. If it looks more like an agent your users talk to, with visual artefacts as needed, ggui is the better fit.

Compatibility today

Section titled “Compatibility today”
  • Both are open protocols (Apache-2.0 for @ggui-ai/* packages; MIT for AG-UI).
  • Both transport over MCP-compatible runtimes. ggui uses MCP tools; AG-UI runs over MCP + its own event envelope; the two can coexist in the same MCP manifest.
  • Shared client wrapping is possible. A single client app (web, iOS, Android) can subscribe to AG-UI events for its primary UI and mount ggui shortCode viewers for ad-hoc UI. Nothing in either protocol forbids the mix.

What’s next

Section titled “What’s next”