CopilotKit × Mastra从 agentic-chat 演示看 CopilotKit 最小对话界面与运行时接线【免费下载链接】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 官方演示集中 Mastra 集成下的agentic-chat演示为对象完整讲解 CopilotKit 最简对话界面的三层接线前端CopilotKitProvider、CopilotChat渲染面、useConfigureSuggestions建议芯片以及后端 Next.js 路由如何把 Mastra agent 挂接到 CopilotKit 运行时。读完本文你能掌握在 Next.js 应用中用 Mastra 驱动一个 AG-UI 流式 agent 对话的最小可行架构并理解演示仓库中 agent 名称注册、resourceId 隔离等支撑该演示可运行的关键实现细节。演示定位CopilotKit 的最简对话表面演示文档README把agentic-chat定义为CopilotKit 最简的表面the simplest CopilotKit surface一个由 agent 驱动、但不依赖共享状态、工具渲染或生成式 UI 的纯对话界面。它展示三件事自然对话在熟悉的聊天界面中与 Copilot 交流流式响应助手消息通过 AG-UI 协议逐 token 流式返回建议芯片Suggestion Chips预置的起始建议以可点击的快速操作芯片形式渲染在输入框下方。文档给出的典型交互方式是点击建议芯片或自行输入提示词例如Write a short sonnet about AIExplain the difference between an LLM and an agentGive me three ideas for a weekend project这三个能力分别对应下面三个前端构建块Provider 接线、CopilotChat渲染、useConfigureSuggestions建议注册。前端接线Provider、Chat 与建议芯片演示页面入口在 page.tsx全文仅 24 行完整代码如下use client; import React from react; import { CopilotKit, CopilotChat } from copilotkit/react-core/v2; import { useAgenticChatSuggestions } from ./suggestions; export default function AgenticChatDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agentagentic_chat Chat / /CopilotKit ); } function Chat() { useAgenticChatSuggestions(); return CopilotChat agentIdagentic_chat /; }对照 README 的 Technical Details 一节三个要点在源码中的落点如下Provider 接线runtimeUrl 与 agent 选择README 指出CopilotKit组件负责把页面连接到运行时两个关键属性为runtimeUrl/api/copilotkit指向 Next.js 的 App Router 路由该路由代理proxy到后端 agent实际实现见 route.tsagentagentic_chat选定运行时中注册的名为agentic_chat的 agent。在 Mastra 集成中这个名字并不是一个独立注册的 agent而是路由层通过别名机制解析到 Mastra 的weatherAgent详见后文后端代理一节。渲染面CopilotChat 与 agentIdREADME 说明CopilotChat渲染完整的聊天 UI包括输入框、消息列表与流式显示。注意源码中CopilotChat agentIdagentic_chat /显式传入了agentId与 Provider 上的agent属性保持一致——在单个 Provider 下只挂载一个 agent 时二者指向同一个 agentagentId的作用是在多 agent 或显式挂载场景下消除歧义。建议芯片useConfigureSuggestions建议逻辑单独抽到 suggestions.ts 中的一个自定义 hookuse client; import { useConfigureSuggestions } from copilotkit/react-core/v2; export function useAgenticChatSuggestions() { useConfigureSuggestions({ suggestions: [ { title: Write a sonnet, message: Write a short sonnet about AI. }, { title: Tell me a joke, message: Tell me a one-line joke. }, { title: Is 17 prime?, message: Walk me through whether 17 is prime., }, ], available: always, }); }对应 README 中的描述useConfigureSuggestions注册静态建议使其以可点击芯片的形式出现在聊天输入下方。从源码可以看出每条建议由title芯片上显示的文案和message点击后实际发送的提示词组成二者解耦允许芯片文案短于完整提示词available: always表示建议在任何对话状态下都可用而非仅在首次进入或无历史消息时显示。README 举例的 Write a short sonnet about AI 正是其中一条建议的message说明文档示例与实现完全一致。后端代理单一路由 agent 别名机制runtimeUrl指向的/api/copilotkit是整个演示以及整个 Mastra 集成站点的运行时入口位于 route.ts。这一节是 README Technical Details 中 Next.js route that proxies to the agent 的完整展开。运行时装配POST 处理器的核心逻辑是三步const runtime new CopilotRuntime({ agents: getAgents(), }); const copilotHandler createCopilotRuntimeHandler({ runtime, basePath: /api/copilotkit, mode: single-route, }); response await copilotHandler(req);CopilotRuntime来自copilotkit/runtime/v2agents是agent 名称 → agent 实例的映射createCopilotRuntimeHandler以single-route模式工作即所有 CopilotKit 请求打到/api/copilotkit这一个路径上由运行时按basePath自行分派路由源码中的注释明确说明了 V2 运行时的角色Mastra agent 自行驱动 LLM运行时只在前端与 agent 之间做 AG-UI 事件的代理broker。这也正是 README 所说流式响应经 AG-UI 逐 token 送达的底层通路。agentic_chat 如何被解析到 weatherAgentREADME 提到agentagentic_chat选定的 agent defined in langgraph.json——这句话沿用了演示集早期基于 LangGraphPython的后端描述从当前仓库源码看Mastra 集成目录下并不存在langgraph.json实际解析发生在路由层demoAgentNames常量数组route.ts 第 40 行起列出了所有演示请求的 agent 名称agentic_chat是其中第一个。源码注释强调这个列表就是唯一的 agent 注册表This list IS the registry任何新增演示都必须在此登记否则运行时会返回 agent-not-found 错误demoAgentIdOverrides映射表把特定演示别名指向专门的 Mastra agent如headless-complete→headlessCompleteAgent、reasoning-default→reasoningAgentagentic_chat不在覆盖表中因此回退到默认的weatherAgentbuildAgents()通过ag-ui/mastra的MastraAgent.getLocalAgents/getLocalAgent把 Mastra 实例中的本地 agent 包装成 AG-UI agent再以mastra-演示名形式的独立resourceId绑定到每个演示别名上。weatherAgent本身的定义在 agents/index.ts一个使用openai(gpt-4o)模型、挂载get_weather等 7 个工具、并启用 LibSQL 存储支撑的 working memory 的 MastraAgent。对 agentic-chat 演示而言工具不会被触发——它就只作为对话模型使用这也印证了 README 最简对话表面的定位。为什么每个演示要独占一个 resourceId源码注释解释了resourceId隔离的动机Mastra Memory 在提供threadId时要求非空resourceId而 CopilotKit 运行时总是提供threadId且getLocalAgents默认对所有本地 agent 套用同一个 resourceId会让多个演示共享同一个工作记忆桶。因此buildAgents()为每个演示别名分配mastra-name形式的独立 resourceId并对 resourceId 唯一性做了断式校验重复即抛错防止跨演示的记忆污染。对 agentic-chat 这样的无状态演示这一机制只是保证它不会读到其他演示残留的 working memory。该注册表还受到测试守护demoAgentNames.parity.test.ts 强制每个演示页面中agent…的字面量都必须出现在demoAgentNames列表中从两侧页面声明 ↔ 路由注册保证一致。可观测性三类失败的关联日志路由层还内置了一套带errorId关联 ID 的错误日志结构把失败分为setup响应头写出前的同步失败如 agent 装配出错可返回 500 JSON与stream头部已刷出后的流中断只能落日志两类并用wrapStreamingResponse包裹流式响应体确保上游 SSE 循环中的异常不会无声逃逸。对运维者来说按errorIdgrep 日志即可关联前后两类的失败。这部分属于演示站点的工程质量细节与 README 描述的对话行为无直接关系但在排查聊天无响应类问题时值得知晓。端到端数据流小结把前后端拼起来agentic-chat 演示的一次完整交互是用户在CopilotChat输入提示词或点击建议芯片触发message发送CopilotKitProvider 将请求发往runtimeUrl即/api/copilotkit路由层从getAgents()缓存中按agentagentic_chat解析到别名绑定的 AG-UI agent底层为weatherAgent运行时以 AG-UI 事件流形式驱动 Mastra agentagent 调用openai(gpt-4o)生成回复事件流经/api/copilotkit的 SSE 响应逐 token 流回前端CopilotChat实时渲染。关键文件索引演示 README演示定位与交互说明page.tsxProvider 接线与CopilotChat渲染suggestions.tsuseConfigureSuggestions静态建议注册route.ts运行时路由、agent 注册表与 resourceId 隔离mastra/index.tsMastra 实例、LibSQL 存储与本地 agent 集合注册agents/index.tsweatherAgent等本地 agent 定义demoAgentNames.parity.test.ts演示页面 agent 名与路由注册表的 parity 测试。【免费下载链接】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），仅供参考