2026/9/10 1:40:59
FEATURED · 精选文章 
CopilotKit Angular 公共 API 契约全解析从导出清单到源码实现【免费下载链接】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/CopilotKitcopilotkit/angular是 CopilotKit 提供的 Angular 22 官方绑定库覆盖聊天、弹窗、侧边栏组件以及基于 signal 的无头 API、工具/活动渲染器、线程、记忆、中断、附件、A2UI、Open Generative UI 与可选的 MCP Apps 支持。本文以 packages/angular/API.md 这份公共导出契约为主线逐层拆解其根入口与 MCP Apps 次入口的全部导出符号、内部扩展点及其背后的实现与测试机制帮助你在集成、定制渲染槽位或维护版本兼容性时能准确判断哪些 API 可安全使用、哪些属于内部实现细节。一、API.md 是什么一份被测试强制的导出契约1.1 契约的定位与约束力API.md是copilotkit/angular的穷举式公共导出契约文档中列出的每一个符号都被视为支持应用层使用的公开 API只有出现在Internal extension points内部扩展点小节下的符号除外。对任一公开符号的移除或不兼容修改都必须走该包标准的破坏性变更流程breaking-change process。这意味着这份文档不是一份普通的 API 速查表而是发布范围的硬约束。配合 packages/angular/package.json 中的build脚本ng-packagr 导出规范化以及ng-package.json中assets: [README.md, API.md]的配置API.md会随包一起发布到 npm成为消费者与维护者共同的契约基准。1.2 测试如何保证清单即事实仓库中的 public-api-documentation.spec.ts 用两个测试用例把文档和真实导出绑定在一起使用 TypeScript 编译器 API 读取src/public-api.ts根入口与src/mcp-apps/index.tsMCP Apps 入口解析出模块的真实导出符号解析API.md中!-- public-api:root:start --/!-- public-api:root:end --与!-- public-api:mcp-apps:start --/!-- public-api:mcp-apps:end --两个标记区间的符号清单断言两者逐一相等且无重复同时校验包内同时携带 README 与 API.md。也就是说任何新增的公共符号若未同步写入 API.md测试会直接失败反之文档里出现一个不存在的导出也会失败。这是文档驱动公共 API的工程化实践值得在你的 Angular 库开发中借鉴。二、根入口copilotkit/angular的完整导出清单从根入口copilotkit/angular导入。完整清单由 API.md 的 root 区块列出可按功能族划分为以下几类下面逐一说明其在项目中的实际角色。2.1 顶层配置与 Provider符号作用provideCopilotKit应用级 Provider注入CopilotKitConfig见下文源码分析COPILOT_KIT_CONFIG/injectCopilotKitConfig配置注入 Token 及对应的 inject 函数CopilotKitConfigprovideCopilotKit接受的完整配置接口A2UIConfig/A2UIDebugExposure/A2UILifecycleContent/A2UILifecycleStatus/A2UIRecoveryOptionsA2UIAG-UI 生成式 UI的主题、目录、生命周期与恢复策略配置OpenGenerativeUIConfig/OpenGenerativeUIContent/OpenGenerativeUIContentSchemaOpen Generative UI 沙箱化 UI 函数配置FrontendToolConfig/ClientTool/HumanInTheLoopConfig前端工具、运行时工具广告与人工介入工具配置RenderToolCallConfig/RenderActivityMessageConfig/SuggestionsConfig含StaticSuggestionsConfig、DynamicSuggestionsConfig工具调用渲染、活动消息渲染与建议配置SLOT_CONFIG/SlotConfig/SlotContext/SlotOutputs/SlotValue/SlotRegistryEntry聊天槽位slot体系配置2.2 组件与渲染器预置 UI 全部为独立standaloneAngular 组件包含顶层容器CopilotKit服务/根、CopilotChat全页聊天、CopilotPopup浮动弹窗、CopilotSidebar侧边栏支持docked/overlay模式与左右位置见CopilotSidebarMode、CopilotSidebarPosition消息视图族CopilotChatView、CopilotChatMessageView、CopilotChatUserMessage、CopilotChatAssistantMessage、CopilotChatReasoningMessage及其*Renderer、*Toolbar、按钮与分支导航组件如CopilotChatUserMessageBranchNavigation、CopilotChatMessageViewCursor输入与交互CopilotChatInput、CopilotChatTextarea、CopilotChatSendButton、CopilotChatToolbar及按钮族、CopilotChatSuggestionPill/CopilotChatSuggestionView、CopilotChatToolsMenu、CopilotChatAudioRecorder含开始/取消/结束转写按钮附件体系CopilotChatAttachmentQueue、CopilotChatAttachmentRenderer、CopilotChatAttachmentsDirective及Attachment/AttachmentModality/AttachmentsConfig/AttachmentUploadError/AttachmentUploadResult类型渲染器CopilotActivity、CopilotDefaultToolRenderer、ToolRenderer、ActivityRenderer、CopilotA2UIActivityRenderer、CopilotA2UIToolRenderer、CopilotA2UIProgress、CopilotA2UIRecovery、CopilotOpenGenerativeUI*Renderer、HumanInTheLoopToolRenderer指令与工具CopilotSlot槽位、CopilotThreadsDrawer/CopilotThreadsDrawerRow、CopilotTooltip、ResizeObserverService、StickToBottom、cn等。2.3 无头HeadlessAPIinject 系列与 register 系列这是大多数应用真正需要的高层 API 入口文档明确点名injectAgentStore注入SignalAgentStore驱动消息/状态/运行中信号injectCapabilities读取解析后 AG-UI agent 声明的能力injectCopilotKitConfig、injectChatConfiguration、injectChatLabels、injectChatState注入配置、标签与聊天状态injectInterrupt、injectMemories、injectThreads中断、记忆与线程控制器registerFrontendTool、registerRenderToolCall、registerHumanInTheLoop、registerComponent、registerRenderActivityMessage、registerRenderToolCall在注入上下文中注册工具/渲染器/组件provideCopilotChatConfiguration、provideCopilotChatLabels、provideSlots声明式提供聊天配置connectAgentContext、renderSlot、createSlotConfig、getSlotConfig、createSlotRenderer、withSlots、isComponentType、isSlotValue、normalizeSlotValue上下文连接与槽位工具parseToolCallArguments、pickToolCallHandler、safeToolValue工具调用解析辅助transcribeAudio、readA2UILifecycleContent语音转写与 A2UI 生命周期内容读取。2.4 类型与常量包括Message、AssistantMessage、AngularToolCall、Thread、Memory族NewMemory/MemoryChanges/MemoryKind/MemoryScope、ChatState、AgentStore、ThreadsStore、InterruptController/InterruptEvent/InterruptExpiredError/InterruptHandlerProps/InterruptView/InterruptRunOptions、TranscriptionError族、ScrollBehavior/ScrollPosition/ScrollState、以及工具名常量如AGUI_SEND_STATE_SNAPSHOT_TOOL_NAME、RENDER_A2UI_TOOL_NAME、OPEN_GENERATIVE_UI_ACTIVITY_TYPE、GENERATE_SANDBOXED_UI_TOOL_NAME、GENERATE_SANDBOXED_UI_DESCRIPTION、DEFAULT_OPEN_GENERATIVE_UI_DESIGN_SKILL等。这些常量由运行时工具调用协议使用可在自定义渲染器中直接引用。2.5 内部扩展点ɵ前缀符号文档在 root 区块末尾明确列出两个仅限内部使用的 DI TokenɵCOPILOTKIT_BUILT_IN_ACTIVITY_RENDERERSɵCOPILOTKIT_INSPECTOR_DEVELOPMENT_MODE它们只服务于 CopilotKit 自身维护的代码Inspector 开发模式与内置渲染器钩子。ɵ前缀与 TSDoc 标记共同表明其内部属性应用代码不得依赖它们。这一点也在 public-api.ts 中体现——ɵCOPILOTKIT_INSPECTOR_DEVELOPMENT_MODE被显式单独 re-export而非随export *混入。三、配置的源码级展开provideCopilotKit与CopilotKitConfigprovideCopilotKit是几乎所有集成场景的起点。从 config.ts 的实现看它不仅仅是把配置对象注册为COPILOT_KIT_CONFIG注入 Token还包含许可证校验与请求头注入逻辑若headers中已存在X-CopilotCloud-Public-Api-Key则保留否则若配置了合法格式ck_pub_前缀 32 位十六进制的licenseKey会自动将其合并进headers当LICENSE_WATERMARK_ENABLED且无有效 key 时会在控制台输出一次性水印警告。因此应用层配置headers与licenseKey时的行为是一致的无需重复设置。完整的CopilotKitConfig字段与 README.md 中给出的接口一致字段类型说明runtimeUrlstringCopilotKit 运行时端点地址headersRecordstring, string发往运行时的默认请求头credentialsRequestCredentialsFetch credentials 模式跨域携带 HTTP-only Cookie 时用includelicenseKeystringCopilotCloud 许可证 key可自动注入请求头propertiesRecordstring, unknown转发给 agent 运行的任意属性agentsRecordstring, AbstractAgent本地浏览器内 agent按agentId索引selfManagedAgentsRecordstring, AbstractAgent由应用直接管理的 AG-UI agenttoolsClientTool[]仅向运行时广告的工具定义无 handlerrenderToolCallsRenderToolCallConfig[]渲染工具调用的组件renderActivityMessagesRenderActivityMessageConfig[]渲染 AG-UI activity 消息的组件suggestionsConfigSuggestionsConfig[]静态或运行时生成的聊天建议frontendToolsFrontendToolConfig[]带 handler 的客户端工具humanInTheLoopHumanInTheLoopConfig[]会暂停等待用户输入的工具defaultToolRenderingboolean是否用纯文本渲染器兜底未知工具默认关闭让缺失渲染器暴露为集成错误而非静默降级a2uiA2UIConfigA2UI 主题、目录、schema、加载 UI 与恢复策略openGenerativeUIOpenGenerativeUIConfig沙箱化 UI 函数与可选的生成 UI 设计指引enableInspectorboolean开发模式下禁用 CopilotKit Inspector默认开发浏览器构建启用生产与 SSR 恒禁用A2UIRecoveryOptions中showAfterMs默认2000ms、showAfterAttempts默认2debugExposure支持hidden | collapsed | verbose客户端诊断可见性可被服务端生命周期内容覆盖。四、无头核心injectAgentStore、injectCapabilities与CopilotKit服务4.1injectAgentStoresignal 化的 AgentStoreinjectAgentStore(default)也接受injectAgentStore(signal(agentId))返回SignalAgentStore。从 agent.ts 的实现可以看到AgentStore的核心形态agent底层AbstractAgentAG-UI 协议 agentmessagesSignalMessage[]消息变更同步stateSignalunknown快照拷贝数组/对象会浅拷贝以避免意外共享引用isRunningSignalboolean由onRunInitialized/onRunFinalized/onRunFailed/onRunErrorEvent等订阅回调驱动interruptController绑定到该 store agent 的中断控制器teardown()公开的清理方法订阅、DestroyRef 回调与中断控制器一并销毁。构造时会对abstractAgent的现有消息与状态做同步种子填充保证首帧渲染即完整而非等待后续可能不会发生的变更事件——这是一个值得注意的响应式时序细节。4.2 代理provisionalagent 与运行时发现injectAgentStore的实现createAgentStoreSignal是理解其行为的钥匙若本地已注册对应agentId的 agent直接使用并通过AgentHandoffBridge做归属移交若未找到本地 agent 但配置了runtimeUrl且运行时尚未连接完成则创建一个ProxiedCopilotRuntimeAgent作为临时代理并在运行时发现真实 agent 后通过 handoff 桥双向镜像消息、状态与运行状态若仍无法解析抛出包含runtimeUrl与已知 agent ID 列表的错误信息。对响应式读者来说computed会同时追踪agents()、runtimeConnectionStatus()、runtimeUrl()、runtimeTransport()、headers()、credentials()等信号任何变化都会触发 agent 重新解析。换 agentsignal 化 agentId 变化时旧 store 会被 teardown 后再连接新 agent。4.3injectCapabilities与CopilotKit服务capabilities.ts 中injectCapabilities(agentId?)返回SignalAgentCapabilities | undefined省略 agentId 时使用环境聊天配置再回退默认 agent若 agent 上存在capabilities字段则读取。A2UI 等能力开关即依赖这类运行时宣告。CopilotKit服务inject(CopilotKit)暴露只读 signalagents、runtimeConnectionStatus、runtimeUrl、runtimeTransportrest | single、headers、credentials、toolCallRenderConfigs等、运行时方法getAgent、addFrontendTool、addRenderToolCall、addHumanInTheLoop、removeTool、updateRuntime以及底层coreCopilotKitCore实例。需要动态修改运行时配置时调用CopilotKit.updateRuntime(...)。4.4 工具注册三件套registerFrontendTool/registerRenderToolCall/registerHumanInTheLoop必须在注入上下文组件构造器、指令或runInInjectionContext中调用订阅与运行时注册会绑定到所属DestroyRef上下文销毁时自动注销。对应的配置类型见 README.mdexport interface RenderToolCallConfigArgs { name: string; // 工具名或 * 表示通配 args: z.ZodTypeArgs; // 参数 Zod schema component: TypeToolRendererArgs; agentId?: string; // 可选 agent 作用域 } export interface FrontendToolConfigArgs { name: string; description: string; parameters: z.ZodTypeArgs; component?: TypeToolRendererArgs; // 可选 UI 渲染器 handler: (args: Args, context: FrontendToolHandlerContext) Promiseunknown; agentId?: string; } export interface HumanInTheLoopConfigArgs { name: string; description: string; parameters: z.ZodTypeArgs; component: TypeHumanInTheLoopToolRendererArgs; agentId?: string; }渲染器组件接收一个 signalToolRenderer暴露toolCall: SignalAngularToolCallArgsHumanInTheLoopToolRenderer暴露SignalHumanInTheLoopToolCallArgs额外含respond(result)。AngularToolCall/HumanInTheLoopToolCall提供args、statusin-progress | executing | complete与result。五、中断、线程、记忆与附件inject*控制器族API.md 清单中的injectInterrupt、injectThreads、injectMemories是三类典型的状态化控制器中断injectInterrupt配合 interrupt.ts 中的InjectInterruptOptionsagentId、enabled过滤器、handler预处理、InterruptView含result的响应式视图与InterruptExpiredError使用。InterruptEvent承载{ name, value }InterruptRunOptions支持runId、resumeResumeEntry[]与forwardedProps。应用在控制器离开视图后不应再 resolve 中断。线程injectThreadsInjectThreadsInput/InjectThreadsResult、ThreadsStore与CopilotThreadsDrawer构成线程列表/恢复体系支持会话恢复与active-thread-connector同步。记忆injectMemories、MemoriesController与Memory族类型MemoryKind、MemoryScope、MemoryChanges、NewMemory负责 agent 记忆的读写与订阅。这些控制器同样要求从注入上下文创建生命周期绑定DestroyRef。附件与语音相关导出AttachmentsConfig、AudioRecorderState、AudioRecorderError、TranscriptionError/TranscriptionErrorCode/TranscriptionResult、transcribeAudio则支撑富输入体验。六、槽位Slots体系可替换的聊天组成原语文档强调除高层组件外其余组件与上下文类型是受支持的定制原语用于替换单个聊天槽位chat slot。该体系由以下符号支撑SLOT_CONFIGToken、SlotConfig、SlotContext、SlotOutputs、SlotValue、SlotRegistryEntry工具函数createSlotConfig、getSlotConfig、renderSlot、createSlotRenderer、normalizeSlotValue、isSlotValue、withSlots、isComponentTypeprovideSlots、RegisterComponentConfig、RenderSlotOptions、CopilotSlot组件。WithSlots高阶能力让你在保留默认聊天组合的前提下把输入区、消息气泡、工具栏、按钮等槽位替换成自定义实现。对应实现位于 src/lib/slotscopilot-slot.ts、slot.types.ts、slot.utils.ts与registerComponent注册机制。七、MCP Apps 次入口copilotkit/angular/mcp-appsMCP Apps 被刻意设计为独立的次入口目的是不让其沙箱与协议代码进入未启用该功能的应用包体积。从package.json的exports映射可见copilotkit/angular/mcp-apps指向独立的fesm2022/copilotkit-angular-mcp-apps.mjs与类型声明文件。该入口的导出来自 src/mcp-apps/index.tsprovideMCPApps()首选的 Provider 启用方式CopilotMCPAppsWidgetMCP Apps 内嵌组件CopilotMCPAppsActivityRenderer/mcpAppsActivityRendererConfig活动渲染器DEFAULT_MCP_APPS_CONFIG/MCP_APPS_CONFIG/MCPAppsConfig/MCPAppsHostInfo配置与宿主信息MCPAppsSnapshotContent/mcpAppsSnapshotContentSchema快照内容与校验 schema。关键的运行时语义README 与 API.md 一致确认MCP 资源与工具请求经由所选 AG-UI agent 转发浏览器端 Provider 不接受服务器 URL渲染器使用与 React SDK 相同的内联srcdoc代理、沙箱权限与资源域 CSPContent Security Policy。启用步骤在应用 providers 中加入provideMCPApps()高级宿主/渲染器/协议测试能力从copilotkit/angular/mcp-apps导入。八、生命周期、SSR 与 zoneless 实践约束API.md 之外的工程约束在 README.md 中明确同样影响 API 的正确使用方式注入上下文要求injectAgentStore、connectAgentContext、registerFrontendTool、registerRenderToolCall、registerRenderActivityMessage、injectInterrupt、injectThreads、injectMemories都必须在 Angular 注入上下文中调用禁止在模块级代码创建也不要把注入的控制器缓存到超出其 injector 生命周期之外。AgentStore.teardown()仅面向手动构建的 storeinjectAgentStore返回的 store 自动清理。zoneless 兼容包面向 standalone、OnPush、signal 化应用测试覆盖provideZonelessChangeDetection()无 Zone.js 依赖应用状态应放 signal 或 Angular outputs 中才能被 zoneless 变更检测观察。SSR/hydration服务端与客户端首渲染需提供一致的配置与初始open/agentId服务端渲染期间不得访问返回的 agent 或运行工具跨源时运行时 URL 使用绝对地址或同源/api/copilotkit代理A2UI、Open Generative UI、音频录制与 MCP Apps 应在浏览器侧启用其沙箱/媒体/iframe 在 hydration 后激活hydration 前不要基于window分支组件树。运行时连接runtimeUrl指向 CopilotKit 运行时端点runtimeTransport支持rest与singleSSE 单流跨域 Cookie 认证用credentials: include并为应用精确 origin 开启 credentialed CORS。九、总结如何用好这份契约API.md的价值在于把公共 API 边界变成可验证、可发布、可审计的工程产物。实际集成时可以按此路径收敛起步provideCopilotKit({ runtimeUrl, headers, ... })注册运行时导入copilotkit/angular/styles.css快速 UI直接使用CopilotChat、CopilotPopup、CopilotSidebaropen为模型信号支持[(open)]受控绑定定制体验用injectAgentStore构建无头聊天或用renderToolCalls、registerRenderToolCall、registerRenderActivityMessage、provideSlots逐槽位替换默认组合高级能力injectInterrupt/injectThreads/injectMemories接续会话与人工介入a2ui、openGenerativeUI、provideMCPApps()按需启用生成式 UI 与 MCP Apps后者从次入口导入合规底线以 API.md 清单为准判断符号是否公共看到ɵ前缀立即视为内部实现避免依赖。无论你是首次集成还是正在维护基于copilotkit/angular的组件库packages/angular/API.md 与 packages/angular/README.md 都是权威依据而 public-api-documentation.spec.ts 的测试模式本身就是文档与实现不脱节的最佳范本。【免费下载链接】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），仅供参考
CopilotKit Angular 公共 API 契约全解析：从导出清单到源码实现
CopilotKit Angular 公共 API 契约全解析从导出清单到源码实现【免费下载链接】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/CopilotKitcopilotkit/angular是 CopilotKit 提供的 Angular 22 官方绑定库覆盖聊天、弹窗、侧边栏组件以及基于 signal 的无头 API、工具/活动渲染器、线程、记忆、中断、附件、A2UI、Open Generative UI 与可选的 MCP Apps 支持。本文以 packages/angular/API.md 这份公共导出契约为主线逐层拆解其根入口与 MCP Apps 次入口的全部导出符号、内部扩展点及其背后的实现与测试机制帮助你在集成、定制渲染槽位或维护版本兼容性时能准确判断哪些 API 可安全使用、哪些属于内部实现细节。一、API.md 是什么一份被测试强制的导出契约1.1 契约的定位与约束力API.md是copilotkit/angular的穷举式公共导出契约文档中列出的每一个符号都被视为支持应用层使用的公开 API只有出现在Internal extension points内部扩展点小节下的符号除外。对任一公开符号的移除或不兼容修改都必须走该包标准的破坏性变更流程breaking-change process。这意味着这份文档不是一份普通的 API 速查表而是发布范围的硬约束。配合 packages/angular/package.json 中的build脚本ng-packagr 导出规范化以及ng-package.json中assets: [README.md, API.md]的配置API.md会随包一起发布到 npm成为消费者与维护者共同的契约基准。1.2 测试如何保证清单即事实仓库中的 public-api-documentation.spec.ts 用两个测试用例把文档和真实导出绑定在一起使用 TypeScript 编译器 API 读取src/public-api.ts根入口与src/mcp-apps/index.tsMCP Apps 入口解析出模块的真实导出符号解析API.md中!-- public-api:root:start --/!-- public-api:root:end --与!-- public-api:mcp-apps:start --/!-- public-api:mcp-apps:end --两个标记区间的符号清单断言两者逐一相等且无重复同时校验包内同时携带 README 与 API.md。也就是说任何新增的公共符号若未同步写入 API.md测试会直接失败反之文档里出现一个不存在的导出也会失败。这是文档驱动公共 API的工程化实践值得在你的 Angular 库开发中借鉴。二、根入口copilotkit/angular的完整导出清单从根入口copilotkit/angular导入。完整清单由 API.md 的 root 区块列出可按功能族划分为以下几类下面逐一说明其在项目中的实际角色。2.1 顶层配置与 Provider符号作用provideCopilotKit应用级 Provider注入CopilotKitConfig见下文源码分析COPILOT_KIT_CONFIG/injectCopilotKitConfig配置注入 Token 及对应的 inject 函数CopilotKitConfigprovideCopilotKit接受的完整配置接口A2UIConfig/A2UIDebugExposure/A2UILifecycleContent/A2UILifecycleStatus/A2UIRecoveryOptionsA2UIAG-UI 生成式 UI的主题、目录、生命周期与恢复策略配置OpenGenerativeUIConfig/OpenGenerativeUIContent/OpenGenerativeUIContentSchemaOpen Generative UI 沙箱化 UI 函数配置FrontendToolConfig/ClientTool/HumanInTheLoopConfig前端工具、运行时工具广告与人工介入工具配置RenderToolCallConfig/RenderActivityMessageConfig/SuggestionsConfig含StaticSuggestionsConfig、DynamicSuggestionsConfig工具调用渲染、活动消息渲染与建议配置SLOT_CONFIG/SlotConfig/SlotContext/SlotOutputs/SlotValue/SlotRegistryEntry聊天槽位slot体系配置2.2 组件与渲染器预置 UI 全部为独立standaloneAngular 组件包含顶层容器CopilotKit服务/根、CopilotChat全页聊天、CopilotPopup浮动弹窗、CopilotSidebar侧边栏支持docked/overlay模式与左右位置见CopilotSidebarMode、CopilotSidebarPosition消息视图族CopilotChatView、CopilotChatMessageView、CopilotChatUserMessage、CopilotChatAssistantMessage、CopilotChatReasoningMessage及其*Renderer、*Toolbar、按钮与分支导航组件如CopilotChatUserMessageBranchNavigation、CopilotChatMessageViewCursor输入与交互CopilotChatInput、CopilotChatTextarea、CopilotChatSendButton、CopilotChatToolbar及按钮族、CopilotChatSuggestionPill/CopilotChatSuggestionView、CopilotChatToolsMenu、CopilotChatAudioRecorder含开始/取消/结束转写按钮附件体系CopilotChatAttachmentQueue、CopilotChatAttachmentRenderer、CopilotChatAttachmentsDirective及Attachment/AttachmentModality/AttachmentsConfig/AttachmentUploadError/AttachmentUploadResult类型渲染器CopilotActivity、CopilotDefaultToolRenderer、ToolRenderer、ActivityRenderer、CopilotA2UIActivityRenderer、CopilotA2UIToolRenderer、CopilotA2UIProgress、CopilotA2UIRecovery、CopilotOpenGenerativeUI*Renderer、HumanInTheLoopToolRenderer指令与工具CopilotSlot槽位、CopilotThreadsDrawer/CopilotThreadsDrawerRow、CopilotTooltip、ResizeObserverService、StickToBottom、cn等。2.3 无头HeadlessAPIinject 系列与 register 系列这是大多数应用真正需要的高层 API 入口文档明确点名injectAgentStore注入SignalAgentStore驱动消息/状态/运行中信号injectCapabilities读取解析后 AG-UI agent 声明的能力injectCopilotKitConfig、injectChatConfiguration、injectChatLabels、injectChatState注入配置、标签与聊天状态injectInterrupt、injectMemories、injectThreads中断、记忆与线程控制器registerFrontendTool、registerRenderToolCall、registerHumanInTheLoop、registerComponent、registerRenderActivityMessage、registerRenderToolCall在注入上下文中注册工具/渲染器/组件provideCopilotChatConfiguration、provideCopilotChatLabels、provideSlots声明式提供聊天配置connectAgentContext、renderSlot、createSlotConfig、getSlotConfig、createSlotRenderer、withSlots、isComponentType、isSlotValue、normalizeSlotValue上下文连接与槽位工具parseToolCallArguments、pickToolCallHandler、safeToolValue工具调用解析辅助transcribeAudio、readA2UILifecycleContent语音转写与 A2UI 生命周期内容读取。2.4 类型与常量包括Message、AssistantMessage、AngularToolCall、Thread、Memory族NewMemory/MemoryChanges/MemoryKind/MemoryScope、ChatState、AgentStore、ThreadsStore、InterruptController/InterruptEvent/InterruptExpiredError/InterruptHandlerProps/InterruptView/InterruptRunOptions、TranscriptionError族、ScrollBehavior/ScrollPosition/ScrollState、以及工具名常量如AGUI_SEND_STATE_SNAPSHOT_TOOL_NAME、RENDER_A2UI_TOOL_NAME、OPEN_GENERATIVE_UI_ACTIVITY_TYPE、GENERATE_SANDBOXED_UI_TOOL_NAME、GENERATE_SANDBOXED_UI_DESCRIPTION、DEFAULT_OPEN_GENERATIVE_UI_DESIGN_SKILL等。这些常量由运行时工具调用协议使用可在自定义渲染器中直接引用。2.5 内部扩展点ɵ前缀符号文档在 root 区块末尾明确列出两个仅限内部使用的 DI TokenɵCOPILOTKIT_BUILT_IN_ACTIVITY_RENDERERSɵCOPILOTKIT_INSPECTOR_DEVELOPMENT_MODE它们只服务于 CopilotKit 自身维护的代码Inspector 开发模式与内置渲染器钩子。ɵ前缀与 TSDoc 标记共同表明其内部属性应用代码不得依赖它们。这一点也在 public-api.ts 中体现——ɵCOPILOTKIT_INSPECTOR_DEVELOPMENT_MODE被显式单独 re-export而非随export *混入。三、配置的源码级展开provideCopilotKit与CopilotKitConfigprovideCopilotKit是几乎所有集成场景的起点。从 config.ts 的实现看它不仅仅是把配置对象注册为COPILOT_KIT_CONFIG注入 Token还包含许可证校验与请求头注入逻辑若headers中已存在X-CopilotCloud-Public-Api-Key则保留否则若配置了合法格式ck_pub_前缀 32 位十六进制的licenseKey会自动将其合并进headers当LICENSE_WATERMARK_ENABLED且无有效 key 时会在控制台输出一次性水印警告。因此应用层配置headers与licenseKey时的行为是一致的无需重复设置。完整的CopilotKitConfig字段与 README.md 中给出的接口一致字段类型说明runtimeUrlstringCopilotKit 运行时端点地址headersRecordstring, string发往运行时的默认请求头credentialsRequestCredentialsFetch credentials 模式跨域携带 HTTP-only Cookie 时用includelicenseKeystringCopilotCloud 许可证 key可自动注入请求头propertiesRecordstring, unknown转发给 agent 运行的任意属性agentsRecordstring, AbstractAgent本地浏览器内 agent按agentId索引selfManagedAgentsRecordstring, AbstractAgent由应用直接管理的 AG-UI agenttoolsClientTool[]仅向运行时广告的工具定义无 handlerrenderToolCallsRenderToolCallConfig[]渲染工具调用的组件renderActivityMessagesRenderActivityMessageConfig[]渲染 AG-UI activity 消息的组件suggestionsConfigSuggestionsConfig[]静态或运行时生成的聊天建议frontendToolsFrontendToolConfig[]带 handler 的客户端工具humanInTheLoopHumanInTheLoopConfig[]会暂停等待用户输入的工具defaultToolRenderingboolean是否用纯文本渲染器兜底未知工具默认关闭让缺失渲染器暴露为集成错误而非静默降级a2uiA2UIConfigA2UI 主题、目录、schema、加载 UI 与恢复策略openGenerativeUIOpenGenerativeUIConfig沙箱化 UI 函数与可选的生成 UI 设计指引enableInspectorboolean开发模式下禁用 CopilotKit Inspector默认开发浏览器构建启用生产与 SSR 恒禁用A2UIRecoveryOptions中showAfterMs默认2000ms、showAfterAttempts默认2debugExposure支持hidden | collapsed | verbose客户端诊断可见性可被服务端生命周期内容覆盖。四、无头核心injectAgentStore、injectCapabilities与CopilotKit服务4.1injectAgentStoresignal 化的 AgentStoreinjectAgentStore(default)也接受injectAgentStore(signal(agentId))返回SignalAgentStore。从 agent.ts 的实现可以看到AgentStore的核心形态agent底层AbstractAgentAG-UI 协议 agentmessagesSignalMessage[]消息变更同步stateSignalunknown快照拷贝数组/对象会浅拷贝以避免意外共享引用isRunningSignalboolean由onRunInitialized/onRunFinalized/onRunFailed/onRunErrorEvent等订阅回调驱动interruptController绑定到该 store agent 的中断控制器teardown()公开的清理方法订阅、DestroyRef 回调与中断控制器一并销毁。构造时会对abstractAgent的现有消息与状态做同步种子填充保证首帧渲染即完整而非等待后续可能不会发生的变更事件——这是一个值得注意的响应式时序细节。4.2 代理provisionalagent 与运行时发现injectAgentStore的实现createAgentStoreSignal是理解其行为的钥匙若本地已注册对应agentId的 agent直接使用并通过AgentHandoffBridge做归属移交若未找到本地 agent 但配置了runtimeUrl且运行时尚未连接完成则创建一个ProxiedCopilotRuntimeAgent作为临时代理并在运行时发现真实 agent 后通过 handoff 桥双向镜像消息、状态与运行状态若仍无法解析抛出包含runtimeUrl与已知 agent ID 列表的错误信息。对响应式读者来说computed会同时追踪agents()、runtimeConnectionStatus()、runtimeUrl()、runtimeTransport()、headers()、credentials()等信号任何变化都会触发 agent 重新解析。换 agentsignal 化 agentId 变化时旧 store 会被 teardown 后再连接新 agent。4.3injectCapabilities与CopilotKit服务capabilities.ts 中injectCapabilities(agentId?)返回SignalAgentCapabilities | undefined省略 agentId 时使用环境聊天配置再回退默认 agent若 agent 上存在capabilities字段则读取。A2UI 等能力开关即依赖这类运行时宣告。CopilotKit服务inject(CopilotKit)暴露只读 signalagents、runtimeConnectionStatus、runtimeUrl、runtimeTransportrest | single、headers、credentials、toolCallRenderConfigs等、运行时方法getAgent、addFrontendTool、addRenderToolCall、addHumanInTheLoop、removeTool、updateRuntime以及底层coreCopilotKitCore实例。需要动态修改运行时配置时调用CopilotKit.updateRuntime(...)。4.4 工具注册三件套registerFrontendTool/registerRenderToolCall/registerHumanInTheLoop必须在注入上下文组件构造器、指令或runInInjectionContext中调用订阅与运行时注册会绑定到所属DestroyRef上下文销毁时自动注销。对应的配置类型见 README.mdexport interface RenderToolCallConfigArgs { name: string; // 工具名或 * 表示通配 args: z.ZodTypeArgs; // 参数 Zod schema component: TypeToolRendererArgs; agentId?: string; // 可选 agent 作用域 } export interface FrontendToolConfigArgs { name: string; description: string; parameters: z.ZodTypeArgs; component?: TypeToolRendererArgs; // 可选 UI 渲染器 handler: (args: Args, context: FrontendToolHandlerContext) Promiseunknown; agentId?: string; } export interface HumanInTheLoopConfigArgs { name: string; description: string; parameters: z.ZodTypeArgs; component: TypeHumanInTheLoopToolRendererArgs; agentId?: string; }渲染器组件接收一个 signalToolRenderer暴露toolCall: SignalAngularToolCallArgsHumanInTheLoopToolRenderer暴露SignalHumanInTheLoopToolCallArgs额外含respond(result)。AngularToolCall/HumanInTheLoopToolCall提供args、statusin-progress | executing | complete与result。五、中断、线程、记忆与附件inject*控制器族API.md 清单中的injectInterrupt、injectThreads、injectMemories是三类典型的状态化控制器中断injectInterrupt配合 interrupt.ts 中的InjectInterruptOptionsagentId、enabled过滤器、handler预处理、InterruptView含result的响应式视图与InterruptExpiredError使用。InterruptEvent承载{ name, value }InterruptRunOptions支持runId、resumeResumeEntry[]与forwardedProps。应用在控制器离开视图后不应再 resolve 中断。线程injectThreadsInjectThreadsInput/InjectThreadsResult、ThreadsStore与CopilotThreadsDrawer构成线程列表/恢复体系支持会话恢复与active-thread-connector同步。记忆injectMemories、MemoriesController与Memory族类型MemoryKind、MemoryScope、MemoryChanges、NewMemory负责 agent 记忆的读写与订阅。这些控制器同样要求从注入上下文创建生命周期绑定DestroyRef。附件与语音相关导出AttachmentsConfig、AudioRecorderState、AudioRecorderError、TranscriptionError/TranscriptionErrorCode/TranscriptionResult、transcribeAudio则支撑富输入体验。六、槽位Slots体系可替换的聊天组成原语文档强调除高层组件外其余组件与上下文类型是受支持的定制原语用于替换单个聊天槽位chat slot。该体系由以下符号支撑SLOT_CONFIGToken、SlotConfig、SlotContext、SlotOutputs、SlotValue、SlotRegistryEntry工具函数createSlotConfig、getSlotConfig、renderSlot、createSlotRenderer、normalizeSlotValue、isSlotValue、withSlots、isComponentTypeprovideSlots、RegisterComponentConfig、RenderSlotOptions、CopilotSlot组件。WithSlots高阶能力让你在保留默认聊天组合的前提下把输入区、消息气泡、工具栏、按钮等槽位替换成自定义实现。对应实现位于 src/lib/slotscopilot-slot.ts、slot.types.ts、slot.utils.ts与registerComponent注册机制。七、MCP Apps 次入口copilotkit/angular/mcp-appsMCP Apps 被刻意设计为独立的次入口目的是不让其沙箱与协议代码进入未启用该功能的应用包体积。从package.json的exports映射可见copilotkit/angular/mcp-apps指向独立的fesm2022/copilotkit-angular-mcp-apps.mjs与类型声明文件。该入口的导出来自 src/mcp-apps/index.tsprovideMCPApps()首选的 Provider 启用方式CopilotMCPAppsWidgetMCP Apps 内嵌组件CopilotMCPAppsActivityRenderer/mcpAppsActivityRendererConfig活动渲染器DEFAULT_MCP_APPS_CONFIG/MCP_APPS_CONFIG/MCPAppsConfig/MCPAppsHostInfo配置与宿主信息MCPAppsSnapshotContent/mcpAppsSnapshotContentSchema快照内容与校验 schema。关键的运行时语义README 与 API.md 一致确认MCP 资源与工具请求经由所选 AG-UI agent 转发浏览器端 Provider 不接受服务器 URL渲染器使用与 React SDK 相同的内联srcdoc代理、沙箱权限与资源域 CSPContent Security Policy。启用步骤在应用 providers 中加入provideMCPApps()高级宿主/渲染器/协议测试能力从copilotkit/angular/mcp-apps导入。八、生命周期、SSR 与 zoneless 实践约束API.md 之外的工程约束在 README.md 中明确同样影响 API 的正确使用方式注入上下文要求injectAgentStore、connectAgentContext、registerFrontendTool、registerRenderToolCall、registerRenderActivityMessage、injectInterrupt、injectThreads、injectMemories都必须在 Angular 注入上下文中调用禁止在模块级代码创建也不要把注入的控制器缓存到超出其 injector 生命周期之外。AgentStore.teardown()仅面向手动构建的 storeinjectAgentStore返回的 store 自动清理。zoneless 兼容包面向 standalone、OnPush、signal 化应用测试覆盖provideZonelessChangeDetection()无 Zone.js 依赖应用状态应放 signal 或 Angular outputs 中才能被 zoneless 变更检测观察。SSR/hydration服务端与客户端首渲染需提供一致的配置与初始open/agentId服务端渲染期间不得访问返回的 agent 或运行工具跨源时运行时 URL 使用绝对地址或同源/api/copilotkit代理A2UI、Open Generative UI、音频录制与 MCP Apps 应在浏览器侧启用其沙箱/媒体/iframe 在 hydration 后激活hydration 前不要基于window分支组件树。运行时连接runtimeUrl指向 CopilotKit 运行时端点runtimeTransport支持rest与singleSSE 单流跨域 Cookie 认证用credentials: include并为应用精确 origin 开启 credentialed CORS。九、总结如何用好这份契约API.md的价值在于把公共 API 边界变成可验证、可发布、可审计的工程产物。实际集成时可以按此路径收敛起步provideCopilotKit({ runtimeUrl, headers, ... })注册运行时导入copilotkit/angular/styles.css快速 UI直接使用CopilotChat、CopilotPopup、CopilotSidebaropen为模型信号支持[(open)]受控绑定定制体验用injectAgentStore构建无头聊天或用renderToolCalls、registerRenderToolCall、registerRenderActivityMessage、provideSlots逐槽位替换默认组合高级能力injectInterrupt/injectThreads/injectMemories接续会话与人工介入a2ui、openGenerativeUI、provideMCPApps()按需启用生成式 UI 与 MCP Apps后者从次入口导入合规底线以 API.md 清单为准判断符号是否公共看到ɵ前缀立即视为内部实现避免依赖。无论你是首次集成还是正在维护基于copilotkit/angular的组件库packages/angular/API.md 与 packages/angular/README.md 都是权威依据而 public-api-documentation.spec.ts 的测试模式本身就是文档与实现不脱节的最佳范本。【免费下载链接】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），仅供参考 
