尧图网页设计 
AG2 集成中的 CopilotKit 预构建弹窗Pre-Built PopupQA 验证指南与实现解析【免费下载链接】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导读本文围绕 AG2 集成仓库中的prebuilt-popup质量验证QA检查清单系统讲解 CopilotKit v2 预构建弹窗组件CopilotPopup /的接入方式、配置要点与验收标准。你将掌握如何在 Next.js 应用中通过runtimeUrlagentId挂载浮动弹窗聊天界面、如何用defaultOpen、labels控制其行为与文案以及如何结合仓库自带的端到端E2E测试与 AG2 后端路由完成从“页面可见”到“Agent 回复”的完整回归验证。一、QA 清单在验证什么从需求到验收QA 文档 prebuilt-popup.md 定义的检查路径只有 5 步却覆盖了弹窗组件三个核心行为维度路由可达性Navigate to /demos/prebuilt-popup——页面必须能正常挂载默认打开态Popup opens by default——首次渲染即应展示弹窗内容而非仅显示角落的启动气泡消息往返Send Say hi from the popup并Verify agent responds——用户输入或点击建议词后Agent 的回复必须出现在弹窗内部。对应的 Expected Results 只有两条Popup opens as overlay以浮层形式打开与Agent replies inside the popup window回复渲染在弹窗窗口内。这组最小验收标准的关键在于弹窗是“叠加在既有布局之上”的浮层页面本身的布局在其下层保持不变。二、Demo 页面结构三行核心代码挂载弹窗该演示的前端实现位于 page.tsx完整的页面组装如下use client; import React from react; import { CopilotKit, CopilotPopup } from copilotkit/react-core/v2; import { MainContent } from ./main-content; import { Suggestions } from ./suggestions-mount; export default function PrebuiltPopupDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agentprebuilt-popup MainContent / CopilotPopup agentIdprebuilt-popup defaultOpen{true} labels{{ chatInputPlaceholder: Ask the popup anything..., }} / Suggestions / /CopilotKit ); }拆解这三层结构CopilotKit顶层 ProviderruntimeUrl指向本仓库的运行时路由/api/copilotkitagent指定默认 Agent 名称。所有子组件弹窗、建议词共享这一上下文CopilotPopup预构建弹窗组件。agentIdprebuilt-popup与顶层agent对应负责把弹窗会话绑定到同一个后端 AgentdefaultOpen{true}声明默认打开labels用于覆写内置文案Suggestions建议词挂载点详情见第四节。页面正文 main-content.tsx 只是一个普通的居中内容区标题 “Popup demo” 与说明文字没有任何弹窗相关的布局代码——这正是“预构建”的含义浮动启动器launcher bubble与聊天浮层完全由CopilotPopup自行渲染在角落既有页面布局保持原样。三、组件实现级解析defaultOpen、labels 与受控模式CopilotPopup的源码位于 CopilotPopup.tsx其完整 props 类型为Props类型作用agentIdstring会话绑定的 Agent 标识defaultOpenboolean非受控模式下弹窗的初始开关状态true表示首次渲染即打开open/onOpenChangeboolean / (open: boolean) void受控模式。传入open后弹窗完全由宿主决定开合自身不再改状态需配合onOpenChange响应开关请求headerReactNode自定义弹窗头部toggleButtonReactNode自定义角落启动气泡width/heightstring | number弹窗尺寸默认由样式系统提供clickOutsideToCloseboolean点击外部是否关闭其余CopilotChatProps透传给内部CopilotChat的聊天配置含labels、welcomeScreen等三个值得注意的实现细节1. labels 覆写 placeholder。演示页传入labels.chatInputPlaceholder: Ask the popup anything...QA 与 E2E 测试正是用这个自定义占位文案来证明“弹窗确实渲染了、且文案覆写生效”的测试断言见 prebuilt-popup.spec.ts。2. 弹窗外壳通过 Context 传递。源码中PopupViewOverride组件刻意保持“身份稳定”stable identitywidth/height 这类随拖拽变化的 props 通过PopupShellPropsContext下发而不是直接作为覆盖组件的依赖。原因在源码注释中写得很清楚——若尺寸变化导致覆盖组件“换身份”React 会卸载并重挂载整个聊天子树使滚动位置归零并触发initialsmooth的可见滚动动画见 CopilotPopup.tsx。3. 许可证检查。组件内部通过checkFeature(popup)校验许可未授权时渲染InlineFeatureWarning并在控制台输出警告CopilotPopup.tsx不影响功能调试但部署前需确认许可配置。四、建议词useConfigureSuggestions 让 QA 用例可一键触发QA 清单中的Send Say hi from the popup除了可以手动输入也能通过建议词一键触发。建议词定义在 suggestions.tsuse client; import { useConfigureSuggestions } from copilotkit/react-core/v2; export function usePrebuiltPopupSuggestions() { useConfigureSuggestions({ suggestions: [ { title: Say hi, message: Say hi from the popup! }, { title: Limerick, message: Write me a quick limerick. }, { title: Is 17 prime?, message: Walk me through whether 17 is prime. }, ], available: always, }); }title是气泡上显示的文字message是点击后实际发送给 Agent 的消息available: always表示建议词在会话的任何阶段都可用挂载组件 suggestions-mount.tsx 仅调用该 hook 并返回null是一个纯逻辑挂载点。注意点击 “Say hi” 发送的实际消息是Say hi from the popup!与 QA 清单的措辞略有出入但语义一致E2E 测试即按此实际消息断言见下节。五、后端接线共享 AG2 Agent 与运行时路由弹窗本身不包含任何 AI 逻辑它只是前端外壳真正的对话能力来自后端。本仓库采用“前端变体复用共享后端”的模式这在 PARITY_NOTES.md 中明确记录prebuilt-popup属于 Batch 1 前端变体复用同一个 agent.py 中的ConversableAgent经AGUIStream包装与prebuilt-sidebar、chat-slots等共享同一后端进程。请求链路由 route.ts 承担const AGENT_URL process.env.AGENT_URL || http://localhost:8000; function createAgent(path /) { return new HttpAgent({ url: ${AGENT_URL}${path} }); } // 前端变体统一注册到共享 Agent const sharedAgentNames [ agentic_chat, // ... prebuilt-sidebar, prebuilt-popup, // ... ];关键事实Agent 后端是独立进程默认http://localhost:8000可用AGENT_URL环境变量覆写本路由通过 AG-UI 协议的HttpAgent代理 CopilotKit 请求prebuilt-popup被注册进sharedAgentNames最终与defaultAgent 一样指向根路径/的同一个ConversableAgent运行时以single-route模式挂载在basePath: /api/copilotkit恰好与页面runtimeUrl对齐调试开关SHOWCASE_ROUTE_DEBUG1可开启逐请求日志GET /api/copilotkit提供健康探针返回agent_url与agent_status可用于排查“弹窗打开但 Agent 无回复”的问题。此外manifest.yaml 中登记了该演示的元信息demo idprebuilt-popup、名称 “Pre-Built: Popup”、描述 “Floating popup chat viaCopilotPopup /”、路由/demos/prebuilt-popup并标注高亮文件为src/agents/agent.py、page.tsx、route.ts与本文分析路径一致。六、从 QA 清单到自动化验收E2E 测试逐条对应QA 文档的 5 个步骤在 prebuilt-popup.spec.ts 中被完整固化为 4 个 Playwright 用例可作为“QA 清单落地为自动化”的范例QA 步骤E2E 断言关键选择器路由可达标题 “Popup demo” 可见L12-L14page.getByRole(heading)弹窗默认打开自定义 placeholder 可见证明弹窗已渲染且 labels 覆写生效L20-L22data-testidcopilot-popup、placeholder浮动启动器可见切换按钮存在L25-L27data-testidcopilot-chat-toggle发送 “Say hi” 且 Agent 回复点击建议词气泡后助理消息可见L34-L45data-testidcopilot-suggestion/copilot-assistant-message手动输入发送输入 “Hello” 并点击发送按钮后消息可见L51-L63data-testidcopilot-send-button关闭与重开关闭后弹窗隐藏、点启动器重新挂载、URL 不变L66-L92data-testidcopilot-close-button测试注释中还有两条值得记录的工程经验一是“Enter 键提交在此部署环境中偶发失效发送按钮是稳定可靠的提交触发点”二是本地开发时自动启用的cpk-web-inspector覆盖层会拦截 Playwright 的指针点击因此关闭弹窗改用 JS 级.click()绕过覆盖层见 L72-L83。这意味着在本地跑 E2E 或手动 QA 时若点击被覆盖层拦截应优先检查 web-inspector 是否开启。七、手动 QA 执行清单可直接使用结合 QA 文档与仓库实现完整的手动验收步骤为启动 AG2 后端http://localhost:8000默认端口可用AGENT_URL调整与 Next.js 前端访问/demos/prebuilt-popup确认标题 “Popup demo” 正常渲染确认页面角落出现浮动启动器气泡QA 第 2 步且弹窗已默认展开为浮层QA 第 3 步因defaultOpen{true}页面上层布局未被打乱在输入框输入或点击 “Say hi” 建议词实际发送消息Say hi from the popup!确认弹窗内部出现 Assistant 回复气泡QA 第 5 步 Expected Results 第 2 条可选回归项点击关闭按钮弹窗收起但启动器仍在再次点击启动器弹窗重新挂载URL 保持/demos/prebuilt-popup不变纯客户端状态切换。若第 5 步 Agent 无回复优先检查GET /api/copilotkit健康探针返回的agent_status是否为reachable以及是否设置OPENAI_API_KEY探针会返回env.OPENAI_API_KEY的 set/NOT SET 状态。八、小结prebuilt-popup演示展示了 CopilotKit 预构建弹窗的完整闭环CopilotKitCopilotPopup两个组件即完成前端浮层接入useConfigureSuggestions提供可一键触发的 QA 消息运行时路由经 AG-UI 协议代理到共享的 AG2ConversableAgent。QA 文档的 5 步清单覆盖了“挂载、默认态、消息往返”三个验收维度而仓库中的 E2E 测试与组件源码则进一步揭示了defaultOpen、labels、受控模式open/onOpenChange、Context 传递外壳 props 等实现级细节——理解这些你便能在自己的 AG2 应用中快速复现同样的弹窗聊天体验并建立可自动化的质量验收基线。【免费下载链接】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），仅供参考 AG2 集成中的 CopilotKit 预构建弹窗（Pre-Built Popup）QA 验证指南与实现解析
AG2 集成中的 CopilotKit 预构建弹窗Pre-Built PopupQA 验证指南与实现解析【免费下载链接】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导读本文围绕 AG2 集成仓库中的prebuilt-popup质量验证QA检查清单系统讲解 CopilotKit v2 预构建弹窗组件CopilotPopup /的接入方式、配置要点与验收标准。你将掌握如何在 Next.js 应用中通过runtimeUrlagentId挂载浮动弹窗聊天界面、如何用defaultOpen、labels控制其行为与文案以及如何结合仓库自带的端到端E2E测试与 AG2 后端路由完成从“页面可见”到“Agent 回复”的完整回归验证。一、QA 清单在验证什么从需求到验收QA 文档 prebuilt-popup.md 定义的检查路径只有 5 步却覆盖了弹窗组件三个核心行为维度路由可达性Navigate to /demos/prebuilt-popup——页面必须能正常挂载默认打开态Popup opens by default——首次渲染即应展示弹窗内容而非仅显示角落的启动气泡消息往返Send Say hi from the popup并Verify agent responds——用户输入或点击建议词后Agent 的回复必须出现在弹窗内部。对应的 Expected Results 只有两条Popup opens as overlay以浮层形式打开与Agent replies inside the popup window回复渲染在弹窗窗口内。这组最小验收标准的关键在于弹窗是“叠加在既有布局之上”的浮层页面本身的布局在其下层保持不变。二、Demo 页面结构三行核心代码挂载弹窗该演示的前端实现位于 page.tsx完整的页面组装如下use client; import React from react; import { CopilotKit, CopilotPopup } from copilotkit/react-core/v2; import { MainContent } from ./main-content; import { Suggestions } from ./suggestions-mount; export default function PrebuiltPopupDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agentprebuilt-popup MainContent / CopilotPopup agentIdprebuilt-popup defaultOpen{true} labels{{ chatInputPlaceholder: Ask the popup anything..., }} / Suggestions / /CopilotKit ); }拆解这三层结构CopilotKit顶层 ProviderruntimeUrl指向本仓库的运行时路由/api/copilotkitagent指定默认 Agent 名称。所有子组件弹窗、建议词共享这一上下文CopilotPopup预构建弹窗组件。agentIdprebuilt-popup与顶层agent对应负责把弹窗会话绑定到同一个后端 AgentdefaultOpen{true}声明默认打开labels用于覆写内置文案Suggestions建议词挂载点详情见第四节。页面正文 main-content.tsx 只是一个普通的居中内容区标题 “Popup demo” 与说明文字没有任何弹窗相关的布局代码——这正是“预构建”的含义浮动启动器launcher bubble与聊天浮层完全由CopilotPopup自行渲染在角落既有页面布局保持原样。三、组件实现级解析defaultOpen、labels 与受控模式CopilotPopup的源码位于 CopilotPopup.tsx其完整 props 类型为Props类型作用agentIdstring会话绑定的 Agent 标识defaultOpenboolean非受控模式下弹窗的初始开关状态true表示首次渲染即打开open/onOpenChangeboolean / (open: boolean) void受控模式。传入open后弹窗完全由宿主决定开合自身不再改状态需配合onOpenChange响应开关请求headerReactNode自定义弹窗头部toggleButtonReactNode自定义角落启动气泡width/heightstring | number弹窗尺寸默认由样式系统提供clickOutsideToCloseboolean点击外部是否关闭其余CopilotChatProps透传给内部CopilotChat的聊天配置含labels、welcomeScreen等三个值得注意的实现细节1. labels 覆写 placeholder。演示页传入labels.chatInputPlaceholder: Ask the popup anything...QA 与 E2E 测试正是用这个自定义占位文案来证明“弹窗确实渲染了、且文案覆写生效”的测试断言见 prebuilt-popup.spec.ts。2. 弹窗外壳通过 Context 传递。源码中PopupViewOverride组件刻意保持“身份稳定”stable identitywidth/height 这类随拖拽变化的 props 通过PopupShellPropsContext下发而不是直接作为覆盖组件的依赖。原因在源码注释中写得很清楚——若尺寸变化导致覆盖组件“换身份”React 会卸载并重挂载整个聊天子树使滚动位置归零并触发initialsmooth的可见滚动动画见 CopilotPopup.tsx。3. 许可证检查。组件内部通过checkFeature(popup)校验许可未授权时渲染InlineFeatureWarning并在控制台输出警告CopilotPopup.tsx不影响功能调试但部署前需确认许可配置。四、建议词useConfigureSuggestions 让 QA 用例可一键触发QA 清单中的Send Say hi from the popup除了可以手动输入也能通过建议词一键触发。建议词定义在 suggestions.tsuse client; import { useConfigureSuggestions } from copilotkit/react-core/v2; export function usePrebuiltPopupSuggestions() { useConfigureSuggestions({ suggestions: [ { title: Say hi, message: Say hi from the popup! }, { title: Limerick, message: Write me a quick limerick. }, { title: Is 17 prime?, message: Walk me through whether 17 is prime. }, ], available: always, }); }title是气泡上显示的文字message是点击后实际发送给 Agent 的消息available: always表示建议词在会话的任何阶段都可用挂载组件 suggestions-mount.tsx 仅调用该 hook 并返回null是一个纯逻辑挂载点。注意点击 “Say hi” 发送的实际消息是Say hi from the popup!与 QA 清单的措辞略有出入但语义一致E2E 测试即按此实际消息断言见下节。五、后端接线共享 AG2 Agent 与运行时路由弹窗本身不包含任何 AI 逻辑它只是前端外壳真正的对话能力来自后端。本仓库采用“前端变体复用共享后端”的模式这在 PARITY_NOTES.md 中明确记录prebuilt-popup属于 Batch 1 前端变体复用同一个 agent.py 中的ConversableAgent经AGUIStream包装与prebuilt-sidebar、chat-slots等共享同一后端进程。请求链路由 route.ts 承担const AGENT_URL process.env.AGENT_URL || http://localhost:8000; function createAgent(path /) { return new HttpAgent({ url: ${AGENT_URL}${path} }); } // 前端变体统一注册到共享 Agent const sharedAgentNames [ agentic_chat, // ... prebuilt-sidebar, prebuilt-popup, // ... ];关键事实Agent 后端是独立进程默认http://localhost:8000可用AGENT_URL环境变量覆写本路由通过 AG-UI 协议的HttpAgent代理 CopilotKit 请求prebuilt-popup被注册进sharedAgentNames最终与defaultAgent 一样指向根路径/的同一个ConversableAgent运行时以single-route模式挂载在basePath: /api/copilotkit恰好与页面runtimeUrl对齐调试开关SHOWCASE_ROUTE_DEBUG1可开启逐请求日志GET /api/copilotkit提供健康探针返回agent_url与agent_status可用于排查“弹窗打开但 Agent 无回复”的问题。此外manifest.yaml 中登记了该演示的元信息demo idprebuilt-popup、名称 “Pre-Built: Popup”、描述 “Floating popup chat viaCopilotPopup /”、路由/demos/prebuilt-popup并标注高亮文件为src/agents/agent.py、page.tsx、route.ts与本文分析路径一致。六、从 QA 清单到自动化验收E2E 测试逐条对应QA 文档的 5 个步骤在 prebuilt-popup.spec.ts 中被完整固化为 4 个 Playwright 用例可作为“QA 清单落地为自动化”的范例QA 步骤E2E 断言关键选择器路由可达标题 “Popup demo” 可见L12-L14page.getByRole(heading)弹窗默认打开自定义 placeholder 可见证明弹窗已渲染且 labels 覆写生效L20-L22data-testidcopilot-popup、placeholder浮动启动器可见切换按钮存在L25-L27data-testidcopilot-chat-toggle发送 “Say hi” 且 Agent 回复点击建议词气泡后助理消息可见L34-L45data-testidcopilot-suggestion/copilot-assistant-message手动输入发送输入 “Hello” 并点击发送按钮后消息可见L51-L63data-testidcopilot-send-button关闭与重开关闭后弹窗隐藏、点启动器重新挂载、URL 不变L66-L92data-testidcopilot-close-button测试注释中还有两条值得记录的工程经验一是“Enter 键提交在此部署环境中偶发失效发送按钮是稳定可靠的提交触发点”二是本地开发时自动启用的cpk-web-inspector覆盖层会拦截 Playwright 的指针点击因此关闭弹窗改用 JS 级.click()绕过覆盖层见 L72-L83。这意味着在本地跑 E2E 或手动 QA 时若点击被覆盖层拦截应优先检查 web-inspector 是否开启。七、手动 QA 执行清单可直接使用结合 QA 文档与仓库实现完整的手动验收步骤为启动 AG2 后端http://localhost:8000默认端口可用AGENT_URL调整与 Next.js 前端访问/demos/prebuilt-popup确认标题 “Popup demo” 正常渲染确认页面角落出现浮动启动器气泡QA 第 2 步且弹窗已默认展开为浮层QA 第 3 步因defaultOpen{true}页面上层布局未被打乱在输入框输入或点击 “Say hi” 建议词实际发送消息Say hi from the popup!确认弹窗内部出现 Assistant 回复气泡QA 第 5 步 Expected Results 第 2 条可选回归项点击关闭按钮弹窗收起但启动器仍在再次点击启动器弹窗重新挂载URL 保持/demos/prebuilt-popup不变纯客户端状态切换。若第 5 步 Agent 无回复优先检查GET /api/copilotkit健康探针返回的agent_status是否为reachable以及是否设置OPENAI_API_KEY探针会返回env.OPENAI_API_KEY的 set/NOT SET 状态。八、小结prebuilt-popup演示展示了 CopilotKit 预构建弹窗的完整闭环CopilotKitCopilotPopup两个组件即完成前端浮层接入useConfigureSuggestions提供可一键触发的 QA 消息运行时路由经 AG-UI 协议代理到共享的 AG2ConversableAgent。QA 文档的 5 步清单覆盖了“挂载、默认态、消息往返”三个验收维度而仓库中的 E2E 测试与组件源码则进一步揭示了defaultOpen、labels、受控模式open/onOpenChange、Context 传递外壳 props 等实现级细节——理解这些你便能在自己的 AG2 应用中快速复现同样的弹窗聊天体验并建立可自动化的质量验收基线。【免费下载链接】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），仅供参考