CopilotKit 异步前端工具Async Frontend Tool实战以 Agno 集成 demo 的query_notes为例【免费下载链接】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 开源仓库中 Agno 集成的 QA 文档 frontend-tools-async.md 为核心骨架完整讲解「异步前端工具Async Frontend Tool」在 CopilotKit 中的注册、执行与渲染全链路Agent 发起工具调用后由浏览器端一个async处理器完成本地数据查询再把结果回传给 Agent 用于后续回复同时以自定义 React 组件把结果渲染成聊天中的结构化卡片。读完本文你将掌握useFrontendTool的 API 契约、参数约束、render生命周期以及如何用建议提示词suggestion pill、data-testid与 e2e 测试验证整条异步链路。1. 文档定位一条 QA 检查清单背后的完整功能原 QA 文档 frontend-tools-async.md 是 Agno 集成示例的一个质量检查清单覆盖三个层面前置条件Prerequisitesdemo 部署在/demos/frontend-tools-asyncAgent 后端必须健康功能检查Feature-Specific Checks点击 Find project-planning notes 建议提示词后断言data-testidnotes-card出现、data-testidnotes-keyword展示搜索关键词、data-testidnote-n1等逐条笔记被渲染错误处理Error Handling控制台无未捕获错误。这条清单不是孤立的手工测试用例而是对 CopilotKit「前端工具Frontend Tool」机制中异步形态的验收标准。它验证的核心事实是工具调用发生后等待一个 500ms 的浏览器端异步数据库往返完成后Agent 才能基于返回结果继续对话且前端 UI 必须能表达「加载中 → 完成」两种状态。该 QA 文档对应的可复现测试位于 tests/e2e/frontend-tools-async.spec.tsdemo 源码位于 src/app/demos/frontend-tools-async/。2. 认识前端工具Frontend Tool与异步形态2.1 什么是前端工具CopilotKit 允许 Agent 调用运行在浏览器端的函数——这就是「前端工具」。它不同于后端工具由服务端执行前端工具天然适合访问浏览器本地数据IndexedDB、localStorage、用户剪贴板、实时 DOM 状态或本例中的内存数据库。在 React 中通过useFrontendToolhook 注册来源use-frontend-tool.tsximport { useFrontendTool } from copilotkit/react-core/v2; useFrontendTool({ name: query_notes, description: Search the users local notes database ..., parameters: z.object({ keyword: z.string().describe(Keyword or phrase to search notes for.), }), handler: async ({ keyword }) { /* 浏览器端执行 */ }, render: ({ args, result, status }) NotesCard ... /, });2.2 异步 vs 同步前端工具的handler既可以是同步函数也可以是async函数。异步形态意味着Agent 发起工具调用后handler返回一个 Promise在 Promise 兑现期间工具状态为「执行中」render拿到status ! completePromise 兑现后结果回传 AgentAgent 基于结果组织最终回复前端卡片从「Querying local notes DB...」切换到「N match(es)」的完成态。这是异步前端工具区别于同步工具的完整闭环Agent 会等待浏览器端的异步结果再继续生成内容。3. demo 全景目录结构与运行前提Agno 集成 demo 中与本主题相关的文件文件作用page.tsxdemo 页面注册工具、配置建议、渲染聊天notes-card.tsx工具结果的卡片渲染组件含全部data-testidfake-notes-db.ts7 条确定性内存笔记 sleep工具_shared/parse-json-result.ts兼容字符串/对象两种结果形态的解析助手tests/e2e/frontend-tools-async.spec.tsPlaywright e2e 验收对应 QA 清单manifest.yaml集成清单Agent 与 demo 路由配置运行前提继承自原 QA 文档在 Agno 集成示例中启动服务将 demo 部署到/demos/frontend-tools-asyncAgent 后端agentfrontend-tools-asyncruntime 为/api/copilotkit必须健康因为工具调用由 Agent 决定是否发起浏览器端无未捕获控制台错误QA 第三步。4. 前端注册异步工具query_notesdemo 页面的核心注册代码位于 page.tsx我们逐段拆解。4.1 工具元信息与参数 SchemauseFrontendTool({ 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).), }), ... });要点description必须足够清晰它会被提供给 Agent 做工具选择与参数推断parameters使用Zod Schema描述z.string().describe(...)里的描述会进入工具协议指导 LLM 正确生成参数react-core 中这类声明来自FrontendTool类型的parameters字段见 frontend-tool.ts工具名query_notes与后端 Agent 侧注册的工具名保持一致才能被正确路由。4.2 异步 handler模拟本地 DB 往返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); // 最多返回 5 条 return { keyword, count: matches.length, notes: matches, }; },技术要点sleep(500)来自 fake-notes-db.ts模拟真实异步数据源的延迟让「加载中」状态可被观察与测试查询逻辑对title、excerpt、tags三个字段做大小写不敏感的子串匹配返回值{ keyword, count, notes }会作为工具结果回传给 Agent供其总结真实场景中这里的NOTES_DB可替换为 IndexedDB、fetch 缓存或任何客户端自有数据源源码注释也明确说明了这一点。4.3 render状态驱动的卡片渲染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} / ); },status字段驱动 UI 状态切换工具执行中loading true卡片显示 Querying local notes DB... 与...占位完成后loading false卡片显示匹配数与笔记列表args?.keyword ?? parsed.keyword的双保险写法保证关键词在「结果尚未返回」与「结果已返回」两种时刻都能显示。其中parseJsonResult兼容了工具结果的两种形态——Agent 发出 JSON 字符串或运行时已解析为对象见 _shared/parse-json-result.ts。4.4 建议提示词Suggestion Pills为了让 QA 可操作demo 用useConfigureSuggestions配置了三个建议按钮page.tsxuseConfigureSuggestions({ 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, });点击 pill 会以message作为用户消息发送引导 Agent 调用query_notes——这正是 QA 文档中点击 suggestion pill的自动化入口。5. 渲染组件NotesCard 与 contenteditable="false">【免费下载链接】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 异步前端工具Async Frontend Tool实战以 Agno 集成 demo 的query_notes为例【免费下载链接】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 开源仓库中 Agno 集成的 QA 文档 frontend-tools-async.md 为核心骨架完整讲解「异步前端工具Async Frontend Tool」在 CopilotKit 中的注册、执行与渲染全链路Agent 发起工具调用后由浏览器端一个async处理器完成本地数据查询再把结果回传给 Agent 用于后续回复同时以自定义 React 组件把结果渲染成聊天中的结构化卡片。读完本文你将掌握useFrontendTool的 API 契约、参数约束、render生命周期以及如何用建议提示词suggestion pill、data-testid与 e2e 测试验证整条异步链路。1. 文档定位一条 QA 检查清单背后的完整功能原 QA 文档 frontend-tools-async.md 是 Agno 集成示例的一个质量检查清单覆盖三个层面前置条件Prerequisitesdemo 部署在/demos/frontend-tools-asyncAgent 后端必须健康功能检查Feature-Specific Checks点击 Find project-planning notes 建议提示词后断言data-testidnotes-card出现、data-testidnotes-keyword展示搜索关键词、data-testidnote-n1等逐条笔记被渲染错误处理Error Handling控制台无未捕获错误。这条清单不是孤立的手工测试用例而是对 CopilotKit「前端工具Frontend Tool」机制中异步形态的验收标准。它验证的核心事实是工具调用发生后等待一个 500ms 的浏览器端异步数据库往返完成后Agent 才能基于返回结果继续对话且前端 UI 必须能表达「加载中 → 完成」两种状态。该 QA 文档对应的可复现测试位于 tests/e2e/frontend-tools-async.spec.tsdemo 源码位于 src/app/demos/frontend-tools-async/。2. 认识前端工具Frontend Tool与异步形态2.1 什么是前端工具CopilotKit 允许 Agent 调用运行在浏览器端的函数——这就是「前端工具」。它不同于后端工具由服务端执行前端工具天然适合访问浏览器本地数据IndexedDB、localStorage、用户剪贴板、实时 DOM 状态或本例中的内存数据库。在 React 中通过useFrontendToolhook 注册来源use-frontend-tool.tsximport { useFrontendTool } from copilotkit/react-core/v2; useFrontendTool({ name: query_notes, description: Search the users local notes database ..., parameters: z.object({ keyword: z.string().describe(Keyword or phrase to search notes for.), }), handler: async ({ keyword }) { /* 浏览器端执行 */ }, render: ({ args, result, status }) NotesCard ... /, });2.2 异步 vs 同步前端工具的handler既可以是同步函数也可以是async函数。异步形态意味着Agent 发起工具调用后handler返回一个 Promise在 Promise 兑现期间工具状态为「执行中」render拿到status ! completePromise 兑现后结果回传 AgentAgent 基于结果组织最终回复前端卡片从「Querying local notes DB...」切换到「N match(es)」的完成态。这是异步前端工具区别于同步工具的完整闭环Agent 会等待浏览器端的异步结果再继续生成内容。3. demo 全景目录结构与运行前提Agno 集成 demo 中与本主题相关的文件文件作用page.tsxdemo 页面注册工具、配置建议、渲染聊天notes-card.tsx工具结果的卡片渲染组件含全部data-testidfake-notes-db.ts7 条确定性内存笔记 sleep工具_shared/parse-json-result.ts兼容字符串/对象两种结果形态的解析助手tests/e2e/frontend-tools-async.spec.tsPlaywright e2e 验收对应 QA 清单manifest.yaml集成清单Agent 与 demo 路由配置运行前提继承自原 QA 文档在 Agno 集成示例中启动服务将 demo 部署到/demos/frontend-tools-asyncAgent 后端agentfrontend-tools-asyncruntime 为/api/copilotkit必须健康因为工具调用由 Agent 决定是否发起浏览器端无未捕获控制台错误QA 第三步。4. 前端注册异步工具query_notesdemo 页面的核心注册代码位于 page.tsx我们逐段拆解。4.1 工具元信息与参数 SchemauseFrontendTool({ 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).), }), ... });要点description必须足够清晰它会被提供给 Agent 做工具选择与参数推断parameters使用Zod Schema描述z.string().describe(...)里的描述会进入工具协议指导 LLM 正确生成参数react-core 中这类声明来自FrontendTool类型的parameters字段见 frontend-tool.ts工具名query_notes与后端 Agent 侧注册的工具名保持一致才能被正确路由。4.2 异步 handler模拟本地 DB 往返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); // 最多返回 5 条 return { keyword, count: matches.length, notes: matches, }; },技术要点sleep(500)来自 fake-notes-db.ts模拟真实异步数据源的延迟让「加载中」状态可被观察与测试查询逻辑对title、excerpt、tags三个字段做大小写不敏感的子串匹配返回值{ keyword, count, notes }会作为工具结果回传给 Agent供其总结真实场景中这里的NOTES_DB可替换为 IndexedDB、fetch 缓存或任何客户端自有数据源源码注释也明确说明了这一点。4.3 render状态驱动的卡片渲染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} / ); },status字段驱动 UI 状态切换工具执行中loading true卡片显示 Querying local notes DB... 与...占位完成后loading false卡片显示匹配数与笔记列表args?.keyword ?? parsed.keyword的双保险写法保证关键词在「结果尚未返回」与「结果已返回」两种时刻都能显示。其中parseJsonResult兼容了工具结果的两种形态——Agent 发出 JSON 字符串或运行时已解析为对象见 _shared/parse-json-result.ts。4.4 建议提示词Suggestion Pills为了让 QA 可操作demo 用useConfigureSuggestions配置了三个建议按钮page.tsxuseConfigureSuggestions({ 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, });点击 pill 会以message作为用户消息发送引导 Agent 调用query_notes——这正是 QA 文档中点击 suggestion pill的自动化入口。5. 渲染组件NotesCard 与 contenteditable="false">【免费下载链接】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），仅供参考
