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 | INLINECODE0 |
| 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 - INLINECODE6 - Use provider/model string format for model selection
- INLINECODE7 - Set maxSteps to prevent infinite tool call loops
- INLINECODE8 - Configure MCP endpoints for external tool access
2. AG-UI Protocol (HIGH)
- -
agui-event-ordering - Emit events in correct order (start -> content -> end) - INLINECODE10 - Stream text incrementally, not as single blocks
- INLINECODE11 - Follow the complete tool call event lifecycle
- INLINECODE12 - Emit STATE_SNAPSHOT events for frontend sync
- INLINECODE13 - Always emit error events on failure
3. State Management (HIGH)
- -
state-snapshot-frequency - Emit state snapshots at meaningful checkpoints - INLINECODE15 - Keep state snapshots minimal and serializable
- INLINECODE16 - Handle bidirectional state conflicts gracefully
- INLINECODE17 - 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 - INLINECODE19 - Always set timeouts with fallback behavior
- INLINECODE20 - Include sufficient context for user decisions
- INLINECODE21 - Preserve full state when resuming after approval
5. Generative UI Emission (MEDIUM)
- -
genui-tool-call-render - Emit tool calls that map to frontend useRenderTool - INLINECODE23 - Stream tool args incrementally for real-time UI
- INLINECODE24 - Use text messages for non-tool status updates
How to Use
Read individual rule files for detailed explanations and code examples:
CODEBLOCK0
Full Compiled Document
For the complete guide with all rules expanded: INLINECODE25
CopilotKit 智能体模式
构建连接 CopilotKit 的 AI 智能体的架构与实现模式。包含 5 个类别共 20 条规则，按影响优先级排序。
适用场景
在以下情况参考这些指南：
- - 设计 CopilotKit 集成的智能体架构
- 实现 AG-UI 协议事件流
- 管理智能体与前端的同步状态
- 在智能体工作流中添加人工介入检查点
- 发出在前端渲染生成式 UI 的工具调用
按优先级分类的规则类别
| 优先级 | 类别 | 影响 | 前缀 |
|---|
| 1 | 智能体架构 | 关键 | architecture- |
| 2 |
AG-UI 协议 | 高 | agui- |
| 3 | 状态管理 | 高 | state- |
| 4 | 人工介入 | 中 | hitl- |
| 5 | 生成式 UI 发出 | 中 | genui- |
快速参考
1. 智能体架构（关键）
- - architecture-built-in-agent - 对简单智能体使用 @copilotkit/runtime/v2 中的 BuiltInAgent
- architecture-model-resolution - 使用 provider/model 字符串格式进行模型选择
- architecture-max-steps - 设置 maxSteps 以防止无限工具调用循环
- architecture-mcp-servers - 配置 MCP 端点以访问外部工具
2. AG-UI 协议（高）
- - agui-event-ordering - 按正确顺序发出事件（开始 -> 内容 -> 结束）
- agui-text-streaming - 增量流式传输文本，而非作为单个块
- agui-tool-call-lifecycle - 遵循完整的工具调用事件生命周期
- agui-state-snapshot - 发出 STATE_SNAPSHOT 事件以同步前端
- agui-error-events - 失败时始终发出错误事件
3. 状态管理（高）
- - state-snapshot-frequency - 在有意义的检查点发出状态快照
- state-minimal-payload - 保持状态快照最小化且可序列化
- state-conflict-resolution - 优雅处理双向状态冲突
- state-thread-isolation - 按线程隔离状态，而非按智能体
4. 人工介入（中）
- - hitl-approval-gates - 使用工具调用而非自定义事件实现审批关卡
- hitl-timeout-fallback - 始终设置超时并附带回退行为
- hitl-context-in-prompt - 在提示中包含足够上下文以供用户决策
- hitl-resume-state - 审批后恢复时保留完整状态
5. 生成式 UI 发出（中）
- - genui-tool-call-render - 发出映射到前端 useRenderTool 的工具调用
- genui-streaming-args - 增量流式传输工具参数以实现实时 UI
- genui-activity-messages - 对非工具状态更新使用文本消息
使用方法
阅读单个规则文件以获取详细说明和代码示例：
rules/architecture-built-in-agent.md
rules/agui-event-ordering.md
完整编译文档
如需包含所有规则扩展的完整指南：AGENTS.md
