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

- Skill: `javimosch/copilotkit-agent-patterns` (Agent Skill)
- Install (CLI): `npx skillmds@latest add javimosch/copilotkit-agent-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/javimosch/copilotkit-agent-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: javimosch (https://skillmd.com/u/javimosch)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/javimosch/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 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`