ag-ui-knowledge

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:

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:

1. Client POSTs a RunAgentInput to the agent's HTTP endpoint.
2. Agent emits RUN_STARTED { threadId, runId }.
3. Agent streams events (text, tool calls, state, reasoning, …).
4. Agent emits RUN_FINISHED or RUN_ERROR.
5. 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

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:

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

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/)

Quickstart (references/quickstart/)

SDKs (references/sdks/)

Integrations (references/)

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.