CopilotKit 前端工具异步执行CrewAI Conversational Flows 集成中的 useFrontendTool 实战与 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 仓库中 CrewAI Conversational Flows 集成示例的frontend-tools-async演示为核心讲解如何用useFrontendTool注册一个完全运行在浏览器端的异步工具并让后端 CrewAI Flow 通过 AG-UI 协议调用它。你将掌握前端工具从声明、参数校验、异步 handler 到自定义渲染的完整链路以及基于 Playwright 和固定 mock 数据的端到端 QA 验证方法。演示背景前端工具异步是什么frontend-tools-async是 CopilotKit 与 CrewAI Conversational Flows 集成中的一个专门演示详见 manifest.yaml 中的frontend-tools-async条目与frontend-toolsIn-App Actions的区别在于前者的 handler 是一个async 函数——它会模拟一次客户端本地数据库查询500ms 延迟返回匹配结果后再由后端 Agent 对结果进行总结完整走通异步前端工具的往返链路。这个演示解决的核心问题是当数据只存在于浏览器端如本地索引、IndexedDB 缓存、用户私有数据时如何让 LLM Agent 依然能够查询并使用这些数据。典型的应用场景是个人笔记搜索、本地收藏夹检索、客户端缓存的业务数据过滤等——数据不出浏览器但 Agent 照常推理与作答。演示页面路由为/demos/frontend-tools-async其功能在集成根目录的 manifest.yaml 中被描述为useFrontendTool with an async handler。前端工具异步执行的完整链路整个链路可以拆成四个环节页面接入、工具注册、异步 handler 执行、结果渲染。1. 页面接入CopilotKit Provider 与 Chat 组件演示页面 page.tsx 用CopilotKitProvider 包住聊天界面指定后端 Agent 名称与 runtime 地址export default function FrontendToolsAsyncDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agentfrontend-tools-async div classNameflex justify-center items-center h-screen w-full div classNameh-full w-full max-w-4xl Chat / /div /div /CopilotKit ); }聊天界面本身是一个标准CopilotChat组件同时通过useConfigureSuggestions提供三个可点击的建议 pill方便 QA 测试与用户快速触发不同关键词useConfigureSuggestions({ suggestions: [ { title: Find project-planning notes, message: Find my notes about project planning. }, { title: Search for auth, message: Search my notes for anything related to auth. }, { title: What do I have about reading?, message: Do I have any notes tagged reading? }, ], available: always, });三个建议分别对应 QA 清单中的两条核心检查project planning 与 auth外加一个 reading 标签查询覆盖了关键词匹配的多种形态。2. 工具注册useFrontendTool 声明前端工具核心是useFrontendToolHook。它注册一个由后端 Agent 决定何时调用、但由浏览器执行的工具。注册时包含四部分工具名、自然语言描述、Zod 参数 schema、执行 handler以及可选的render渲染器useFrontendTool({ name: query_notes, description: Search the users local notes database for notes whose title, excerpt, or tags contain the given keyword (case-insensitive). Returns up to 5 matching notes., parameters: z.object({ keyword: z .string() .describe(Keyword or phrase to search notes for (case-insensitive).), }), handler: async ({ keyword }: { keyword: string }) { await sleep(500); const q keyword.toLowerCase(); const matches NOTES_DB.filter((n) { return ( n.title.toLowerCase().includes(q) || n.excerpt.toLowerCase().includes(q) || (n.tags ?? []).some((t) t.toLowerCase().includes(q)) ); }).slice(0, 5); return { keyword, count: matches.length, notes: matches }; }, render: ({ args, result, status }) { /* ... */ }, });关键点description 即工具契约LLM 依赖这段描述决定是否调用该工具、传什么参数因此它必须写清楚匹配字段title/excerpt/tags、大小写不敏感以及最多返回 5 条。Zod schema 负责参数校验这里只声明了一个keyword字符串参数并用.describe()补充语义便于模型正确生成参数。handler 是 async 的它await sleep(500)模拟客户端数据库往返然后对内存中的NOTES_DB做大小写不敏感的三字段标题、摘要、标签模糊匹配slice(0, 5)限制结果数量最后返回结构化结果{ keyword, count, notes }。这个返回值会作为工具结果回传给后端 Agent供其总结作答。3. 异步结果渲染NotesCard 组件render回调接收{ args, result, status }三个字段将工具执行状态映射到自定义 UI。这里的结果通过共享辅助函数 parse-json-result.ts 统一解析render: ({ args, result, status }) { const loading status ! complete; const parsed parseJsonResult{ keyword?: string; count?: number; notes?: Note[]; }(result); return ( NotesCard loading{loading} keyword{args?.keyword ?? parsed.keyword ?? } notes{parsed.notes} / ); },parseJsonResult兼容两种结果形态——Agent 以 JSON 字符串发出时自动JSON.parse已解析为对象时直接透传解析失败则回退为空对象。loading由status ! complete推导因此在 500ms 模拟延迟期间卡片会先显示Querying local notes DB...的加载态。NotesCard 是一个品牌化的结果卡片并暴露了 QA 所需的全部测试锚点锚点含义data-testidnotes-card外层容器data-testidnotes-keyword标题区展示Matching keyworddata-testidnotes-list匹配结果的ul列表data-testidnote-n1…note-n7每条笔记的独立行卡片同时渲染匹配计数N matches、每条笔记的标题/摘要/标签 chips以及空结果时的No notes matched占位。由于每个工具调用会渲染一张独立卡片连续多次查询会在聊天流中形成多张卡片叠加的效果。4. 数据源确定性的内存笔记库前端工具的数据来自 fake-notes-db.ts 中的NOTES_DB常量共 7 条笔记id 为 n1–n7覆盖规划、认证、购物、阅读、户外、职业等主题。文件头注释明确说明真实应用里这应是 IndexedDB、拉取的缓存或其他客户端私有数据存储这里保持内联且确定是为了让异步 handler 的往返在测试与截图中可复现。结合该数据可以精确预判 QA 的匹配结果查询 project planning命中 n1Q2 project planning kickofftags 含 planning/project与 n5Project planning retrospective notes。查询 auth命中 n2Planning: migrate auth to passkeystags 含 auth。查询 reading命中 n4Book recommendationstags 含 reading。这正是 QA 清单中每条断言能精确落到具体笔记 id 的底层依据。后端如何配合CrewAI Flow 只负责发出调用前端工具并非由前端直接触发而是由后端 CrewAI Flow 在推理时决定调用。仓库中的 frontend_tool_flow.py 是这一路径的后端实现SYSTEM_PROMPT ( You are a concise showcase assistant. When a supplied frontend tool can fulfill the users request, you MUST call it; never claim that you lack access and never substitute a prose answer. After the browser returns a tool result, summarize it briefly. ) class FrontendToolFlow(Flow[CopilotKitState]): start() async def chat(self) - None: response await copilotkit_stream( await acompletion( modelopenai/gpt-5.4, messages[ {role: system, content: SYSTEM_PROMPT}, *self.state.messages, ], toolsself.state.copilotkit.actions or None, tool_choice( required if self.state.copilotkit.actions and self.state.messages and self.state.messages[-1].get(role) user else auto ), parallel_tool_callsFalse, streamTrue, ) ) self.state.messages.append(response.choices[0].message)这段实现的关键设计前端工具从copilotkit.actions注入CrewAI Flow 自身不定义query_notes它只把前端通过 AG-UI 上报的 actions 透传给 LLM 的tools参数。System Prompt 强制调用明确要求能调用前端工具就必须调用不得声称无权限、不得用散文回答替代并在浏览器返回工具结果后做简要总结——这让演示结果确定、可断言。tool_choice的按轮次策略当存在 actions 且最后一条消息来自用户时强制required否则回退auto保证用户提问的那一轮必然触发工具调用。不在后端伪造工具结果流式发出的前端工具调用即结束本次 Flow 运行工具由浏览器执行结果在下一请求中带回。这正是前端工具与后端工具最本质的分工区别。这个 Flow 通过 API 路由注册给前端。在 route.ts 中frontend-tools-async与frontend_tools、human_in_the_loop、hitl-in-chat、hitl-in-app、open-gen-ui、open-gen-ui-advanced等别名一起被路由到同一个后端端点const AGENT_URL process.env.AGENT_URL || http://localhost:8000; function createAgent(path /chat) { const feature path.replace(/^\//, ); return new HttpAgent({ url: ${AGENT_URL}/conversational_flows/${feature} }); } agents[frontend-tools-async] createAgent(/frontend-tools);也就是说浏览器端query_notes的工具声明会随会话请求一起送到/conversational_flows/frontend-toolsCrewAI Flow 据此生成工具调用并流式回传前端拿到调用后在本地执行 async handler。运行时通过 AG-UI 协议代理到独立的 Python 后端默认http://localhost:8000并且route.ts的 GET 端点还提供/health探活与AGENT_URL环境信息便于排查前端连上了但 Agent 未响应的问题。QA 验证清单解读从手工检查到 Playwright 自动化关联文档 frontend-tools-async.md 本身是一份精炼的 QA 清单包含 5 项检查导航到/demos/frontend-tools-async提问 Find my notes about project planning验证NotesCarddata-testidnotes-card渲染且标题包含查询关键词验证匹配笔记n1、n5出现在data-testidnotes-list内再提问 Search my notes for auth验证结果随查询更新。这份清单已被仓库中的 frontend-tools-async.spec.ts 完整实现为 4 条 Playwright 用例覆盖清单中的每一项并有所扩展Playwright 用例对应清单项断言要点页面加载composer 3 个 pill第 1 项输入框 placeholder 可见三个建议按钮可见project-planning pill → Notes DB 卡片第 2–4 项卡片可见、标题含 project planning、列表含 n1 与 n5auth pill → Notes DB 卡片第 5 项卡片可见、标题含 auth、列表含 n2reading pill → Notes DB 卡片 锁定叙述扩展项卡片含 n4、标题、摘要、标签 chip、匹配数 1 match且第二轮回合叙述以固定短语开头同一会话内顺序点击 3 个 pill回归项每张卡片各自渲染卡片数依次变为 1 → 2 → 3值得注意的测试设计细节关键词标题即工具结果已回传的证据测试断言notes-keyword标题显示Matching project planning等文本这证明异步 handler 已针对 fixture 发出的query_notes(keyword...)调用在真实NOTES_DB上执行完毕。反向断言防止误路由project-planning 用例断言通用 plan 文案不出现、auth 用例断言 showcase-assistant 兜底文案不出现防止其他 fixture 拦截了本应发给前端工具的 prompt。aimock 多 pill 回归测试最后一个用例专门针对同一会话内连点多个工具 pill 时只渲染第一张卡片的旧 bug。其修复方案是用toolCallId串联 fixture、去掉hasToolResult门控验证所有 pill 在单会话内各自渲染自己的 Notes DB 卡片。Python 侧同样有验证tests/python/test_specialized_flows.py校验frontend-tools-async别名指向/frontend-tools端点并验证query_notes工具调用的消息结构tests/python/test_d6_fixture_parity.py校验frontend-tools-async.jsonfixture 与toolCallId如call_d5_query_notes_project_planning_001的匹配优先级。前端工具的适用边界与设计建议从本演示的源码结构可以总结出前端工具尤其是异步版的适用边界适合前端工具的场景数据或能力只存在于浏览器端——本地数据库、IndexedDB 缓存、客户端私有状态、需要用户设备参与的操作。工具声明只描述能做什么数据完全不出浏览器。不适合的场景需要服务端权威计算、鉴权、共享数据的操作仍应走后端工具前端工具的结果可信度取决于浏览器环境。务必保持 handler 确定性演示刻意使用内存常量 固定延迟让结果可被测试与截图复现。真实场景中如需稳定 QA也应通过 mock 或受控数据源实现同样的确定性。渲染锚点是 QA 的契约为关键渲染节点提供稳定的data-testid如notes-card、notes-list、note-*并让标题直接体现工具入参如Matching keyword是让异步 UI 可自动化验证的关键工程实践。如何运行与验证本地复现该演示需先启动 Python Agent 后端再启动 Next.js 前端默认 Agent 地址为http://localhost:8000可通过环境变量AGENT_URL覆盖若需逐请求调试日志可设置SHOWCASE_ROUTE_DEBUG1。启动后访问/demos/frontend-tools-async点击建议 pill 或直接输入问题即可观察Agent 推理 → 前端异步 handler 执行 → Notes DB 卡片渲染 → Agent 总结的完整闭环。随后可运行仓库中的 Playwright 用例tests/e2e/frontend-tools-async.spec.ts与 Python 侧的tests/python/test_specialized_flows.py、tests/python/test_d6_fixture_parity.py验证各项断言。总结frontend-tools-async演示展示了 CopilotKit前端工具模式在 CrewAI Conversational Flows 集成中的完整实现前端通过useFrontendTool声明工具与异步 handlerCrewAI Flow 通过copilotkit.actions感知工具并强制调用浏览器执行后把结构化结果交还 Agent 总结最终以自定义NotesCard渲染。配合确定性的内存数据与三层自动化验证Playwright E2E、Python 流程测试、fixture 一致性测试这一模式可以安全复用到任何Agent 需要访问浏览器私有数据的场景。【免费下载链接】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），仅供参考