CopilotKit Angular 包 1.5x 演进全解析：运行时传输自动检测、推理消息组件与前端工具集成-平芜编程栈

CopilotKit Angular 包 1.5x 演进全解析：运行时传输自动检测、推理消息组件与前端工具集成

【免费下载链接】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

本篇技术指南以仓库中 packages/angular/CHANGELOG.md 为主体脉络，系统梳理@copilotkit/angular从 1.51.0 到 1.54.3 的版本演进，重点解读运行时传输（REST 与 SSE 单流）自动检测、reasoning 推理消息的默认组件、前端工具与 Core 的深度集成，以及 MCP/A2UI 中间件直接从 CopilotKit 运行时启用等关键能力。读完你不仅能读懂这份 CHANGELOG，还能结合 packages/angular/src 下的源码定位每个能力对应的实现文件与测试，为升级选型与二次开发提供依据。

版本演进全景：1.5x 系列在改什么

@copilotkit/angular是 CopilotKit 在 Angular 生态的一等公民绑定包，随 packages/angular/README.md 所述，提供独立 Chat / Popup / Sidebar 组件、基于 Signal 的 headless API、工具与活动渲染器、线程、记忆、中断、附件、A2UI、Open Generative UI 以及可选的 MCP Apps 支持。

从 CHANGELOG 可以看到 1.51.0 至 1.54.3 的节奏：

版本	关键变更	类型
1.54.3	依赖对齐`@copilotkit/core@1.55.2`/`shared@1.55.2`	Patch
1.54.2	依赖对齐 core/shared 1.55.1	Patch
1.54.1	新增运行时传输自动检测（REST vs single-endpoint）（b4a8b7a）	Patch
1.54.0	弃用全部`@copilotkitnext/_`包，迁移至`@copilotkit/_`等价物（3780c6a）	Patch
1.53.0	支持直接从 CopilotKit runtime 启用 MCP 与 A2UI 中间件（1510f64）	Patch
1.52.0	新增 reasoning 消息支持与默认推理消息组件（ef0f539）	Patch
1.51.4	Angular 包内完成前端工具与 Core 的集成（9bc868d）	Patch
1.51.3	新增 UMD 导出（d36fc1e）	Patch
1.51.2	依赖策略从 peerDependencies 改为 dependencies（e59d23f）	Patch
1.51.0	更新版本策略（2839a15）	Patch

一个值得注意的工程细节：每个正式版本都与其-next.x预发布版本一一对应（如1.54.3对应1.54.3-next.1/1.54.3-next.0），且每个版本都列出配套的@copilotkit/core与@copilotkit/shared精确版本。这说明 Angular 包与核心运行时采用严格的同步发布策略——升级时务必连带升级 core/shared，避免跨版本混用。该版本矩阵在 packages/angular/package.json 的copilotkit.angularSupport字段中有据可查：编译基线为 Angular 22（compilerMajor 22、TypeScript 6.0.3），rxjs要求^7.8.0，并以严格 peer 校验安装。

运行时传输自动检测：REST 与 SSE 单流（1.54.1）

1.54.1 的b4a8b7a提交为 Angular 包带来了运行时传输自动检测，这是本阶段最值得关注的能力变化。

从 packages/angular/src/lib/copilotkit.ts 的实现看，CopilotKit服务维护了一个runtimeTransport只读信号（L105-L106），其类型来自@copilotkit/core的CopilotRuntimeTransport，初值为"auto"：

readonly #runtimeTransport = signal<CopilotRuntimeTransport>("auto"); readonly runtimeTransport = this.#runtimeTransport.asReadonly();

"auto"意味着由 Core 层根据 runtime 的/info能力自动选择传输通道："rest"（REST 端点协议）或"single"（SSE 单流传输）。测试文件 packages/angular/src/lib/copilotkit.spec.ts 中同样出现了runtimeTransport = "auto"与runtimeTransport: "single"的用例，印证了这一取值空间。

如何在运行时切换传输

当应用需要在运行期修改 runtime 配置时，可调用CopilotKit.updateRuntime(...)，该方法支持传入runtimeUrl、runtimeTransport、headers、credentials、properties、agents与selfManagedAgents：

this.copilotKit.updateRuntime({ runtimeTransport: "single", // 显式切到 SSE 单流 runtimeUrl: "http://localhost:3001/api/copilotkit", });

对应实现见 packages/angular/src/lib/copilotkit.ts 的updateRuntime（L636-L678）：每个字段都是可选增量更新，setRuntimeTransport与内部信号同步更新，未传入的字段保持不变。因此它非常适合做"运行时环境切换"（如开发/生产 runtime 切换、灰度路由切换），而无需重建整个应用。

与代理 Agent 的联动

传输模式还参与 Agent 的解析流程。在 packages/angular/src/lib/agent.ts 的resolveAgent中，当本地找不到 Agent 但配置了runtimeUrl、且运行状态处于Disconnected/Connecting/Error时，会创建ProxiedCopilotRuntimeAgent代理，其构造参数包含transport: this.#copilotkit.runtimeTransport()（L192-L197）。也就是说：传输自动检测不仅决定消息通道，还决定代理 Agent 以哪种协议与远端 runtime 建立连接。

Reasoning 推理消息：新增支持与默认组件（1.52.0）

1.52.0 的ef0f539提交为 Angular 包引入了reasoning 消息支持及默认渲染组件，并在 1.51.5-next.0 中先行落地。

reasoning（推理过程）消息与普通助手消息不同，它承载模型的"思考过程"，通常需要以可折叠的方式展示，避免挤占对话主内容。实现位于 packages/angular/src/lib/components/chat/copilot-chat-reasoning-message.ts，组件选择器为copilot-chat-reasoning-message，其核心交互包括：

可折叠头部按钮：通过aria-expanded暴露展开状态，点击toggle()在展开/收起之间切换；
流式指示：当isStreaming() && !hasContent()时显示脉冲圆点动画，提示推理内容仍在生成；
内容区使用grid-template-rows在1fr与0fr间平滑过渡（200ms ease-in-out），实现轻量无 JS 的折叠动画；
推理正文复用copilot-chat-assistant-message-renderer渲染 Markdown 内容。

公共 API 层面，packages/angular/src/public-api.ts 导出了copilot-chat-reasoning-message及配套工具模块copilot-chat-reasoning-message-utils（含formatReasoningDuration等），聊天视图 copilot-chat-view.ts 与消息视图 copilot-chat-message-view.ts 均接入该组件。测试用例见 packages/angular/src/lib/components/chat/tests/copilot-chat-reasoning-message.spec.ts，覆盖展开/收起、流式占位、无内容降级等行为。

使用建议

reasoning 组件是默认内置的，无需额外注册。若你的 Agent（基于 AG-UI 协议）返回带推理内容的消息，聊天视图会自动以可折叠块呈现；若需自定义推理消息外观，可基于copilot-chat-reasoning-message的输入与样式类做替换。

前端工具与 Core 的集成（1.51.4）

1.51.4 的9bc868d提交完成了Angular 包内前端工具与 Core 的集成，使工具注册不再是 React 的专利。前端工具（Frontend Tool）指在浏览器端声明、携带本地 handler 的工具——Agent 在远端运行，通过工具调用回到前端执行应用代码。

核心类型定义在 packages/angular/src/lib/tools.ts：

export interface FrontendToolConfig<Args> { name: string; description: string; parameters: z.ZodType<Args>; // Zod 参数 schema component?: Type<ToolRenderer<Args>>; // 可选 UI 渲染器 handler: (args: Args, context: FrontendToolHandlerContext) => Promise<unknown>; agentId?: string; // 可选 Agent 作用域 }

handler是可选的：对于纯展示型工具（只渲染组件、不执行应用代码），可以不提供 handler——此时 Core 会插入一个空工具结果并结束该轮，避免向线程写入虚构结果（packages/angular/src/lib/copilotkit.ts 中#bindClientTool的实现注释对此有明确说明）。

CopilotKit服务的addFrontendTool会把工具的 handler 包进runInInjectionContext(injector, ...)（L335-L339），确保 handler 内可以安全地使用 Angular 依赖注入。注册辅助函数registerFrontendTool还自动绑定DestroyRef，在注入上下文销毁时自动removeTool，无需手动清理（packages/angular/src/lib/tools.ts L157-L172）。

registerFrontendTool({ name: "lookup", description: "Fetch a record", parameters: z.object({ id: z.string() }), handler: async ({ id }) => ({ id, ok: true }), });

同文件还提供了更简洁的registerComponent：它自动为工具拼接面向模型的描述前缀（"Use this tool to display the ... component in the chat."），使同一工具在 React / Vue / Angular 前端下对模型读起来一致——这是跨框架一致性的直接证据。前端工具同样支持通过webmcp字段暴露给浏览器内 Agent 的 WebMCP API（document.modelContext）。

MCP 与 A2UI 中间件：直接从 runtime 启用（1.53.0）

1.53.0 的1510f64提交实现了enable MCP and A2UI middleware directly from copilotkit runtime，即客户端无需单独配置，只要 runtime 端能力就绪，A2UI 等中间件即可在 CopilotKit 运行时中直接激活。

Angular 侧与之配套的逻辑在 packages/angular/src/lib/copilotkit.ts：

withA2UICatalogCapability（L73-L80）：当配置了a2ui.catalog时，向每次 Agent run 的properties注入a2uiCatalogAvailable: true，runtime 据此 per-run 启用 A2UI 中间件并注入渲染工具；
#isA2UIActive（L427-L429）：core.a2uiEnabled || catalog !== undefined，即runtime/info通告能力或显式提供 catalog 任一满足即激活；
激活后#syncBuiltInA2UI注册RENDER_A2UI_TOOL_NAME与AGUI_SEND_STATE_SNAPSHOT_TOOL_NAME两个内置工具渲染器，并向 Agent 上下文注入 catalog 能力、组件 schema 与 A2UI 生成/设计指南。

这一机制与 CHANGELOG 1.53.0 的描述互为印证：中间件的启用由 runtime 主导，前端只需声明 catalog 或信任 runtime 的能力通告。

MCP Apps 的定位

按 packages/angular/README.md 的说明，MCP Apps 是刻意保持"次级入口"的功能：需要额外调用provideMCPApps()加入应用 providers，并从@copilotkit/angular/mcp-apps导入高级宿主 API（对应 packages/angular/package.json 的./mcp-apps导出子路径）。MCP 资源与工具请求均经由所选 AG-UI Agent 转发，浏览器端 provider 不接受服务器 URL。

包工程治理：弃用、UMD 与依赖策略

除了功能演进，1.5x 系列还包含三项重要的工程化变更：

1.54.0：`@copilotkitnext/_`全面弃用（3780c6a）

CHANGELOG 明确标注："deprecate: mark all @copilotkitnext/_ packages as deprecated in favor of @copilotkit/_ equivalents"。@copilotkitnext/曾用于发布预发布版本，如今 npm 发布策略收敛为统一的@copilotkit/命名空间。升级到 1.54.0 及以上时，应把@copilotkitnext/angular、@copilotkitnext/core、@copilotkitnext/shared等包名替换为@copilotkit/前缀的等价物。

1.51.3：新增 UMD 导出（d36fc1e）

该版本为包新增 UMD 构建产物，便于在无打包器的场景（如script标签、CodePen 类环境）直接引入。UMD 导出由@copilotkit/shared同步提供，说明工具函数层同时具备该能力。

1.51.2：deps 替代 peerdeps（e59d23f）

依赖策略由 peerDependencies 调整为 dependencies。这意味着@copilotkit/core、@copilotkit/shared等作为直接依赖随包安装，降低用户手动安装对等依赖的成本；与之对照，@angular/core、@angular/common、@angular/cdk、rxjs仍是用户需自行提供的 peer 依赖（版本要求见 packages/angular/package.json 的peerDependencies：Angular 22、rxjs ^7.8.0）。

1.51.0：版本策略更新（2839a15）

这是 1.5x 系列的开端，确立了后续"core/shared/angular 同版本号对齐 +-next预发布"的版本节奏，从 CHANGELOG 的依赖对齐列表可以完整追溯。

从 CHANGELOG 出发的升级自查清单

基于以上分析，升级@copilotkit/angular到最新 1.54.x 时建议按此清单核对：

包名迁移：若仍引用@copilotkitnext/...，先迁移到@copilotkit/...（1.54.0 起弃用）；
依赖对齐：同步升级@copilotkit/core与@copilotkit/shared到 CHANGELOG 标注的精确版本（当前 1.55.2），避免混用；
Angular 基线：确认应用 Angular 版本在受支持的 major（仓库编译基线为 Angular 22），并提供rxjs ^7.8.0；
传输行为：若依赖旧版显式指定 transport 的代码，1.54.1 起默认"auto"自动检测，可通过CopilotKit.runtimeTransport信号观察当前生效值，或调用updateRuntime({ runtimeTransport })显式覆盖；
推理消息：1.52.0 起 reasoning 消息自带默认可折叠组件，无需额外注册；
工具注册：1.51.4 起可在组件/指令内用registerFrontendTool/registerComponent/registerRenderToolCall注册工具，生命周期随注入上下文自动清理；
A2UI/MCP：1.53.0 起 A2UI 中间件可直接由 runtime 启用；MCP Apps 作为次级入口需显式provideMCPApps()。

CopilotKit Angular 包 1.5x 演进全解析：运行时传输自动检测、推理消息组件与前端工具集成