ag-ui-protocol/ag-ui · 19k stars · Intermediate · 15 min · 2026-11-17

Stream any agent into your app with the AG-UI protocol

AG-UI is an open, event-based protocol that lets any agent framework stream text, tool calls and shared state to any user-facing app over one event stream.

TL;DR

AG-UI (Agent-User Interaction Protocol) standardizes how an agent talks to a front end: the app sends one RunAgentInput, the agent streams back typed events. You can scaffold an app with npx create-ag-ui-app@latest, or speak the protocol directly with a 30-line Python server and a TypeScript client. The same client keeps working when you swap the agent framework.

Why this repo matters

The README says agents don't fit request/response: they stream tokens, call tools mid-response, update shared state, pause for a human and spawn subagents, and every framework does it differently. AG-UI replaces that custom wiring with one bi-directional event stream, so the same agent can power a web app, a mobile app, a terminal or Slack. It sits next to MCP (tools and context) and A2A (agent-to-agent): AG-UI is the one that brings agents to users. The repo is MIT licensed, and AG-UI 1.0 ships a frozen specification backed by a JSON Schema.

Best practices

  • Start from the minimal agent. The README says only the run lifecycle events are required, so begin with RUN_STARTED and RUN_FINISHED and add event families as you need them.
  • Pick the event family that matches the feature. The README maps streaming chat, generative UI, shared state, frontend tools, human in the loop, reasoning, subagents and multimodal input to events in the spec.
  • Sync state with snapshots and deltas. Shared state is "synced with snapshots and JSON Patch deltas" (STATE_SNAPSHOT, STATE_DELTA).
  • Model approvals as interrupts. For human in the loop, a run ends with an interrupt outcome; the user approves, edits or rejects, and the next run resumes.
  • Mind the transport. The Python example's encoder emits SSE; the spec also defines a binary HTTP + Protobuf binding, so pick the transport your client and server both support.
  • Check the Dojo before wiring a framework. The README says every listed framework has a live demo in the Dojo.

How-to

Where do I start?

1. Scaffold an app

How do I get something running fastest? The README's quick start uses the CLI, which scaffolds a frontend (CopilotKit on Next.js, or a terminal client) wired to the agent framework you pick:

npx create-ag-ui-app@latest
export OPENAI_API_KEY="sk-..."

The generated templates call OpenAI, so set the key before npm run dev.

Next: Write the agent by hand

Try it

Run the Python server and the TypeScript client above. Then add another chunk to the for loop in server.py and confirm the client prints it without any client change.

Pitfalls

  • Wrong runtime versions. The server example needs Python 3.9+ and the client needs Node.js 20+.
  • Missing key for the CLI templates. The generated templates call OpenAI, so OPENAI_API_KEY must be set before npm run dev.
  • Confusing AG-UI with generative UI specs. The README says A2UI, MCP Apps and Open-JSON-UI describe what UI an agent wants to show; AG-UI is the runtime protocol that carries those payloads.

Next steps