CopilotKit 预置侧边栏CopilotSidebar实战解析Langroid 集成中的实现与 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 仓库中 Langroid 集成示例的 QA 文档showcase/integrations/langroid/qa/prebuilt-sidebar.md为主线深入拆解prebuilt-sidebar演示的完整实现链路——从前端CopilotSidebar /组件的两行接入到建议快捷指令、折叠/展开交互再到 Next.js 路由把请求转发给 Langroid Agent 后端。读完本文你将掌握如何用预置侧边栏组件在几分钟内为任意页面接入一个默认展开、可折叠、支持快捷指令的 AI 聊天栏并学会用 Playwright 对它做端到端验收。一、这个 QA 文档在验证什么QA 文档给出了 5 个验收步骤本质上是一份针对侧边栏聊天功能的“最小冒烟测试清单”访问/demos/prebuilt-sidebar路由页面主内容区域应显示 Sidebar demo 标题侧边栏应停靠在页面一侧且默认展开发送 hi 后 Agent 应正常回复点击 launcher悬浮开关按钮可折叠/重新展开侧边栏。这 5 步覆盖了三个核心关注点路由与页面挂载是否正确、预置侧边栏的默认展示行为是否符合预期、以及聊天链路含折叠/展开交互是否可用。下面逐层对应到仓库里的真实源码与测试。二、最小接入两行 JSX 完成侧边栏挂载演示页面 src/app/demos/prebuilt-sidebar/page.tsx 展示了接入方式的核心骨架use client; import React from react; import { CopilotKit, CopilotSidebar } from copilotkit/react-core/v2; import { MainContent } from ./main-content; import { Suggestions } from ./suggestions-mount; export default function PrebuiltSidebarDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agentprebuilt-sidebar MainContent / CopilotSidebar agentIdprebuilt-sidebar defaultOpen{true} / Suggestions / /CopilotKit ); }关键点有三CopilotKit根组件通过runtimeUrl/api/copilotkit指定运行时端点agentprebuilt-sidebar指定默认 Agent 名称。整个页面只需包一层聊天能力即全局可用。CopilotSidebar /预置组件以agentIdprebuilt-sidebar绑定同一个 AgentdefaultOpen{true}让侧边栏首屏即展开。Suggestions /子组件只负责注册快捷指令详见第四节渲染时返回null不影响布局。与page.tsx平级的 main-content.tsx 是普通的主内容区页面说明文字里特意强调了这个组件的行为CopilotSidebar /是停靠dock在视口边缘的会推动页面内容而不是覆盖它——这与浮层型弹窗CopilotPopup形成对比也是第 3 条 QA 步骤“docked on the side”的语义来源。三、默认展开与停靠布局defaultOpen 的行为验证QA 第 3 步要求“sidebar docked on the side, open by default”对应端到端测试 prebuilt-sidebar.spec.ts 中的第一组断言await expect(page.getByPlaceholder(Type a message)).toBeVisible();注释说明得很清楚defaultOpen{true}意味着侧边栏的聊天输入框placeholder 为 Type a message在首次渲染时即挂载且可见。同时测试还断言侧边栏自带的开关按钮存在await expect( page.locator([data-testidcopilot-chat-toggle]).first(), ).toBeVisible();copilot-chat-toggle是组件内置的 launcher 按钮 testid无需前端自行实现折叠逻辑。关于停靠行为还可以从组件自带的侧边栏 testid 与无障碍属性看出设计测试用[data-testidcopilot-sidebar]定位侧边栏并用aria-hidden属性判断开合状态——默认展开时该属性为false折叠后变为true。这意味着开合是纯客户端状态不改变 URL测试末尾专门断言 URL 仍停留在/demos/prebuilt-sidebar便于无刷新地切换聊天面板。四、快捷指令useConfigureSuggestions 注入建议药丸侧边栏聊天框上方渲染的快捷指令来自 suggestions.tsuse client; import { useConfigureSuggestions } from copilotkit/react-core/v2; export function usePrebuiltSidebarSuggestions() { useConfigureSuggestions({ suggestions: [ { title: Say hi, message: Say hi! }, { title: Fun fact, message: Give me a fun fact. }, { title: Is 17 prime?, message: Walk me through whether 17 is prime. }, ], available: always, }); }每个建议由title药丸上显示的文字和message点击后真正发送给 Agent 的消息组成available: always表示建议药丸始终可见不受对话状态影响suggestions-mount.tsx 是一个纯挂载组件调用 hook 后返回null把建议注册逻辑从页面结构中隔离出来。端到端测试正是借用了这条链路完成“发消息”验证找到[data-testidcopilot-suggestion]中文本为 Say hi 的药丸并点击随后断言[data-testidcopilot-assistant-message]出现——由于该演示没有前端工具往返成功的信号就是“出现了一条助手气泡”。五、折叠与展开launcher 交互与无障碍状态QA 第 5 步“Click the launcher to collapse/expand the sidebar”对应测试文件中的最后一组用例它把开合状态落在aria-hidden属性上const sidebar page.locator([data-testidcopilot-sidebar]); // 默认展开aria-hiddenfalse await expect(sidebar).toHaveAttribute(aria-hidden, false); // 从内部关闭按钮收起侧边栏展开时会拦截外部 toggle 的指针事件 await page.evaluate(() { const btn document.querySelector([data-testidcopilot-close-button]); if (btn) (btn as HTMLElement).click(); }); await expect(sidebar).toHaveAttribute(aria-hidden, true, { timeout: 10000 }); // 通过悬浮 launcher 重新打开 await page.locator([data-testidcopilot-chat-toggle]).first().click(); await expect(sidebar).toHaveAttribute(aria-hidden, false, { timeout: 10000 });几个值得注意的实现细节均可从测试注释中确认侧边栏收起时通过CSS transform 滑出但组件仍然保持挂载因此aria-hidden是判断开合的权威信号展开状态下外部 toggle 会被侧边栏拦截指针事件所以测试从内部copilot-close-button关闭测试使用 JS 级.click()而非 Playwright 的指针点击是为了绕开 localhost 下自动启用的cpk-web-inspector开发覆盖层——这是真实环境里验证侧边栏交互时容易踩的坑。六、后端接线runtime 如何把请求交给 Langroid Agent前端连的是runtimeUrl/api/copilotkit真实路由实现在 src/app/api/copilotkit/route.ts。核心链路是后端独立进程Langroid Agent 跑在单独的 Python 服务上地址默认http://localhost:8000可用AGENT_URL环境变量覆盖AG-UI 协议代理createAgent()用ag-ui/client的HttpAgent包装后端地址运行时通过 AG-UI 协议把请求转发给 Langroid单路由多别名agentNames数组中注册了包括prebuilt-sidebar在内的 30 多个名字全部映射到同一个统一 Agent 端点/。注释明确说明这些“聊天外壳变体”前端差异仅体现在 UI 组合上CopilotChat vs Sidebar vs Popup 等后端 Agent 是同一个单路由模式createCopilotRuntimeHandler({ runtime, basePath: /api/copilotkit, mode: single-route })让所有 Agent 共享一个 POST 端点由请求体中的 agent 名称分派。此外路由的GET分支是一个健康探针返回后端 Agent 可达状态与OPENAI_API_KEY是否配置方便排查“页面能开但 Agent 不回话”的问题。这解释了 QA 第 4 步“Send hi and verify agent responds”为什么能成立只要GET /api/copilotkit显示agent_status: reachable消息往返链路就已打通。七、QA 步骤到代码的完整映射把 QA 文档、前端源码、路由和端到端测试串起来可以得到一张清晰的验证矩阵QA 步骤验证内容对应实现/测试依据1. 访问/demos/prebuilt-sidebar路由挂载page.tsx 为该路由的默认导出2. Sidebar demo 标题可见页面内容渲染main-content.tsx 中的h13. 侧边栏停靠且默认展开布局与默认状态defaultOpen{true}测试断言输入框与aria-hiddenfalse4. 发送 hi 收到回复消息往返链路点击 Say hi 药丸后断言助手气泡出现5. launcher 折叠/展开交互与无障碍copilot-chat-toggle/copilot-close-button/aria-hidden状态切换在 manifest.yaml 中该演示注册为prebuilt-sidebarPre-Built: Sidebarroute: /demos/prebuilt-sidebar并标记为interaction_modalities: sidebar的典型代表说明“预置侧边栏”是 Langroid 集成所支持的三种交互模态sidebar / embedded / chat之一。八、把这套方案复用到你自己的项目基于以上源码落地一个“默认展开的侧边栏聊天”只需四步包一层 Provider在应用根组件或单个页面外包CopilotKit runtimeUrl/api/copilotkit agentyour-agent放置预置组件在页面任意位置写CopilotSidebar agentIdyour-agent defaultOpen{true} /defaultOpen可省略默认关闭或设为false注册快捷指令可选调用useConfigureSuggestions配置suggestions与available点击药丸即发送预设消息接通后端确认/api/copilotkit路由已通过 AG-UI 协议代理到你的 Agent 服务参考 route.ts 的单路由模式并用GET健康探针验证agent_status。最后把 prebuilt-sidebar.spec.ts 里的四个用例页面加载、建议药丸、手动输入、折叠/展开纳入你的 CI就能像这份 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考