CopilotKit × Google ADK 声明式 UI 渲染实战JSON Render 演示的架构与 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 与 Google ADK 集成演示中的declarative-json-renderBYOC json-render场景展开系统讲解如何让 ADK Agent 以结构化 JSON 描述 UI组件树 属性再由前端json-render/react渲染器把流式 JSON 实时翻译成可交互的 React 组件。你将掌握该演示的完整架构链路、前置条件、逐步骤 QA 验收清单与预期结果并通过源码级分析理解流式解析、组件白名单校验、错误回退等底层实现原理可直接复用到你自己的 BYOCBring Your Own Component声明式 UI 项目中。一、场景定位什么是 BYOC json-render 演示在 showcase/integrations/google-adk 中CopilotKit 与 Google ADK 后端协作实现了一种让大模型输出 JSON、前端按 JSON 渲染组件的声明式 UI 模式。byoc_json_render是其中的一个 Agent 端点它对应演示页面/demos/declarative-json-render其 QA 验收文档位于 qa/declarative-json-render.md。与传统的模型返回纯文本不同该演示中 ADK Agent 的输出是一个包含{ root, elements }扁平元素表的 JSON specjson-render/react的Renderer /在 JSON 解析完成后将其绘制为真实组件。这是一种典型的BYOC思路——不在前端硬编码每种 UI 形态而是用受控的组件目录catalog约束模型可生成的组件类型让 Agent 动态拼装仪表盘。注ADK 集成中byoc_json_render与byoc-hashbrown共享同一个byoc_agent实例Agent 的响应同时携带两种线格式ui[]数组与root/elements映射各自前端渲染器只提取自己关心的键。详见 byoc_agents.py。二、前置条件依据 QA 文档运行与验证该演示需要满足以下条件前置项说明演示部署演示页面部署在/demos/declarative-json-renderADK Agent 后端在${AGENT_URL}/byoc_json_render可访问且健康环境变量Next.js 应用中配置GOOGLE_API_KEY与AGENT_URL前端依赖json-render/corejson-render/react已加入package.json该仓库锁定为0.18.0见 package.jsonAgent 注册byoc_json_render在src/agents/registry.py中注册映射到byoc_agent后端启动方式package.json的dev脚本使用concurrently同时启动 Next.jsnext dev --turbopack与 uvicorn 的 ADK FastAPI 服务默认监听0.0.0.0:8000支持PORT环境变量覆盖见 agent_server.pynpm run devGOOGLE_API_KEY用于驱动 Gemini 模型DEFAULT_MODEL gemini-3.1-flash-lite见 shared_chat.py。若未设置entrypoint.sh 默认仅告警但 Gemini 相关的聊天能力会在请求时返回结构化错误设置REQUIRE_GOOGLE_API_KEY1可改为启动即失败fail-fast。三、前端接线从 CopilotKit 到 json-render 渲染器3.1 页面与 Runtime 挂载演示页 page.tsx 使用CopilotKit包裹runtimeUrl指向专用API 路由/api/copilotkit-declarative-json-render并绑定agentbyoc_json_renderCopilotKit runtimeUrl/api/copilotkit-declarative-json-render agent{AGENT_ID} 这条专用路由 route.ts 与默认的多 Agent/api/copilotkit运行时隔离通过ag-ui/client的HttpAgent把请求转发到 Python 侧 ADK 端点const AGENT_URL process.env.AGENT_URL || http://localhost:8000; const byocJsonRenderAgent new HttpAgent({ url: ${AGENT_URL}/byoc_json_render, headers, // 透传 x-aimock-context 等入站请求头 }); const runtime new CopilotRuntime({ agents: { byoc_json_render: byocJsonRenderAgent }, });3.2 聊天组件与自定义 Assistant 消息视图chat.tsx 渲染CopilotChat并通过messageView.assistantMessage把默认的助手气泡替换为自定义的JsonRenderAssistantMessageCopilotChat agentId{AGENT_ID} messageView{{ assistantMessage: JsonRenderAssistantMessage }} /这意味着每条助手消息都会先经过自定义渲染器若内容能解析为合法的 json-render spec就渲染组件树否则回退到默认气泡。3.3 建议提示Suggestion Pillssuggestions.ts 通过useConfigureSuggestions注册三条建议available: always表示欢迎屏始终展示export const BYOC_JSON_RENDER_SUGGESTIONS [ { title: Sales dashboard, message: Show me the sales dashboard with metrics and a revenue chart }, { title: Revenue by category,message: Break down revenue by category as a pie chart }, { title: Expense trend, message: Show me monthly expenses as a bar chart }, ];这三条建议正是 QA 文档 Step 1 中期望出现的三个标题与 E2E 测试 declarative-json-render.spec.ts 断言一一对应。四、QA 验收步骤详解以下步骤完全继承 QA 文档的验收清单并补充了可验证的源码证据。Step 1页面加载导航至/demos/declarative-json-render。聊天输入框chat composer可见。欢迎屏出现三个建议提示Sales dashboard、Revenue by category、Expense trend数据源见上文suggestions.ts。控制台无报错。E2E 对应断言page.locator(textarea, [placeholder*message]).first()可见10 秒超时三个建议标题均可见。Step 2Sales dashboard 建议点击 Sales dashboard 后60 秒内助手气泡内出现data-testidjson-render-root包裹层。包裹层内渲染data-testidmetric-cardKPI 指标卡。包裹层内渲染图表data-testidbar-chart或data-testidpie-chart。渲染完成后不展示任何原始 JSON 文本——流式 JSON 被组件替换。json-render-root由 json-render-renderer.tsx 输出metric-card与图表分别由 metric-card.tsx 与 charts/bar-chart.tsx以及 pie-chart渲染。Step 3Revenue by category点击 Revenue by category 后60 秒内出现data-testidpie-chart包含多个分类扇区与图例legend。对应 E2Espec 第 57-65 行。Step 4Expense trend点击 Expense trend 后60 秒内出现data-testidbar-chartX 轴带月份标签month labels。Step 5自由表单提示输入 Show me a metric for quarterly revenue 并发送至少渲染一个metric-card控制台无报错。这一步验证模型在未命中预设建议时仍能按 prompt 约束输出合法 spec。Step 6多轮对话在上一轮渲染可见后发送后续提示如 Now break that down by region。出现新的助手消息与新的 json-render 渲染且之前的渲染保留在对话记录中。这验证了多轮上下文中每条消息的独立渲染与历史留存。Step 7格式错误输出处理若 Agent 偶尔返回非 JSON 文本如追问 tell me a joke 强制触发聊天应回退为默认助手气泡渲染纯文本。不允许崩溃或卡在加载转圈。这正是渲染器中的兜底逻辑见下文错误回退机制。五、预期结果与验收基准QA 文档明确了三项核心预期渲染时限建议触发后在 60 秒内完成渲染。预算略高于 hashbrown 演示——因为 JSON{ root, elements }spec 比 hashbrown 的 token 流更冗长结构更 verbose。零未捕获异常控制台无 uncaught errors。流式降级在 JSON 尚未解析完成前流式内容回退为纯文本一旦 JSON 解析成功立即切换为渲染组件。对应地Playwright E2E 测试 为第 2、3、4 步都设置了 60000ms 超时断言与文档 60 秒基准一致。六、源码级原理流式 JSON 如何变成 UI6.1 解析管线parseSpec与extractJsonObjectjson-render-renderer.tsx 是核心extractJsonObject(raw)第 70-99 行剥离可能的代码围栏json ... 然后做花括号配平扫描——逐字符跟踪{/}深度、字符串状态与转义返回第一个平衡的完整 JSON 对象字符串。这是对模型输出夹杂散文或代码围栏的容错处理。parseSpec(content)第 43-67 行对提取到的文本执行JSON.parse然后校验结构root必须是字符串elements必须是对象root必须指向elements中存在的键每个元素必须有字符串type且type 必须在ALLOWED_TYPES白名单MetricCard、BarChart、PieChart内props若存在必须是对象。任一环节失败即返回null渲染器随即回退到默认气泡if (!spec) return CopilotChatAssistantMessage {...props} /。这就是 Step 7坏输出不崩溃的实现保障。6.2 组件目录catalog与 zod 模式catalog.ts 用json-render/core的defineCatalog声明模型可用的三种组件及其属性模式zod schemaMetricCardlabel: string、value: string、trend: string | nullBarCharttitle、description: string | null、data: Array{label, value}PieChart与 BarChart 相同的结构。每个组件还配有description用于在模型侧描述组件用途如 PieChart 用于把总量拆分为分类扇区。6.3 组件注册表registryregistry.tsx 通过defineRegistry把目录中的组件名映射到真实 React 实现。其中MetricCard的实现会转发 children——这对应elements中的children数组使 Agent 可以把图表嵌套在指标卡之下一个root为 MetricCard、children引用 PieChart/BarChart 的仪表盘树MetricCard: ({ props, children }) ( div classNameflex w-full flex-col items-stretch gap-3 MetricCard {...(props as MetricCardComponentProps)} / {children} /div ),spec 的类型定义见 types.tsroot: string、elements: Recordid, { type, props, children?: string[] }。6.4 ADK Agent如何保证输出合法 JSONPython 侧 byoc_agents.py 定义byoc_agent LlmAgent(...)关键配置instruction_BYOC_SYSTEM_PROMPT统一 prompt 详细规定了ui[]与root/elements双格式的组件名、属性、示例响应Sales dashboard 示例并要求不允许代码围栏、不允许前言、必须整体是合法 JSONtools[]不挂任何后端工具全部仪表盘数据由模型内联生成前端流式 JSON 解析器可渐进重建 UIgenerate_content_configtypes.GenerateContentConfig(response_mime_typeapplication/json, temperature0.2)Gemini 侧强制 JSON 对象输出模式temperature0.2在保证模式遵守的同时保留样本数据的变化after_model_callbackstop_on_terminal_text见 shared_chat.py该回调仅在最终完整文本轮且finish_reasonSTOP时终止 Agent 循环避免流式中间分片或带 function_call 的混合响应导致提前结束。6.5 后端注册与端点挂载registry.py 中declarative-hashbrown: AgentSpec(byoc_agent), byoc_json_render: AgentSpec(byoc_agent),agent_server.py 遍历注册表为每个 agent 名在/agent_name挂载 ADK FastAPI 端点——于是${AGENT_URL}/byoc_json_render即byoc_json_render的可达 HTTP 地址与前端HttpAgent的 URL 拼接逻辑闭环。七、常见验收陷阱与排查建议60 秒超时仍未渲染优先检查AGENT_URL是否指向健康的 ADK 服务、GOOGLE_API_KEY是否有效其次查看网络面板确认/api/copilotkit-declarative-json-render的 SSE 流是否持续输出。渲染出的是纯文本而非组件说明parseSpec返回了null多为模型输出的 JSON 中出现了白名单之外的type、root指向不存在的元素 id或 JSON 本身畸形。可打开控制台观察是否有 spec 校验相关的告警。控制台报错但页面可用注意stop_on_terminal_text对 Gemini 混合 textfunction_call 响应的保护逻辑若你自定义了 Agent请保留该回调以规避无限调用工具或提前终止两类问题。八、总结通过本文你可以清晰地看到一条完整链路ADK Agentbyoc_agent强制 JSON 输出→ FastAPI 端点/${AGENT_URL}/byoc_json_render→ CopilotKit 专用 Runtime 路由 → 自定义JsonRenderAssistantMessage→parseSpec白名单校验 →json-render/react的Renderer /绘制组件树。QA 文档中的七步验收覆盖了页面加载、三类建议、自由表单、多轮与坏输出回退而仓库中的 catalog.ts、registry.tsx 与 byoc_agents.py 则是支撑这些验收的底层实现——理解它们你就能把Agent 输出 JSON、前端渲染组件的 BYOC 模式迁移到自己的产品中。【免费下载链接】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 × Google ADK 声明式 UI 渲染实战：JSON Render 演示的架构与 QA 验收指南
CopilotKit × Google ADK 声明式 UI 渲染实战JSON Render 演示的架构与 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 与 Google ADK 集成演示中的declarative-json-renderBYOC json-render场景展开系统讲解如何让 ADK Agent 以结构化 JSON 描述 UI组件树 属性再由前端json-render/react渲染器把流式 JSON 实时翻译成可交互的 React 组件。你将掌握该演示的完整架构链路、前置条件、逐步骤 QA 验收清单与预期结果并通过源码级分析理解流式解析、组件白名单校验、错误回退等底层实现原理可直接复用到你自己的 BYOCBring Your Own Component声明式 UI 项目中。一、场景定位什么是 BYOC json-render 演示在 showcase/integrations/google-adk 中CopilotKit 与 Google ADK 后端协作实现了一种让大模型输出 JSON、前端按 JSON 渲染组件的声明式 UI 模式。byoc_json_render是其中的一个 Agent 端点它对应演示页面/demos/declarative-json-render其 QA 验收文档位于 qa/declarative-json-render.md。与传统的模型返回纯文本不同该演示中 ADK Agent 的输出是一个包含{ root, elements }扁平元素表的 JSON specjson-render/react的Renderer /在 JSON 解析完成后将其绘制为真实组件。这是一种典型的BYOC思路——不在前端硬编码每种 UI 形态而是用受控的组件目录catalog约束模型可生成的组件类型让 Agent 动态拼装仪表盘。注ADK 集成中byoc_json_render与byoc-hashbrown共享同一个byoc_agent实例Agent 的响应同时携带两种线格式ui[]数组与root/elements映射各自前端渲染器只提取自己关心的键。详见 byoc_agents.py。二、前置条件依据 QA 文档运行与验证该演示需要满足以下条件前置项说明演示部署演示页面部署在/demos/declarative-json-renderADK Agent 后端在${AGENT_URL}/byoc_json_render可访问且健康环境变量Next.js 应用中配置GOOGLE_API_KEY与AGENT_URL前端依赖json-render/corejson-render/react已加入package.json该仓库锁定为0.18.0见 package.jsonAgent 注册byoc_json_render在src/agents/registry.py中注册映射到byoc_agent后端启动方式package.json的dev脚本使用concurrently同时启动 Next.jsnext dev --turbopack与 uvicorn 的 ADK FastAPI 服务默认监听0.0.0.0:8000支持PORT环境变量覆盖见 agent_server.pynpm run devGOOGLE_API_KEY用于驱动 Gemini 模型DEFAULT_MODEL gemini-3.1-flash-lite见 shared_chat.py。若未设置entrypoint.sh 默认仅告警但 Gemini 相关的聊天能力会在请求时返回结构化错误设置REQUIRE_GOOGLE_API_KEY1可改为启动即失败fail-fast。三、前端接线从 CopilotKit 到 json-render 渲染器3.1 页面与 Runtime 挂载演示页 page.tsx 使用CopilotKit包裹runtimeUrl指向专用API 路由/api/copilotkit-declarative-json-render并绑定agentbyoc_json_renderCopilotKit runtimeUrl/api/copilotkit-declarative-json-render agent{AGENT_ID} 这条专用路由 route.ts 与默认的多 Agent/api/copilotkit运行时隔离通过ag-ui/client的HttpAgent把请求转发到 Python 侧 ADK 端点const AGENT_URL process.env.AGENT_URL || http://localhost:8000; const byocJsonRenderAgent new HttpAgent({ url: ${AGENT_URL}/byoc_json_render, headers, // 透传 x-aimock-context 等入站请求头 }); const runtime new CopilotRuntime({ agents: { byoc_json_render: byocJsonRenderAgent }, });3.2 聊天组件与自定义 Assistant 消息视图chat.tsx 渲染CopilotChat并通过messageView.assistantMessage把默认的助手气泡替换为自定义的JsonRenderAssistantMessageCopilotChat agentId{AGENT_ID} messageView{{ assistantMessage: JsonRenderAssistantMessage }} /这意味着每条助手消息都会先经过自定义渲染器若内容能解析为合法的 json-render spec就渲染组件树否则回退到默认气泡。3.3 建议提示Suggestion Pillssuggestions.ts 通过useConfigureSuggestions注册三条建议available: always表示欢迎屏始终展示export const BYOC_JSON_RENDER_SUGGESTIONS [ { title: Sales dashboard, message: Show me the sales dashboard with metrics and a revenue chart }, { title: Revenue by category,message: Break down revenue by category as a pie chart }, { title: Expense trend, message: Show me monthly expenses as a bar chart }, ];这三条建议正是 QA 文档 Step 1 中期望出现的三个标题与 E2E 测试 declarative-json-render.spec.ts 断言一一对应。四、QA 验收步骤详解以下步骤完全继承 QA 文档的验收清单并补充了可验证的源码证据。Step 1页面加载导航至/demos/declarative-json-render。聊天输入框chat composer可见。欢迎屏出现三个建议提示Sales dashboard、Revenue by category、Expense trend数据源见上文suggestions.ts。控制台无报错。E2E 对应断言page.locator(textarea, [placeholder*message]).first()可见10 秒超时三个建议标题均可见。Step 2Sales dashboard 建议点击 Sales dashboard 后60 秒内助手气泡内出现data-testidjson-render-root包裹层。包裹层内渲染data-testidmetric-cardKPI 指标卡。包裹层内渲染图表data-testidbar-chart或data-testidpie-chart。渲染完成后不展示任何原始 JSON 文本——流式 JSON 被组件替换。json-render-root由 json-render-renderer.tsx 输出metric-card与图表分别由 metric-card.tsx 与 charts/bar-chart.tsx以及 pie-chart渲染。Step 3Revenue by category点击 Revenue by category 后60 秒内出现data-testidpie-chart包含多个分类扇区与图例legend。对应 E2Espec 第 57-65 行。Step 4Expense trend点击 Expense trend 后60 秒内出现data-testidbar-chartX 轴带月份标签month labels。Step 5自由表单提示输入 Show me a metric for quarterly revenue 并发送至少渲染一个metric-card控制台无报错。这一步验证模型在未命中预设建议时仍能按 prompt 约束输出合法 spec。Step 6多轮对话在上一轮渲染可见后发送后续提示如 Now break that down by region。出现新的助手消息与新的 json-render 渲染且之前的渲染保留在对话记录中。这验证了多轮上下文中每条消息的独立渲染与历史留存。Step 7格式错误输出处理若 Agent 偶尔返回非 JSON 文本如追问 tell me a joke 强制触发聊天应回退为默认助手气泡渲染纯文本。不允许崩溃或卡在加载转圈。这正是渲染器中的兜底逻辑见下文错误回退机制。五、预期结果与验收基准QA 文档明确了三项核心预期渲染时限建议触发后在 60 秒内完成渲染。预算略高于 hashbrown 演示——因为 JSON{ root, elements }spec 比 hashbrown 的 token 流更冗长结构更 verbose。零未捕获异常控制台无 uncaught errors。流式降级在 JSON 尚未解析完成前流式内容回退为纯文本一旦 JSON 解析成功立即切换为渲染组件。对应地Playwright E2E 测试 为第 2、3、4 步都设置了 60000ms 超时断言与文档 60 秒基准一致。六、源码级原理流式 JSON 如何变成 UI6.1 解析管线parseSpec与extractJsonObjectjson-render-renderer.tsx 是核心extractJsonObject(raw)第 70-99 行剥离可能的代码围栏json ... 然后做花括号配平扫描——逐字符跟踪{/}深度、字符串状态与转义返回第一个平衡的完整 JSON 对象字符串。这是对模型输出夹杂散文或代码围栏的容错处理。parseSpec(content)第 43-67 行对提取到的文本执行JSON.parse然后校验结构root必须是字符串elements必须是对象root必须指向elements中存在的键每个元素必须有字符串type且type 必须在ALLOWED_TYPES白名单MetricCard、BarChart、PieChart内props若存在必须是对象。任一环节失败即返回null渲染器随即回退到默认气泡if (!spec) return CopilotChatAssistantMessage {...props} /。这就是 Step 7坏输出不崩溃的实现保障。6.2 组件目录catalog与 zod 模式catalog.ts 用json-render/core的defineCatalog声明模型可用的三种组件及其属性模式zod schemaMetricCardlabel: string、value: string、trend: string | nullBarCharttitle、description: string | null、data: Array{label, value}PieChart与 BarChart 相同的结构。每个组件还配有description用于在模型侧描述组件用途如 PieChart 用于把总量拆分为分类扇区。6.3 组件注册表registryregistry.tsx 通过defineRegistry把目录中的组件名映射到真实 React 实现。其中MetricCard的实现会转发 children——这对应elements中的children数组使 Agent 可以把图表嵌套在指标卡之下一个root为 MetricCard、children引用 PieChart/BarChart 的仪表盘树MetricCard: ({ props, children }) ( div classNameflex w-full flex-col items-stretch gap-3 MetricCard {...(props as MetricCardComponentProps)} / {children} /div ),spec 的类型定义见 types.tsroot: string、elements: Recordid, { type, props, children?: string[] }。6.4 ADK Agent如何保证输出合法 JSONPython 侧 byoc_agents.py 定义byoc_agent LlmAgent(...)关键配置instruction_BYOC_SYSTEM_PROMPT统一 prompt 详细规定了ui[]与root/elements双格式的组件名、属性、示例响应Sales dashboard 示例并要求不允许代码围栏、不允许前言、必须整体是合法 JSONtools[]不挂任何后端工具全部仪表盘数据由模型内联生成前端流式 JSON 解析器可渐进重建 UIgenerate_content_configtypes.GenerateContentConfig(response_mime_typeapplication/json, temperature0.2)Gemini 侧强制 JSON 对象输出模式temperature0.2在保证模式遵守的同时保留样本数据的变化after_model_callbackstop_on_terminal_text见 shared_chat.py该回调仅在最终完整文本轮且finish_reasonSTOP时终止 Agent 循环避免流式中间分片或带 function_call 的混合响应导致提前结束。6.5 后端注册与端点挂载registry.py 中declarative-hashbrown: AgentSpec(byoc_agent), byoc_json_render: AgentSpec(byoc_agent),agent_server.py 遍历注册表为每个 agent 名在/agent_name挂载 ADK FastAPI 端点——于是${AGENT_URL}/byoc_json_render即byoc_json_render的可达 HTTP 地址与前端HttpAgent的 URL 拼接逻辑闭环。七、常见验收陷阱与排查建议60 秒超时仍未渲染优先检查AGENT_URL是否指向健康的 ADK 服务、GOOGLE_API_KEY是否有效其次查看网络面板确认/api/copilotkit-declarative-json-render的 SSE 流是否持续输出。渲染出的是纯文本而非组件说明parseSpec返回了null多为模型输出的 JSON 中出现了白名单之外的type、root指向不存在的元素 id或 JSON 本身畸形。可打开控制台观察是否有 spec 校验相关的告警。控制台报错但页面可用注意stop_on_terminal_text对 Gemini 混合 textfunction_call 响应的保护逻辑若你自定义了 Agent请保留该回调以规避无限调用工具或提前终止两类问题。八、总结通过本文你可以清晰地看到一条完整链路ADK Agentbyoc_agent强制 JSON 输出→ FastAPI 端点/${AGENT_URL}/byoc_json_render→ CopilotKit 专用 Runtime 路由 → 自定义JsonRenderAssistantMessage→parseSpec白名单校验 →json-render/react的Renderer /绘制组件树。QA 文档中的七步验收覆盖了页面加载、三类建议、自由表单、多轮与坏输出回退而仓库中的 catalog.ts、registry.tsx 与 byoc_agents.py 则是支撑这些验收的底层实现——理解它们你就能把Agent 输出 JSON、前端渲染组件的 BYOC 模式迁移到自己的产品中。【免费下载链接】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），仅供参考