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.
This skill documents CopilotKit's AG-UI (Agent-User Interaction) protocol, an open, event-based protocol for streaming communication between agent backends and frontends. It solves the problem of standardizing how an agent's output — text, tool calls, state, reasoning, and lifecycle signals — reaches a UI, so developers building custom agent backends or new framework integrations have a precise contract to implement rather than reverse-engineering the wire format.
The skill covers the full event taxonomy grouped into families: lifecycle (RUN_STARTED/FINISHED/ERROR, STEP_STARTED/FINISHED), streaming text, tool calls, state synchronization (snapshots versus JSON Patch deltas per RFC 6902), reasoning, activity updates, and custom extension points. It documents the SSE wire format, convenience chunk events that auto-expand into Start/Content/End triads, and the three core npm packages (@ag-ui/core, @ag-ui/client, @ag-ui/encoder). Reference material walks through building an AG-UI backend step by step — extending AbstractAgent to return an RxJS Observable, exposing an HTTP SSE endpoint with EventEncoder, handling tool-call round trips, emitting state and activity updates, and reporting steps — with concrete TypeScript and Express examples.
It targets developers building custom agent backends, integrating new agent frameworks (LangGraph, Mastra, CrewAI) with CopilotKit, or debugging streaming, event-ordering, and encoding issues. It explicitly defers React hooks/components to the copilotkit-develop skill and runtime setup to copilotkit-setup, positioning itself as the protocol-and-backend reference in the CopilotKit skill family.
AG-UI (Agent-User Interaction) is CopilotKit's open, event-based protocol for agent-to-frontend communication. All interaction flows as typed events streamed over SSE (Server-Sent Events) or binary protobuf transport.
Define an endpoint that accepts a POST with a RunAgentInput body and responds with text/event-stream. Emit events in order — RUN_STARTED first, then content events, then RUN_FINISHED or RUN_ERROR — encoding each with @ag-ui/encoder's EventEncoder. In-process agents can instead extend AbstractAgent and return an RxJS Observable<BaseEvent>.
Agents emit STATE_SNAPSHOT to replace all client state, or STATE_DELTA with JSON Patch (RFC 6902) operations for incremental updates. MESSAGES_SNAPSHOT and activity snapshot/delta events follow similar patterns.
The agent emits TOOL_CALL_START/ARGS/END, then typically RUN_FINISHED. The client executes the tool, appends the result to messages, and starts a new run; the agent sees the tool result in input.messages and continues.
Use copilotkit-develop for React hooks and frontend components, copilotkit-setup for runtime configuration, and copilotkit-integrations for framework-specific guides. This skill is for the protocol and custom backends.
Quick Setup:
.claude/skills/Repository
copilotkit/copilotkit