CopilotKit 与 AG2 集成实战用 Tool-Based Generative UI 让 Agent 工具调用渲染出 React 图表组件【免费下载链接】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/CopilotKitTool-Based Generative UI工具驱动的生成式 UI是 CopilotKit 生成式 UI 体系中的核心模式之一Agent 在对话过程中调用后端工具返回结构化数据前端不把结果展示成普通文本而是将工具结果交给自定义 React 组件渲染。本文以 AG2 集成 showcase 中的gen-ui-tool-based演示为骨架从组件注册、Schema 定义、后端工具契约到端到端验证完整讲解如何在 CopilotKit 中把「工具结果」变成「可交互的图表 UI」。这个 Demo 在解决什么问题在传统 Chat UI 里Agent 调用工具后用户看到的是大段 JSON 或纯文本。而 Tool-Based Generative UI 的目标是Agent 只负责返回结构化数据前端负责决定这些数据长什么样。这也正是 CopilotKit 官方文档中对该模式的定位——The agent calls a backend tool that returns structured data; the frontend renders that tool result as a custom React component instead of plain text见 README。在这个 demo 中AgentAG2 的 ConversableAgent通过query_data等后端工具返回销售、流量等 JSON 结构化数据前端通过useComponent将工具名如render_bar_chart、render_pie_chart映射到 BarChart / PieChart 两个 React 组件用户发出Show me a bar chart of quarterly sales这类自然语言请求后Agent 调用工具聊天流里直接渲染出带标题、图例、动画的图表卡片。该 demo 在集成清单 manifest.yaml 中被登记为gen-ui-tool-based路由为/demos/gen-ui-tool-based属于generative-ui生成式 UI能力分类与gen-ui-agentAgent 驱动的长任务生成 UI、tool-rendering工具结果渲染等并列。前端用 useComponent 注册「工具名 → 组件」映射Demo 的入口页面 page.tsx 是整个模式的核心全部逻辑不过几十行use client; import React from react; import { CopilotChat, CopilotKit, useComponent, } from copilotkit/react-core/v2; import { BarChart, barChartPropsSchema } from ./bar-chart; import { PieChart, pieChartPropsSchema } from ./pie-chart; import { useSuggestions } from ./suggestions; function Chat() { useComponent({ name: render_bar_chart, description: Display a bar chart with labeled numeric values., parameters: barChartPropsSchema, render: BarChart, }); useComponent({ name: render_pie_chart, description: Display a pie chart with labeled numeric values., parameters: pieChartPropsSchema, render: PieChart, }); useSuggestions(); return ( div classNameflex justify-center items-center h-screen w-full div classNameh-full w-full max-w-4xl CopilotChat agentIdgen-ui-tool-based classNameh-full rounded-2xl / /div /div ); } export default function ControlledGenUiDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agentgen-ui-tool-based Chat / /CopilotKit ); }useComponent 的底层原理useComponent并不是一个独立的新机制而是对useFrontendTool的便捷封装。在源码 packages/react-core/src/v2/hooks/use-component.tsx#L59-L92 中可以看到它的实现方式自动为工具拼接面向模型model-facing的描述前缀Use this tool to display the name component in the chat. This tool renders a visual UI component for the user.开发者传入的description会追加在该前缀之后将parameters任何符合 Standard Schema V1 规范的类型库例如 zod透传给底层 frontend tool模型据此知道该工具需要哪些参数渲染时把工具调用的args展开后作为 props 传给注册的 React 组件还支持agentId限定只对某个 Agent 生效与followUp是否允许模型在渲染后继续追问以及第二个参数deps与useEffect相同的依赖刷新语义。也就是说useComponent把「注册一个带 Schema 的渲染组件」这件事压缩成了一次声明底层依然是 CopilotKit 的 frontend tool 体系在驱动。Schema 与组件解耦图表组件的 Schema 定义在组件文件里与页面解耦。柱状图 bar-chart.tsxexport const barChartPropsSchema z.object({ title: z.string().describe(Chart title), description: z.string().describe(Brief description or subtitle), data: z.array( z.object({ label: z.string(), value: z.number(), }), ), }); export type BarChartProps z.infertypeof barChartPropsSchema;饼图 pie-chart.tsx 使用完全相同的 schema 形状。这意味着Schema 即契约zod schema 一方面驱动模型生成参数describe注释会被当作对模型的提示另一方面通过z.infer推导出 TypeScript 类型让render组件的 props 在编译期就类型安全数据形状统一{ label, value }的结构对模型友好柱状图与饼图可以共用同一份数据。图表组件的实现细节BarChart 基于 Recharts 实现值得注意的几个工程细节bar-chart.tsx空数据降级当data为空时渲染一张占位卡片No data available避免图表库在空数组上抛错增量动画通过useRef(new Setnumber())记录已经渲染过的柱子 index只有新到达的数据柱才触发barSlideIn关键帧动画translateY(40px) → 0避免流式更新时整图反复重播动画品牌配色固定 7 色板#BEC2FF、#85ECCE、#FFAC4D等按 index 取模循环上色。PieChart 则是手写的 SVG 环形图pie-chart.tsx用strokeDasharray/strokeDashoffset计算每个扇区的弧长与间隔底部附带图例列表显示每个类目的数值和百分比。组件自带完整的降级 UI并且通过Number(item.value) || 0做了数据容错。后端Agent 工具如何返回结构化数据前端注册好render_bar_chart/render_pie_chart后Agent 端需要有一个能被模型调用的工具来产生数据。AG2 侧的核心 agent 定义在 src/agents/agent.py其中query_data就是图表数据入口async def query_data( query: Annotated[str, Natural language query for financial data], ) - str: Query financial database for chart data. # Return a JSON string (not a list): autogen serializes non-str returns # with str(), producing a Python repr (single quotes) that the frontends # parseJsonResult/JSON.parse cannot parse. Same pattern as get_weather. return json.dumps(query_data_impl(query))源码注释里透露了一个非常关键的跨端契约细节agent.py工具必须返回 JSON 字符串json.dumps而不能直接返回 Python list 或 dict。原因在于 autogen/AG2 对非字符串返回值会用str()序列化生成带单引号的 Python repr如{label: Q1, value: 100}前端JSON.parse无法解析。这个坑同样适用于manage_sales_todos、get_sales_todos、schedule_meeting、search_flights等其余工具。整个 agent 的装配方式如下agent.py使用 AG2 的ConversableAgent承载全部工具通过AGUIStream(agent)以 AG-UI 协议把 Agent 暴露给 CopilotKit runtime前端通过CopilotKit runtimeUrl/api/copilotkit agentgen-ui-tool-based连接到该 runtime聊天请求经由/api/copilotkit路由见 route.ts转发给 agent。提示词引导让 Agent 主动产出图表为了让用户开箱即用地看到图表效果demo 还用useConfigureSuggestions配置了三条建议提示词suggestions.tsuse client; import { useConfigureSuggestions } from copilotkit/react-core/v2; export function useSuggestions() { useConfigureSuggestions({ suggestions: [ { title: Sales bar chart, message: Show me a bar chart of quarterly sales for Q1, Q2, Q3, Q4., }, { title: Traffic pie chart, message: Show me a pie chart of website traffic by source., }, { title: Market share, message: Show a pie chart of smartphone market share by brand., }, ], available: always, }); }available: always表示建议始终可见而非仅在输入框聚焦或空态时出现。这些建议文案同时在端到端测试中被断言是验证 demo 行为的一部分。端到端验证测试如何证明「工具结果渲染为 UI」Playwright 测试 tests/e2e/gen-ui-tool-based.spec.ts 把该模式的可验收行为固化成了断言页面加载即出现三条建议 pillSales bar chart、Traffic pie chart、Market share必须通过[data-testidcopilot-suggestion]可见饼图请求输入Show me a pie chart of revenue by category后在[data-testidcopilot-assistant-message]内应出现一个可见的svgPieChart 的渲染结果超时 60 秒柱状图请求输入Show me a bar chart of monthly expenses同样断言 assistant 消息内出现svg基础对话普通消息能收到 assistant 回复。测试的断言方式在 assistant 消息里查找svg精准对应了本文模式的定义图表不是聊天窗口外部的静态页面而是作为一条 assistant 消息内容被动态渲染进对话流的。这说明useComponent渲染的组件会作为消息的一部分参与对话历史与流式输出。运行与查看方式该 demo 属于 AG2 集成 showcase。查看它的推荐路径阅读 showcase 根目录 README 了解 AG2 集成的整体结构与启动方式本地运行时启动 Next.js 应用与 AG2 agent 后端agent通过AGUIStream暴露访问/demos/gen-ui-tool-based后端健康检查可通过/api/health见 QA 文档 qa/gen-ui-tool-based.mdQA 清单还给出了加载时间预期sidebar 3 秒内、agent 10 秒内回复等可观察指标运行 Playwright e2e 测试验证核心行为。模式小结Tool-Based Generative UI 的关键要点前后端各司其职后端工具只返回 JSON 结构化数据前端用useComponent声明「工具名 → 渲染组件 → 参数 Schema」三元组把展示逻辑完全留在客户端。Schema 即双端契约zod 等 Standard Schema V1 兼容库既指导模型生成参数又为 React 组件提供类型推导一处定义两端受益。注意序列化边界AG2 工具返回值务必json.dumps成 JSON 字符串避免 Python repr 破坏前端解析agent.py 中的注释是该坑的一手记录。渲染是消息流的一部分组件以 assistant 消息形态内联渲染e2e 测试对copilot-assistant-message内svg的断言即是证明因此流式更新、加载与完成状态天然融入对话体验。如果需要在项目里复刻该模式只需三步后端提供一个返回 JSON 字符串的工具前端用 zod 定义参数 Schema 并用useComponent注册渲染组件在CopilotKit内挂载CopilotChat即可。全部源码均可在此仓库的 showcase/integrations/ag2/src/app/demos/gen-ui-tool-based/ 目录下查阅。【免费下载链接】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 与 AG2 集成实战：用 Tool-Based Generative UI 让 Agent 工具调用渲染出 React 图表组件
CopilotKit 与 AG2 集成实战用 Tool-Based Generative UI 让 Agent 工具调用渲染出 React 图表组件【免费下载链接】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/CopilotKitTool-Based Generative UI工具驱动的生成式 UI是 CopilotKit 生成式 UI 体系中的核心模式之一Agent 在对话过程中调用后端工具返回结构化数据前端不把结果展示成普通文本而是将工具结果交给自定义 React 组件渲染。本文以 AG2 集成 showcase 中的gen-ui-tool-based演示为骨架从组件注册、Schema 定义、后端工具契约到端到端验证完整讲解如何在 CopilotKit 中把「工具结果」变成「可交互的图表 UI」。这个 Demo 在解决什么问题在传统 Chat UI 里Agent 调用工具后用户看到的是大段 JSON 或纯文本。而 Tool-Based Generative UI 的目标是Agent 只负责返回结构化数据前端负责决定这些数据长什么样。这也正是 CopilotKit 官方文档中对该模式的定位——The agent calls a backend tool that returns structured data; the frontend renders that tool result as a custom React component instead of plain text见 README。在这个 demo 中AgentAG2 的 ConversableAgent通过query_data等后端工具返回销售、流量等 JSON 结构化数据前端通过useComponent将工具名如render_bar_chart、render_pie_chart映射到 BarChart / PieChart 两个 React 组件用户发出Show me a bar chart of quarterly sales这类自然语言请求后Agent 调用工具聊天流里直接渲染出带标题、图例、动画的图表卡片。该 demo 在集成清单 manifest.yaml 中被登记为gen-ui-tool-based路由为/demos/gen-ui-tool-based属于generative-ui生成式 UI能力分类与gen-ui-agentAgent 驱动的长任务生成 UI、tool-rendering工具结果渲染等并列。前端用 useComponent 注册「工具名 → 组件」映射Demo 的入口页面 page.tsx 是整个模式的核心全部逻辑不过几十行use client; import React from react; import { CopilotChat, CopilotKit, useComponent, } from copilotkit/react-core/v2; import { BarChart, barChartPropsSchema } from ./bar-chart; import { PieChart, pieChartPropsSchema } from ./pie-chart; import { useSuggestions } from ./suggestions; function Chat() { useComponent({ name: render_bar_chart, description: Display a bar chart with labeled numeric values., parameters: barChartPropsSchema, render: BarChart, }); useComponent({ name: render_pie_chart, description: Display a pie chart with labeled numeric values., parameters: pieChartPropsSchema, render: PieChart, }); useSuggestions(); return ( div classNameflex justify-center items-center h-screen w-full div classNameh-full w-full max-w-4xl CopilotChat agentIdgen-ui-tool-based classNameh-full rounded-2xl / /div /div ); } export default function ControlledGenUiDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agentgen-ui-tool-based Chat / /CopilotKit ); }useComponent 的底层原理useComponent并不是一个独立的新机制而是对useFrontendTool的便捷封装。在源码 packages/react-core/src/v2/hooks/use-component.tsx#L59-L92 中可以看到它的实现方式自动为工具拼接面向模型model-facing的描述前缀Use this tool to display the name component in the chat. This tool renders a visual UI component for the user.开发者传入的description会追加在该前缀之后将parameters任何符合 Standard Schema V1 规范的类型库例如 zod透传给底层 frontend tool模型据此知道该工具需要哪些参数渲染时把工具调用的args展开后作为 props 传给注册的 React 组件还支持agentId限定只对某个 Agent 生效与followUp是否允许模型在渲染后继续追问以及第二个参数deps与useEffect相同的依赖刷新语义。也就是说useComponent把「注册一个带 Schema 的渲染组件」这件事压缩成了一次声明底层依然是 CopilotKit 的 frontend tool 体系在驱动。Schema 与组件解耦图表组件的 Schema 定义在组件文件里与页面解耦。柱状图 bar-chart.tsxexport const barChartPropsSchema z.object({ title: z.string().describe(Chart title), description: z.string().describe(Brief description or subtitle), data: z.array( z.object({ label: z.string(), value: z.number(), }), ), }); export type BarChartProps z.infertypeof barChartPropsSchema;饼图 pie-chart.tsx 使用完全相同的 schema 形状。这意味着Schema 即契约zod schema 一方面驱动模型生成参数describe注释会被当作对模型的提示另一方面通过z.infer推导出 TypeScript 类型让render组件的 props 在编译期就类型安全数据形状统一{ label, value }的结构对模型友好柱状图与饼图可以共用同一份数据。图表组件的实现细节BarChart 基于 Recharts 实现值得注意的几个工程细节bar-chart.tsx空数据降级当data为空时渲染一张占位卡片No data available避免图表库在空数组上抛错增量动画通过useRef(new Setnumber())记录已经渲染过的柱子 index只有新到达的数据柱才触发barSlideIn关键帧动画translateY(40px) → 0避免流式更新时整图反复重播动画品牌配色固定 7 色板#BEC2FF、#85ECCE、#FFAC4D等按 index 取模循环上色。PieChart 则是手写的 SVG 环形图pie-chart.tsx用strokeDasharray/strokeDashoffset计算每个扇区的弧长与间隔底部附带图例列表显示每个类目的数值和百分比。组件自带完整的降级 UI并且通过Number(item.value) || 0做了数据容错。后端Agent 工具如何返回结构化数据前端注册好render_bar_chart/render_pie_chart后Agent 端需要有一个能被模型调用的工具来产生数据。AG2 侧的核心 agent 定义在 src/agents/agent.py其中query_data就是图表数据入口async def query_data( query: Annotated[str, Natural language query for financial data], ) - str: Query financial database for chart data. # Return a JSON string (not a list): autogen serializes non-str returns # with str(), producing a Python repr (single quotes) that the frontends # parseJsonResult/JSON.parse cannot parse. Same pattern as get_weather. return json.dumps(query_data_impl(query))源码注释里透露了一个非常关键的跨端契约细节agent.py工具必须返回 JSON 字符串json.dumps而不能直接返回 Python list 或 dict。原因在于 autogen/AG2 对非字符串返回值会用str()序列化生成带单引号的 Python repr如{label: Q1, value: 100}前端JSON.parse无法解析。这个坑同样适用于manage_sales_todos、get_sales_todos、schedule_meeting、search_flights等其余工具。整个 agent 的装配方式如下agent.py使用 AG2 的ConversableAgent承载全部工具通过AGUIStream(agent)以 AG-UI 协议把 Agent 暴露给 CopilotKit runtime前端通过CopilotKit runtimeUrl/api/copilotkit agentgen-ui-tool-based连接到该 runtime聊天请求经由/api/copilotkit路由见 route.ts转发给 agent。提示词引导让 Agent 主动产出图表为了让用户开箱即用地看到图表效果demo 还用useConfigureSuggestions配置了三条建议提示词suggestions.tsuse client; import { useConfigureSuggestions } from copilotkit/react-core/v2; export function useSuggestions() { useConfigureSuggestions({ suggestions: [ { title: Sales bar chart, message: Show me a bar chart of quarterly sales for Q1, Q2, Q3, Q4., }, { title: Traffic pie chart, message: Show me a pie chart of website traffic by source., }, { title: Market share, message: Show a pie chart of smartphone market share by brand., }, ], available: always, }); }available: always表示建议始终可见而非仅在输入框聚焦或空态时出现。这些建议文案同时在端到端测试中被断言是验证 demo 行为的一部分。端到端验证测试如何证明「工具结果渲染为 UI」Playwright 测试 tests/e2e/gen-ui-tool-based.spec.ts 把该模式的可验收行为固化成了断言页面加载即出现三条建议 pillSales bar chart、Traffic pie chart、Market share必须通过[data-testidcopilot-suggestion]可见饼图请求输入Show me a pie chart of revenue by category后在[data-testidcopilot-assistant-message]内应出现一个可见的svgPieChart 的渲染结果超时 60 秒柱状图请求输入Show me a bar chart of monthly expenses同样断言 assistant 消息内出现svg基础对话普通消息能收到 assistant 回复。测试的断言方式在 assistant 消息里查找svg精准对应了本文模式的定义图表不是聊天窗口外部的静态页面而是作为一条 assistant 消息内容被动态渲染进对话流的。这说明useComponent渲染的组件会作为消息的一部分参与对话历史与流式输出。运行与查看方式该 demo 属于 AG2 集成 showcase。查看它的推荐路径阅读 showcase 根目录 README 了解 AG2 集成的整体结构与启动方式本地运行时启动 Next.js 应用与 AG2 agent 后端agent通过AGUIStream暴露访问/demos/gen-ui-tool-based后端健康检查可通过/api/health见 QA 文档 qa/gen-ui-tool-based.mdQA 清单还给出了加载时间预期sidebar 3 秒内、agent 10 秒内回复等可观察指标运行 Playwright e2e 测试验证核心行为。模式小结Tool-Based Generative UI 的关键要点前后端各司其职后端工具只返回 JSON 结构化数据前端用useComponent声明「工具名 → 渲染组件 → 参数 Schema」三元组把展示逻辑完全留在客户端。Schema 即双端契约zod 等 Standard Schema V1 兼容库既指导模型生成参数又为 React 组件提供类型推导一处定义两端受益。注意序列化边界AG2 工具返回值务必json.dumps成 JSON 字符串避免 Python repr 破坏前端解析agent.py 中的注释是该坑的一手记录。渲染是消息流的一部分组件以 assistant 消息形态内联渲染e2e 测试对copilot-assistant-message内svg的断言即是证明因此流式更新、加载与完成状态天然融入对话体验。如果需要在项目里复刻该模式只需三步后端提供一个返回 JSON 字符串的工具前端用 zod 定义参数 Schema 并用useComponent注册渲染组件在CopilotKit内挂载CopilotChat即可。全部源码均可在此仓库的 showcase/integrations/ag2/src/app/demos/gen-ui-tool-based/ 目录下查阅。【免费下载链接】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），仅供参考