R034 · Agent principles and patterns › Agent interaction protocols

AG-UI: an event protocol between agents and user-facing apps

Read the original

agent-protocolsagent-architectureagent-harnesshuman-oversight

TL;DR

AG-UI (Agent–User Interaction Protocol, open source, born from CopilotKit's work with LangChain and CrewAI) standardizes the connection between an agent backend and the application a person uses. It fills the third slot next to MCP (agent to tools and data) and A2A (agent to agent): agent to user. It came up in Sam Keen's post as an approach to UI and AI integration.

The core idea is that an agent run is not a request and response but a typed event stream: lifecycle, streamed text, streamed tool calls, state snapshots and JSON Patch deltas, reasoning, sub-agents and interrupts. Any frontend that understands the stream (a web app, a terminal, a mobile app, Slack or Teams) can drive any backend that emits it. Support is broad: LangChain, CrewAI, Microsoft Agent Framework, Google ADK, AWS Strands and Bedrock AgentCore, Mastra, Pydantic AI, LlamaIndex, the Claude Agent SDK and OpenAI Agents SDK, with SDKs in about ten languages.

Why a separate protocol

The docs argue that agents break the REST/GraphQL model because they:

Without a shared contract, every agent framework and every frontend wires these ad hoc.

Architecture

run input:messages, state, toolstyped event stream(SSE, WebSocket,webhook)

App or client
(web, terminal,
mobile, Slack)

Agent backend
(any framework)

Tools and data
(MCP)

Other agents
(A2A)

The event model

FamilyEventsPattern
LifecycleRunStarted, RunFinished, RunError, StepStarted, StepFinishedRun boundaries; RunFinished can end in success or interrupt with the pending interrupts
TextTextMessageStart, Content, End (or Chunk)Start, content, end
Tool callsToolCallStart, Args, End, Result (or Chunk)Start, content, end; args stream as they are generated
StateStateSnapshot, StateDelta, MessagesSnapshotSnapshot then JSON Patch (RFC 6902) deltas
ActivityActivitySnapshot, ActivityDeltaSnapshot then delta
ReasoningReasoningStart, message events, ReasoningEnd, ReasoningEncryptedValueVisible summaries, or encrypted reasoning carried opaquely
Sub-agentsSubagentStarted, Finished, ErrorNested delegation with scoped state
Escape hatchesRaw, CustomAnything the protocol does not cover

Events sharing an ID (a messageId or toolCallId) form one logical stream, so text and several tool calls can interleave. On top of the events sit higher-level building blocks: shared read-write state with conflict resolution, frontend-executed tool calls, rendering of backend tool output, generative UI (static typed components, or a small declarative language the app validates before mounting), human-in-the-loop interrupts (pause, approve, edit, retry, escalate without losing state) and live agent steering.

Tradeoffs and failure modes

Review checklist

Sources

Connections

See R034 on the knowledge map

Part of the Research notes on nowucca.com. Figures and claims are the source's own unless the summary says otherwise.