CopilotKit × Google ADK 生成式 UI 实战Agentic 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 集成的gen-ui-agent演示为对象系统讲解智能体在长任务执行过程中通过工具调用向客户端流式发布状态、由前端实时渲染为任务进度卡片这一 Agentic Generative UI 的完整链路。读完本文你将掌握该功能的前后端实现原理、QA 验证清单的执行方法以及对应的 Playwright 端到端测试是如何锁定单一状态卡片原地更新这一核心契约的。一、Demo 概览什么是 Agentic Generative UIgen-ui-agent是 showcase/integrations/google-adk 集成包中的核心演示之一。它展示了一种典型场景智能体在后台执行一个多步骤的长期任务如制定计划同时把每一步的状态实时推送给前端前端在聊天流中原地渲染一张不断刷新的任务进度卡片用户无需等待全部完成即可看到中间过程。该功能在 CopilotKit 生态中被称为 Agentic Generative UI核心特征是Agent 驱动的 UI 渲染UI 形态和内容由后端智能体的状态决定而非由前端预先写死。这一点在演示目录的 README.md 中有明确说明The agent renders custom UI as it works through long-running tasks, streaming status updates and intermediate results into the chat.在仓库内这个演示与 mastra、strands、ag2、agno、crewai-crews、langgraph-typescript、pydantic-ai 等所有其他集成的同名演示保持一致的实现模式见 page.tsx 顶部注释因此本文的分析对理解整个 CopilotKit 生态的生成式 UI 模式具有通用参考价值。二、QA 前置条件Demo 部署与后端健康检查按照 gen-ui-agent.md 的 QA 清单开始验证前需要满足两个前置条件Demo 已部署且可访问——即本地启动或云端部署的 showcase 前端已就绪Agent 后端健康——通过检查/api/health端点确认后端存活。后端健康检查的实现位于 agent_server.py它通过 FastAPI middleware 拦截GET /health请求并在路由解析之前短路返回从而保证即使其余路由异常健康端点依然可达。这一设计保证了 QA 流程的第一步——后端是否健康——永远有确定性的探测入口。后端进程会遍历 registry.py 中定义的AGENT_REGISTRY为每个条目挂载一个 ADKAgent middleware 到/agent_name路径前端 Next.js 的/api/copilotkit路由再将 agent 名称代理到对应的后端路径。gen-ui-agent正是通过gen-ui-agent: AgentSpec(gen_ui_agent)这一行注册进 registry 的。三、基础功能验证页面加载与聊天交互QA 清单的第一组检查项对应页面加载与基础聊天导航到 gen-ui-agent 演示页路由为/demos/gen-ui-agent聊天界面以居中、全高布局加载聊天输入框占位文本为Type a message发送一条基础消息后Agent 能正常回复。前端的布局与交互在 page.tsx 中实现页面根节点使用CopilotKit runtimeUrl/api/copilotkit agentgen-ui-agent包裹Chat组件内以flex justify-center items-center h-screen w-full实现居中全高布局并在容器内放置max-w-4xl的CopilotChat组件。这条检查项在端到端测试 gen-ui-agent.spec.ts 中有完全对应的断言page loads with chat input用getByPlaceholder(Type a message)断言输入框可见sends message and gets assistant response填入 Hello 并按回车在 30 秒超时内等待data-testidcopilot-assistant-message出现message list container exists发送消息后等待data-testidcopilot-message-list可见注意测试注释中说明CopilotChat v2 在无消息时会渲染欢迎屏因此消息列表容器只有发出第一条消息后才出现。四、建议按钮Suggestions从 QA 清单看前端的提示配置QA 清单要求验证页面上存在两个建议按钮Simple plan建议按钮计划 5 步去火星Complex plan建议按钮计划 10 步做披萨。注QA 文档描述的是该 demo 的通用验收标准仓库实际代码中建议按钮通过useConfigureSuggestions配置具体条目以 suggestions.ts 为准内容包括 Plan a product launch为移动应用制定产品发布计划、Organize a team offsite组织三天工程团队团建、Research a competitor调研主要竞争对手三条配置为available: always始终可用。QA 中点击建议按钮即可触发对应任务的验证逻辑同样适用于仓库内的建议按钮——点击后按钮文案对应的消息会填充并发送从而启动一次完整的计划任务执行。五、任务进度追踪器useAgent 状态流的核心验证这是整个 QA 清单最核心的部分。它验证的是Agent 流式发布状态 → 前端订阅并实时渲染这一链路。5.1 触发与渲染契约QA 步骤为点击 Simple plan 建议或输入 Build a plan to go to Mars in 5 steps 之类的计划型消息然后验证TaskProgress组件渲染对应data-testidagent-state-card进度条出现且带渐变填充步骤条目带描述文字对应data-testidagent-step文案内容对应data-testidtask-step-text的语义N/N Complete 计数器随步骤完成实时更新。这里需要说明QA 文档中使用的 testidtask-progress、task-step-text是该 QA 模板在不同集成间复用时的通用命名在 Google ADK 集成的实际实现中等价断言使用agent-state-card与agent-step详见 gen-ui-agent.spec.ts 与 InlineAgentStateCard.tsx。验证时以实际页面 DOM 为准。5.2 前端useAgent 订阅实时状态在 page.tsx 中Chat组件通过 v2 版本的useAgent钩子订阅 agent 状态const { agent } useAgent({ agentId: gen-ui-agent, updates: [UseAgentUpdate.OnStateChanged], }); const steps (agent.state as AgentState | undefined)?.steps ?? []; const status agent.isRunning ? inProgress : complete;updates: [UseAgentUpdate.OnStateChanged]声明只订阅状态变化事件agent.state.steps直接读取后端发布的步骤数组agent.isRunning决定卡片整体处于 inProgress进行中还是 complete完成状态。随后通过CopilotChat的messageView.children插槽把MessageListWithState注入聊天转录流CopilotChat agentIdgen-ui-agent classNameh-full rounded-2xl messageView{{ children: ({ messageElements, interruptElement }) ( MessageListWithState messageElements{messageElements} interruptElement{interruptElement} steps{steps} status{status} / ), }} /在 message-list-with-state.tsx 中步骤非空时把InlineAgentStateCard渲染在消息元素之后、中断元素之前从而实现状态卡片嵌在聊天流中的效果。关键设计点源码注释明确强调这套模式替代了早期 V1 的useCoAgentStateRender方案。旧方案会在每条改变状态的 agent 消息下各生成一张卡片导致一次执行产生 7 张堆叠的重复卡片新方案通过useAgentmessageView.children渲染单张原地更新的卡片无论状态更新多少次页面上始终只有一张。5.3 后端set_steps 工具与状态发布后端 Agent 定义在 gen_ui_agent.py。它由 Google ADK 的LlmAgent构建绑定了set_steps自定义工具和AGUIToolset()def set_steps(tool_context: ToolContext, steps: list[dict]) - dict: Publish the current plan step statuses. tool_context.state[steps] steps return {status: ok, step_count: len(steps)}set_steps每次被调用都会把完整的步骤列表写入 ADK 会话状态state[steps]中由 AG-UI 协议流式推送到客户端。步骤是{id, title, status}三字段结构status取值限定为pending、in_progress、completed三者之一——这与前端InlineAgentStateCard.tsx中Step类型的定义完全一致前端类型声明见 InlineAgentStateCard.tsx。_INSTRUCTION系统提示词则规定了 Agent 的执行纪律规划恰好 3 个步骤一次性以statuspending调用set_steps对每个步骤先以in_progress发布、再以completed发布串行等待禁止并行调用三步全部完成后发送一条最终总结消息并终止不再调用任何工具每次调用都必须携带完整的三个步骤列表仅改变status字段保持id与title跨调用不变。这套整表重发、单字段变更的协议正是前端能够原地更新、而不需要做增量合并的前提——每次状态变更都是一份完整快照。5.4 卡片的三种步骤状态视觉呈现QA 清单要求验证三种步骤状态的不同视觉表现对应 InlineAgentStateCard.tsx 中StepMarker的实现已完成步骤completed圆形标记使用浅绿色背景#85ECCE配勾选图标SVG check path步骤标题显示删除线line-through和浅灰文字#838389QA 文档描述的绿色背景渐变 对勾图标 绿色文字即对应此状态。当前进行步骤in_progress圆形标记使用蓝紫色背景#BEC2FF配旋转的 spinner SVGanimate-spin标题加粗font-medium并使用深色文字#010507头部区域同时显示SpinnerIcon和 Step X of N 文案对应 QA 中的Processing... 语义与脉动动画animate-spin。未来待处理步骤pending圆形标记为白底灰边框显示步骤序号数字标题使用中等灰文字#57575B对应 QA 文档描述的灰色背景 时钟图标 弱化文字。卡片头部还实现了进度语义done steps.filter(s s.status completed).length统计完成数标题区在全部完成时显示 All N steps complete否则显示 Step X of N对应 QA 中的 N/N Complete 计数器没有任何步骤时显示 Planning…。进度条宽度随完成数增长的直观效果即由这些头部文案与标记状态的逐条切换体现。5.5 复杂计划场景QA 清单的第二个功能场景是输入 Plan to make pizza in 10 steps验证进度追踪器出现 10 个步骤进度条宽度随步骤完成逐渐增加。该场景与前一个场景共享同一套机制无论步骤数量是 5、10 还是 3set_steps都会把完整的步骤列表写入状态前端卡片按steps.length渲染条目、按done/total更新头部计数。步骤数量与执行链长度是后端指令控制的当前 gen_ui_agent.py 固定为 3 步但这不影响前端对任意数量步骤的通用渲染能力。六、错误处理验证QA 清单的最后一部分要求发送空消息应被优雅处理不能崩溃正常使用过程中控制台不应出现报错。这与仓库整体的测试基础设施一致展示目录的端到端测试tests/e2e/gen-ui-agent.spec.ts在每个用例中均依赖 Playwright 对页面稳定性的约束而空消息等边界输入由CopilotChat组件自身的输入校验兜底。若验证过程中发现控制台报错可以结合 docs-links.json 中登记的文档路由定位对应功能说明排查前后端协议不匹配问题。七、预期结果与自动化回归验证QA 文档给出了明确的性能与正确性验收标准指标验收标准聊天界面加载3 秒内完成Agent 首次回复10 秒内返回任务进度追踪器实时显示步骤完成进度进度条动画平滑无卡顿UI 稳定性无报错、无布局破损这些人工 QA 标准在仓库中被自动化测试固化gen-ui-agent.spec.ts 中与本文主题最相关的三条回归测试renders a single agent-state-card that updates in place——发送计划消息后等待agent-state-card出现、至少一个agent-step渲染断言卡片数量始终为 1而非每个状态更新一张随后等待 spinner 消失agent.isRunning翻转再次断言仍只有一张卡片。这条测试直接锁定了单卡片原地更新契约。eventually marks every step as completed——等待 3 个data-statuscompleted的步骤全部出现并断言总步骤数也恰好为 3无孤儿步骤验证pending → in_progress → completed完整链路走到终点。steps animate through pending before completing (no fixture short-circuit)——防止测试夹具短路夹具必须触发完整的 7 次set_steps调用链一次全量 pending 每步两次状态切换禁止一次性把所有步骤都标成 completed从而保证卡片确实经历了顺序动画。这些测试还顺带验证了第 5.1 节提到的状态流经过 toolCallId 串联的实现细节——后端按 7 次调用串行发布状态测试则通过data-status属性断言最终收敛到全部 completed。八、小结从 QA 清单到实现的可追溯链路把 QA 文档的检查项映射回源码可以得到一条完整的可追溯链路前置条件→ agent_server.py 的/healthmiddlewareAgent 注册→ registry.py 中的gen-ui-agent: AgentSpec(gen_ui_agent)状态发布→ gen_ui_agent.py 的set_steps工具与_INSTRUCTION提示词状态订阅→ page.tsx 的useAgentmessageView.children卡片渲染→ InlineAgentStateCard.tsx 的三种步骤状态视觉与计数逻辑自动化验证→ gen-ui-agent.spec.ts 的单卡片契约、全步骤完成、无夹具短路三条回归测试。这套后端工具写状态、AG-UI 协议流推送、前端 useAgent 订阅、messageView.children 注入单卡片的模式是 CopilotKit 生态中 Agentic Generative UI 的通用范式。无论你后续接入 mastra、strands、langgraph 还是其他后端框架只要掌握本文的set_steps状态协议与useAgent订阅渲染这两条主线就能把任意多步骤长任务改造成具备实时可视进度的生成式 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考