copilotkit-react-patterns

CopilotKit React 代理应用程序的最佳实践。在编写、审查或重构使用 CopilotKit 挂钩（useAgent、useFrontendTool、useRenderTool、useCopilotAction、useCopilotReadable）、提供程序 (CopilotKit) 或聊天 UI 组件（CopilotChat、CopilotSidebar、CopilotPopup）的 React 代码时使用。触发涉及 React 中的代理集成、工具渲染、共享状态或生成 UI 的任务。

# CopilotKit React Patterns

Best practices for building agentic React applications with CopilotKit. Contains 25 rules across 6 categories, prioritized by impact to guide code generation and refactoring. Covers both v1 (`@copilotkit/react-core`) and v2 (`@copilotkit/react-core/v2`) APIs.

## When to Apply

Reference these guidelines when:
- Setting up `CopilotKit` provider in a React application
- Using agent hooks (useAgent, useFrontendTool, useCopilotAction)
- Rendering tool calls or custom messages from agents
- Managing shared state between UI and agents via useCopilotReadable or useCoAgent
- Building chat interfaces with CopilotChat, CopilotSidebar, or CopilotPopup
- Configuring suggestions for proactive agent assistance

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Provider Setup | CRITICAL | `provider-` |
| 2 | Agent Hooks | HIGH | `agent-` |
| 3 | Tool Rendering | HIGH | `tool-` |
| 4 | Context & State | MEDIUM | `state-` |
| 5 | Chat UI | MEDIUM | `ui-` |
| 6 | Suggestions | LOW | `suggestions-` |

## Quick Reference

### 1. Provider Setup (CRITICAL)

- `provider-runtime-url` - Always configure runtimeUrl to connect to your agent backend
- `provider-single-endpoint` - Configure the agent prop for CoAgent routing
- `provider-nested-providers` - Scope agent configurations with nested CopilotKit providers
- `provider-tool-registration` - Register tools via hooks inside provider, not as props when possible

### 2. Agent Hooks (HIGH)

- `agent-use-agent-updates` - Specify update subscriptions to avoid unnecessary re-renders
- `agent-agent-id` - Always pass agentId when running multiple agents
- `agent-context-description` - Write descriptive context values for useCopilotReadable
- `agent-frontend-tool-deps` - Declare dependency arrays for useFrontendTool
- `agent-stable-tool-handlers` - Use useCallback for tool handler functions

### 3. Tool Rendering (HIGH)

- `tool-typed-args` - Define Zod schemas for useRenderTool parameters (v2)
- `tool-status-handling` - Handle all three tool call statuses (inProgress, executing, complete)
- `tool-wildcard-fallback` - Register a wildcard renderer as fallback for unknown tools
- `tool-render-vs-frontend` - Use useRenderTool for display-only, useFrontendTool for side effects
- `tool-component-hook` - Use useFrontendTool render prop for simple component rendering

### 4. Context & State (MEDIUM)

- `state-minimal-context` - Provide only relevant context to agents, not entire app state
- `state-structured-values` - Use structured objects in useCopilotReadable, not serialized strings
- `state-context-granularity` - Split context into multiple useCopilotReadable calls by domain
- `state-avoid-stale-closures` - Use functional state updates in tool handlers

### 5. Chat UI (MEDIUM)

- `ui-chat-layout` - Choose CopilotSidebar for persistent chat, CopilotPopup for on-demand
- `ui-custom-labels` - Always customize labels for your domain instead of defaults
- `ui-welcome-screen` - Provide a welcome screen with suggested prompts
- `ui-input-mode` - Use appropriate inputMode for your use case

### 6. Suggestions (LOW)

- `suggestions-configure` - Use useConfigureSuggestions (v2) or useCopilotChatSuggestions (v1)
- `suggestions-context-driven` - Provide rich context so suggestions are relevant
- `suggestions-loading-state` - Handle suggestion loading states via useSuggestions (v2)

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/provider-runtime-url.md
rules/agent-use-agent-updates.md
rules/tool-typed-args.md
```

Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references

## Full Compiled Document

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

---

## 中文说明

# CopilotKit React 模式

使用 CopilotKit 构建代理式 React 应用的最佳实践。包含 6 大类别共 25 条规则，按影响程度优先排序，用于指导代码生成和重构。同时涵盖 v1 (`@copilotkit/react-core`) 和 v2 (`@copilotkit/react-core/v2`) API。

## 何时应用

在以下情况下参考这些准则：
- 在 React 应用中设置 `CopilotKit` 提供程序
- 使用代理挂钩（useAgent、useFrontendTool、useCopilotAction）
- 渲染代理的工具调用或自定义消息
- 通过 useCopilotReadable 或 useCoAgent 管理 UI 与代理之间的共享状态
- 使用 CopilotChat、CopilotSidebar 或 CopilotPopup 构建聊天界面
- 配置建议以实现主动式代理辅助

## 按优先级划分的规则类别

| 优先级 | 类别 | 影响 | 前缀 |
|----------|----------|--------|--------|
| 1 | 提供程序设置 | 关键 | `provider-` |
| 2 | 代理挂钩 | 高 | `agent-` |
| 3 | 工具渲染 | 高 | `tool-` |
| 4 | 上下文与状态 | 中 | `state-` |
| 5 | 聊天 UI | 中 | `ui-` |
| 6 | 建议 | 低 | `suggestions-` |

## 快速参考

### 1. 提供程序设置（关键）

- `provider-runtime-url` - 始终配置 runtimeUrl 以连接到你的代理后端
- `provider-single-endpoint` - 配置 agent 属性以实现 CoAgent 路由
- `provider-nested-providers` - 使用嵌套的 CopilotKit 提供程序来限定代理配置的作用域
- `provider-tool-registration` - 尽可能通过提供程序内部的挂钩注册工具，而不是作为属性

### 2. 代理挂钩（高）

- `agent-use-agent-updates` - 指定更新订阅以避免不必要的重新渲染
- `agent-agent-id` - 运行多个代理时始终传递 agentId
- `agent-context-description` - 为 useCopilotReadable 编写描述性的上下文值
- `agent-frontend-tool-deps` - 为 useFrontendTool 声明依赖数组
- `agent-stable-tool-handlers` - 对工具处理函数使用 useCallback

### 3. 工具渲染（高）

- `tool-typed-args` - 为 useRenderTool 参数定义 Zod 模式（v2）
- `tool-status-handling` - 处理全部三种工具调用状态（inProgress、executing、complete）
- `tool-wildcard-fallback` - 注册通配符渲染器作为未知工具的回退方案
- `tool-render-vs-frontend` - 对仅显示用途使用 useRenderTool，对有副作用的使用 useFrontendTool
- `tool-component-hook` - 对简单的组件渲染使用 useFrontendTool 的 render 属性

### 4. 上下文与状态（中）

- `state-minimal-context` - 仅向代理提供相关上下文，而非整个应用状态
- `state-structured-values` - 在 useCopilotReadable 中使用结构化对象，而非序列化字符串
- `state-context-granularity` - 按领域将上下文拆分为多个 useCopilotReadable 调用
- `state-avoid-stale-closures` - 在工具处理程序中使用函数式状态更新

### 5. 聊天 UI（中）

- `ui-chat-layout` - 持久化聊天选择 CopilotSidebar，按需聊天选择 CopilotPopup
- `ui-custom-labels` - 始终为你的领域自定义标签，而非使用默认值
- `ui-welcome-screen` - 提供带有建议提示的欢迎屏幕
- `ui-input-mode` - 针对你的使用场景使用合适的 inputMode

### 6. 建议（低）

- `suggestions-configure` - 使用 useConfigureSuggestions（v2）或 useCopilotChatSuggestions（v1）
- `suggestions-context-driven` - 提供丰富的上下文，使建议更具相关性
- `suggestions-loading-state` - 通过 useSuggestions（v2）处理建议加载状态

## 如何使用

阅读各个规则文件以获取详细说明和代码示例：

```
rules/provider-runtime-url.md
rules/agent-use-agent-updates.md
rules/tool-typed-args.md
```

每个规则文件包含：
- 简要说明其重要性
- 带说明的错误代码示例
- 带说明的正确代码示例
- 额外的上下文和参考资料

## 完整编译文档

如需包含所有展开规则的完整指南：`AGENTS.md`