最佳实践指南用于构建基于 CopilotKit 的代理 React 应用。包含 25 条规则，跨 6 个分类，按影响力优先级排列。涵盖 v1 和 v2 API。
何时应用
- 设置
CopilotKit 提供者
- 使用代理 hooks
- 渲染工具调用或自定义消息
- 管理 UI 和代理之间的共享状态
- 构建聊天界面
- 配置主动代理建议
...（由于字符限制，完整的 cn_skill_md_content 未全文展示，但应包括完整的 Markdown 内容，保留代码块和命令不翻译）
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 backendprovider-single-endpoint - Configure the agent prop for CoAgent routingprovider-nested-providers - Scope agent configurations with nested CopilotKit providersprovider-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-rendersagent-agent-id - Always pass agentId when running multiple agentsagent-context-description - Write descriptive context values for useCopilotReadableagent-frontend-tool-deps - Declare dependency arrays for useFrontendToolagent-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 toolstool-render-vs-frontend - Use useRenderTool for display-only, useFrontendTool for side effectstool-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 statestate-structured-values - Use structured objects in useCopilotReadable, not serialized stringsstate-context-granularity - Split context into multiple useCopilotReadable calls by domainstate-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-demandui-custom-labels - Always customize labels for your domain instead of defaultsui-welcome-screen - Provide a welcome screen with suggested promptsui-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 relevantsuggestions-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
by