CopilotKit React Activity Messages 渲染指南从自定义渲染器到源码级解析机制【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit本指南以 CopilotKit 官方 React 技能文档 rendering-activity-messages.md 为核心骨架系统讲解如何在 React 应用中通过renderActivityMessages属性注册自定义 Activity 消息渲染器掌握其解析顺序、Schema 校验、内置渲染器覆盖等实战能力并结合 react-core 源码剖析其底层实现原理。读完本文你将能够为任意activityType编写类型安全、可被 Agent 流式驱动渲染的自定义 UI并避免三类高频踩坑。一、概述Activity 消息渲染体系Activity 消息是 Agent 在运行过程中而非最终回复主动下发的过程性/交互性消息例如进度条、MCP 应用卡片、生成式 UI 表面等。在 CopilotKit v2 的 React 体系中Activity 消息渲染器的注册方式是将渲染器对象放入CopilotKit提供者Provider的renderActivityMessages数组属性中渲染时由useRenderActivityMessagehook聊天组件内部消费统一解析并调用。用户提供的渲染器被放置在数组的最前面因此对于相同的activityType它们会优先于内置的MCPAppsActivityType与OpenGenerativeUIActivityType渲染器被命中从而实现覆盖内置渲染器的能力这一合并逻辑见 CopilotKitProvider.tsx[...renderActivityMessagesList, ...builtInActivityRenderers]。二、渲染器解析顺序Resolver OrderuseRenderActivityMessage在收到一条 Activity 消息时按以下优先级查找匹配的渲染器(activityType, agentId)精确匹配activityType与当前会话 agent 的agentId都匹配的渲染器(activityType, unscoped)匹配activityType匹配、但未指定agentIdunscoped的渲染器*通配符渲染器activityType为*的兜底渲染器null均未命中时返回nullUI 不渲染任何内容。这一逻辑在源码 use-render-activity-message.tsx 中实现先从renderers中过滤出所有activityType匹配的渲染器然后依次尝试agentId agentId、agentId undefined、activityType *三种候选。其中 agent 的agentId来源于useCopilotChatConfiguration()?.agentId ?? DEFAULT_AGENT_ID默认 agent ID 定义于copilotkit/shared意味着未显式配置 agent 的会话默认使用 DEFAULT_AGENT_ID 参与匹配。三、核心类型ReactActivityMessageRenderer渲染器对象由 types/react-activity-message-renderer.ts 中定义的ReactActivityMessageRendererTActivityContent接口约束包含四个字段字段类型说明activityTypestring要匹配的 Activity 类型使用*可作为通配渲染器agentIdstring可选将渲染器限定到特定 agent未指定时对所有 agent 生效参与解析顺序的第 2 级contentStandardSchemaV1any, TActivityContent描述 Activity 消息 content 载荷的 Schema使用 Standard Schema 规范zod schema 天然兼容renderReact.ComponentType{ activityType: string; content: TActivityContent; message: ActivityMessage; agent: AbstractAgent | undefined }负责渲染消息内容的 React 组件接收activityType、校验后的content、原始message以及当前agent可能为undefined注意render的类型是ComponentType即它会被当作一个真正的 React 元素挂载——这正是不能在render函数体内直接调用 hooks这一约束的来源详见第六节。四、基础设置注册一个自定义渲染器在 Provider 层级完成渲染器注册。以下完整示例来自原文档展示了如何为一个progress类型的 Activity 消息渲染进度卡片use client; import { CopilotKit } from copilotkit/react-core/v2; import type { ReactActivityMessageRenderer } from copilotkit/react-core/v2; import { z } from zod; import { useMemo } from react; import { Card, CardContent } from /components/ui/card; import { Progress } from /components/ui/progress; const progressRenderer: ReactActivityMessageRenderer{ percent: number; label: string; } { activityType: progress, content: z.object({ percent: z.number().min(0).max(1), label: z.string() }), render: ({ content }) ( Card CardContent div{content.label}/div Progress value{content.percent * 100} / /CardContent /Card ), }; export function Providers({ children }: { children: React.ReactNode }) { const renderers useMemo(() [progressRenderer], []); return ( CopilotKit runtimeUrl/api/copilotkit renderActivityMessages{renderers} {children} /CopilotKit ); }几个值得注意的细节Schema 双向约束content同时充当运行时校验器与 TypeScript 类型来源z.object({ percent: z.number().min(0).max(1), ... })让render回调中的content自动获得类型推导必须useMemo稳定化renderActivityMessages数组的引用必须稳定详见第六节因此在模块顶层定义渲染器或使用useMemo(() [...], [])包裹入口必须use client渲染器涉及组件挂载与状态属于客户端代码。五、核心模式Core Patterns5.1 Agent 作用域渲染器Agent-scoped renderer当希望某一渲染器仅对特定 agent 的活动生效时添加agentId字段。解析器会优先命中(activityType, agentId)的精确组合从而隔离不同 agent 之间的同名 Activity 类型const researchProgress: ReactActivityMessageRenderer{ step: string } { activityType: research-step, agentId: research, content: z.object({ step: z.string() }), render: ({ content }) ResearchStepBadge step{content.step} /, };5.2 覆盖内置渲染器Override a built-in以 MCP Apps 为例内置的 MCP Apps 渲染器使用activityType常量MCPAppsActivityType其值为字符串mcp-apps定义见 MCPAppsActivityRenderer.tsx。由于用户渲染器在合并数组中位于内置渲染器之前注册相同activityType的自定义渲染器即可覆盖内置表现import { MCPAppsActivityType } from copilotkit/react-core/v2; const customMcpRenderer: ReactActivityMessageRendererunknown { activityType: MCPAppsActivityType, // mcp-apps — 必须与导出的常量一致 content: z.unknown(), render: ({ content, message }) CustomMCPCard payload{content} /, };建议始终导入并使用导出常量而非手写字符串字面量以免与内置类型产生偏移。同理生成式 UI 内置渲染器使用OpenGenerativeUIActivityType值为open-generative-ui见 OpenGenerativeUIRenderer.tsx。5.3 直接使用 hook自定义聊天表面如果不使用 CopilotKit 内置聊天组件而是自建聊天界面可以直接调用useRenderActivityMessage获得renderActivityMessage函数对任意ActivityMessage列表执行解析与渲染import { useRenderActivityMessage } from copilotkit/react-core/v2; import type { ActivityMessage } from ag-ui/core; export function ActivityList({ messages }: { messages: ActivityMessage[] }) { const { renderActivityMessage } useRenderActivityMessage(); return ( div {messages.map((m) ( div key{m.id}{renderActivityMessage(m)}/div ))} /div ); }renderActivityMessage对单条消息返回React.ReactElement | null未命中渲染器或校验失败时返回null。hook 同时暴露findRenderer(activityType)用于仅查询匹配到的渲染器而不渲染见 use-render-activity-message.tsx。该 hook 从copilotkit/react-core/v2的子路径导出见 hooks/index.ts。六、常见错误Common Mistakes6.1 高风险Content Schema 与服务端载荷不兼容render回调拿到的content是经过 Schema 校验后的值如果 Schema 字段与服务端实际下发的字段不一致将导致渲染静默失败。错误示例——渲染器期望pct但服务端下发的是percent// Renderer 期望 pct const r: ReactActivityMessageRenderer{ pct: number } { activityType: progress, content: z.object({ pct: z.number() }), render: ({ content }) Bar value{content.pct} /, }; // 但服务端下发的是 { percent: 0.5 } —— 字段名不匹配正确示例const r: ReactActivityMessageRenderer{ percent: number } { activityType: progress, content: z.object({ percent: z.number() }), render: ({ content }) Bar value{content.percent} /, };底层机制每一条进入的 Activity 消息都会调用renderer.content[~standard].validate(message.content)执行校验见 use-render-activity-message.tsx。Schema 不匹配时parseResult.issues存在代码仅输出一条console.warn(Failed to parse content for activity message …)并返回null——UI 什么都不渲染且失败是静默的除非你主动打开控制台。另外如果校验返回的是 Promise异步校验同样会被拒绝并警告Async content validation is not supported因此请务必使用同步 Schemazod 默认同步校验符合要求。6.2 中风险在render内执行副作用 / 直接调用 Hooksrender会在消息列表每次 tick 时重新渲染因此在函数体内写副作用会导致重复触发// 错误每次重渲染都会触发 trackEvent render: ({ content }) { trackEvent(content); return Badge{content.label}/Badge; };更隐蔽的错误是直接违反 React Hooks 规则——在render内调用useEffect// 错误render 是作为普通函数被解析器调用的——不是 React 组件—— // 因此在其内部直接调用 hooks 是非法的 render: ({ content }) { useEffect(() trackEvent(content), [content]); return Badge{content.label}/Badge; };正确做法把副作用提升到一个独立包装组件中由 React 将其作为真实元素挂载function TrackedBadge({ content }: { content: { label: string } }) { useEffect(() { trackEvent(content); }, [content]); return Badge{content.label}/Badge; } // 在渲染器中 render: ({ content }) TrackedBadge content{content} /;从源码看renderActivityMessage内部确实是const Component renderer.render; ... return Component key{message.id} activityType{...} content{...} message{...} agent{...} /的方式将render作为组件元素挂载见 use-render-activity-message.tsx因此合法的副作用写法是让render返回一个内部使用 hooks 的子组件。6.3 中风险内联构建renderActivityMessages数组不要在 JSX 中直接内联数组字面量否则每次渲染都会产生新数组引用// 错误每次渲染都是新数组触发稳定性警告 CopilotKit runtimeUrl/api/copilotkit renderActivityMessages{[progressRenderer, customMcpRenderer]} /正确做法const renderers useMemo(() [progressRenderer, customMcpRenderer], []); CopilotKit runtimeUrl/api/copilotkit renderActivityMessages{renderers} /;Provider 内部使用useStableArrayProp处理该属性见 CopilotKitProvider.tsx当检测到每次渲染传入的数组引用都不同时会通过console.error输出警告renderActivityMessages must be a stable array.。因此应使用useMemo记忆化或将数组提升到模块作用域顶层。七、源码级原理内置渲染器如何被注册Provider 在初始化时会构建一份内置 Activity 渲染器列表见 CopilotKitProvider.tsx其构成逻辑为MCP Apps 渲染器始终注册activityType: MCPAppsActivityType、Schema 为MCPAppsActivityContentSchema、组件为MCPAppsActivityRendererOpen Generative UI 渲染器条件注册当openGenUIActive为真时追加activityType: OpenGenerativeUIActivityType的渲染器A2UI 渲染器前置插入当a2uiActive为真时通过createA2UIMessageRenderer生成渲染器并unshift到列表最前——它负责生成式 UI 的整个生命周期骨架屏 → 重试 → 失败 → 渲染完成的表面并可通过a2ui.recovery调节渲染前的 UX 表现。随后用户提供的渲染器数组与内置列表合并[...renderActivityMessagesList, ...builtInActivityRenderers]。因为用户数组在前findRenderer使用filterfind查找第一个匹配项所以同名activityType的用户渲染器必然优先于内置渲染器命中——这正是覆盖内置能力的源码级保证。八、测试与验证react-core 的 e2e 测试为上述行为提供了可复现的验证样例CopilotChatActivityRendering.e2e.test.tsx 覆盖了自定义 Activity 渲染器的注册、agent 作用域渲染以及解析优先级等场景MCPAppsActivityRenderer.e2e.test.tsx 大量使用MCPAppsActivityType常量第 21 行导入并验证了mcp-apps字面量必须与常量一致的约定第 653 行注释明确说明CopilotChatFrontendActivityCard.e2e.test.tsx 演示了前端 Activity 卡片渲染器的典型用法。结语Activity 消息渲染是 CopilotKit 前端栈中Agent 驱动 UI的核心通道在 Provider 层注册ReactActivityMessageRenderer配合useRenderActivityMessage的确定性解析顺序agent 作用域 → 全局 → 通配符 → 空即可将服务端下发的过程性消息映射为任意自定义 React 组件。写作渲染器时牢记三条红线——Schema 必须与服务端载荷严格对齐否则静默失败、副作用必须提升到包装组件因为render以组件方式挂载且随消息列表频繁重渲染、渲染器数组必须保持引用稳定否则触发useStableArrayProp警告。在此基础上你可以自由覆盖内置的mcp-apps/open-generative-ui渲染器构建完全符合业务形态的 Agent 交互界面。【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考