copilotkit-agent-patterns

用于构建与 CopilotKit 集成的 AI 代理的模式。在设计代理架构、实现 AG-UI 事件流、管理代理和 UI 之间的共享状态、添加人机循环检查点或从代理发出生成 UI 时使用。在涉及 CopilotKit 运行时、BuiltInAgent 或 AG-UI 协议的代理实施任务上触发。

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

---

## 中文说明

# CopilotKit Agent Patterns

用于构建连接 CopilotKit 的 AI 代理的架构与实现模式。包含跨 5 个类别的 20 条规则，按影响程度排定优先级。

## 适用场景

在以下情况下参考这些指南：
- 为 CopilotKit 集成设计代理架构
- 实现 AG-UI 协议的事件流
- 管理代理与前端之间的状态同步
- 为代理工作流添加人机协同（human-in-the-loop）检查点
- 发出在前端渲染生成式 UI 的工具调用

## 规则类别（按优先级）

| 优先级 | 类别 | 影响程度 | 前缀 |
|----------|----------|--------|--------|
| 1 | 代理架构 | CRITICAL | `architecture-` |
| 2 | AG-UI 协议 | HIGH | `agui-` |
| 3 | 状态管理 | HIGH | `state-` |
| 4 | 人机协同 | MEDIUM | `hitl-` |
| 5 | 生成式 UI 发出 | MEDIUM | `genui-` |

## 快速参考

### 1. 代理架构（CRITICAL）

- `architecture-built-in-agent` - 对于简单代理，使用来自 @copilotkit/runtime/v2 的 BuiltInAgent
- `architecture-model-resolution` - 使用 provider/model 字符串格式进行模型选择
- `architecture-max-steps` - 设置 maxSteps 以防止无限的工具调用循环
- `architecture-mcp-servers` - 配置 MCP 端点以访问外部工具

### 2. AG-UI 协议（HIGH）

- `agui-event-ordering` - 以正确顺序发出事件（start -> content -> end）
- `agui-text-streaming` - 增量式流式输出文本，而非作为单个块发送
- `agui-tool-call-lifecycle` - 遵循完整的工具调用事件生命周期
- `agui-state-snapshot` - 发出 STATE_SNAPSHOT 事件以同步前端
- `agui-error-events` - 在失败时始终发出错误事件

### 3. 状态管理（HIGH）

- `state-snapshot-frequency` - 在有意义的检查点发出状态快照
- `state-minimal-payload` - 保持状态快照精简且可序列化
- `state-conflict-resolution` - 优雅地处理双向状态冲突
- `state-thread-isolation` - 按线程隔离状态，而非按代理隔离

### 4. 人机协同（MEDIUM）

- `hitl-approval-gates` - 使用工具调用作为审批关卡，而非自定义事件
- `hitl-timeout-fallback` - 始终设置带有回退行为的超时
- `hitl-context-in-prompt` - 包含足够的上下文以供用户做出决策
- `hitl-resume-state` - 在审批后恢复时保留完整状态

### 5. 生成式 UI 发出（MEDIUM）

- `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`