AG-UI Protocol Skill

Overview

AG-UI (Agent-User Interaction) is CopilotKit's open event-based protocol for agent-to-UI communication. All agent-frontend interaction flows through typed events streamed over SSE (Server-Sent Events) or binary protobuf transport. Agents implement

AbstractAgent.run()

returning an RxJS

Observable<BaseEvent>

, and the client SDK handles event application, state management, and message history.

When to Use

Building a custom agent backend that needs to speak AG-UI
Implementing
```
AbstractAgent.run()
```
for a new framework integration
Debugging why events aren't reaching the frontend or arriving malformed
Understanding event ordering (lifecycle, text, tool calls, state)
Working with state synchronization (snapshots vs JSON Patch deltas)
Implementing human-in-the-loop interrupt/resume flows
Troubleshooting SSE streaming or encoding issues

When NOT to Use

For CopilotKit React hooks and frontend components, use
```
copilotkit-develop
```
For CopilotKit runtime setup and configuration, use
```
copilotkit-setup
```
For framework-specific integration guides (LangGraph, Mastra, CrewAI), use
```
copilotkit-integrations
```

Quick Reference

Event Families

Family	Events	Purpose
Lifecycle	`RUN_STARTED` , `RUN_FINISHED` , `RUN_ERROR` , `STEP_STARTED` , `STEP_FINISHED`	Run boundaries and progress
Text	`TEXT_MESSAGE_START` , `TEXT_MESSAGE_CONTENT` , `TEXT_MESSAGE_END`	Streaming text messages
Tool Calls	`TOOL_CALL_START` , `TOOL_CALL_ARGS` , `TOOL_CALL_END` , `TOOL_CALL_RESULT`	Agent tool invocations
State	`STATE_SNAPSHOT` , `STATE_DELTA` , `MESSAGES_SNAPSHOT`	State synchronization
Reasoning	`REASONING_START` , `REASONING_MESSAGE_START/CONTENT/END` , `REASONING_END` , `REASONING_ENCRYPTED_VALUE`	Chain-of-thought visibility
Activity	`ACTIVITY_SNAPSHOT` , `ACTIVITY_DELTA`	Structured progress updates
Custom	`RAW` , `CUSTOM`	Extension points

Convenience Chunk Events

TEXT_MESSAGE_CHUNK

and

TOOL_CALL_CHUNK

auto-expand into Start/Content/End triads via the client's

transformChunks

pipeline. Use these for simpler backend implementations.

SSE Wire Format

Each event is a JSON object sent as an SSE data line:

data: {"type":"RUN_STARTED","threadId":"t1","runId":"r1"}\n\n
data: {"type":"TEXT_MESSAGE_START","messageId":"m1","role":"assistant"}\n\n
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","delta":"Hello"}\n\n
data: {"type":"TEXT_MESSAGE_END","messageId":"m1"}\n\n
data: {"type":"RUN_FINISHED","threadId":"t1","runId":"r1"}\n\n

Packages

Package	npm	Purpose
`@ag-ui/core`	Events, types, schemas	Protocol definition
`@ag-ui/client`	AbstractAgent, HttpAgent, middleware, event application	Client SDK
`@ag-ui/encoder`	EventEncoder (SSE + protobuf)	Server-side encoding

Workflow: Building an AG-UI Backend

Define your endpoint -- Accept POST with
```
RunAgentInput
```
body, respond with
```
text/event-stream
```
Parse input -- Extract
```
threadId
```
,
```
runId
```
,
```
messages
```
,
```
tools
```
,
```
state
```
,
```
context
```
from the request body
Emit events in order --
```
RUN_STARTED
```
first, then content events, then
```
RUN_FINISHED
```
or
```
RUN_ERROR
```

Encode as SSE -- Use

@ag-ui/encoder

EventEncoder.encode()

or manually write

data: JSON\n\n

Handle tool results -- Client sends
```
TOOL_CALL_RESULT
```
back; agent processes and continues

See

references/building-agents.md

for a complete working example.

Key Protocol Rules

Every run MUST start with
```
RUN_STARTED
```
and end with
```
RUN_FINISHED
```
or
```
RUN_ERROR
```
```
TEXT_MESSAGE_CONTENT.delta
```
must be non-empty
Tool call events are linked by
```
toolCallId
```
```
STATE_DELTA
```
uses RFC 6902 JSON Patch operations
Multiple sequential runs are supported -- each must complete before the next starts
Messages accumulate across runs; state continues unless reset by
```
STATE_SNAPSHOT
```

References

```
references/protocol-spec.md
```
-- Complete event type reference with schemas and examples
```
references/building-agents.md
```
-- Step-by-step guide to building AG-UI backends
```
references/event-flow-diagrams.md
```
-- ASCII sequence diagrams for common flows
```
references/client-sdk.md
```
-- @ag-ui/client API reference

copilotkit-agui

NPX Install

Tags

SKILL.md Content