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's 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 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
1---2name: copilotkit-agui3description: Use when building custom agent backends, implementing the AG-UI protocol, debugging streaming issues, or understanding how agents communicate with frontends. Covers event types, SSE transport, AbstractAgent/HttpAgent patterns, state synchronization, tool calls, and human-in-the-loop flows.4---56# AG-UI Protocol Skill78## Overview910AG-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.1112## When to Use1314- Building a custom agent backend that needs to speak AG-UI15- Implementing `AbstractAgent.run()` for a new framework integration16- Debugging why events aren't reaching the frontend or arriving malformed17- Understanding event ordering (lifecycle, text, tool calls, state)18- Working with state synchronization (snapshots vs JSON Patch deltas)19- Implementing human-in-the-loop interrupt/resume flows20- Troubleshooting SSE streaming or encoding issues2122## When NOT to Use2324- For CopilotKit React hooks and frontend components, use `copilotkit-develop`25- For CopilotKit runtime setup and configuration, use `copilotkit-setup`26- For framework-specific integration guides (LangGraph, Mastra, CrewAI), use `copilotkit-integrations`2728## Quick Reference2930### Event Families3132| Family | Events | Purpose |33|--------|--------|---------|34| Lifecycle | `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`, `STEP_STARTED`, `STEP_FINISHED` | Run boundaries and progress |35| Text | `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END` | Streaming text messages |36| Tool Calls | `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END`, `TOOL_CALL_RESULT` | Agent tool invocations |37| State | `STATE_SNAPSHOT`, `STATE_DELTA`, `MESSAGES_SNAPSHOT` | State synchronization |38| Reasoning | `REASONING_START`, `REASONING_MESSAGE_START/CONTENT/END`, `REASONING_END`, `REASONING_ENCRYPTED_VALUE` | Chain-of-thought visibility |39| Activity | `ACTIVITY_SNAPSHOT`, `ACTIVITY_DELTA` | Structured progress updates |40| Custom | `RAW`, `CUSTOM` | Extension points |4142### Convenience Chunk Events4344`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.4546### SSE Wire Format4748Each event is a JSON object sent as an SSE data line:4950```51data: {"type":"RUN_STARTED","threadId":"t1","runId":"r1"}\n\n52data: {"type":"TEXT_MESSAGE_START","messageId":"m1","role":"assistant"}\n\n53data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","delta":"Hello"}\n\n54data: {"type":"TEXT_MESSAGE_END","messageId":"m1"}\n\n55data: {"type":"RUN_FINISHED","threadId":"t1","runId":"r1"}\n\n56```5758### Packages5960| Package | npm | Purpose |61|---------|-----|---------|62| `@ag-ui/core` | Events, types, schemas | Protocol definition |63| `@ag-ui/client` | AbstractAgent, HttpAgent, middleware, event application | Client SDK |64| `@ag-ui/encoder` | EventEncoder (SSE + protobuf) | Server-side encoding |6566## Workflow: Building an AG-UI Backend67681. **Define your endpoint** -- Accept POST with `RunAgentInput` body, respond with `text/event-stream`692. **Parse input** -- Extract `threadId`, `runId`, `messages`, `tools`, `state`, `context` from the request body703. **Emit events in order** -- `RUN_STARTED` first, then content events, then `RUN_FINISHED` or `RUN_ERROR`714. **Encode as SSE** -- Use `@ag-ui/encoder`'s `EventEncoder.encode()` or manually write `data: JSON\n\n`725. **Handle tool results** -- Client sends `TOOL_CALL_RESULT` back; agent processes and continues7374See `references/building-agents.md` for a complete working example.7576## Key Protocol Rules7778- Every run MUST start with `RUN_STARTED` and end with `RUN_FINISHED` or `RUN_ERROR`79- `TEXT_MESSAGE_CONTENT.delta` must be non-empty80- Tool call events are linked by `toolCallId`81- `STATE_DELTA` uses RFC 6902 JSON Patch operations82- Multiple sequential runs are supported -- each must complete before the next starts83- Messages accumulate across runs; state continues unless reset by `STATE_SNAPSHOT`8485## References8687- `references/protocol-spec.md` -- Complete event type reference with schemas and examples88- `references/building-agents.md` -- Step-by-step guide to building AG-UI backends89- `references/event-flow-diagrams.md` -- ASCII sequence diagrams for common flows90- `references/client-sdk.md` -- @ag-ui/client API reference
copilotkit