copilotkit-agent-patterns

name: copilotkit-agent-patterns

description: Patterns for building AI agents that integrate with CopilotKit. Use when designing agent architecture, implementing AG-UI event streaming, managing shared state between agent and UI, adding human-in-the-loop checkpoints, or emitting generative UI from agents. Triggers on agent implementation tasks involving CopilotKit runtime, BuiltInAgent, or AG-UI protocol.

license: MIT

metadata:

author: copilotkit

version: "2.0.0"

CopilotKit Agent Patterns

Architecture and implementation patterns for building AI agents that connect to CopilotKit. Contains 20 rules across 5 categories, prioritized by impact.

When to Apply

Reference these guidelines when:

• Designing agent architecture for CopilotKit integration

• Implementing AG-UI protocol event streaming

• Managing state synchronization between agent and frontend

• Adding human-in-the-loop checkpoints to agent workflows

• Emitting tool calls that render generative UI in the frontend

Rule Categories by Priority

| Priority | Category | Impact | Prefix |

|----------|----------|--------|--------|

| 1 | Agent Architecture | CRITICAL | architecture- |

| 2 | AG-UI Protocol | HIGH | agui- |

| 3 | State Management | HIGH | state- |

| 4 | Human-in-the-Loop | MEDIUM | hitl- |

| 5 | Generative UI Emission | MEDIUM | genui- |

Quick Reference

1. Agent Architecture (CRITICAL)

• architecture-built-in-agent - Use BuiltInAgent from @copilotkit/runtime/v2 for simple agents

• architecture-model-resolution - Use provider/model string format for model selection

• architecture-max-steps - Set maxSteps to prevent infinite tool call loops

• architecture-mcp-servers - Configure MCP endpoints for external tool access

2. AG-UI Protocol (HIGH)

• agui-event-ordering - Emit events in correct order (start -> content -> end)

• agui-text-streaming - Stream text incrementally, not as single blocks

• agui-tool-call-lifecycle - Follow the complete tool call event lifecycle

• agui-state-snapshot - Emit STATE_SNAPSHOT events for frontend sync

• agui-error-events - Always emit error events on failure

3. State Management (HIGH)

• state-snapshot-frequency - Emit state snapshots at meaningful checkpoints

• state-minimal-payload - Keep state snapshots minimal and serializable

• state-conflict-resolution - Handle bidirectional state conflicts gracefully

• state-thread-isolation - Isolate state per thread, not per agent

4. Human-in-the-Loop (MEDIUM)

• hitl-approval-gates - Use tool calls for approval gates, not custom events

• hitl-timeout-fallback - Always set timeouts with fallback behavior

• hitl-context-in-prompt - Include sufficient context for user decisions

• hitl-resume-state - Preserve full state when resuming after approval

5. Generative UI Emission (MEDIUM)

• genui-tool-call-render - Emit tool calls that map to frontend useRenderTool

• genui-streaming-args - Stream tool args incrementally for real-time UI

• genui-activity-messages - Use text messages for non-tool status updates

How to Use

Read individual rule files for detailed explanations and code examples:

rules/architecture-built-in-agent.md

rules/agui-event-ordering.md

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md