CopilotKit langgraph-fastapi 集成奇偶性管理PARITY_NOTES.md 与 D6 行为验证机制深度解析【免费下载链接】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/PARITY_NOTES.md为核心文档系统讲解该集成相对langgraph-python基准north star被**有意批准sanctioned**保留的差异、其背后的 D6 行为验证工作流以及如何用bin/showcase test langgraph-fastapi:demo --d6判定真实行为一致性。读完本文你将理解字节级一致与行为级一致的区别掌握逐 slug 提示词隔离、共享基准缺陷与作用域化测试分歧这三类典型场景的判定与处理方法。一、什么是奇偶性Parity以 langgraph-python 为基准的行为契约在 CopilotKit 的 showcase 体系中langgraph-python是多个集成的北极星north star参照物。langgraph-fastapi作为其中一个集成默认目标是与langgraph-python做到逐字节一致byte-identical——除集成自身的名称/标题外其余文件预期完全一致。奇偶性的最终裁判不是代码比对而是行为通过 D6 测试命令 用bin/showcase test langgraph-fastapi:demo --d6运行真实浏览器会话由 aimock 回放 fixture、probe 断言 DOM 结果。面向 Agent 的硬性规则该文档明确了一条面向自动化 Agent 的规则凡被列入 PARITY_NOTES.md 的文件都是故意不同的不允许为了向langgraph-python对齐而修复它们。如果某个条目看起来可疑必须先运行 D6 验证bin/showcase test langgraph-fastapi:demo --d6再与人讨论而不是直接改动。这条规则的目的是防止自动化流程把经过论证的设计决策当作风滚草drift回滚掉。二、a2ui-recovery逐 slug 提示词隔离load-bearing 设计a2ui-recovery是langgraph-fastapi集成中唯一无法与langgraph-python字节一致的 demo原因出在 aimock fixture 的路由机制上。根因fixture 不携带 x-aimock-context 路由头a2ui-recovery的 D6 fixture见 showcase/aimock/d6/langgraph-fastapi/a2ui-recovery.json不发送x-aimock-context路由头因此 aimock 无法按框架上下文区分集成只能依赖提示词文本本身来消歧。一旦不同集成使用相同提示词就会在共享的 aimock 匹配器中发生碰撞。这就是逐 slug 唯一提示词成为 load-bearing 设计的原因。三个被批准的文件级差异被批准保留差异的三个文件及其理由如下文件差异原因src/app/demos/a2ui-recovery/suggestions.ts使用独特的两枚 pill 提示词fixture 不携带 context 路由头提示词即 fixture 键必须全局唯一src/app/demos/a2ui-recovery/chat.tsx不注入声明式生成式 UI 的销售上下文 hook独特提示词设计的结果——数据集由后端 prompt fixture 承载src/app/demos/a2ui-recovery/page.tsx文档注释中引用了本集成的后端路径纯注释差异不影响行为langgraph-fastapi的 HEAL 提示词是Put together a quarterly metrics overview and repair a malformed first attempt.而langgraph-python的则是Build my Q2 revenue summary and self-correct a malformed first attempt.。这个差异是有意的——若把 fastapi 对齐到 LGP 的提示词aimock 会因找不到匹配 fixture 而报STRICT no-match导致 D6 变红。提示词、fixture、前端三者的锁步关系a2ui-recovery的核心是两枚提示词 pill它们通过 aimock fixture 确定性驱动 validate→retry 恢复循环OSS-158 / OSS-375HEALRecover a bad render内层render_a2ui子代理首次尝试输出自由格式/松散参数组件与数据以 JSON 字符串形式给出中间件parse_and_fix单次将其修复为合法 surface 并绘制。EXHAUSTShow an unrecoverable failure每次渲染尝试都结构非法循环到达尝试上限后返回a2ui_recovery_exhausted信封前端渲染为优雅的failed状态绝不绘制损坏的 surface。对应的 fixture 文件 a2ui-recovery.json 中用sequenceIndex编排多轮响应sequenceIndex: 0返回非法 surface如children: [missing-metric]引用悬空子节点sequenceIndex: 1返回合法 surface两个declarative-metric磁贴。匹配字段是userMessage独特提示词toolName: render_a2ui。前端方面suggestions.ts 通过useConfigureSuggestions注册两枚 pill并注释说明了提示词在 langgraph-fastapi 上下文内唯一、不与 declarative-gen-uia2ui_dynamicfixture 碰撞的设计约束。后端工具由 Agent 拥有而非运行时注入与 declarative-gen-ui 依赖运行时自动注入generate_a2ui不同本 demo 的恢复循环在图内运行。核心实现在 src/agents/src/recovery_agent.pygraph create_agent( modelChatOpenAI(model_MODEL), tools[ get_a2ui_tools( { model: ChatOpenAI(model_MODEL), default_catalog_id: declarative-gen-ui-catalog, recovery: {maxAttempts: 3}, on_a2ui_attempt: _log_attempt, } ) ], middleware[CopilotKitMiddleware()], system_promptSYSTEM_PROMPT, )关键点ag_ui_langgraph.get_a2ui_tools的实体内联运行render_a2ui子代理 工具包恢复循环 恢复耗尽硬失败信封recovery: {maxAttempts: 3}是恢复循环的尝试上限配合on_a2ui_attempt回调见同文件_log_attempt逐次记录每次尝试的 ok/errors 供开发观测使用前端配套路由 src/app/api/copilotkit-a2ui-recovery/route.ts 必须设置a2ui.injectA2UITool: false否则运行时自 CopilotKit#5611 起 provider catalog 默认开启注入会注入第二份工具副本造成双重绑定。该 demo 复用了 declarative-gen-ui 的 catalogdefaultCatalogId: declarative-gen-ui-catalog前端页面通过CopilotKit runtimeUrl/api/copilotkit-a2ui-recovery agenta2ui-recovery a2ui{{ catalog: myCatalog }}注册。后端langgraph.json中的a2ui_recovery: ./src/agents/src/recovery_agent.py:graph完成图注册。为何用键入输入而非点击 pill这里有一个值得注意的探针实现细节D5 探针 showcase/harness/src/probes/scripts/d5-a2ui-recovery.ts 特意用输入文本而非点击 pill 的方式发送提示词因为从preFillhook 中点击 pill带skipSend会在会话运行器快照 run-lifecycle 基线之前启动 agent 运行导致done-signal-missing误报。键入输入则让运行器先捕获基线与可工作的声明式探针保持一致。HEAL 恰好只发送一次fixture 通过sequenceIndex编排 0非法→ 1合法一次请求在内部完成重试若发第二次就会推进越过 seq1 导致失败。断言采用增量设计——两个轮次在同一浏览器会话中运行A2UI 渲染节点与失败卡片会跨轮次累积因此每轮在preFill中捕获基线HEAL 断言新增 ≥2 个declarative-metric且 0 个新失败卡片EXHAUST 断言新增 ≥1 个失败卡片且 0 个新 metric 磁贴。临时性的 Retrying generation… (N/M) 标签因阈值门控与时间依赖而刻意不断言。更深层的修复方向超出当前范围文档明确指出更彻底的修复是给 a2ui-recovery 流程增加上下文路由context routing使所有集成共享同一提示词——但这超出当前范围目前逐 slug 唯一提示词是被接受的折中方案。三、a2ui-recovery 的 D6 红属于共享基准缺陷而非 fastapi 缺陷除了上述提示词隔离分歧a2ui-recovery的 D6 单元格目前还有一处独立的红色状态且并非fastapi 特有 bug——它在langgraph-python基准上同样复现DOM 层surface-missing。因此 fastapi 在此处的行为已经与 LGP 对齐integrations/langgraph-fastapi/目录下没有需要修复的东西。2026-07-27 的 live-trace 关键发现HEAL 轮次从未绘制出探针要求的 ≥2 个declarative-metric磁贴validate→retry 循环未能可靠地把 seq0非法推进到 seq1合法叙述声称已恢复并绘制了指标总览而 DOM 显示硬失败卡片Couldnt generate the UIworker 日志为waitForTurnComplete: turn 1 did not complete … reasonsurface-missing。失败运行的第二个 SSE 流膨胀到约 13 MBfastapi 与 LGP 的transferSize均为 12–14M而绿色对照组是干净短流——与恢复循环过度迭代/重复发射而非在愈合 surface 处停止的行为一致。mastraTypeScript 的getA2UITools稳定绿色3/3说明 demo 本身可实现fastapi、LGP、google-adk 共享Python侧ag_ui_langgraph.get_a2ui_toolsv0.0.41Agent 容器内的 pip 依赖不在本仓库中该函数即重点怀疑对象。已被 trace 排除的因素文档明确列出了通过 trace 排除的候选aimock 无匹配/404/STRICT均无、injectA2UITool存在且正确、catalog 注册defaultCatalogId: declarative-gen-ui-catalog与 LGP 相同、fastapi 侧接线漂移route.ts、recovery_agent.py、langgraph.json与 LGP 结构一致。修复的跟踪位置修复共享 Python 恢复循环被跟踪为针对基准 /ag_ui_langgraph包的独立 PR不在 fastapi 对齐分支内。文档特别警告单次偶然的绿色不能复现不要把一个孤立的绿色运行当作已修复。四、declarative-json-render作用域化的 D6 分歧网格单元格为绿色byocD6 featureType 覆盖两个声明式 demodeclarative-hashbrownhashbrownai/react流式结构化输出与declarative-json-renderjson-render/react分层 JSON spec Zod 校验 catalog。两者用两个不同的第三方渲染库绘制同一个销售仪表盘指标卡 饼图/柱状图。网格状态fastapi 的 byoc 单元格是绿色的共享探针 showcase/harness/src/probes/scripts/d5-byoc.ts 导航到首选路由declarative-hashbrown并发送 hashbrown pillShow me a Q4 sales dashboard…命中 fastapi 的 hashbrown fixture → 通过。注意该探针的preNavigateRoute按集成声明的 demo 决定导航目标断言只要求出现metric-card与任一图表选择器bar-chart/pie-chart。作用域化运行变红的两层原因——均非 fastapi 缺陷执行bin/showcase test langgraph-fastapi:declarative-json-render --d6这类作用域化运行会变红原因是分层叠加的探针限制harness 侧全舰队影响d5-byoc.ts的buildTurns在得知实际导航路由之前执行而D5BuildContext不暴露demos[]路由扇出信息只存在于D5RouteContext因此它总是发送 hashbrown pill即使页面被强制导航到 json-render 页——按设计用错误的 pill 驱动了作用域化 json-render 运行。已作为后续改进项跟踪让探针按页选择 pill。有意的架构选择langgraph-python把两个渲染器折叠在一个统一的render_dashboard工具调用形态之后任意 pill → 两页消费相同 payload因此它的作用域化 json-render 运行碰巧通过。而langgraph-fastapi把两个库保持为真正独立的集成各有自己的 pill 与 fixture——hashbrown pill 对应较短的一枚 json-render pillShow me the sales dashboard with metrics and a revenue chart见 declarative-json-render/suggestions.ts。为什么不应该修复它文档的结论很明确fastapi 的拆分更忠实于每个库的实际行为把它折叠成 LGP 的统一契约反而是内容降级因此不做。净效果是只有在手动作用域化测试路径上存在已批准的分歧门禁网格单元格byoc是绿色且两个 demo 线上渲染均正常。真正的修复在探针侧按页选择 pill而不是改写 fastapi 的 json-render demo 去适配统一契约。从后端实现看fastapi 的 json-render Agentbyoc_json_render_agent.py输出json-render/react的扁平元素映射格式{ root, elements }且要求只输出 JSON、不加散文、不加代码围栏response_format{type: json_object}在模型层保证这一点。这与 hashbrown Agent 是各自独立的实现正好印证了文档所述两个库作为真正独立集成的架构立场。五、实操指引如何正确验证与处理奇偶性分歧综合上述三类场景可以总结出一套可复用的操作流程先用行为验证不要用代码比对下结论。奇偶性的裁判是 D6bin/showcase test langgraph-fastapi:demo --d6。只有行为对齐才叫对齐。遇到文件级差异先查 PARITY_NOTES.md。凡列入该文档的文件如a2ui-recovery的三个文件都是有意为之Agent 不得修复若怀疑条目有误先跑 D6 再讨论。判定红色状态归属。红色不一定是你这个集成的缺陷先在基准集成langgraph-python上复现同一测试若能复现即为共享基准缺陷修复应跟踪到基准/上游包如ag_ui_langgraph不在本集成分支再检查是否命中探针已知限制如d5-byoc.ts无法按页选择 pill这类问题应修复探针而非 demo最后才是排查集成自身接线对照route.ts、Agent 文件、langgraph.json与基准的结构一致性。警惕偶然绿色。一次性通过不代表修复完成尤其在共享恢复循环这类问题域中需以可复现的多次绿色为准。保持提示词全局唯一。在无 context 路由头的 demo如a2ui-recovery中提示词即 fixture 键跨集成必须唯一改动提示词必须同步更新前端suggestions.ts、D5 探针PROMPTS表与 aimock fixture 三处保持锁步。六、总结PARITY_NOTES.md 是 CopilotKit showcase 体系中一份颇具代表性的工程判断记录它把与基准字节级一致的默认目标与三类经过论证的例外逐 slug 提示词隔离、共享基准缺陷、作用域化测试分歧显式区分开来并用行为即裁判D6的验证机制兜底。对于参与该仓库集成的开发者或自动化 Agent理解这份文档的语义——哪些差异是有意的、哪些红色是共享的、哪些修复该落在探针侧——比盲目追求 diff 为零重要得多。相关文件可按以下路径继续深入集成说明showcase/integrations/langgraph-fastapi/PARITY_NOTES.md恢复 Agentshowcase/integrations/langgraph-fastapi/src/agents/src/recovery_agent.py专属运行时路由showcase/integrations/langgraph-fastapi/src/app/api/copilotkit-a2ui-recovery/route.tsD6 探针showcase/harness/src/probes/scripts/d5-a2ui-recovery.ts、showcase/harness/src/probes/scripts/d5-byoc.tsaimock fixtureshowcase/aimock/d6/langgraph-fastapi/a2ui-recovery.json【免费下载链接】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），仅供参考