| name | ag-ui-knowledge |
| description | Expert guidance for AG-UI (Agent–User Interaction Protocol) — the open, event-based protocol connecting AI agents to user-facing apps. Covers the run lifecycle, event types (lifecycle, text, tool-call, state, activity, reasoning), RunAgentInput, AbstractAgent/HttpAgent, multimodal messages, shared state via STATE_SNAPSHOT/STATE_DELTA (RFC 6902 JSON Patch), frontend-defined tools, interrupt-aware HITL with RunAgentInput.resume, encrypted reasoning for ZDR, capability discovery, middleware, serialization with parentRunId branching, the TypeScript (`@ag-ui/client`, `@ag-ui/core`) and Python (`ag-ui-protocol`) SDKs plus community SDKs. Use whenever someone builds or consumes AG-UI, wires up CopilotKit, LangGraph, CrewAI, Mastra, Pydantic AI, LlamaIndex, Agno, AG2, Microsoft Agent Framework, Google ADK, AWS Strands, or Bedrock AgentCore, or mentions AG-UI, ag_ui, RunStartedEvent, STATE_DELTA, TOOL_CALL_START, REASONING_*, AbstractAgent, HttpAgent, or EventEncoder. Always invoke.
|
| license | MIT |
| metadata | {"author":"Ikuma Yamashita","version":"1.2.0"} |
AG-UI Knowledge
You are an expert in the AG-UI (Agent–User Interaction Protocol) — the open,
event-based protocol that standardizes how AI agents communicate with
user-facing applications in real time.
What AG-UI Is
AG-UI sits at the Agent ↔ User Interaction layer of the agentic-protocol
stack, alongside two siblings:
| Layer | Protocol | Purpose |
|---|
| Agent ↔ Tools / Data | MCP (Model Context Protocol) | Securely connect agents to tools, workflows, and data sources |
| Agent ↔ Agent | A2A (Agent to Agent) | Coordinate work across distributed agents |
| Agent ↔ User | AG-UI | Stream events between an agent runtime and the user-facing app |
A single agent often uses all three. AG-UI is built by CopilotKit in partnership
with LangGraph and CrewAI.
Design principles
- Event-driven — every interaction is a stream of typed, discriminated
events (see Event categories).
- Transport-agnostic — events flow over SSE, WebSockets, HTTP binary
(protobuf), or anything else. AG-UI does not mandate a transport.
- Framework-agnostic — any backend (LangGraph, CrewAI, Mastra, custom) can
emit AG-UI events; any frontend can consume them.
- Bidirectional shared state — agent and frontend share a JSON state model
via snapshots and JSON-Patch deltas.
- Human-in-the-loop is first-class — agents pause mid-run by ending with
an interrupt outcome; clients resume by starting a new run carrying the user's
response.
Core concepts (quick reference)
Most everyday AG-UI questions can be answered from this section without opening
a reference file. Open references/ for full schemas, examples, or edge cases.
Run lifecycle
Every agent interaction is a run on a thread:
- Client POSTs a
RunAgentInput to the agent's HTTP endpoint.
- Agent emits
RUN_STARTED { threadId, runId }.
- Agent streams events (text, tool calls, state, reasoning, …).
- Agent emits
RUN_FINISHED or RUN_ERROR.
RUN_FINISHED carries an optional outcome:
- omitted → legacy normal completion
{ type: "success" } → normal completion{ type: "interrupt", interrupts: [...] } → paused for human input.
Client resumes by starting a new run with
RunAgentInput.resume = [{ interruptId, status, payload? }, …].
A parentRunId on RUN_STARTED creates a git-like branching log within the
same thread (time travel, alternative paths).
Event categories
| Category | Events |
|---|
| Lifecycle | RUN_STARTED, RUN_FINISHED, RUN_ERROR, STEP_STARTED, STEP_FINISHED |
| Text message | TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END, TEXT_MESSAGE_CHUNK |
| Tool call | TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_RESULT, TOOL_CALL_CHUNK |
| State | STATE_SNAPSHOT, STATE_DELTA, MESSAGES_SNAPSHOT |
| Activity (in-progress UI) | ACTIVITY_SNAPSHOT, ACTIVITY_DELTA |
| Reasoning | REASONING_START, REASONING_MESSAGE_START/CONTENT/END/CHUNK, REASONING_END, REASONING_ENCRYPTED_VALUE |
| Special | RAW, CUSTOM |
| Draft | META_EVENT |
| Deprecated (→ v1.0.0) | THINKING_* (replaced by REASONING_*) |
Two recurring patterns:
- Start-Content-End for streaming (text messages, tool calls, reasoning).
*_CHUNK is a convenience event that auto-opens/closes the surrounding
Start/End triad.
- Snapshot-Delta for state. Snapshots replace; deltas mutate via RFC 6902
JSON Patch.
Message roles
user, assistant, system, tool, developer, activity, reasoning.
user content may be a plain string or an array of multimodal InputContent
(text, image, audio, video, document — each with a source of data or
url).assistant may carry toolCalls and optional encryptedContent for
ZDR-style state continuity.tool carries toolCallId linking back to the originating tool call, plus
optional error.activity is frontend-only — never forwarded to the agent. Use it for
progress UI (activityType: "PLAN" | "SEARCH" | …, structured content).reasoning represents agent chain-of-thought. May be encrypted via
encryptedValue; is round-tripped back to the agent on subsequent turns.
State
STATE_SNAPSHOT { snapshot } — replace the entire state.STATE_DELTA { delta } — apply an array of RFC 6902 JSON Patch operations
(add, remove, replace, move, copy, test).MESSAGES_SNAPSHOT { messages } — replace the full message history.
The reference implementation uses fast-json-patch. On patch failure a client
may request a fresh snapshot. State must be emitted before a
RUN_FINISHED interrupt so resume is mode-agnostic (works for both replay-
style and checkpoint-style continuations).
Tools
Tools are defined by the frontend and passed in RunAgentInput.tools. The
agent calls them via the TOOL_CALL_* event triad; the frontend executes and
returns a tool-role message with the matching toolCallId. CopilotKit
exposes this through React's useCopilotAction hook.
Interrupts (human-in-the-loop)
An Interrupt carries { id, reason, message?, toolCallId?, responseSchema?, expiresAt?, metadata? }. Core reason values: tool_call, input_required,
confirmation. Frameworks namespace custom reasons as <framework>:<name>
(e.g. langgraph:database_modification).
Contract: a single resume array must address every open interrupt;
RunAgentInput on a thread with pending interrupts must include resume or
the agent emits RUN_ERROR. For tool-bound interrupts the agent does not
re-emit TOOL_CALL_START/ARGS/END after resume — it emits TOOL_CALL_RESULT
against the original toolCallId.
Reasoning
REASONING_* events stream visible reasoning summaries; REASONING_ENCRYPTED_VALUE
attaches an opaque chain-of-thought blob (subtype: "message" | "tool-call")
that the client stores and forwards back on subsequent turns without
decrypting. This is the ZDR / store:false story.
Capabilities
Agents may expose getCapabilities(): Promise<AgentCapabilities> for
discovery, not negotiation. Ten typed sub-objects: identity, transport,
tools, output, state, multiAgent, reasoning, multimodal,
execution, humanInTheLoop, plus custom. Omitted = unknown, never assumed.
Implementation paths
When implementing AG-UI, pick the role you're playing:
| Role | When to use | Key abstractions |
|---|
| Server | Building a new agent from scratch; want maximum control over emitted events | FastAPI/Express endpoint, EventEncoder, emit events directly |
| Middleware | Adapting an existing framework or protocol (LangGraph, CrewAI, an internal SDK) to AG-UI | Extend AbstractAgent, translate framework events to AG-UI events inside run() |
| Client | Building a UI (web, mobile, CLI) that talks to an AG-UI agent | HttpAgent or AbstractAgent.subscribe, handle the event stream |
Both server and middleware implementations expose the same HTTP contract:
POST RunAgentInput, return an SSE (or binary) stream of BaseEvent objects.
SDKs at a glance
| Language | Package(s) | Status | Install |
|---|
| TypeScript / JavaScript | @ag-ui/core, @ag-ui/client, @ag-ui/encoder, @ag-ui/proto | 1st-party | npm install @ag-ui/client |
| Python | ag-ui-protocol (ag_ui.core, ag_ui.encoder) | 1st-party | pip install ag-ui-protocol |
| Rust | ag-ui-client crate | Community | cargo add ag-ui-client |
| Java, Kotlin, Go, Dart, Ruby | various | Community | see upstream sdks/community/ |
| .NET, Nim, Flowise, Langflow, Cloudflare Agents | — | In progress | tracked as upstream issues |
Quick start: npx create-ag-ui-app@latest scaffolds a project.
Routing table — which reference file do I open?
There are 17 reference files in references/. Open the ones below based on the
question. Always prefer the most specific file.
Concepts (references/concepts/)
| Question | File |
|---|
| Full event schema, properties of every event type, draft/deprecated events | concepts/events.md |
| Architecture overview, transport patterns, middleware layer | concepts/architecture.md |
AbstractAgent shape, agent capabilities (high-level), agent lifecycle | concepts/agents.md |
| Message schemas (User/Assistant/System/Tool/Activity/Developer/Reasoning), multimodal input, vendor-neutrality | concepts/messages.md |
STATE_SNAPSHOT vs STATE_DELTA, RFC 6902 JSON Patch examples, CopilotKit useCoAgent | concepts/state.md |
Tool schema, frontend-defined tools, tool-call lifecycle, useCopilotAction | concepts/tools.md |
Interrupt-aware run lifecycle, Interrupt type, resume rules, tool-bound interrupts, approve-with-edits, parallel interrupts | concepts/interrupts.md |
Reasoning events, encrypted chain-of-thought, ZDR/store:false, migration from THINKING_* | concepts/reasoning.md |
AgentCapabilities and all ten typed sub-objects | concepts/capabilities.md |
Middleware pipeline mechanics (use, MiddlewareFunction, Middleware class), built-in FilterToolCallsMiddleware | concepts/middleware.md |
Stream compaction, branching with parentRunId, normalized input | concepts/serialization.md |
| Generative-UI specs (A2UI/Google, Open-JSON-UI/OpenAI, MCP-UI/Microsoft+Shopify); AG-UI is the runtime, not a gen-UI spec | concepts/generative-ui-specs.md |
Quickstart (references/quickstart/)
| Question | File |
|---|
| Building a Python/FastAPI AG-UI endpoint from scratch (OpenAI example) | quickstart/server.md |
| Building a JS/TS adapter that wraps an existing framework | quickstart/middleware.md |
| Building a client (CLI/web) that consumes AG-UI events; Mastra + tools example | quickstart/client.md |
SDKs (references/sdks/)
| Question | File |
|---|
TypeScript: @ag-ui/client (AbstractAgent, HttpAgent, middleware, AgentSubscriber), @ag-ui/core types and events, @ag-ui/encoder, @ag-ui/proto | sdks/typescript.md |
Python: ag_ui.core types/events, ag_ui.encoder.EventEncoder, FastAPI/SSE patterns, multimodal input | sdks/python.md |
| Rust, Java, Kotlin, Go, Dart, Ruby — install hints and pointers into the upstream repo | sdks/others.md |
Integrations (references/)
| Question | File |
|---|
| Which agent frameworks support AG-UI (LangGraph, CrewAI, Mastra, Microsoft Agent Framework, Google ADK, AWS Strands, Bedrock AgentCore, Pydantic AI, Agno, LlamaIndex, AG2), which clients (CopilotKit), which related specs (A2A, MCP Apps, A2UI, Oracle Agent Spec) | integrations.md |
Source
All references in this skill are distilled from the upstream AG-UI documentation
at submodules/ag-ui/docs/ (102 MDX files, snapshotted at the submodule's
current commit). When the user needs the absolute latest text — release notes,
draft specs, brand-new integrations — check the submodule directly or
github.com/ag-ui-protocol/ag-ui.
Each reference file cites its upstream path at the top so you can verify or
expand from there.
