CopilotKit 实战为 CrewAI Conversational Flows 集成聊天内 Human-in-the-LoopHITL交互与验收指南【免费下载链接】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 仓库中 CrewAI Conversational Flows 集成的 Human-in-the-LoopHITL人工介入能力展开聚焦在聊天界面内完成人工审批这一核心交互。你将了解到/demos/hitl-in-chat演示背后useHumanInTheLoop与useInterrupt两种实现路径如何共用同一套 StepSelector 卡片、如何通过data-testid与建议按钮驱动自动化验证并掌握一套可直接复用的 QA 验收清单与 E2E 测试范式用于在自己项目中验收Agent 等待用户确认后再执行的功能闭环。关联文档与演示定位本文讲解的核心文档是 showcase/integrations/crewai-conversational-flows/qa/hitl-in-chat.md它是一份面向该集成仓库的 QA 验收指南QA Quality Assurance。与之配套的还有前端演示源码showcase/integrations/crewai-conversational-flows/src/app/demos/hitl-in-chat/page.tsx时间选择卡片组件showcase/integrations/crewai-conversational-flows/src/app/demos/hitl-in-chat/time-picker-card.tsx另一份相关 QA 文档showcase/integrations/crewai-conversational-flows/qa/hitl-in-app.md应用级弹窗 HITLE2E 测试showcase/integrations/crewai-conversational-flows/tests/e2e/hitl-in-chat.spec.ts从仓库 manifest.yaml 的注册信息可以确认该集成以hitl-in-chatIn-Chat Human in the Loop用户批准 Agent 动作后再执行、hitl-in-chat-booking通过useHumanInTheLoop内联渲染时间选择卡片的预订流程与hitl原始向后兼容版本三个演示条目形式存在。前置条件部署与健康检查在开始任何 QA 步骤之前需要先确认运行环境就绪Demo 已部署且可访问前端演示页面能够正常加载Agent 后端健康检查/api/health接口。在后端健康检查的实现上showcase/integrations/crewai-conversational-flows/src/app/api/copilotkit/route.ts 提供了参考GET /api/copilotkit会以 3 秒超时探测后端AGENT_URL默认http://localhost:8000的/health端点并在返回 JSON 中给出agent_url与agent_statusreachable/error (N)/unreachable (message)等字段便于快速判断后端是否可达。同时前端通过CopilotKit runtimeUrl/api/copilotkit把运行时请求代理到该路由。基础功能验收访问 HITL 演示页面导航到 HITL 演示页面/demos/hitl。注意URL 路径/demos/hitl特意比功能 IDhitl-in-chat更短两者并不等价。这是该演示的既有设计QA 时应以实际路由为准。从 manifest.yaml 可以看到/demos/hitl被标记为 Original CrewAI HITL demo — kept for backwards-compat为向后兼容保留的原始演示。验证聊天界面在居中的max-w-4xl容器中加载。对应实现见 page.tsxdiv classNameflex justify-center items-center h-screen w-full外层居中、内层max-w-4xl包裹CopilotChat /。验证聊天输入框占位文本 Type a message 可见。发送一条基础消息。验证 Agent 有响应。验收参考标准QA 文档给出的预期结果同样适用于基础功能检查聊天界面在 3 秒内加载完成Agent 在 10 秒内给出响应。功能专项检查建议按钮SuggestionsHITL 演示通过建议按钮降低用户输入成本引导用户快速触发需要人工确认的 Agent 动作。检查项如下验证 Simple plan 建议按钮可见验证 Complex plan 建议按钮可见点击 Simple plan 建议验证它触发了以 5 个步骤规划一次火星之旅的相关消息。这两个建议的实现位于 src/app/demos/hitl/suggestions.ts通过useConfigureSuggestions配置available: always表示建议始终可用export function useHitlSuggestions() { useConfigureSuggestions({ suggestions: [ { title: Simple plan, message: Please plan a trip to mars in 5 steps., }, { title: Complex plan, message: Please plan a pasta dish in 10 steps., }, ], available: always, }); }与之对照聊天内预订版演示hitl-in-chat的建议则是 Book a call with sales 与 Schedule a 1:1 with Alice见 page.tsx。步骤选择与批准Step Selection and Approval一张卡片两种实现路径QA 文档明确指出无论底层流程使用 interrupt hook 还是前端 HITL 工具HITL 演示都渲染同一张 StepSelector 卡片。框架相关的 hook 名称属于各 package 演示源码中的实现细节QA 只验证用户可见的卡片行为。这一设计在源码中可以得到印证interrupt hook 路径在 src/app/demos/hitl/page.tsx 中useInterrupt监听后端事件将event.value?.steps传给StepSelector用户确认后将所选步骤的描述拼接成字符串通过resolve()返回给 Agent。前端 HITL 工具路径同一文件中还注册了useHumanInTheLoopname: generate_task_steps接收steps数组参数其render渲染StepsFeedback用户点击确认/拒绝后通过respond()把结果回传 Agent。两条路径最终都呈现在CopilotChat内部的同一张卡片上从而实现了一个 QA 流程覆盖两种实现。StepSelector 卡片的实现细节卡片本体是 src/app/demos/hitl/step-selector.tsx关键结构如下卡片根节点带data-testidselect-steps每个步骤项带data-testidstep-item内部是 Checkbox 步骤文本步骤文本带data-testidstep-text未选中时显示删除线与灰色line-through text-neutral-400头部 Badge 实时显示{enabledCount}/{localSteps.length} selected即 N/N selected底部按钮文案为Perform Steps (N)N 为当前选中的步骤数点击后仅把status enabled的步骤通过onConfirm回传。StepsFeedbacksteps-feedback.tsx则进一步提供了Reject / Confirm (N)双按钮决策流点击后通过respond({ accepted: false })或respond({ accepted: true, steps: [...] })回传结果卡片随即显示 Accepted成功样式或 Rejected破坏性样式Badge同时两个按钮置灰禁用与 QA 文档中验证卡片反映决策Accepted / Rejected且按钮禁用的检查项一一对应。逐项检查清单QA 文档针对该卡片列出的检查项发送 Plan a trip to Mars in 5 steps验证 StepSelector 卡片出现data-testidselect-steps验证步骤项以复选框形式展示data-testidstep-item验证步骤文本可见data-testidstep-text验证选中计数显示为 N/N selected取消勾选一个步骤验证计数减少重新勾选验证计数增加点击 Perform Steps (N) / Confirm (N) 按钮验证 Agent 在确认后继续处理在新会话中触发相同流程并点击 Reject若存在验证卡片反映决策Accepted / Rejected且按钮禁用。同一交互在预订场景中的应用hitl-in-chat-booking演示把同一套聊天内 HITL机制用于预订场景useHumanInTheLoop声明了一个book_call工具参数为topic与attendee均由 zod 描述render渲染 TimePickerCard。该卡片提供 4 个预设时间槽DEFAULT_SLOTS如 Tomorrow 10:00 AM、Monday 3:30 PM用户点击某个槽位后onSubmit({ chosen_time, chosen_label })把选择回传卡片切换为 Booked for ... 的已选状态data-testidtime-picker-picked也可点击 None of these work 取消data-testidtime-picker-cancelled。这体现了useHumanInTheLoop的参数校验zod schema、自定义渲染与结果回传的完整闭环。错误处理检查发送一条空消息应被优雅处理不崩溃。验证正常使用过程中控制台无报错no console errors。这两项检查确保 HITL 交互在边界输入与常规操作下都保持稳定属于任何交互型功能 QA 的兜底项。预期结果汇总QA 文档给出的最终验收标准预期结果说明聊天在 3 秒内加载页面可交互的时限Agent 在 10 秒内响应单轮回复的时限StepSelector 渲染且复选框可切换选择/取消选择逻辑正确Accept/Reject 流程无错误完成决策回传闭环正常无 UI 错误或布局破坏卡片状态切换不影响整体布局从 QA 清单到自动化测试QA 清单描述的手动步骤在仓库中已由 Playwright 测试自动化为 hitl-in-chat.spec.ts覆盖了页面加载输入框 Type a message 可见建议触发 HITL填写 Schedule a 1:1 with Alice... 后time-picker-card出现且断言没有出现泛化的 Nice to meet you, Alice 回复防止宽松 fixture 拦截建议导致 HITL 流程未触发选择槽位闭环点击time-picker-slot后time-picker-picked出现随后收到包含 Booked ... Alice 的 assistant 消息双建议端到端两条建议在同一次会话中连续执行都能各自渲染新的卡片并完成预订回归用例同一会话内连续两次预订时第二次不能跳过 picker 直接输出 Booked 文本早期曾因 confirmation fixture 以hasToolResult: true为键而在第二轮提前命中。这些测试与 QA 文档的检查项一一对应适合作为手测清单 → 自动化回归的模板每个data-testidtime-picker-card、time-picker-slot、time-picker-picked、select-steps、step-item、step-text既是 QA 的定位锚点也是 E2E 测试的选择器。架构接线HITL 前端如何到达后端为了让 HITL 卡片真正生效前端 Agent 别名必须正确接线到后端 Flow。从 route.ts 可以看到agents[human_in_the_loop] createAgent(/frontend-tools); agents[hitl-in-chat] createAgent(/frontend-tools); agents[hitl-in-app] createAgent(/frontend-tools);即hitl-in-chat、hitl-in-app与原始的human_in_the_loop都路由到同一个 CrewAIFrontendToolFlow后端注册见 conversational_flows.py 中frontend-tools: _conversational_type(FrontendToolFlow)。这也解释了 QA 文档中无论底层使用 interrupt hook 还是前端 HITL 工具卡片行为一致的架构基础前端可以通过useInterrupt后端主动中断、等待用户 resolve或useHumanInTheLoop前端注册工具、Agent 调用后等待用户 respond两条路径触发同一用户可见交互后端均以 AG-UI 协议经 CopilotKit Runtime 代理AGENT_URL指向独立的:8000后端进程。写在最后本文以 QA 文档为骨架串起了从部署健康检查、建议按钮、步骤选择/批准、错误处理到预期结果的全链路验收方法并补充了 StepSelector、TimePickerCard 与useHumanInTheLoop/useInterrupt的源码级实现细节以及对应 Playwright 自动化的回归范式。无论你是在复现该演示、扩展自己的 HITL 场景还是为交互型功能编写 QA 清单都可以直接复用其中的检查项、data-testid锚点与手测 → 自动化的映射思路。【免费下载链接】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 实战：为 CrewAI Conversational Flows 集成聊天内 Human-in-the-Loop（HITL）交互与验收指南
CopilotKit 实战为 CrewAI Conversational Flows 集成聊天内 Human-in-the-LoopHITL交互与验收指南【免费下载链接】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 仓库中 CrewAI Conversational Flows 集成的 Human-in-the-LoopHITL人工介入能力展开聚焦在聊天界面内完成人工审批这一核心交互。你将了解到/demos/hitl-in-chat演示背后useHumanInTheLoop与useInterrupt两种实现路径如何共用同一套 StepSelector 卡片、如何通过data-testid与建议按钮驱动自动化验证并掌握一套可直接复用的 QA 验收清单与 E2E 测试范式用于在自己项目中验收Agent 等待用户确认后再执行的功能闭环。关联文档与演示定位本文讲解的核心文档是 showcase/integrations/crewai-conversational-flows/qa/hitl-in-chat.md它是一份面向该集成仓库的 QA 验收指南QA Quality Assurance。与之配套的还有前端演示源码showcase/integrations/crewai-conversational-flows/src/app/demos/hitl-in-chat/page.tsx时间选择卡片组件showcase/integrations/crewai-conversational-flows/src/app/demos/hitl-in-chat/time-picker-card.tsx另一份相关 QA 文档showcase/integrations/crewai-conversational-flows/qa/hitl-in-app.md应用级弹窗 HITLE2E 测试showcase/integrations/crewai-conversational-flows/tests/e2e/hitl-in-chat.spec.ts从仓库 manifest.yaml 的注册信息可以确认该集成以hitl-in-chatIn-Chat Human in the Loop用户批准 Agent 动作后再执行、hitl-in-chat-booking通过useHumanInTheLoop内联渲染时间选择卡片的预订流程与hitl原始向后兼容版本三个演示条目形式存在。前置条件部署与健康检查在开始任何 QA 步骤之前需要先确认运行环境就绪Demo 已部署且可访问前端演示页面能够正常加载Agent 后端健康检查/api/health接口。在后端健康检查的实现上showcase/integrations/crewai-conversational-flows/src/app/api/copilotkit/route.ts 提供了参考GET /api/copilotkit会以 3 秒超时探测后端AGENT_URL默认http://localhost:8000的/health端点并在返回 JSON 中给出agent_url与agent_statusreachable/error (N)/unreachable (message)等字段便于快速判断后端是否可达。同时前端通过CopilotKit runtimeUrl/api/copilotkit把运行时请求代理到该路由。基础功能验收访问 HITL 演示页面导航到 HITL 演示页面/demos/hitl。注意URL 路径/demos/hitl特意比功能 IDhitl-in-chat更短两者并不等价。这是该演示的既有设计QA 时应以实际路由为准。从 manifest.yaml 可以看到/demos/hitl被标记为 Original CrewAI HITL demo — kept for backwards-compat为向后兼容保留的原始演示。验证聊天界面在居中的max-w-4xl容器中加载。对应实现见 page.tsxdiv classNameflex justify-center items-center h-screen w-full外层居中、内层max-w-4xl包裹CopilotChat /。验证聊天输入框占位文本 Type a message 可见。发送一条基础消息。验证 Agent 有响应。验收参考标准QA 文档给出的预期结果同样适用于基础功能检查聊天界面在 3 秒内加载完成Agent 在 10 秒内给出响应。功能专项检查建议按钮SuggestionsHITL 演示通过建议按钮降低用户输入成本引导用户快速触发需要人工确认的 Agent 动作。检查项如下验证 Simple plan 建议按钮可见验证 Complex plan 建议按钮可见点击 Simple plan 建议验证它触发了以 5 个步骤规划一次火星之旅的相关消息。这两个建议的实现位于 src/app/demos/hitl/suggestions.ts通过useConfigureSuggestions配置available: always表示建议始终可用export function useHitlSuggestions() { useConfigureSuggestions({ suggestions: [ { title: Simple plan, message: Please plan a trip to mars in 5 steps., }, { title: Complex plan, message: Please plan a pasta dish in 10 steps., }, ], available: always, }); }与之对照聊天内预订版演示hitl-in-chat的建议则是 Book a call with sales 与 Schedule a 1:1 with Alice见 page.tsx。步骤选择与批准Step Selection and Approval一张卡片两种实现路径QA 文档明确指出无论底层流程使用 interrupt hook 还是前端 HITL 工具HITL 演示都渲染同一张 StepSelector 卡片。框架相关的 hook 名称属于各 package 演示源码中的实现细节QA 只验证用户可见的卡片行为。这一设计在源码中可以得到印证interrupt hook 路径在 src/app/demos/hitl/page.tsx 中useInterrupt监听后端事件将event.value?.steps传给StepSelector用户确认后将所选步骤的描述拼接成字符串通过resolve()返回给 Agent。前端 HITL 工具路径同一文件中还注册了useHumanInTheLoopname: generate_task_steps接收steps数组参数其render渲染StepsFeedback用户点击确认/拒绝后通过respond()把结果回传 Agent。两条路径最终都呈现在CopilotChat内部的同一张卡片上从而实现了一个 QA 流程覆盖两种实现。StepSelector 卡片的实现细节卡片本体是 src/app/demos/hitl/step-selector.tsx关键结构如下卡片根节点带data-testidselect-steps每个步骤项带data-testidstep-item内部是 Checkbox 步骤文本步骤文本带data-testidstep-text未选中时显示删除线与灰色line-through text-neutral-400头部 Badge 实时显示{enabledCount}/{localSteps.length} selected即 N/N selected底部按钮文案为Perform Steps (N)N 为当前选中的步骤数点击后仅把status enabled的步骤通过onConfirm回传。StepsFeedbacksteps-feedback.tsx则进一步提供了Reject / Confirm (N)双按钮决策流点击后通过respond({ accepted: false })或respond({ accepted: true, steps: [...] })回传结果卡片随即显示 Accepted成功样式或 Rejected破坏性样式Badge同时两个按钮置灰禁用与 QA 文档中验证卡片反映决策Accepted / Rejected且按钮禁用的检查项一一对应。逐项检查清单QA 文档针对该卡片列出的检查项发送 Plan a trip to Mars in 5 steps验证 StepSelector 卡片出现data-testidselect-steps验证步骤项以复选框形式展示data-testidstep-item验证步骤文本可见data-testidstep-text验证选中计数显示为 N/N selected取消勾选一个步骤验证计数减少重新勾选验证计数增加点击 Perform Steps (N) / Confirm (N) 按钮验证 Agent 在确认后继续处理在新会话中触发相同流程并点击 Reject若存在验证卡片反映决策Accepted / Rejected且按钮禁用。同一交互在预订场景中的应用hitl-in-chat-booking演示把同一套聊天内 HITL机制用于预订场景useHumanInTheLoop声明了一个book_call工具参数为topic与attendee均由 zod 描述render渲染 TimePickerCard。该卡片提供 4 个预设时间槽DEFAULT_SLOTS如 Tomorrow 10:00 AM、Monday 3:30 PM用户点击某个槽位后onSubmit({ chosen_time, chosen_label })把选择回传卡片切换为 Booked for ... 的已选状态data-testidtime-picker-picked也可点击 None of these work 取消data-testidtime-picker-cancelled。这体现了useHumanInTheLoop的参数校验zod schema、自定义渲染与结果回传的完整闭环。错误处理检查发送一条空消息应被优雅处理不崩溃。验证正常使用过程中控制台无报错no console errors。这两项检查确保 HITL 交互在边界输入与常规操作下都保持稳定属于任何交互型功能 QA 的兜底项。预期结果汇总QA 文档给出的最终验收标准预期结果说明聊天在 3 秒内加载页面可交互的时限Agent 在 10 秒内响应单轮回复的时限StepSelector 渲染且复选框可切换选择/取消选择逻辑正确Accept/Reject 流程无错误完成决策回传闭环正常无 UI 错误或布局破坏卡片状态切换不影响整体布局从 QA 清单到自动化测试QA 清单描述的手动步骤在仓库中已由 Playwright 测试自动化为 hitl-in-chat.spec.ts覆盖了页面加载输入框 Type a message 可见建议触发 HITL填写 Schedule a 1:1 with Alice... 后time-picker-card出现且断言没有出现泛化的 Nice to meet you, Alice 回复防止宽松 fixture 拦截建议导致 HITL 流程未触发选择槽位闭环点击time-picker-slot后time-picker-picked出现随后收到包含 Booked ... Alice 的 assistant 消息双建议端到端两条建议在同一次会话中连续执行都能各自渲染新的卡片并完成预订回归用例同一会话内连续两次预订时第二次不能跳过 picker 直接输出 Booked 文本早期曾因 confirmation fixture 以hasToolResult: true为键而在第二轮提前命中。这些测试与 QA 文档的检查项一一对应适合作为手测清单 → 自动化回归的模板每个data-testidtime-picker-card、time-picker-slot、time-picker-picked、select-steps、step-item、step-text既是 QA 的定位锚点也是 E2E 测试的选择器。架构接线HITL 前端如何到达后端为了让 HITL 卡片真正生效前端 Agent 别名必须正确接线到后端 Flow。从 route.ts 可以看到agents[human_in_the_loop] createAgent(/frontend-tools); agents[hitl-in-chat] createAgent(/frontend-tools); agents[hitl-in-app] createAgent(/frontend-tools);即hitl-in-chat、hitl-in-app与原始的human_in_the_loop都路由到同一个 CrewAIFrontendToolFlow后端注册见 conversational_flows.py 中frontend-tools: _conversational_type(FrontendToolFlow)。这也解释了 QA 文档中无论底层使用 interrupt hook 还是前端 HITL 工具卡片行为一致的架构基础前端可以通过useInterrupt后端主动中断、等待用户 resolve或useHumanInTheLoop前端注册工具、Agent 调用后等待用户 respond两条路径触发同一用户可见交互后端均以 AG-UI 协议经 CopilotKit Runtime 代理AGENT_URL指向独立的:8000后端进程。写在最后本文以 QA 文档为骨架串起了从部署健康检查、建议按钮、步骤选择/批准、错误处理到预期结果的全链路验收方法并补充了 StepSelector、TimePickerCard 与useHumanInTheLoop/useInterrupt的源码级实现细节以及对应 Playwright 自动化的回归范式。无论你是在复现该演示、扩展自己的 HITL 场景还是为交互型功能编写 QA 清单都可以直接复用其中的检查项、data-testid锚点与手测 → 自动化的映射思路。【免费下载链接】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），仅供参考