====== AG-UI Protocol ======

The **AG-UI (Agent-User Interaction) Protocol** is an open, lightweight, event-based protocol that standardizes real-time bi-directional communication between AI agent backends and user-facing frontends. Created and maintained by [[https://www.copilotkit.ai|CopilotKit]], AG-UI replaces traditional REST/GraphQL patterns with event-sourced streaming, enabling agents to push intermediate state, tool calls, and UI updates to frontends as they process.

===== Overview =====

Traditional API patterns (REST, GraphQL) were designed for request-response cycles with deterministic endpoints. AI agents, however, are long-running, nondeterministic processes that produce intermediate outputs, invoke tools, and update state progressively. AG-UI bridges this gap by defining a unified event stream over HTTP Server-Sent Events (SSE) or WebSockets.

AG-UI occupies a distinct layer in the emerging agent protocol stack:

^ Layer ^ Protocol ^ Purpose ^
| Agent to Tools | MCP | Backend data/tool access |
| Agent to Agent | A2A | Task delegation |
| **Agent to User** | **AG-UI** | Real-time UI synchronization |

===== Core Concepts =====

=== Event Streaming ===

Agents emit a sequence of typed JSON events over a single POST connection. Event types include:

  * ''TEXT_MESSAGE_CONTENT'' — Streaming text tokens
  * ''TOOL_CALL_START'' / ''TOOL_CALL_END'' — Tool invocation lifecycle
  * ''STATE_DELTA'' — Incremental state patches
  * ''THINKING'' — Internal reasoning steps (separate from public responses)
  * ''CUSTOM'' — Extension events for domain-specific needs

=== State Management ===

AG-UI maintains persistent, shared structured state across sessions using efficient delta patches. This enables frontend and backend to stay synchronized without full state transfers, handling concurrent edits and partial updates gracefully.

=== Tool Integration ===

Tool calls are first-class events in AG-UI. When an agent invokes a tool, the frontend receives ''TOOL_CALL_START'' with parameters, can display progress indicators, and receives results via ''TOOL_CALL_END''. This standardizes the rendering of tool usage across any agent framework.

=== Human-in-the-Loop ===

AG-UI supports interrupts where agents can pause execution and request user input. The frontend renders appropriate input controls, collects the response, and sends it back through the event channel.

===== Code Example =====

Connecting to an AG-UI agent stream:

<code python>
import httpx
import json

AG_UI_ENDPOINT = "https://agent.example.com/ag-ui/stream"

async def stream_agent_events(prompt: str):
    async with httpx.AsyncClient() as client:
        async with client.stream(
            "POST",
            AG_UI_ENDPOINT,
            json={"messages": [{"role": "user", "content": prompt}]},
            headers={"Accept": "text/event-stream"}
        ) as response:
            async for line in response.aiter_lines():
                if line.startswith("data: "):
                    event = json.loads(line[6:])
                    event_type = event["type"]

                    if event_type == "TEXT_MESSAGE_CONTENT":
                        print(event["delta"], end="", flush=True)
                    elif event_type == "TOOL_CALL_START":
                        print(f"\n[Tool: {event['name']}({event['args']})]")
                    elif event_type == "STATE_DELTA":
                        print(f"\n[State update: {event['delta']}]")
                    elif event_type == "THINKING":
                        print(f"\n[Thinking: {event['content'][:50]}...]")

import asyncio
asyncio.run(stream_agent_events("Summarize today's news"))
</code>

===== Generative UI Integration =====

AG-UI pairs with generative UI specifications to enable agents to dynamically render interactive components. Three patterns are supported:

  * **Static Pattern** — Agent fills data into predefined frontend components; maximum control and consistency
  * **Declarative Pattern** — Agent assembles UI from a component registry using JSON specs (A2UI, Open-JSON-UI); flexible yet predictable
  * **Open-ended Pattern** — Agent outputs raw content (HTML, iframes); maximum flexibility but less control

The protocol manages the lifecycle of these UI elements through tool events and state deltas, enabling spec-agnostic rendering.

===== Framework Compatibility =====

AG-UI is designed to be backend-agnostic. Switching between agent frameworks requires no frontend changes:

  * **LangGraph** — Native AG-UI event emission
  * **CrewAI** — AG-UI adapter integration
  * **OpenAI Agents** — Compatible via AG-UI SDK
  * **Mastra** — Built-in AG-UI support

TypeScript and Python SDKs are available, along with React component libraries for rapid frontend development.

===== References =====

  * [[https://docs.ag-ui.com/introduction|AG-UI Documentation]]
  * [[https://github.com/ag-ui-protocol/ag-ui|AG-UI GitHub Repository]]
  * [[https://www.copilotkit.ai/blog/introducing-ag-ui-the-protocol-where-agents-meet-users|CopilotKit — Introducing AG-UI]]
  * [[https://www.datacamp.com/tutorial/ag-ui|DataCamp — AG-UI Tutorial]]

===== See Also =====

  * [[generative_ui|Generative UI]]
  * [[model_context_protocol|Model Context Protocol (MCP)]]
  * [[agent2agent_protocol|Agent-to-Agent Protocol (A2A)]]
  * [[agent_communication_protocol|Agent Communication Protocol (ACP)]]