CopilotKit React 能力特性门控指南深入 useCapabilities 与 AgentCapabilities【免费下载链接】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导读useCapabilities是 CopilotKit React 前端copilotkit/react-corev2提供的特性门控feature-gating入口它基于useAgent读取 agent 在 runtime/info响应中声明的能力清单让 UI 可以按“该 agent 是否支持语音转写、工具、流式传输”等能力有选择地渲染。读完本文你将掌握useCapabilities的完整用法、AgentCapabilities的字段语义与声明规则以及三类高危误用的规避方法并能在多 agent 界面中精确地为每个 agent 声明和消费能力。useCapabilities 的定位与工作原理useCapabilities是 react-core skill 中 “Feature-gate UI on declared agent capabilities” 一节对应的核心 hook它建立在同目录的 agent-access.md 所述的useAgent之上。整个数据流可以概括为服务端 agent 通过配置声明自己的能力如是否支持工具、是否支持客户端工具、是否支持流式传输前端在连接 runtime 时通过/info握手拿到这些能力填充到 agent 实例的capabilities字段useCapabilities内部调用useAgent并同步读取该字段返回给组件用于条件渲染。从源码看use-capabilities.tsx 的实现非常精简export function useCapabilities( agentId?: string, ): AgentCapabilities | undefined { const { agent } useAgent({ agentId }); if (agent capabilities in agent) { return (agent as { capabilities?: AgentCapabilities }).capabilities; } return undefined; }值得注意的同步语义这个 hook没有 loading 状态。它从 agent 实例同步读取capabilities字段因此在/info握手完成之前返回值始终是undefined。AgentCapabilities类型来自ag-ui/coreAG-UI 协议客户端核心包是一个 partial 声明——agent 可以只声明部分能力其余字段允许缺失。这一行为在测试中得到了完整覆盖useCapabilities的四个分支agent 暴露 capabilities、agent 无 capabilities 属性、agent 尚未连接、capabilities 显式为 undefined均有对应的单元测试见 use-capabilities.test.tsxAngular 端也有等价的injectCapabilities及其测试 capabilities.spec.ts。快速上手按能力渲染 UIuseCapabilities从copilotkit/react-core/v2导出使用前请确保已在应用根部挂载CopilotKitProvider参见 provider-setup.md。以下是一个“语音录制按钮”示例只有当 agent 声明支持转录transcription时才显示“Record”按钮。use client; import { useCapabilities } from copilotkit/react-core/v2; export function VoiceButton() { const caps useCapabilities(); // 不传参数时默认取 DEFAULT_AGENT_ID // 握手尚未完成——先渲染占位骨架不要急于隐藏 if (caps undefined) return div classNameskeleton h-8 w-8 /; // 握手完成——按能力做特性门控 if (!caps.transcription) return null; return buttonRecord/button; }核心使用模式1. 作用域限定到指定 agentuseCapabilities接受可选的agentId参数。在多 agent 应用中可以为每个 agent 读取其独立声明的能力const caps useCapabilities(research);当省略agentId时hook 会继承外层聊天配置所解析的 agent并回退到默认 agent——这与useAgent的解析规则完全一致测试中mockUseAgent被断言以{ agentId: undefined }调用。2. 用能力门控工具类 UI对于依赖 agent 工具能力的面板应当同时处理“握手未完成”和“能力未声明”两种状态const caps useCapabilities(default); if (caps undefined) return ToolsSkeleton /; if (caps.tools?.supported false) return null; return ToolsPanel /;3. 防御性收窄可选字段因为AgentCapabilities是 partial 声明agent 可以选择不声明某个字段。读取时应使用可选链与空值合并而不是假定字段一定存在const caps useCapabilities(); const maxTokens caps?.maxOutputTokens ?? unknown;AgentCapabilities 的字段结构与默认声明从 runtime 侧实现可以准确还原AgentCapabilities的字段构成。BuiltInAgent在未显式声明能力时会返回一组自动推断的默认值见 packages/runtime/src/agent/index.tsconst inferred: AgentCapabilities { tools: { supported: true, clientProvided: true, }, transport: { streaming: true, }, humanInTheLoop: { interrupts: true, }, };据此可以确认能力按“类别category”组织常见的字段组合包括能力类别字段含义toolssupportedagent 是否支持工具调用toolsclientProvided是否支持浏览器端客户端注册的工具对应useFrontendTooltransportstreaming是否支持流式传输humanInTheLoopinterrupts是否支持人工介入中断/恢复transcription布尔是否支持语音转写本文示例中的caps.transcriptionmaxOutputTokens数值最大输出 token 数上限需要说明的是transcription、maxOutputTokens等字段在文档与示例中出现但并非BuiltInAgent默认推断集合的一部分属于 agent 按需自行声明的能力——这也正是“AgentCapabilities是 partial 声明每个字段都可选”这一设计的意义。常见错误与规避高危把undefined当作“无能力”握手完成前useCapabilities返回undefined。如果把undefined与{ transcription: false }混为一谈功能会在握手期间被永久隐藏。错误写法function VoiceButton() { const caps useCapabilities(); if (!caps?.transcription) return null; // 握手期间按钮被永久隐藏 return buttonRecord/button; }正确写法function VoiceButton() { const caps useCapabilities(); if (caps undefined) return div classNameskeleton h-8 w-8 /; if (!caps.transcription) return null; return buttonRecord/button; }要点caps undefined只意味着“还不知道”应当显示占位只有握手完成后的显式false才意味着“不支持”。实现与注释见 use-capabilities.tsx。中危对可选字段使用非空断言AgentCapabilities的每个字段都可选。caps!.maxOutputTokens在 agent 未声明该字段时会直接崩溃。错误写法const caps useCapabilities(); return divMax tokens: {caps!.maxOutputTokens}/div; // 若 agent 未声明 capabilities或未声明 maxOutputTokens此处崩溃正确写法const caps useCapabilities(); return divMax tokens: {caps?.maxOutputTokens ?? unknown}/div;原则先收窄narrow再解引用deref。中危期望服务端 capabilities 做深合并BuiltInAgent对capabilities配置执行的是类别级别的浅合并——提供某个类别如tools会整体替换该类别而不是仅覆盖其中个别字段。这一点在 packages/runtime/src/agent/index.ts 的注释中有明确说明并在 getCapabilities() 中以“展开 inferred 默认值后再展开显式覆盖”的方式实现// 浅合并显式覆盖在类别级别替换默认值其余类别由 inferred 填充 return { ...inferred, ...capabilities, };错误写法期望clientProvided保留默认值// Server: new BuiltInAgent({ // ... capabilities: { tools: { supported: true } }, }); // 客户端期望 caps.tools.clientProvided 仍为默认的 true —— 实际已被整体替换正确写法提供完整类别// Server — 提供完整的类别字段 new BuiltInAgent({ // ... capabilities: { tools: { supported: true, clientProvided: true } }, });因此在覆盖任一能力类别时必须同时提供该类别下的全部字段客户端看到的将严格等于你声明的内容。这一浅合并语义在ProxiedCopilotRuntimeAgentpackages/core/src/agent.ts中同样被保留——代理类将capabilities原样传递给useCapabilities消费方。小结useCapabilities是连接“服务端能力声明”与“客户端 UI 门控”的桥梁服务端通过BuiltInAgent的capabilities配置声明注意类别级浅合并规则客户端通过/info握手获取后由 hook 同步暴露。使用时牢记三条纪律——先区分undefined未握手与false不支持、对可选字段先收窄再解引用、声明能力时提供完整类别——即可在多 agent 场景下构建既稳健又精确的响应式界面。进一步的配套能力可参考 agent-access.mdagent 访问与订阅与 switching-agents.md多 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），仅供参考