CopilotKit × CrewAI Conversational FlowsBYOC Hashbrown 声明式 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 仓库中showcase/integrations/crewai-conversational-flows的 BYOC Hashbrown 演示展开完整讲解如何在 CrewAI 会话流Conversational Flows后端中驱动一个“自带 UI 组件库”Bring Your Own ComponentsBYOC的销售分析仪表盘后端 LLM 直接输出 Hashbrown 线格式wire format的 JSON 信封前端通过hashbrownai/react的流式 JSON 解析器把组件渐进式渲染出来。读完本文你将掌握从 CrewAI 系统提示词定制、FastAPI 端点挂载、Next.js 运行时代理到 Playwright 级 QA 验收的完整链路可直接复用到你自己的声明式生成式 UI 集成中。1. 前置条件在运行或验证/demos/declarative-hashbrown以及等价的旧路由/demos/byoc-hashbrown之前需要满足以下条件依据 qa/declarative-hashbrown.md演示页面可访问/demos/declarative-hashbrown后端agent_server.py正常运行且健康它把该 Crew 挂载在/conversational_flows/byoc-hashbrown端点路由代理 src/app/api/copilotkit-byoc-hashbrown/route.ts 将请求代理到${AGENT_URL}/conversational_flows/byoc-hashbrownAGENT_URL默认值为http://localhost:8000可通过环境变量覆盖agent 后端已设置OPENAI_API_KEYCrew 的 chat LLM 使用gpt-5.4前端包中已安装hashbrownai/core与hashbrownai/react版本0.5.0-beta.42. 什么是 BYOC Hashbrown概念与线格式“BYOC”Bring Your Own Components指的是 UI 组件渲染能力由接入方自带的组件库提供而不是依赖 CopilotKit 内置的固定组件集合。在本演示中这个自带库就是 Hashbrownhashbrownai/react。关键设计决策在于线格式的选择后端必须输出与 Hashbrown schema 形状完全一致的JSON 对象而不是 Hashbrown 的 XMLui.../uiDSL。原因在 src/agents/byoc_hashbrown_agent.py 的模块文档中写得很清楚XML DSL 是 Hashbrown 自身驱动 LLM 时由 Hashbrown 编译成 schema 文档的中间产物而本演示是由 CrewAI 直接驱动 LLM因此必须让模型直接产出最原始的 schema 形状避免二次编译{ ui: [ { metric: { props: { ... } } }, { pieChart: { props: { title: ..., data: [{...}] } } }, { barChart: { props: { ... } } }, { dealCard: { props: { ... } } }, { Markdown: { props: { children: ... } } } ] }前端则用hashbrownai/react的useJsonParser(content, kit.schema)消费这个信封在 token 逐段到达时渐进式组装 UI——这也是整个演示“边流式边渲染、无整页刷新”体验的基础。一个容易踩坑的实现细节pieChart与barChart的data字段必须是JSON 编码后的字符串embedded JSON string而非对象数组。这样在部分流式partial streaming期间 schema 仍能保持稳定解析器不会因为字段类型在流式中间态发生变化而报错。3. 后端实现CrewAI 侧的纯 JSON 输出适配3.1 最小单 Agent CrewCrew 本体被刻意保持为“空壳”单 Agent 结构byoc_hashbrown_agent.pyAgent 使用gpt-5.4作为llmtools[]禁止调用任何工具Task 的描述与期望输出均为“返回单个符合 hashbrown schema 的 JSON 对象”Crew 使用Process.sequential并通过chat_llmgpt-5.4指定会话 LLMCrew 之所以必须有 agent task仅仅是因为ChatWithCrewFlow需要至少一个 agent 和一个 task 才能完成平台侧样板platform boilerplate的装配真正的行为完全由后续注入的自定义系统消息决定Agent 的 role/backstory 只承担文档性作用。Crew 实例通过模块级_cached_crew缓存复用避免每个请求重建。3.2 系统提示词约束 LLM 输出 hashbrown JSONBYOC_HASHBROWN_SYSTEM_PROMPTbyoc_hashbrown_agent.py是整条链路的“输出契约”其要点包括强制形状ALWAYS 输出单个形如{ui: [ { componentName: { props: { ... } } }, ... ]}的 JSON 对象禁止噪音不得用代码围栏包裹、不得有任何前言或解释、必须是合法 JSON、不调用工具、不追问澄清信息组件白名单metric、pieChart、barChart、dealCard、Markdown五个组件各自 props schema 如下表组件props schema说明metric{ label: string, value: string }KPI 卡片value为已格式化字符串如$1.2M、248pieChart{ title: string, data: string }环形图data为 JSON 编码字符串至少 3 段{label, value}对象barChart{ title: string, data: string }纵向柱状图data为 JSON 编码字符串至少 3 根柱通常按时间排序dealCard{ title: string, stage: string, value: number }单个销售机会stage必须是prospect/qualified/proposal/negotiation/closed-won/closed-lost之一value是裸数字无货币符号与千分位逗号Markdown{ children: string }短说明文字用于小节标题与摘要children支持标准 Markdown数据纪律用户要仪表盘或图表时必须生成合理示例数据而非拒绝图表数据行数控制在 3–6 行、标签尽量简短Markdown只用于短标题/衔接句不输出长段落绝不输出白名单之外的组件图表data必须是 JSON 字符串内部引号需要转义提示词内置了一个完整的 Q4 销售仪表盘示例响应覆盖 Markdown 标题 两个 metric 饼图 柱状图可作为 prompt 工程层面的可直接复制范本。3.3 两条注入管线preseed 与 hard-overrideCrewAI 桥接层ag_ui_crewai.endpoint.add_crewai_crew_fastapi_endpoint默认通过build_system_message(crew_chat_inputs)组装系统提示词而generate_crew_chat_inputs会执行二次 AI 调用来描述 crew 及输入并把固定的一套“CrewAI platform”样板话术自我介绍、询问澄清等包裹在提示词外层——这恰恰与纯 JSON 输出目标相冲突。因此 src/agents/_chat_flow_helpers.py 提供了两条互补的注入管线preseed_system_prompt(crew_name, description)在延迟的 Flow 构造发生之前向桥接层的 chat-input 生成器注册一个手写的ChatInputs(crew_description我们的提示词, inputs[])。好处是build_system_message会把我们的描述原样嵌入同时跳过启动期的二次 AI 描述调用让 crew 构造变成同步且廉价的首请求不再被 LLM 探测LLM probe阻塞。代码通过拦截crew_chat_generate_crew_chat_inputs实现不直接写桥接层的 weakref 缓存保持缓存不变式安全。install_custom_system_message(crew_name, full_system_message)针对 BYOC 这类必须精确控制输出形状的场景通过 monkey-patchChatWithCrewFlow.__init__在实例构造完成后立即把自定义系统消息覆盖到self.system_message上彻底替换上游拼好的整套含样板话术的系统消息。钩子以crew_name为键未注册自定义消息的 crew 自动回退到默认行为。两个 helper 的调用顺序与幂等性都经过设计可安全地在add_crewai_crew_fastapi_endpoint之前或之后调用端点构造被延迟到首次请求且模块级字典只在首次注入时打一次 patch。3.4 后端路由与端点挂载src/app/api/copilotkit-byoc-hashbrown/route.ts 是 Next.js 侧的运行时代理通过copilotkit/runtime/v2创建CopilotRuntime用ag-ui/client的HttpAgent指向http://localhost:8000/conversational_flows/byoc-hashbrownagents表中同时注册byoc-hashbrown-demo与default两个键保证页面以agentbyoc-hashbrown-demo挂载时能命中同一后端POST处理器使用createCopilotRuntimeHandler以single-route模式处理请求basePath为/api/copilotkit-byoc-hashbrown异常会以 500 {error, stack}JSON 形式返回便于排查agent_server.py则负责把byoc_hashbrown_agent的 crew 挂到/conversational_flows/byoc-hashbrownFastAPI 端点前端运行时 URL 与后端端点由此连通。4. 前端消费方式与页面装配前端页面src/app/demos/byoc-hashbrown/page.tsx只是对src/app/demos/declarative-hashbrown/page.tsx的再导出两个 URL 渲染完全一致——旧路由/demos/byoc-hashbrown是为了兼容历史路径保留的别名。装配链路依据 qa/declarative-hashbrown.md 的集成说明与 route.ts 注释页面把CopilotChat包裹在HashBrownDashboardprovider 中用runtimeUrl/api/copilotkit-byoc-hashbrown指向专属运行时agentbyoc-hashbrown-demo通过useUiKituseJsonParser覆写 assistant 消息槽位把 hashbrown 形状的结构化输出渲染成 catalog 组件页面根节点带data-testidbyoc-hashbrown-root标记渲染器如hashbrown-renderer.tsx负责把metric、pieChart、barChart、dealCard映射为对应 UI 卡片Markdown组件允许在仪表盘上方渲染 Markdown 标题——这是预期行为不算 catalog 违规5. 端到端 QA 验收步骤下面的验收清单可直接作为手动测试用例或转译为 Playwright 断言参考 e2e 目录下的declarative-hashbrown.spec.ts与 claude-sdk-python 侧的tests/e2e/byoc-hashbrown.spec.ts。5.1 页面加载导航到/demos/declarative-hashbrown页头可见 “Declarative UI: Hashbrown”页面可见提及hashbrownai/react的简短描述聊天区底部可见输入框composercomposer 内可见 3 个建议 pill标签为Sales dashboard、Revenue by category、Expense trend控制台无红色报错amber 水合警告可容忍5.2 Sales dashboard 建议点击 “Sales dashboard” pilluseConfigureSuggestions会自动派发该消息45 秒内至少一个data-testidmetric-card渲染进对话记录45 秒内至少一个图表data-testidbar-chart或data-testidpie-chart渲染渲染内容渐进式出现——完整响应结束前先出现部分 UI可选视觉检查5.3 Revenue by category点击 “Revenue by category”45 秒内渲染出饼图data-testidpie-chart图例至少 4 段标签与数值可读5.4 Expense trend点击 “Expense trend”45 秒内渲染出柱状图data-testidbar-chart图表至少 3 根柱标签形似月份5.5 自由输入输入 “Show me revenue trends for the last six months” 并回车至少一个 catalog 组件metric、chart 或 deal被渲染5.6 多轮对话首次渲染完成后发送后续提示如 “Now break it down by region”新渲染与之前的渲染并列出现在对话记录中不清空历史5.7 错误处理空输入发送是 no-op按钮保持禁用原始 JSON 信封对用户不可见——消息列表中只出现渲染后的 catalog 组件成功流程中控制台保持干净6. 期望结果与判定标准建议 pill 在 45 秒内产出 hashbrown 渲染流式渲染随 JSON chunk 到达而渐进组装无未捕获异常不出现useHashBrownKit must be used within HashBrownDashboard错误多轮对话不清空先前渲染结合 claude-sdk-python 侧同名 QA 文档showcase/integrations/claude-sdk-python/qa/byoc-hashbrown.md补充的通用判定聊天在 3 秒内加载、Agent 在 15 秒内响应、后端发出的是{ui: [...]}JSON 信封而绝不出 XML——这三条是判断“BYOC 输出契约是否被破坏”的快速哨兵。7. 集成注意事项与已知约定hashbrown 信封提示词位于 src/agents/byoc_hashbrown_agent.py后端模块上的byoc_前缀是刻意的并保持不变运行时侧尚未重命名页面仍挂runtimeUrl/api/copilotkit-byoc-hashbrown、agentbyoc-hashbrown-demo页面根节点带data-testidbyoc-hashbrown-root与 north star 不同旧路由/demos/byoc-hashbrown再导出同一页面两个 URL 渲染一致assistant 会在仪表盘上方额外输出一个 Markdown 标题这是预期行为不属于 catalog 违规CrewAI 桥接层要求 agent task 的最小结构才能完成平台样板装配若你的 crew 目标是纯结构化输出请复刻本文 3.3 节的preseed_system_promptinstall_custom_system_message双管线方案以绕开build_system_message中不利于结构化输出的固定话术【免费下载链接】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），仅供参考