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\nPackages
| 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
RunAgentInputbody, respond withtext/event-stream - Parse input -- Extract
threadId,runId,messages,tools,state,contextfrom the request body - Emit events in order --
RUN_STARTEDfirst, then content events, thenRUN_FINISHEDorRUN_ERROR - Encode as SSE -- Use
@ag-ui/encoder'sEventEncoder.encode()or manually writedata: JSON\n\n - Handle tool results -- Client sends
TOOL_CALL_RESULTback; agent processes and continues
See references/building-agents.md for a complete working example.
Key Protocol Rules
- Every run MUST start with
RUN_STARTEDand end withRUN_FINISHEDorRUN_ERROR TEXT_MESSAGE_CONTENT.deltamust be non-empty- Tool call events are linked by
toolCallId STATE_DELTAuses 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 examplesreferences/building-agents.md-- Step-by-step guide to building AG-UI backendsreferences/event-flow-diagrams.md-- ASCII sequence diagrams for common flowsreferences/client-sdk.md-- @ag-ui/client API reference