CopilotKit 与 Google ADK 集成Open-Ended Generative UI高级版沙箱桥接功能端到端验证指南【免费下载链接】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 仓库中 Google ADK 集成showcase/integrations/google-adk的 open-gen-ui-advanced 演示系统讲解开放生成式 UI高级版的完整功能验证方法。该演示的核心能力是Agent 在对话中流式生成一个可交互的沙箱 iframe UIiframe 内的 HTML/JS 通过Websandbox.connection.remote.*桥接调用宿主页面上注册的安全函数evaluateExpression、notifyHost实现沙箱 → 宿主 → 可见结果的往返闭环。读完本文你将掌握该 demo 的验证前置条件、逐项功能验收步骤、沙箱约束检查方法、错误处理路径以及背后运行时中间件与宿主函数实现的源码级原理。一、验证前的整体架构认知在动手执行测试步骤之前先建立对该 demo 架构的整体认知。open-gen-ui-advanced 演示的完整链路涉及四个关键部件Agent 后端Python / Google ADKshowcase/integrations/google-adk/src/agents/open_gen_ui_agents.py定义了open_gen_ui_advanced_agent使用AGUIToolset()工具其系统提示词_OPEN_GEN_UI_ADVANCED_INSTRUCTION强制要求 Agent 在每一轮用户对话中恰好调用一次generateSandboxedUi前端工具生成交互式 HTML/CSS/JS并要求生成的 UI 必须调用 Agent 上下文中列出的宿主侧沙箱函数。OGUI 运行时路由showcase/integrations/google-adk/src/app/api/copilotkit-ogui/route.ts创建CopilotRuntime通过openGenerativeUI: { agents: [open-gen-ui, open-gen-ui-advanced] }开启OpenGenerativeUIMiddleware——正是它把 Agent 流式输出的generateSandboxedUi工具调用转换为open-generative-uiactivity 事件。前端 Providershowcase/integrations/google-adk/src/app/demos/open-gen-ui-advanced/page.tsx中的CopilotKit openGenerativeUI{{ sandboxFunctions: openGenUiSandboxFunctions }}把宿主侧函数数组传给内置的OpenGenerativeUIActivityRenderer后者将 Agent 生成的 HTML/CSS 挂载进沙箱 iframe并把宿主函数以可调用的 remote 形式注入 iframe。宿主沙箱函数showcase/integrations/google-adk/src/app/demos/open-gen-ui-advanced/sandbox-functions.ts导出evaluateExpression与notifyHost两个处理函数。值得注意的一个易错点在 Agent 提示词中有明确说明iframe 内调用宿主函数必须写await Websandbox.connection.remote.functionName(args)而不是window.sandbox.*——因为渲染器把处理函数挂在 Websandbox 桥接上而非window.sandbox全局对象。二、前置条件核查执行验证前逐项确认以下前置条件均可在仓库源码中直接核实前置条件源码依据说明Demo 已部署且可访问演示页面showcase/integrations/google-adk/src/app/demos/open-gen-ui-advanced/page.tsx导航到 open-gen-ui-advanced demo 页面Agent 后端健康健康检查路由showcase/integrations/google-adk/src/app/api/health/route.ts访问/api/health确认返回正常open_gen_ui_advancedgraph 已注册OGUI 运行时showcase/integrations/google-adk/src/app/api/copilotkit-ogui/route.tsopenGenerativeUI.agents必须包含open-gen-ui-advanced且HttpAgent指向${AGENT_URL}/open_gen_ui_advanced默认http://localhost:8000沙箱函数已导出showcase/integrations/google-adk/src/app/demos/open-gen-ui-advanced/sandbox-functions.ts必须导出evaluateExpression和notifyHost其中第三条是最容易漏配的一环如果openGenerativeUI.agents列表缺少open-gen-ui-advancedOpenGenerativeUIMiddleware不会对该 Agent 的流生效iframe 将保持空白。三、基本功能验证这是对 demo 主链路的第一轮冒烟测试验证核心渲染是否成立导航到 open-gen-ui-advanced demo 页面验证CopilotChat在居中的max-w-4xl容器内全高度渲染。前端实现见 page.tsx外层为flex justify-center items-center h-screen w-full内层h-full w-full max-w-4xlChat组件内CopilotChat使用flex-1 rounded-2xl撑满高度验证输入撰写栏input composer可见发送一条基础消息例如Hi验证 Agent 调用了generateSandboxedUi且一个沙箱 iframe 挂载到了助手回复回合中。四、特性专项验证4.1 Suggestions 建议提示进入页面后撰写栏上方应出现三条建议定义见showcase/integrations/google-adk/src/app/demos/open-gen-ui-advanced/suggestions.ts通过useConfigureSuggestions挂载available: always✅Calculator (calls evaluateExpression)— 触发计算器场景✅Ping the host (calls notifyHost)— 触发宿主通知场景✅Inline expression evaluator— 触发内联表达式求值场景。每个message字符串同时充当确定性 aimock fixture 的键保持其短小且与showcase/aimock/d5-all.json中的 fixture 条目对齐以确保每次点击药丸都产生稳定的generateSandboxedUi工具调用。4.2 沙箱→宿主evaluateExpression计算器点击Calculator (calls evaluateExpression)建议验证沙箱 iframe 渲染出一个计算器 UI包含数字按钮、运算符按钮、显示区和按钮关键约束检查所有按钮必须使用typebuttoniframe 内不得存在form元素。原因在于 iframe 仅以sandboxallow-scripts运行浏览器会在任何onsubmit处理器执行之前就阻止沙箱内表单的提交按钮——这正是 Agent 系统提示词中显式禁止form和typesubmit的缘由见 open_gen_ui_agents.py 中_OPEN_GEN_UI_ADVANCED_INSTRUCTION的 Sandbox iframe restrictions (CRITICAL) 段落通过计算器按钮或生成的输入框输入类似12 * (3 4.5)的表达式在按下之前打开浏览器 DevTools 控制台按下验证宿主控制台输出[open-gen-ui/advanced] evaluateExpression 12 * (3 4.5) 90。这一日志来自宿主函数evaluateExpression的 handler 实现console.log语句见 sandbox-functions.ts验证显示区更新为90——即宿主返回的res.value验证显示区下方出现一条计算历史记录条目闭环感知验证在后续用户回合中输入What was the result of my last calculation?验证 Agent 的文本回复引用了刚计算出的值。这条验证覆盖完整往返链路沙箱调用 → 宿主处理 → 可见结果 → 通过后续回合上下文被 Agent 感知。4.3 沙箱→宿主notifyHostPing开启新一轮对话点击Ping the host (calls notifyHost)建议验证沙箱 iframe 渲染出一张卡片卡片上只有一个Say hi to the host按钮打开浏览器 DevTools 控制台点击该按钮验证宿主控制台输出[open-gen-ui/advanced] notifyHost: Hi from the sandbox!。宿主实现见 sandbox-functions.tshandler 先打印日志再返回确认对象验证卡片更新并显示返回的确认对象包含receivedAtISO-8601 时间戳由new Date().toISOString()生成和回显的message字段。4.4 沙箱→宿主内联表达式求值器开启新一轮对话点击Inline expression evaluator建议验证沙箱 iframe 渲染出文本输入框 Evaluate 按钮同样无form、按钮为typebutton输入2 2并点击Evaluate验证输出区渲染4来自res.value输入非法表达式abc 1并点击Evaluate验证输出区渲染res.error中的错误字符串如Unsupported characters in expression.。4.5 沙箱约束验证这是高级版区别于基础版的安全性核心务必逐条验证iframe 的sandbox属性必须是sandboxallow-scripts单独一项——不得出现allow-forms、allow-same-origin。这意味着 iframe 内代码没有同源权限也无法提交表单iframe 内不得发起任何网络请求在 DevTools 的 Network 面板中按 iframe frame 过滤应无请求记录。Agent 系统提示词明确要求生成的代码不得使用fetch/XHR/localStorage/document.cookie与宿主页面的全部交互只能经由Websandbox.connection.remote.*Agent 自身的聊天文本保持简短一句话以内真实的输出是渲染出的 UI而不是聊天文本。此约束同样固化在系统提示词中Keep your own chat message brief (1 sentence max)。五、错误处理验证错误处理是衡量桥接健壮性的关键维度结合宿主函数源码逐项验证非法字符注入向计算器/求值器输入含不支持字符的表达式如alert(1)确认宿主返回res.ok false且错误为Unsupported characters in expression.。源码依据evaluateExpression首先用正则/^[\d\-*/().\s]$/白名单校验表达式不匹配立即拒绝——从而保证永远不会执行任意 JS见 sandbox-functions.ts除零场景输入1/0验证 handler 返回{ ok: false, error: Not a finite number. }且 UI 渲染错误路径。源码依据Function(...)求值得到Infinity后Number.isFinite(value)检查将其拦截见 sandbox-functions.ts流中途刷新页面验证刷新后无残留的损坏 UI空消息输入空消息应被直接拒绝且不产生错误控制台噪音检查除沙箱函数 handler 内两处有意为之的console.log之外即evaluateExpression与notifyHost各自的日志控制台不应出现其他报错。六、预期结果与验收标准完成以上全部步骤后对照以下验收标准判断 demo 是否通过聊天在 3 秒内加载完成提交提示后约 15 秒内首个可交互的沙箱 UI 挂载完成沙箱 → 宿主的往返按钮点击 →Websandbox.connection.remote.fn→ 可见结果在无需页面刷新的情况下完成evaluateExpression在合法输入时返回{ ok, value }在被拒绝输入时返回{ ok: false, error }notifyHost返回{ ok: true, receivedAt, message }其中receivedAt为合法的 ISO-8601 时间戳全程无 UI 错误、无布局破坏。七、验证方法的可复用要点将该 QA 流程沉淀为方法论可迁移到其他集成的 open-gen-ui-advanced 演示仓库中 ag2、agno、langgraph-python、mastra、pydantic-ai、strands 等 20 余个集成目录下均存在同构的demos/open-gen-ui-advanced/sandbox-functions.ts且共享相同的宿主函数实现契约。复用时关注三点注册链路三处必须同时对齐route.ts的openGenerativeUI.agents、page.tsx的agent属性与openGenerativeUI.sandboxFunctions、后端 Agent 的工具/提示词沙箱约束不是锦上添花而是硬性前提allow-scripts独占决定了form与typesubmit必然失效宿主函数契约的返回字段名如res.value而非res.result必须与 Agent 上下文中的描述严格一致控制台日志是桥接是否生效的最快观测点两个 handler 的console.log前缀[open-gen-ui/advanced]是排查往返链路问题的首选探针。【免费下载链接】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），仅供参考