copilotkit-agui

name: copilotkit-agui description: "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." version: 1.0.0

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

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

Workflow: Building an AG-UI Backend

1. Define your endpoint -- Accept POST with RunAgentInput body, respond with text/event-stream
2. Parse input -- Extract threadId, runId, messages, tools, state, context from the request body
3. Emit events in order -- RUN_STARTED first, then content events, then RUN_FINISHED or RUN_ERROR
4. Encode as SSE -- Use @ag-ui/encoder's EventEncoder.encode() or manually write data: JSON\n\n
5. 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