CopilotKit 预构建弹窗CopilotPopup验收指南以 LlamaIndex 集成为例的 QA 全流程解析【免费下载链接】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 仓库中 LlamaIndex 集成示例的 QA 验证清单 showcase/integrations/llamaindex/qa/prebuilt-popup.md 为主线结合对应的 demo 页面、Playwright 端到端测试与后端 AG-UI Agent 实现完整讲解预构建弹窗组件CopilotPopup /的接入方式、关键配置项与可自动化的验收方法。读完本文你将掌握如何验证一个浮动弹窗聊天组件是否正确挂载、默认展开、与后端 Agent 正常对话以及如何把这一系列人工 QA 步骤改写成可重复执行的自动化测试。一、QA 清单在项目中的定位prebuilt-popup.md是 CopilotKit showcase 体系中按功能维度拆分的 QA 检查清单之一。在showcase/integrations/llamaindex/qa/目录下还并存着prebuilt-sidebar.md、agentic-chat.md、tool-rendering.md等同构清单它们共同覆盖了该集成LlamaIndex在 CopilotKit 上支持的全部功能特性。该清单的 4 个验收点分别为导航到/demos/prebuilt-popup路由验证浮动CopilotPopup /启动器launcher可见验证弹窗默认处于打开状态发送Say hi from the popup!并验证 Agent 正常响应。其中导航到指定路由是前提后三点则分别对应弹窗组件的三个核心行为挂载与呈现、默认展开状态、消息收发链路。这三个行为也正是清单对应功能manifest.yaml 中 features 列表里登记的prebuilt-popup在 prebuilt-popup.spec.ts 端到端测试中被逐一验证的对象。二、第一步确认 Demo 路由与页面挂载清单要求先导航到/demos/prebuilt-popup。该路由的入口组件位于 showcase/integrations/llamaindex/src/app/demos/prebuilt-popup/page.tsxuse 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 ( // region[popup-basic-setup] CopilotKit runtimeUrl/api/copilotkit agentprebuilt-popup MainContent / CopilotPopup agentIdprebuilt-popup defaultOpen{true} labels{{ chatInputPlaceholder: Ask the popup anything..., }} / Suggestions / /CopilotKit // endregion[popup-basic-setup] ); }这段代码同时展示了预构建弹窗的最小可用接入模式其中三个要点直接决定了 QA 清单能否通过CopilotKit根组件通过runtimeUrl指向同仓库下的 Next.js API 路由/api/copilotkit并通过agent指定默认 Agent。CopilotPopup /浮层agentId与 Provider 的agent保持一致defaultOpen{true}决定首屏是否展开labels.chatInputPlaceholder覆盖默认的输入占位文案。页面正文与弹窗解耦MainContent /渲染的是普通页面内容见 main-content.tsx弹窗作为浮动层叠加其上——这正是popup 浮在页面上方、原有布局保持不变的产品形态。页面正文在 e2e 测试中承担路由已挂载的断言锚点page.getByRole(heading, { name: Popup demo })必须可见其文案与 main-content.tsx 中的h1Popup demo/h1逐字对应。这意味着验收第一步的核心是确认路由渲染出预期页面骨架而非仅仅不报错。三、第二步验证浮动启动器Launcher可见清单的第二项是验证CopilotPopup /的浮动 launcher 气泡可见。启动器是弹窗关闭时留在页面角落的圆形悬浮按钮用于再次唤起聊天面板。在 prebuilt-popup.spec.ts 中launcher 通过稳定的测试标识符定位await expect( page.locator([data-testidcopilot-chat-toggle]).first(), ).toBeVisible();copilot-chat-toggle是 CopilotPopup 内部渲染的开关按钮的data-testid它在本仓库的整个预构建组件体系中是一致约定的定位锚点prebuilt-sidebar等其他 demo 的 e2e 测试也采用同样的 testid 模式。从实现结构看启动器与弹窗内容属于同一组件的两个渲染状态关闭时仅渲染启动器打开时渲染启动器加聊天面板。该断言因此既验证了组件已挂载也隐含验证了组件具备可再次唤起的能力。四、第三步验证默认展开defaultOpen清单第三项要求弹窗默认打开。这一行为由页面上的defaultOpen{true}属性直接驱动。defaultOpen是CopilotPopup /的首屏初始状态开关为true时组件在首次渲染即展开聊天面板为false默认值时则收起为角落的 launcher 气泡。e2e 测试对该行为的验证方式非常值得借鉴——它没有直接断言组件状态而是断言自定义占位文案可见// defaultOpen{true} means the popup window is open on first paint. The // demo sets a custom placeholder via labels.chatInputPlaceholder — we // assert on that literal string to prove the popup rendered AND its // labels override took effect. await expect( page.getByPlaceholder(Ask the popup anything...), ).toBeVisible();由于输入框只存在于展开的聊天面板内部Ask the popup anything...这个占位符可见就等价于面板已展开。同时这个断言还顺带验证了labels.chatInputPlaceholder自定义项生效——一举两得。这也提醒我们QA 时选择只在目标状态出现的唯一文案作为断言依据比直接断言布尔状态更稳健。补充一点与关闭行为相关的实现细节测试注释明确说明关闭时 CopilotPopupView 会卸载其内容由其内部isRendered状态跟踪因此弹窗关闭的可靠信号是data-testidcopilot-popup从 DOM 中消失而非被 CSS 隐藏。测试随后通过点击copilot-chat-toggle重新唤起弹窗并断言copilot-popup再次可见同时验证 URL 保持不变/demos/prebuilt-popup$证明展开/收起是纯客户端状态切换。五、第四步发送消息并验证 Agent 响应清单最后一项要求发送Say hi from the popup!并验证 Agent 回复。这条消息其实来自 Demo 页面上注册的建议气泡suggestion pill而非手动输入。5.1 建议气泡的注册方式建议由 suggestions.ts 通过useConfigureSuggestions钩子注册并由 suggestions-mount.tsx 挂载到页面use 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, }); }suggestions数组中的每一项包含显示用的title与发送用的messageavailable: always表示这些建议气泡始终可用不限定在空聊天等特定状态下。QA 清单中的消息Say hi from the popup!正是第一条建议{ title: Say hi, message: Say hi from the popup! }的message字段——人工 QA 时点击气泡即可发出该消息。e2e 测试对建议气泡的定位是data-testidcopilot-suggestion且文本包含Say hiconst sayHiPill page .locator([data-testidcopilot-suggestion]) .filter({ hasText: Say hi }) .first(); await expect(sayHiPill).toBeVisible({ timeout: 15000 }); await sayHiPill.click();点击后测试断言data-testidcopilot-assistant-message的助手消息可见超时 45 秒为后端 LLM 往返预留余量。该测试还覆盖了另一条手动输入路径向输入框fill(Hello)后点击copilot-send-button同样断言收到助手回复。5.2 消息如何到达 LlamaIndex Agent消息从弹窗发出的完整链路如下浏览器将消息发送到runtimeUrl指向的 Next.js API 路由 showcase/integrations/llamaindex/src/app/api/copilotkit/route.ts路由通过createCopilotRuntimeHandlernew CopilotRuntime({ agents })建立 CopilotKit Runtime并以 AG-UI 协议将请求代理到独立进程中的 LlamaIndex Agent 服务默认http://localhost:8000prebuilt-popup属于该路由注册的sharedAgentNames之一其请求由agents表中的createAgent()即new HttpAgent({ url: ${AGENT_URL}/run })转发到 Agent 服务的默认/run端点LlamaIndex 侧由 src/agents/agent.py 构建的FixedAGUIChatWorkflow使用OpenAI(modelgpt-4.1)处理对话回复经同一链路流式返回弹窗。从源码结构看prebuilt-popup与多数共享 demo 共用同一后端 Agent——per-demo 的行为差异主要由前端驱动如本 demo 的建议气泡、labels定制、弹窗布局而非各自独立的系统提示词。这一点在路由文件的注释中也有明确说明// Shared-router agents — every id here resolves to the same backend same tool set. Per-demo behavior is driven by the frontend.Agent 的系统提示词要求保持回复简洁1 到 2 句话因此对Say hi from the popup!这类寒暄预期响应是简短的自然语言文本。这也解释了为什么 QA 只验证收到回复而非收到特定回复——后端是无工具no tools的中性对话重点是端到端链路贯通。六、把人工 QA 升级为自动化测试人工按清单逐项点击验证是发布前的最低保障但同样的 4 个验收点在 prebuilt-popup.spec.ts 中已被固化为 4 个 Playwright 测试用例构成一个可重复执行的回归屏障QA 清单项对应测试用例关键断言导航到/demos/prebuilt-popuppage loads with heading and the popup open by defaultheading: Popup demo可见launcher 可见同上copilot-chat-toggle可见弹窗默认打开同上占位符Ask the popup anything...可见data-testidcopilot-popup亦可见发送消息并收到回复Say hi suggestion pill...与typing a message and clicking send...copilot-assistant-message可见额外关闭/重开popup close button unmounts...关闭后copilot-popup隐藏点击 toggle 后再次可见URL 不变测试代码中还沉淀了两条宝贵的实战经验值得在编写类似测试时复用cpk-web-inspector叠加层会拦截指针事件在 localhost 开发环境下自动启用的cpk-web-inspector会拦截 Playwright 的基于指针的click()因此关闭按钮的点击需通过page.evaluate(() document.querySelector(...).click())以 JS 层点击绕过注释中说明这与共享工具_genuine-shared.ts:clickByJs是同一模式。输入框回车提交不稳定测试注释指出textarea 上的 Enter 提交在该部署上偶发丢失因此提交消息统一点击copilot-send-button按钮这是每个聊天输入区都稳定存在的提交入口。七、排查建议当任一 QA 步骤失败时可按如下顺序定位均以本仓库实际结构为依据路由 404确认页面位于 src/app/demos/prebuilt-popup/ 目录下Next.js App Router 会据此生成/demos/prebuilt-popup路由。launcher 不可见确认CopilotPopup /位于CopilotKit之内且未设置会导致其隐藏的自定义样式启动器的 testid 为copilot-chat-toggle。弹窗未默认展开检查defaultOpen是否显式设为true默认值为false即收起状态。Agent 无响应先访问/api/copilotkit的GET健康探针其返回 JSON 中包含agent_url与agent_status可用于确认后端http://localhost:8000是否可达、OPENAI_API_KEY是否已配置确认 Provider 的agent与CopilotPopup的agentId一致本 demo 均为prebuilt-popup且该名称在 route.ts 的sharedAgentNames或specializedAgents中已注册。需要逐请求排障时可设置环境变量SHOWCASE_ROUTE_DEBUG1开启该路由的详细日志。八、小结一个只有四行的 QA 清单背后实际上覆盖了预构建弹窗组件完整的三层链路前端组件挂载与初始状态defaultOpen、labels、交互入口launcher 气泡与 suggestion pill、以及端到端消息收发Next.js Runtime 代理 → AG-UI → LlamaIndex Agent。本文对应的实现文件均可直接在仓库中对照阅读demo 页面、建议气泡注册、后端 Agent 工作流、运行时代理路由与端到端测试。照此流程你可以把任何一个预构建组件 demo 的人工验收快速升级为可长期回归的自动化测试。【免费下载链接】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 预构建弹窗（CopilotPopup）验收指南：以 LlamaIndex 集成为例的 QA 全流程解析
CopilotKit 预构建弹窗CopilotPopup验收指南以 LlamaIndex 集成为例的 QA 全流程解析【免费下载链接】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 仓库中 LlamaIndex 集成示例的 QA 验证清单 showcase/integrations/llamaindex/qa/prebuilt-popup.md 为主线结合对应的 demo 页面、Playwright 端到端测试与后端 AG-UI Agent 实现完整讲解预构建弹窗组件CopilotPopup /的接入方式、关键配置项与可自动化的验收方法。读完本文你将掌握如何验证一个浮动弹窗聊天组件是否正确挂载、默认展开、与后端 Agent 正常对话以及如何把这一系列人工 QA 步骤改写成可重复执行的自动化测试。一、QA 清单在项目中的定位prebuilt-popup.md是 CopilotKit showcase 体系中按功能维度拆分的 QA 检查清单之一。在showcase/integrations/llamaindex/qa/目录下还并存着prebuilt-sidebar.md、agentic-chat.md、tool-rendering.md等同构清单它们共同覆盖了该集成LlamaIndex在 CopilotKit 上支持的全部功能特性。该清单的 4 个验收点分别为导航到/demos/prebuilt-popup路由验证浮动CopilotPopup /启动器launcher可见验证弹窗默认处于打开状态发送Say hi from the popup!并验证 Agent 正常响应。其中导航到指定路由是前提后三点则分别对应弹窗组件的三个核心行为挂载与呈现、默认展开状态、消息收发链路。这三个行为也正是清单对应功能manifest.yaml 中 features 列表里登记的prebuilt-popup在 prebuilt-popup.spec.ts 端到端测试中被逐一验证的对象。二、第一步确认 Demo 路由与页面挂载清单要求先导航到/demos/prebuilt-popup。该路由的入口组件位于 showcase/integrations/llamaindex/src/app/demos/prebuilt-popup/page.tsxuse 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 ( // region[popup-basic-setup] CopilotKit runtimeUrl/api/copilotkit agentprebuilt-popup MainContent / CopilotPopup agentIdprebuilt-popup defaultOpen{true} labels{{ chatInputPlaceholder: Ask the popup anything..., }} / Suggestions / /CopilotKit // endregion[popup-basic-setup] ); }这段代码同时展示了预构建弹窗的最小可用接入模式其中三个要点直接决定了 QA 清单能否通过CopilotKit根组件通过runtimeUrl指向同仓库下的 Next.js API 路由/api/copilotkit并通过agent指定默认 Agent。CopilotPopup /浮层agentId与 Provider 的agent保持一致defaultOpen{true}决定首屏是否展开labels.chatInputPlaceholder覆盖默认的输入占位文案。页面正文与弹窗解耦MainContent /渲染的是普通页面内容见 main-content.tsx弹窗作为浮动层叠加其上——这正是popup 浮在页面上方、原有布局保持不变的产品形态。页面正文在 e2e 测试中承担路由已挂载的断言锚点page.getByRole(heading, { name: Popup demo })必须可见其文案与 main-content.tsx 中的h1Popup demo/h1逐字对应。这意味着验收第一步的核心是确认路由渲染出预期页面骨架而非仅仅不报错。三、第二步验证浮动启动器Launcher可见清单的第二项是验证CopilotPopup /的浮动 launcher 气泡可见。启动器是弹窗关闭时留在页面角落的圆形悬浮按钮用于再次唤起聊天面板。在 prebuilt-popup.spec.ts 中launcher 通过稳定的测试标识符定位await expect( page.locator([data-testidcopilot-chat-toggle]).first(), ).toBeVisible();copilot-chat-toggle是 CopilotPopup 内部渲染的开关按钮的data-testid它在本仓库的整个预构建组件体系中是一致约定的定位锚点prebuilt-sidebar等其他 demo 的 e2e 测试也采用同样的 testid 模式。从实现结构看启动器与弹窗内容属于同一组件的两个渲染状态关闭时仅渲染启动器打开时渲染启动器加聊天面板。该断言因此既验证了组件已挂载也隐含验证了组件具备可再次唤起的能力。四、第三步验证默认展开defaultOpen清单第三项要求弹窗默认打开。这一行为由页面上的defaultOpen{true}属性直接驱动。defaultOpen是CopilotPopup /的首屏初始状态开关为true时组件在首次渲染即展开聊天面板为false默认值时则收起为角落的 launcher 气泡。e2e 测试对该行为的验证方式非常值得借鉴——它没有直接断言组件状态而是断言自定义占位文案可见// defaultOpen{true} means the popup window is open on first paint. The // demo sets a custom placeholder via labels.chatInputPlaceholder — we // assert on that literal string to prove the popup rendered AND its // labels override took effect. await expect( page.getByPlaceholder(Ask the popup anything...), ).toBeVisible();由于输入框只存在于展开的聊天面板内部Ask the popup anything...这个占位符可见就等价于面板已展开。同时这个断言还顺带验证了labels.chatInputPlaceholder自定义项生效——一举两得。这也提醒我们QA 时选择只在目标状态出现的唯一文案作为断言依据比直接断言布尔状态更稳健。补充一点与关闭行为相关的实现细节测试注释明确说明关闭时 CopilotPopupView 会卸载其内容由其内部isRendered状态跟踪因此弹窗关闭的可靠信号是data-testidcopilot-popup从 DOM 中消失而非被 CSS 隐藏。测试随后通过点击copilot-chat-toggle重新唤起弹窗并断言copilot-popup再次可见同时验证 URL 保持不变/demos/prebuilt-popup$证明展开/收起是纯客户端状态切换。五、第四步发送消息并验证 Agent 响应清单最后一项要求发送Say hi from the popup!并验证 Agent 回复。这条消息其实来自 Demo 页面上注册的建议气泡suggestion pill而非手动输入。5.1 建议气泡的注册方式建议由 suggestions.ts 通过useConfigureSuggestions钩子注册并由 suggestions-mount.tsx 挂载到页面use 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, }); }suggestions数组中的每一项包含显示用的title与发送用的messageavailable: always表示这些建议气泡始终可用不限定在空聊天等特定状态下。QA 清单中的消息Say hi from the popup!正是第一条建议{ title: Say hi, message: Say hi from the popup! }的message字段——人工 QA 时点击气泡即可发出该消息。e2e 测试对建议气泡的定位是data-testidcopilot-suggestion且文本包含Say hiconst sayHiPill page .locator([data-testidcopilot-suggestion]) .filter({ hasText: Say hi }) .first(); await expect(sayHiPill).toBeVisible({ timeout: 15000 }); await sayHiPill.click();点击后测试断言data-testidcopilot-assistant-message的助手消息可见超时 45 秒为后端 LLM 往返预留余量。该测试还覆盖了另一条手动输入路径向输入框fill(Hello)后点击copilot-send-button同样断言收到助手回复。5.2 消息如何到达 LlamaIndex Agent消息从弹窗发出的完整链路如下浏览器将消息发送到runtimeUrl指向的 Next.js API 路由 showcase/integrations/llamaindex/src/app/api/copilotkit/route.ts路由通过createCopilotRuntimeHandlernew CopilotRuntime({ agents })建立 CopilotKit Runtime并以 AG-UI 协议将请求代理到独立进程中的 LlamaIndex Agent 服务默认http://localhost:8000prebuilt-popup属于该路由注册的sharedAgentNames之一其请求由agents表中的createAgent()即new HttpAgent({ url: ${AGENT_URL}/run })转发到 Agent 服务的默认/run端点LlamaIndex 侧由 src/agents/agent.py 构建的FixedAGUIChatWorkflow使用OpenAI(modelgpt-4.1)处理对话回复经同一链路流式返回弹窗。从源码结构看prebuilt-popup与多数共享 demo 共用同一后端 Agent——per-demo 的行为差异主要由前端驱动如本 demo 的建议气泡、labels定制、弹窗布局而非各自独立的系统提示词。这一点在路由文件的注释中也有明确说明// Shared-router agents — every id here resolves to the same backend same tool set. Per-demo behavior is driven by the frontend.Agent 的系统提示词要求保持回复简洁1 到 2 句话因此对Say hi from the popup!这类寒暄预期响应是简短的自然语言文本。这也解释了为什么 QA 只验证收到回复而非收到特定回复——后端是无工具no tools的中性对话重点是端到端链路贯通。六、把人工 QA 升级为自动化测试人工按清单逐项点击验证是发布前的最低保障但同样的 4 个验收点在 prebuilt-popup.spec.ts 中已被固化为 4 个 Playwright 测试用例构成一个可重复执行的回归屏障QA 清单项对应测试用例关键断言导航到/demos/prebuilt-popuppage loads with heading and the popup open by defaultheading: Popup demo可见launcher 可见同上copilot-chat-toggle可见弹窗默认打开同上占位符Ask the popup anything...可见data-testidcopilot-popup亦可见发送消息并收到回复Say hi suggestion pill...与typing a message and clicking send...copilot-assistant-message可见额外关闭/重开popup close button unmounts...关闭后copilot-popup隐藏点击 toggle 后再次可见URL 不变测试代码中还沉淀了两条宝贵的实战经验值得在编写类似测试时复用cpk-web-inspector叠加层会拦截指针事件在 localhost 开发环境下自动启用的cpk-web-inspector会拦截 Playwright 的基于指针的click()因此关闭按钮的点击需通过page.evaluate(() document.querySelector(...).click())以 JS 层点击绕过注释中说明这与共享工具_genuine-shared.ts:clickByJs是同一模式。输入框回车提交不稳定测试注释指出textarea 上的 Enter 提交在该部署上偶发丢失因此提交消息统一点击copilot-send-button按钮这是每个聊天输入区都稳定存在的提交入口。七、排查建议当任一 QA 步骤失败时可按如下顺序定位均以本仓库实际结构为依据路由 404确认页面位于 src/app/demos/prebuilt-popup/ 目录下Next.js App Router 会据此生成/demos/prebuilt-popup路由。launcher 不可见确认CopilotPopup /位于CopilotKit之内且未设置会导致其隐藏的自定义样式启动器的 testid 为copilot-chat-toggle。弹窗未默认展开检查defaultOpen是否显式设为true默认值为false即收起状态。Agent 无响应先访问/api/copilotkit的GET健康探针其返回 JSON 中包含agent_url与agent_status可用于确认后端http://localhost:8000是否可达、OPENAI_API_KEY是否已配置确认 Provider 的agent与CopilotPopup的agentId一致本 demo 均为prebuilt-popup且该名称在 route.ts 的sharedAgentNames或specializedAgents中已注册。需要逐请求排障时可设置环境变量SHOWCASE_ROUTE_DEBUG1开启该路由的详细日志。八、小结一个只有四行的 QA 清单背后实际上覆盖了预构建弹窗组件完整的三层链路前端组件挂载与初始状态defaultOpen、labels、交互入口launcher 气泡与 suggestion pill、以及端到端消息收发Next.js Runtime 代理 → AG-UI → LlamaIndex Agent。本文对应的实现文件均可直接在仓库中对照阅读demo 页面、建议气泡注册、后端 Agent 工作流、运行时代理路由与端到端测试。照此流程你可以把任何一个预构建组件 demo 的人工验收快速升级为可长期回归的自动化测试。【免费下载链接】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），仅供参考