CopilotKit-agent-patterns

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.

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:

text

rules/architecture-built-in-agent.md
rules/agui-event-ordering.md

Full Compiled Document

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