copilotkit-agent-patterns

# 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 ag...

# CopilotKit Agent Patterns

A structured skill for CopilotKit agent architecture and implementation, optimized for agents and LLMs.

## Structure

- `rules/` - Individual rule files (one per rule)
  - `_sections.md` - Section metadata (titles, impacts, descriptions)
  - `_template.md` - Template for creating new rules
  - `{prefix}-{name}.md` - Individual rule files
- `metadata.json` - Document metadata (version, organization, abstract)
- __`AGENTS.md`__ - Compiled output (generated)

## Categories

| # | Category | Rules | Prefix |
|---|----------|-------|--------|
| 1 | Agent Architecture | 4 | `architecture-` |
| 2 | AG-UI Protocol | 5 | `agui-` |
| 3 | State Management | 4 | `state-` |
| 4 | Human-in-the-Loop | 4 | `hitl-` |
| 5 | Generative UI Emission | 3 | `genui-` |

## Getting Started

```bash
pnpm install
pnpm build
pnpm validate
```