/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

| 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

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