AG-UI: The Open Protocol Bringing Agents into Your UI

Introduction: The Chat UI Bottleneck

Agent capabilities have improved dramatically over the past two years. Model reasoning has advanced, tool-calling is reliable, multi-step workflows are shipping in production. The weak link is increasingly the user interface itself.

Most production agentic applications today look like this: a text input, a streaming response, maybe a loading spinner. That pattern made sense when agents were primarily information retrieval systems. It breaks down when agents are executing tools, managing long-running workflows, validating user inputs mid-run, or rendering structured outputs like charts, forms, and dashboards.

The friction is structural, not cosmetic. A text-based interface creates at least three distinct bottlenecks for real agentic work:

• Hidden execution: Tool calls happen behind chat messages. A user watching an agent "think" has no visibility into whether it's calling a database, running code, or waiting on an external API. The execution is opaque by default.
• Ambiguous inputs: Free-text inputs are hard to validate at the point of collection. An agent asking "what date range should I use?" will accept garbage and fail downstream — or waste tokens re-asking.
• Trust deficit: Multi-step flows that produce a final result with no visible intermediate state feel like black boxes. Users don't know whether to trust the output or how to intervene when something goes wrong.

The standard response to this has been ad-hoc: every team wires its own WebSocket connections, invents its own state sync mechanism, and builds bespoke UI components that talk to a specific agent framework. This works until you need to swap frameworks, add a new agent, or integrate with a third-party tool. Then you rebuild from scratch.

AG-UI — the Agent-User Interaction Protocol — is an attempt to solve this at the protocol level. It standardizes the event stream that flows between any agentic backend and any user-facing frontend, so that the wiring logic can be written once and reused across the ecosystem. ^[1]

What Is AG-UI?

AG-UI is an open, lightweight, event-based protocol that standardizes how AI agents connect to user-facing applications. The official description from the AG-UI documentation frames it plainly: it is "the general-purpose, bi-directional connection between a user-facing application and any agentic backend." ^[2]

The protocol ships as an npm package (@ag-ui/core) and defines a set of typed event structures that agent backends emit and frontend clients consume. It is transport-agnostic: the same event semantics work over Server-Sent Events (SSE), WebSockets, webhooks, or any other streaming mechanism. A flexible middleware layer handles transformation and compatibility, so existing agent frameworks don't require a complete rewrite to emit AG-UI events.

The origin story matters for understanding the design philosophy. AG-UI was born from CopilotKit's operational experience building agent-user interaction infrastructure for LangGraph and CrewAI integrations. The patterns that emerged from shipping those integrations — lifecycle events, state delta sync, tool call visibility — were extracted into a standalone protocol and opened to the broader ecosystem. ^[3]

The Event Model

AG-UI defines approximately 16 standard event types, organized into six functional categories: ^[2]

Every event carries a base set of properties: a type identifier, an optional timestamp, and an optional rawEvent field for preserving the original upstream data when events are transformed through middleware. Thread and run IDs provide the correlation handles that let frontends associate events with specific conversations and executions.

The lifecycle event model is worth examining closely, because it's what makes agent-native UIs fundamentally different from chat UIs. A well-instrumented AG-UI agent run looks like:

RUN_STARTED { threadId, runId }
  STEP_STARTED { stepName: "fetch_data" }
    TOOL_CALL_START { toolName: "query_database" }
    TOOL_CALL_ARGS { args: { table: "orders", limit: 100 } }
    TOOL_CALL_END { result: [...] }
  STEP_FINISHED
  TEXT_MESSAGE_START
    TEXT_MESSAGE_CONTENT { delta: "Based on 847 orders..." }
  TEXT_MESSAGE_END
RUN_FINISHED

A frontend consuming this stream can render a progress indicator that shows exactly which step is running, surface the tool call as an expandable detail pane, and begin streaming the response text — all from the same event channel, without any custom wiring.

The Three-Protocol Stack

AG-UI is explicitly positioned as complementary to two other major agentic protocols that emerged in 2024–2025. Understanding where it fits requires understanding what the others do:

• MCP (Model Context Protocol) — Anthropic's protocol for giving agents access to tools and context sources. MCP defines how an agent connects to tool servers; it says nothing about how results are presented to users.
• A2A (Agent-to-Agent) — Google's protocol for agent-to-agent communication. A2A enables multi-agent orchestration where a supervisor delegates to sub-agents; it is not concerned with the end-user interface layer.
• AG-UI — The user-facing layer. Defines how an agent's outputs, state, and execution events flow into and out of the application the user is actually looking at.

The "not competing, complementary" framing is deliberate — and accurate. Each protocol addresses a different integration boundary. The interesting engineering question is how they compose, which is explored in the MCP Apps section below.

Three Patterns of Generative UI

AG-UI enables more than streamed text. The broader concept it enables is generative UI: user interfaces that adapt in real time based on agent state and decisions. CopilotKit's documentation identifies three distinct patterns, each representing a different tradeoff between frontend control and agent freedom. ^[4]

Static Generative UI: Frontend Owns the Components

In the static pattern, the frontend pre-builds a library of UI components. The agent doesn't generate UI — it selects which component to activate and provides the structured data to populate it. Control stays firmly with the frontend team; the agent operates within a bounded vocabulary of UI primitives.

The implementation hook in CopilotKit is useFrontendTool:

import { useFrontendTool } from "@copilotkit/react-core";
import { WeatherCard } from "./components/WeatherCard";

// Register the tool with a React component to render
useFrontendTool({
  name: "showWeatherCard",
  description: "Display a weather card for a given location",
  parameters: {
    location: { type: "string" },
    temperature: { type: "number" },
    conditions: { type: "string" }
  },
  render: ({ status, args }) => (
    <WeatherCard
      loading={status === "inProgress"}
      location={args.location}
      temperature={args.temperature}
      conditions={args.conditions}
    />
  )
});

When the agent calls showWeatherCard, CopilotKit renders the registered React component immediately, with the loading state active. As the tool call progresses and arguments stream in, the component re-renders with real data. The transition from inProgress to complete is handled by the AG-UI TOOL_CALL_START → TOOL_CALL_END event pair.

When to use this pattern: When you need predictable, brand-consistent UI. When your design system defines the component library. When the agent's job is selection and data-filling, not interface invention. This is the lowest-risk pattern for production deployments.

Declarative Generative UI: Agent Describes the Interface

The declarative pattern gives the agent more freedom. Instead of selecting from a fixed component library, the agent emits a structured description of the UI it wants — in a standardized JSON or JSONL format — and the frontend renders it according to its own constraints and design system.

Two standards are converging here:

• A2UI — Google's JSONL-based declarative spec. An agent emits a sequence of structured events: surfaceUpdate (declare what UI surface to use), dataModelUpdate (push the data model), and beginRendering (trigger rendering). A live composer is available at a2ui-composer.ag-ui.com.
• Open-JSON-UI — An open standardization effort built on top of OpenAI's internal declarative UI schema, making that format available across frameworks.

The key insight in the declarative pattern is that the agent describes intent, not implementation. It might say "I need a two-column comparison table with these rows" and the frontend decides whether that renders as an HTML table, a React data grid, or a mobile-optimized card stack. The agent's output is portable across frontends.

When to use this pattern: When agents need to compose novel UI structures that weren't anticipated at build time. When you have multiple frontend targets (web, mobile, desktop) that should render the same agent output differently. When control needs to be shared between the agent and the frontend team.

Open-Ended Generative UI: Agent Owns the Surface

At the far end of the control spectrum, the agent returns a complete UI artifact — typically an HTML document or web component — that the frontend hosts in a sandboxed environment. The frontend is essentially a container; the agent is the designer.

This is the pattern that MCP Apps implements (discussed in detail in the next section). The agent can produce charts, interactive forms, or full dashboards without the frontend team pre-building any components. The tradeoff is that consistency and security become the frontend's primary concerns rather than layout and data.

When to use this pattern: When the output space is genuinely unpredictable — analytics tools, exploratory data interfaces, or situations where the agent needs to invent novel UI structures per query. Requires robust sandboxing and careful review of the security model.

The three patterns form a spectrum, not a hierarchy. The right choice depends on how much you trust the agent, how consistent your UI needs to be, and how much variance you expect in the types of output the agent produces.

AG-UI + MCP Apps: The Runtime Sync Layer

MCP gave agents tools. Those tools return JSON. For a long time, that was fine — the host application would take the JSON and render something. But as agents started producing richer outputs (charts, interactive forms, multi-step dashboards), every host had to rebuild the same rendering logic from scratch. A visualization MCP server would work in one agent host and require complete reimplementation in another.

MCP Apps (formally SEP-1865) addresses this at the protocol level. Authored by MCP core maintainers at OpenAI and Anthropic, co-developed with the MCP-UI creators, it allows MCP servers to declare UI resources directly: ^[5]

• MCP servers expose UI via a ui://... URI scheme in their resource declarations
• Tools reference their associated UI resources through the _meta field in tool responses
• UI runs in sandboxed iframes — isolation from the host application
• Communication between the iframe UI and the host happens via MCP JSON-RPC over postMessage

The sandboxed iframe model provides meaningful security boundaries: an MCP server's UI cannot directly read host application state, manipulate the DOM outside its container, or exfiltrate data without going through the controlled postMessage channel. That said, the security properties depend entirely on the iframe sandbox attributes the host application sets — which is an implementation concern, not a protocol guarantee.

The missing piece in MCP Apps alone is real-time state synchronization. An iframe that hosts a chart needs to know when the agent's execution state changes. It needs live updates, not just an initial data snapshot. This is where AG-UI functions as the sync layer.

AG-UI's Role in the MCP Apps Stack

AG-UI contributes three specific event types that make MCP Apps interactive rather than static:

• TOOL_CALL_START — Signals that the agent has begun executing a tool. The iframe can show a loading state before any result data arrives.
• STATE_SNAPSHOT — Delivers the full current state of the agent to the UI. Used for initialization and recovery after reconnects.
• STATE_DELTA — Delivers an incremental update as a JSON Patch (RFC 6902). Only the diff is transmitted, not the full state. For a chart tracking live data from an agent workflow, this means bandwidth-efficient updates without full re-renders on every tick.

The STATE_DELTA design is worth highlighting. JSON Patch is a well-specified format for describing changes to a JSON document — add, remove, replace, move, copy, test operations on specific paths. It means an agent that updates a single field in a large state object sends a handful of bytes rather than reserializing the entire state. For applications with high-frequency updates (real-time dashboards, live agent monitoring), this matters.

The full CopilotKit + MCP Apps + AG-UI data flow looks like this:

# Agent execution flow with MCP Apps + AG-UI

Agent → calls MCP tool → tool response includes:
  {
    data: { ... },
    _meta: { ui: "ui://my-chart-server/bar-chart" }
  }

CopilotKit receives tool response:
  → Fetches ui:// resource from MCP server
  → Renders iframe with sandboxed HTML
  → Begins AG-UI event stream to iframe:
      STATE_SNAPSHOT { agentState: { ... } }

Agent continues execution:
  → Emits STATE_DELTA { patch: [{ op: "replace", path: "/data/0", value: 42 }] }
  → CopilotKit forwards delta to iframe via postMessage

User interacts with iframe chart:
  → Interaction event forwarded via postMessage to CopilotKit
  → CopilotKit injects as frontend tool call into agent loop

The bidirectionality is crucial. User interactions with MCP App UIs — clicking a data point, submitting a form, selecting a filter — can be forwarded back into the agent's execution context. This enables genuine human-in-the-loop collaboration within MCP-served UIs, not just passive display.

Getting started with MCP Apps via CopilotKit is straightforward: npx copilotkit create -f mcp-apps scaffolds the necessary configuration. The more substantive work is on the MCP server side, declaring your UI resources correctly and ensuring the AG-UI event stream reflects your agent's actual state model.

Real-World Case: VoltOps "Ask AI"

Protocol specifications are useful; production deployments are more useful. VoltOps — the observability console for the VoltAgent TypeScript agent framework — shipped "Ask AI" as a real-world AG-UI integration that illustrates what the protocol enables in a developer tooling context. ^[6]

VoltAgent is an open-source TypeScript framework for building production AI agents. The VoltOps console at console.voltagent.dev provides what production agent deployments actually need: real-time execution traces, performance metrics, structured logs, and OpenTelemetry-compatible export. It's built on the premise that agent developers need the same observability tooling that distributed systems engineers have had for years.

The observability data — execution traces, tool call logs, error events — is inherently complex to navigate. Before "Ask AI," an engineer debugging a failed agent run had to manually trace through nested execution spans, correlate timestamps, and read raw JSON log entries. Useful data, but slow to surface.

"Ask AI" embeds CopilotKit (and through it, AG-UI) directly into the VoltOps console. An engineer can ask natural language questions over their agent execution data: "Why did this run fail?", "What patterns are showing up in the last 24 hours of errors?", "Which tool calls are taking the longest?" The conversational layer queries the observability data, not a generic knowledge base.

This demonstrates a pattern that will likely proliferate: embedding conversational AI as a first-class UI primitive inside developer tooling. The agent isn't a separate product — it's a query interface over the application's own data. AG-UI handles the real-time event stream between the VoltOps console's frontend and the underlying agent that interprets the observability data.

The broader implication: AG-UI isn't just for chat applications. Any application with structured data and complex state — monitoring dashboards, analytics platforms, developer consoles, CMS systems — is a candidate for this pattern. The "Ask AI" integration is the UI layer; AG-UI is the protocol that makes it liveable to implement.

Framework Ecosystem

One of the stronger signals for a protocol's viability is breadth of adoption, particularly across competing frameworks. AG-UI has achieved first-party integrations with a notable cross-section of the current agent framework landscape: ^[1]

The organizational spread — Microsoft, Google, Amazon, Anthropic-adjacent tooling, independent frameworks — matters because it suggests AG-UI is being evaluated on technical merit rather than corporate alignment. A protocol that only one vendor's frameworks support has questionable neutrality; AG-UI's current adoption profile looks more like it's converging toward a standard than toward vendor lock-in.

That said, "first-party support" covers a range of implementation depths. Some integrations are deep (LangGraph's integration emerged from the original CopilotKit partnership and is well-tested at scale). Others may be shallower adapters that emit a subset of the event types. When evaluating whether a specific framework's AG-UI integration meets your application's needs, it's worth inspecting which event categories are actually implemented — particularly state management events, which require more framework-side work than lifecycle events.

The in-progress integrations are also informative. OpenAI Agent SDK support would dramatically expand the potential user base; Cloudflare Agents support would bring edge-deployed agents into the protocol. These are not minor additions.

Getting Started

There are three entry points depending on your starting context.

New Project: Create AG-UI App

The create-ag-ui-app CLI scaffolds a minimal project with the protocol wired up:

npx create-ag-ui-app my-agent-ui
cd my-agent-ui
npm install
npm run dev

This gives you a reference implementation of the AG-UI event stream with a working frontend connector. It's the fastest path to seeing the protocol in action before integrating with a real agent backend.

Existing CopilotKit Project: useFrontendTool

If you're already using CopilotKit, the primary AG-UI integration surface is the useFrontendTool hook for static generative UI, and the useCoAgent / useCoAgentStateRender hooks for state-reactive UI components:

import { useCoAgentStateRender } from "@copilotkit/react-core";

// Render a component that tracks agent state in real time
useCoAgentStateRender({
  name: "my_agent",
  render: ({ state, status }) => (
    <AgentStatusPanel
      currentStep={state.currentStep}
      progress={state.progress}
      isRunning={status === "inProgress"}
    />
  )
});

The state object here is maintained by AG-UI's STATE_SNAPSHOT and STATE_DELTA events — the frontend always has the current agent state without polling.

Exploring the Protocol: AG-UI Dojo

The AG-UI Dojo is the protocol's interactive playground. It lets you explore event types, send test events, and observe how the frontend responds — useful for understanding the protocol before committing to an implementation. For teams evaluating AG-UI against alternatives, the Dojo is the fastest way to develop an intuition for the event model.

MCP Apps Scaffold

# Scaffold a CopilotKit project with MCP Apps support
npx copilotkit create -f mcp-apps

This configures the iframe container, MCP server connection, and AG-UI event stream forwarding. The MCP server side still requires manual implementation of the ui:// resource declarations and the AG-UI event emission logic.

Critical Assessment

AG-UI addresses a real problem and has accumulated meaningful adoption. But it also carries genuine tradeoffs and open questions that practitioners should think through before committing to it as infrastructure.

What AG-UI Does Well

Transport agnosticism is genuinely useful. The ability to run the same event semantics over SSE in production (lower overhead, simpler server infrastructure) and WebSockets in development (easier to debug with full duplex) without changing application logic is a practical advantage. Most ad-hoc implementations hardcode a transport and pay the cost when requirements change.

The event model maps cleanly to UI state machines. Lifecycle events (RUN_STARTED, STEP_STARTED, etc.) give frontends a principled way to manage loading states, progress indicators, and error boundaries. This isn't novel in isolation — it's standard observable pattern territory — but having a shared vocabulary across frameworks reduces the per-integration design work.

Broad framework adoption reduces framework lock-in for frontend teams. If your agent backend migrates from LangGraph to CrewAI (or adds a second framework), your frontend event handling code doesn't change. The protocol abstracts the framework.

STATE_DELTA with JSON Patch is the right default for state sync. Full state snapshots on every update are fine at small scale; they're expensive at high frequency. Starting with delta encoding as the default rather than retrofitting it later is the correct engineering decision.

What's Missing or Uncertain

State model complexity scales quickly. The AG-UI state management model — snapshot + deltas — is straightforward for simple agent states. For agents with deeply nested, frequently-updated state objects (multi-agent workflows, agents with large working memory), managing the delta stream becomes more complex. JSON Patch paths can become brittle when state structure changes. There's limited guidance in the current documentation about state schema design and migration strategies.

The iframe security model for MCP Apps requires careful implementation. The protocol design is sound, but the security properties are only as strong as the host application's iframe sandbox configuration. This is the kind of thing that teams get wrong under deadline pressure — permissive sandbox attributes, loose postMessage origin validation, insufficient CSP headers. The protocol should provide stronger implementation guidance (or a reference implementation with secure defaults) rather than leaving this as a host concern.

Standardization governance is an open question. AG-UI originated from CopilotKit. The GitHub organization (ag-ui-protocol) is separate from CopilotKit's main org, signaling intent to be a neutral standard. But the governance model — how breaking changes are decided, who controls the spec, how conflicts between major adopters are resolved — is not yet as formalized as, say, the OpenAPI Specification's governance structure. For teams making multi-year infrastructure bets, this is worth watching.

Competing approaches exist. Vercel's AI SDK has its own streaming protocol and UI hooks that many Next.js teams are already using. Anthropic's streaming event format for tool calls is similar in spirit. Teams with existing investments in these ecosystems may find migration costs outweigh the benefits of standardization, particularly if their agent-UI integration is already working. AG-UI's value proposition is strongest for teams starting fresh or maintaining agent-UI integrations across multiple frameworks.

Conclusion

Agent-native user interfaces are not a styling problem. They require fundamentally different infrastructure than chat applications: real-time execution visibility, structured state synchronization, human-in-the-loop interaction at arbitrary points in a workflow, and UI surfaces that can adapt to what an agent is doing rather than just what it's saying.

The streaming text pattern that most agentic apps use today was the right starting point — ship something, learn from users, iterate. But it becomes a constraint as agent capabilities expand. Tool calls that are invisible to users, ambiguous free-text inputs that fail downstream validation, multi-step workflows that feel like black boxes: these are not UX polish issues. They're reliability and trust issues.

AG-UI's contribution is to separate the problem into protocol-level and application-level concerns. The protocol defines the event vocabulary — what a TOOL_CALL_START means, how state deltas are structured, what a run lifecycle looks like. Applications implement against that vocabulary once and get interoperability across the framework ecosystem for free.

The three generative UI patterns — static, declarative, open-ended — give practitioners a decision framework rather than forcing a single approach. Static generative UI is production-safe and design-system-compatible. Declarative UI is portable across frontends. Open-ended UI via MCP Apps enables genuinely dynamic agent outputs at the cost of a more complex security posture.

None of this is a solved problem. The state model has complexity at scale, the MCP Apps security model requires careful implementation, and governance of the protocol spec is still maturing. But the direction is right: agents and user interfaces need a shared language, and building that language at the protocol level rather than re-solving it per framework is the only path to a maintainable ecosystem.

The 7 million weekly agent-user interactions flowing through CopilotKit's infrastructure suggest this is already production scale, not a research prototype. The convergence of LangGraph, CrewAI, Microsoft, Google, and AWS on a common protocol — even if driven partly by pragmatism — is a meaningful signal that the agent-UI layer is becoming standardized infrastructure rather than competitive differentiation.

For developers building agentic applications today: the chat box was a reasonable MVP. AG-UI is what comes next.

References

1. AG-UI Protocol GitHub Repository — ag-ui-protocol/ag-ui
2. AG-UI Official Documentation — docs.ag-ui.com
3. CopilotKit Blog — AG-UI Is Redefining the Agent–User Interaction Layer (October 2025)
4. CopilotKit Blog — Generative UI in 2026
5. CopilotKit Blog — MCP Apps: Bringing UI to Model Context Protocol
6. VoltOps Console — console.voltagent.dev
7. CopilotKit — AG-UI Protocol Overview
8. Microsoft Learn — AG-UI Integration with Agent Framework