 Agentic Generative UI 验证指南：从 QA 检查清单到源码级实现解析)
CopilotKit × LangGraph (FastAPI) Agentic Generative UI 验证指南从 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 开源仓库中showcase/integrations/langgraph-fastapi/qa/gen-ui-agent.md质量验证文档为核心骨架完整解析 Agentic Generative UI生成式 UI / 代理状态驱动 UIdemo 的验收流程并对照仓库内 FastAPI LangGraph 后端、Next.js 前端与 Playwright 端到端测试源码讲清Agent 如何在对话中实时流式渲染任务进度 UI这条完整链路。读完本文你将掌握该 demo 的部署前置条件、逐项测试步骤、期望验收标准以及useAgent状态订阅、set_steps状态发布工具、messageView.children内联渲染等关键实现原理。一、这个 demo 在验证什么仓库清单 manifest.yaml 对该 demo 的定义是Agent-state-driven Gen UI — the agent plans a live step list viaCommand(update{steps}); the frontend subscribes throughuseAgentand renders the steps insideCopilotChatsmessageView.childrenslot.即后端 LangGraph Agent 在执行长任务的过程中通过自定义状态发布工具把计划步骤清单 每步状态实时推送给前端前端在聊天流中原地渲染一张会持续更新的任务进度卡片。这区别于每发一条消息渲染一张卡片的传统方案是 CopilotKit v2 中 Agentic Generative UI 的标准示范。在 langgraph.json 中后端图被注册为gen_ui_agent映射到./src/agents/src/gen_ui_agent.py:graph前端页面入口为src/app/demos/gen-ui-agent/page.tsx路由为/demos/gen-ui-agent。QA 文档即针对该端到端 demo 编写。二、整体架构与数据流从源码结构看这条链路分三层后端 Agentgen_ui_agent.py定义steps状态字段与set_steps工具模型每推进一个步骤就调用一次该工具把最新步骤状态写入 LangGraph 状态运行时路由route.ts通过LangGraphAgent把前端请求桥接到 LangGraph 后端服务前端 Demopage.tsx用useAgent订阅实时状态用messageView.children把状态卡片内联进聊天记录。数据流为用户发送消息 → LangGraph Agent 规划步骤并调用set_steps→ 每次调用后更新的steps状态被流式推送 → 前端useAgent收到状态变更 →InlineAgentStateCard就地重渲染。2.1 后端显式状态 Schema 状态编辑工具gen_ui_agent.py 的核心设计是显式状态 状态编辑工具class Step(TypedDict): id: str title: str status: Literal[pending, in_progress, completed] def _last_steps(_prev: list[Step] | None, new: list[Step] | None) - list[Step]: Reducer: last write wins (accepts parallel tool calls in one superstep). return new if new is not None else (_prev or []) class GenUiAgentState(AgentState): steps: Annotated[NotRequired[list[Step]], _last_steps, OmitFromInput]Step是强类型步骤结构status只能取pending/in_progress/completed三态_last_steps是状态归约器reducer语义为最后一次写入胜出从而兼容同一 superstep 内多个并行工具调用OmitFromInput标记steps不参与用户输入注入只能由 Agent 内部写入。步骤发布由set_steps工具完成gen_ui_agent.pytool def set_steps( steps: list[Step], tool_call_id: Annotated[str, InjectedToolCallId] ) - Command[Any]: Publish the current plan step statuses. Call this every time a step transitions (including the first enumeration of steps). return Command( update{ steps: steps, messages: [ ToolMessage( fPublished {len(steps)} step(s)., nameset_steps, idstr(uuid.uuid4()), tool_call_idtool_call_id, ) ], } )关键点工具返回的是Command(update{...})直接写入状态而非仅返回文本因此每次调用都会产生一次可被流式推送的状态更新。模型行为由 SYSTEM_PROMPT 约束先一次性把全部步骤置为pending发布然后逐步骤执行in_progress→completed的两次调用全部完成后再发一条总结消息并停止且明确禁止并行调用set_steps。最后通过langchain.agents.create_agent组装图gen_ui_agent.pygraph create_agent( modelinit_chat_model(openai:gpt-4o-mini, temperature0, use_responses_apiFalse), tools[set_steps], system_promptSYSTEM_PROMPT, state_schemaGenUiAgentState, middleware[CopilotKitMiddleware()], ).with_config({recursion_limit: 50})源码注释解释了为何不用create_deep_agent其 planner sub-agent 中间件会消耗过多 superstep容易触发 LangGraph 默认递归上限当前 ReAct 循环名义约 15 个 supersteprecursion_limit50可提供约 3 倍余量。2.2 运行时LangGraphAgent 桥接与递归上限配置前端所有 agent 请求统一走 route.ts 的POST处理器。gen-ui-agent被显式注册为专用图route.tsagents[gen-ui-agent] createAgent(gen_ui_agent);该路由的createAgent有一个值得注意的实现细节route.tsPython 侧with_config({recursion_limit: 50})在经由 LangGraph Server runs API 调用时不会生效因此后端把上限烘焙进assistantConfig随每次运行下发return new LangGraphAgent({ deploymentUrl: ${AGENT_URL}/, graphId, assistantConfig: { recursion_limit: options.recursionLimit ?? 100 }, });这正是 QA 文档要求Agent 在 10 秒内响应、进度卡片正常更新的底层保障——若递归上限不足set_steps链在跑完前被截断卡片将停留在陈旧状态。2.3 前端useAgent 订阅 messageView.children 内联渲染page.tsx 是前端核心const { agent } useAgent({ agentId: gen-ui-agent, updates: [UseAgentUpdate.OnStateChanged], }); const steps (agent.state as AgentState | undefined)?.steps ?? []; const status agent.isRunning ? inProgress : complete; return ( CopilotChat agentIdgen-ui-agent classNameh-full rounded-2xl messageView{{ children: ({ messageElements, interruptElement }) ( MessageListWithState messageElements{messageElements} interruptElement{interruptElement} steps{steps} status{status} / ), }} / );useAgent以OnStateChanged订阅状态变更agent.state.steps即后端发布的步骤数组messageView.children是 v2 的消息视图插槽MessageListWithStatemessage-list-with-state.tsx把普通消息、状态卡片、中断插槽组合渲染且整轮运行只挂载一张卡片、就地更新。该设计取代了旧版useCoAgentStateRender每状态消息一张卡片的方案page.tsx顶部注释与 e2e 回归测试均有说明。三、QA 前置条件QA 文档 gen-ui-agent.md 明确要求测试前满足Demo 已部署并可访问即showcase/integrations/langgraph-fastapi目录下的应用已完成构建并运行Agent 后端健康访问/api/health确认后端 Agent 状态正常该 health 端点源码位于 src/app/api/health/route.tssrc/app/api/copilotkit/route.ts的GET处理器也会返回agent_status供排查桥接状态。四、测试步骤 1基础功能验证按 QA 文档执行导航到 gen-ui-agent demo 页面/demos/gen-ui-agent验证聊天界面以居中、满高布局加载对应page.tsx中flex justify-center items-center h-screen w-full与max-w-4xl容器验证输入框占位符Type a message可见Playwright 测试 gen-ui-agent.spec.ts 同样用getByPlaceholder(Type a message)断言发送一条基础消息验证 Agent 正常回复e2e 中断言data-testidcopilot-assistant-message在 30 秒内可见。五、测试步骤 2特性专项检查5.1 Suggestions 建议按钮验证Simple plan建议按钮可见对应用 5 步去火星的规划提示验证Complex plan建议按钮可见对应用 10 步做披萨的规划提示。实现层面建议按钮由useConfigureSuggestions配置suggestions.ts每条建议包含展示标题title与点击后发送的messageavailable: always表示始终可点。需要说明的是当前仓库源码中的建议文案已更新为Plan a product launch / Organize a team offsite / Research a competitor三条见 suggestions.tsQA 文档中的 Mars / pizza 文案属于该清单更早版本验证时可点击任一建议按钮检查其 message 是否作为用户消息发出并触发规划流程。5.2 任务进度跟踪器useAgent 状态流式渲染这是本 demo 的验收核心点击 Simple plan 建议或输入 Build a plan to go to Mars in 5 steps验证TaskProgress组件渲染QA 文档旧版 testid 为data-testidtask-progress验证进度条出现且带渐变填充验证步骤项带描述出现旧版 testiddata-testidtask-step-text验证N/N Complete计数器随步骤完成而更新验证已完成步骤呈现绿色背景渐变对勾图标绿色文字验证当前处理中步骤呈现蓝/紫背景渐变旋转 spinner 图标 Processing... 文案脉冲动画验证未来待处理步骤呈现灰色背景时钟图标弱化muted文字色。当前源码中的对应实现进度卡片组件为InlineAgentStateCardInlineAgentStateCard.tsx其中已完成步骤薄荷绿圆形底bg-[#85ECCE] 对勾 SVG 标题划线弱化InlineAgentStateCard.tsx进行中步骤蓝紫色圆形底bg-[#BEC2FF]animate-spin旋转 spinnerInlineAgentStateCard.tsx待处理步骤白底描边圆形 序号数字 灰色弱化文字InlineAgentStateCard.tsx头部标题动态切换Step X of Y、All N steps complete 或 Planning…进行中显示卡片级 spinner完成时切换为绿色对勾InlineAgentStateCard.tsx。testid 差异提示QA 文档中的task-progress/task-step-text对应旧版组件当前源码已改用data-testidagent-state-card与data-testidagent-step带data-status属性区分三态Playwright 测试也基于新 testid 编写。验证时若发现文档 testid 与页面 DOM 不符以当前源码的agent-state-card/agent-step为准。5.3 复杂计划Complex Plan输入 Plan to make pizza in 10 steps验证进度跟踪器中出现10 个步骤验证进度条宽度随步骤完成而递增。同样地QA 文档此处描述的10 步来自建议文案所在的旧版本行为当前后端 SYSTEM_PROMPT 固定要求规划恰好 3 个步骤e2e 测试也断言恰好 3 步全部completed见 gen-ui-agent.spec.ts。验证时以步骤数量与后端发布的步骤数组一致、且逐步骤推进到 completed为准具体步数取决于部署的后端版本。六、测试步骤 3错误处理发送一条空消息验证被优雅处理不崩溃、无异常堆栈正常使用过程中验证无 console 报错。从实现看空消息在前端输入层即可被拦截输入框发送逻辑同时后端set_steps每次调用都会回写一条ToolMessagegen_ui_agent.py确保工具执行链路在状态异常时仍能留下可追踪的对话记录。七、期望结果与验收标准QA 文档给出的最终验收标准QA 清单的Expected Results汇总如下验收项标准聊天加载时间3 秒内完成加载Agent 响应时间10 秒内给出响应任务进度跟踪实时显示步骤完成情况steps状态逐次流式更新进度条动画平滑推进、无卡顿跳变UI 稳定性无报错、无布局破损这套人工验收标准与仓库中的自动化 e2e 回归测试一一对应gen-ui-agent.spec.ts页面加载 输入框可见对应 3 秒加载发送消息后 30 秒内收到 assistant 回复对应 10 秒响应留有余量单卡片就地更新回归整轮set_steps调用约 7 次状态更新只允许出现一张agent-state-cardspinner 消失后仍为一张gen-ui-agent.spec.ts杜绝旧版一状态一卡片的卡片堆积问题全部步骤完成3 个agent-step全部到达data-statuscompleted且总数与完成数一致、无孤儿步骤gen-ui-agent.spec.ts状态动画不被短路回归测试专门验证步骤确实经历pending → in_progress → completed链条而非 fixture 一次性输出全 completedgen-ui-agent.spec.ts。八、从 QA 文档到自动化验收体系一览层次载体作用人工验收qa/gen-ui-agent.md部署后逐项人工验证 UI 与交互后端实现gen_ui_agent.py提供steps状态与set_steps发布工具运行时接线src/app/api/copilotkit/route.ts注册gen-ui-agent专用图并下发递归上限前端渲染page.tsx InlineAgentStateCard.tsxuseAgent订阅 卡片三态渲染自动化回归tests/e2e/gen-ui-agent.spec.ts用 Playwright 固化上述验收标准目录清单manifest.yaml定义 demo 名称、描述、路由与高亮文件九、排查与运维建议结合源码注释以下问题与解法值得 QA/运维人员关注状态卡片停留在上一次运行的陈旧内容多为 LangGraph 递归上限不足导致最后一次set_steps未能流式返回。Python 侧with_config在 Server 调用模式下不生效需像 route.ts 那样把recursion_limit写入assistantConfig。出现多张重复卡片属于旧版useCoAgentStateRender行为当前版本通过useAgentmessageView.children单卡片内联渲染规避可用 e2e 中的toHaveCount(1)断言监控回归。Agent 后端不可达先查/api/health再确认AGENT_URL默认http://localhost:8123见 route.ts指向的 LangGraph 服务是否运行了gen_ui_agent图。结语QA 文档qa/gen-ui-agent.md看似只是一份验收清单但结合仓库源码即可还原出一套完整的 Agentic Generative UI 工程范式后端用Command(update)显式发布状态、前端用useAgent订阅并以单卡片就地渲染、运行时负责桥接与递归上限兜底、Playwright 把全部验收标准固化为回归测试。这套人工 QA 源码实现 自动化回归三位一体的模式同样适用于仓库内 mastra、strands、ag2、agno、crewai-crews、langgraph-typescript、pydantic-ai 等其他集成的 gen-ui-agent demo见 page.tsx 顶部注释可直接迁移复用。【免费下载链接】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 × LangGraph (FastAPI) Agentic Generative UI 验证指南：从 QA 检查清单到源码级实现解析
CopilotKit × LangGraph (FastAPI) Agentic Generative UI 验证指南从 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 开源仓库中showcase/integrations/langgraph-fastapi/qa/gen-ui-agent.md质量验证文档为核心骨架完整解析 Agentic Generative UI生成式 UI / 代理状态驱动 UIdemo 的验收流程并对照仓库内 FastAPI LangGraph 后端、Next.js 前端与 Playwright 端到端测试源码讲清Agent 如何在对话中实时流式渲染任务进度 UI这条完整链路。读完本文你将掌握该 demo 的部署前置条件、逐项测试步骤、期望验收标准以及useAgent状态订阅、set_steps状态发布工具、messageView.children内联渲染等关键实现原理。一、这个 demo 在验证什么仓库清单 manifest.yaml 对该 demo 的定义是Agent-state-driven Gen UI — the agent plans a live step list viaCommand(update{steps}); the frontend subscribes throughuseAgentand renders the steps insideCopilotChatsmessageView.childrenslot.即后端 LangGraph Agent 在执行长任务的过程中通过自定义状态发布工具把计划步骤清单 每步状态实时推送给前端前端在聊天流中原地渲染一张会持续更新的任务进度卡片。这区别于每发一条消息渲染一张卡片的传统方案是 CopilotKit v2 中 Agentic Generative UI 的标准示范。在 langgraph.json 中后端图被注册为gen_ui_agent映射到./src/agents/src/gen_ui_agent.py:graph前端页面入口为src/app/demos/gen-ui-agent/page.tsx路由为/demos/gen-ui-agent。QA 文档即针对该端到端 demo 编写。二、整体架构与数据流从源码结构看这条链路分三层后端 Agentgen_ui_agent.py定义steps状态字段与set_steps工具模型每推进一个步骤就调用一次该工具把最新步骤状态写入 LangGraph 状态运行时路由route.ts通过LangGraphAgent把前端请求桥接到 LangGraph 后端服务前端 Demopage.tsx用useAgent订阅实时状态用messageView.children把状态卡片内联进聊天记录。数据流为用户发送消息 → LangGraph Agent 规划步骤并调用set_steps→ 每次调用后更新的steps状态被流式推送 → 前端useAgent收到状态变更 →InlineAgentStateCard就地重渲染。2.1 后端显式状态 Schema 状态编辑工具gen_ui_agent.py 的核心设计是显式状态 状态编辑工具class Step(TypedDict): id: str title: str status: Literal[pending, in_progress, completed] def _last_steps(_prev: list[Step] | None, new: list[Step] | None) - list[Step]: Reducer: last write wins (accepts parallel tool calls in one superstep). return new if new is not None else (_prev or []) class GenUiAgentState(AgentState): steps: Annotated[NotRequired[list[Step]], _last_steps, OmitFromInput]Step是强类型步骤结构status只能取pending/in_progress/completed三态_last_steps是状态归约器reducer语义为最后一次写入胜出从而兼容同一 superstep 内多个并行工具调用OmitFromInput标记steps不参与用户输入注入只能由 Agent 内部写入。步骤发布由set_steps工具完成gen_ui_agent.pytool def set_steps( steps: list[Step], tool_call_id: Annotated[str, InjectedToolCallId] ) - Command[Any]: Publish the current plan step statuses. Call this every time a step transitions (including the first enumeration of steps). return Command( update{ steps: steps, messages: [ ToolMessage( fPublished {len(steps)} step(s)., nameset_steps, idstr(uuid.uuid4()), tool_call_idtool_call_id, ) ], } )关键点工具返回的是Command(update{...})直接写入状态而非仅返回文本因此每次调用都会产生一次可被流式推送的状态更新。模型行为由 SYSTEM_PROMPT 约束先一次性把全部步骤置为pending发布然后逐步骤执行in_progress→completed的两次调用全部完成后再发一条总结消息并停止且明确禁止并行调用set_steps。最后通过langchain.agents.create_agent组装图gen_ui_agent.pygraph create_agent( modelinit_chat_model(openai:gpt-4o-mini, temperature0, use_responses_apiFalse), tools[set_steps], system_promptSYSTEM_PROMPT, state_schemaGenUiAgentState, middleware[CopilotKitMiddleware()], ).with_config({recursion_limit: 50})源码注释解释了为何不用create_deep_agent其 planner sub-agent 中间件会消耗过多 superstep容易触发 LangGraph 默认递归上限当前 ReAct 循环名义约 15 个 supersteprecursion_limit50可提供约 3 倍余量。2.2 运行时LangGraphAgent 桥接与递归上限配置前端所有 agent 请求统一走 route.ts 的POST处理器。gen-ui-agent被显式注册为专用图route.tsagents[gen-ui-agent] createAgent(gen_ui_agent);该路由的createAgent有一个值得注意的实现细节route.tsPython 侧with_config({recursion_limit: 50})在经由 LangGraph Server runs API 调用时不会生效因此后端把上限烘焙进assistantConfig随每次运行下发return new LangGraphAgent({ deploymentUrl: ${AGENT_URL}/, graphId, assistantConfig: { recursion_limit: options.recursionLimit ?? 100 }, });这正是 QA 文档要求Agent 在 10 秒内响应、进度卡片正常更新的底层保障——若递归上限不足set_steps链在跑完前被截断卡片将停留在陈旧状态。2.3 前端useAgent 订阅 messageView.children 内联渲染page.tsx 是前端核心const { agent } useAgent({ agentId: gen-ui-agent, updates: [UseAgentUpdate.OnStateChanged], }); const steps (agent.state as AgentState | undefined)?.steps ?? []; const status agent.isRunning ? inProgress : complete; return ( CopilotChat agentIdgen-ui-agent classNameh-full rounded-2xl messageView{{ children: ({ messageElements, interruptElement }) ( MessageListWithState messageElements{messageElements} interruptElement{interruptElement} steps{steps} status{status} / ), }} / );useAgent以OnStateChanged订阅状态变更agent.state.steps即后端发布的步骤数组messageView.children是 v2 的消息视图插槽MessageListWithStatemessage-list-with-state.tsx把普通消息、状态卡片、中断插槽组合渲染且整轮运行只挂载一张卡片、就地更新。该设计取代了旧版useCoAgentStateRender每状态消息一张卡片的方案page.tsx顶部注释与 e2e 回归测试均有说明。三、QA 前置条件QA 文档 gen-ui-agent.md 明确要求测试前满足Demo 已部署并可访问即showcase/integrations/langgraph-fastapi目录下的应用已完成构建并运行Agent 后端健康访问/api/health确认后端 Agent 状态正常该 health 端点源码位于 src/app/api/health/route.tssrc/app/api/copilotkit/route.ts的GET处理器也会返回agent_status供排查桥接状态。四、测试步骤 1基础功能验证按 QA 文档执行导航到 gen-ui-agent demo 页面/demos/gen-ui-agent验证聊天界面以居中、满高布局加载对应page.tsx中flex justify-center items-center h-screen w-full与max-w-4xl容器验证输入框占位符Type a message可见Playwright 测试 gen-ui-agent.spec.ts 同样用getByPlaceholder(Type a message)断言发送一条基础消息验证 Agent 正常回复e2e 中断言data-testidcopilot-assistant-message在 30 秒内可见。五、测试步骤 2特性专项检查5.1 Suggestions 建议按钮验证Simple plan建议按钮可见对应用 5 步去火星的规划提示验证Complex plan建议按钮可见对应用 10 步做披萨的规划提示。实现层面建议按钮由useConfigureSuggestions配置suggestions.ts每条建议包含展示标题title与点击后发送的messageavailable: always表示始终可点。需要说明的是当前仓库源码中的建议文案已更新为Plan a product launch / Organize a team offsite / Research a competitor三条见 suggestions.tsQA 文档中的 Mars / pizza 文案属于该清单更早版本验证时可点击任一建议按钮检查其 message 是否作为用户消息发出并触发规划流程。5.2 任务进度跟踪器useAgent 状态流式渲染这是本 demo 的验收核心点击 Simple plan 建议或输入 Build a plan to go to Mars in 5 steps验证TaskProgress组件渲染QA 文档旧版 testid 为data-testidtask-progress验证进度条出现且带渐变填充验证步骤项带描述出现旧版 testiddata-testidtask-step-text验证N/N Complete计数器随步骤完成而更新验证已完成步骤呈现绿色背景渐变对勾图标绿色文字验证当前处理中步骤呈现蓝/紫背景渐变旋转 spinner 图标 Processing... 文案脉冲动画验证未来待处理步骤呈现灰色背景时钟图标弱化muted文字色。当前源码中的对应实现进度卡片组件为InlineAgentStateCardInlineAgentStateCard.tsx其中已完成步骤薄荷绿圆形底bg-[#85ECCE] 对勾 SVG 标题划线弱化InlineAgentStateCard.tsx进行中步骤蓝紫色圆形底bg-[#BEC2FF]animate-spin旋转 spinnerInlineAgentStateCard.tsx待处理步骤白底描边圆形 序号数字 灰色弱化文字InlineAgentStateCard.tsx头部标题动态切换Step X of Y、All N steps complete 或 Planning…进行中显示卡片级 spinner完成时切换为绿色对勾InlineAgentStateCard.tsx。testid 差异提示QA 文档中的task-progress/task-step-text对应旧版组件当前源码已改用data-testidagent-state-card与data-testidagent-step带data-status属性区分三态Playwright 测试也基于新 testid 编写。验证时若发现文档 testid 与页面 DOM 不符以当前源码的agent-state-card/agent-step为准。5.3 复杂计划Complex Plan输入 Plan to make pizza in 10 steps验证进度跟踪器中出现10 个步骤验证进度条宽度随步骤完成而递增。同样地QA 文档此处描述的10 步来自建议文案所在的旧版本行为当前后端 SYSTEM_PROMPT 固定要求规划恰好 3 个步骤e2e 测试也断言恰好 3 步全部completed见 gen-ui-agent.spec.ts。验证时以步骤数量与后端发布的步骤数组一致、且逐步骤推进到 completed为准具体步数取决于部署的后端版本。六、测试步骤 3错误处理发送一条空消息验证被优雅处理不崩溃、无异常堆栈正常使用过程中验证无 console 报错。从实现看空消息在前端输入层即可被拦截输入框发送逻辑同时后端set_steps每次调用都会回写一条ToolMessagegen_ui_agent.py确保工具执行链路在状态异常时仍能留下可追踪的对话记录。七、期望结果与验收标准QA 文档给出的最终验收标准QA 清单的Expected Results汇总如下验收项标准聊天加载时间3 秒内完成加载Agent 响应时间10 秒内给出响应任务进度跟踪实时显示步骤完成情况steps状态逐次流式更新进度条动画平滑推进、无卡顿跳变UI 稳定性无报错、无布局破损这套人工验收标准与仓库中的自动化 e2e 回归测试一一对应gen-ui-agent.spec.ts页面加载 输入框可见对应 3 秒加载发送消息后 30 秒内收到 assistant 回复对应 10 秒响应留有余量单卡片就地更新回归整轮set_steps调用约 7 次状态更新只允许出现一张agent-state-cardspinner 消失后仍为一张gen-ui-agent.spec.ts杜绝旧版一状态一卡片的卡片堆积问题全部步骤完成3 个agent-step全部到达data-statuscompleted且总数与完成数一致、无孤儿步骤gen-ui-agent.spec.ts状态动画不被短路回归测试专门验证步骤确实经历pending → in_progress → completed链条而非 fixture 一次性输出全 completedgen-ui-agent.spec.ts。八、从 QA 文档到自动化验收体系一览层次载体作用人工验收qa/gen-ui-agent.md部署后逐项人工验证 UI 与交互后端实现gen_ui_agent.py提供steps状态与set_steps发布工具运行时接线src/app/api/copilotkit/route.ts注册gen-ui-agent专用图并下发递归上限前端渲染page.tsx InlineAgentStateCard.tsxuseAgent订阅 卡片三态渲染自动化回归tests/e2e/gen-ui-agent.spec.ts用 Playwright 固化上述验收标准目录清单manifest.yaml定义 demo 名称、描述、路由与高亮文件九、排查与运维建议结合源码注释以下问题与解法值得 QA/运维人员关注状态卡片停留在上一次运行的陈旧内容多为 LangGraph 递归上限不足导致最后一次set_steps未能流式返回。Python 侧with_config在 Server 调用模式下不生效需像 route.ts 那样把recursion_limit写入assistantConfig。出现多张重复卡片属于旧版useCoAgentStateRender行为当前版本通过useAgentmessageView.children单卡片内联渲染规避可用 e2e 中的toHaveCount(1)断言监控回归。Agent 后端不可达先查/api/health再确认AGENT_URL默认http://localhost:8123见 route.ts指向的 LangGraph 服务是否运行了gen_ui_agent图。结语QA 文档qa/gen-ui-agent.md看似只是一份验收清单但结合仓库源码即可还原出一套完整的 Agentic Generative UI 工程范式后端用Command(update)显式发布状态、前端用useAgent订阅并以单卡片就地渲染、运行时负责桥接与递归上限兜底、Playwright 把全部验收标准固化为回归测试。这套人工 QA 源码实现 自动化回归三位一体的模式同样适用于仓库内 mastra、strands、ag2、agno、crewai-crews、langgraph-typescript、pydantic-ai 等其他集成的 gen-ui-agent demo见 page.tsx 顶部注释可直接迁移复用。【免费下载链接】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），仅供参考