CopilotKit CrewAI Crews 集成质量保障指南Agentic Chat 全链路 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 Crews 集成的 QA 文档 为核心系统讲解如何对一个基于 CrewAI Flow 的 Agentic Chat 演示应用进行端到端质量验证涵盖前置检查、基础功能、前端工具Frontend Tools、渲染工具Render Tool、Agent 上下文Agent Context以及异常处理等全部测试步骤并结合仓库源码说明每一步背后的实现原理。读完本指南你将掌握一套可直接复用的 CopilotKit 聊天类演示 QA 清单并能对照源码理解测试断言为何有效。前置条件演示可用性与后端健康检查QA 文档明确了两项硬性前置条件Demo 已部署并可访问即agentic-chat演示页面在浏览器中可正常打开本地开发时访问/demos/agentic-chat。Agent 后端健康通过/api/health检查后端状态。仓库中的健康检查实现位于 health route返回 JSON 结构如下export async function GET() { return NextResponse.json({ status: ok, integration: crewai-crews, timestamp: new Date().toISOString(), }); }在实际部署环境中可以通过curl /api/health验证返回status: ok这是所有后续 QA 步骤的前提。值得注意的是CopilotKit 运行时路由也提供 GET 健康探针二者可配合使用见 copilotkit route。基本功能验证聊天界面的最小可用契约页面加载与输入框QA 第一步是导航到 agentic-chat 演示页确认聊天界面正常加载输入框占位符为Type a message背景容器data-testidbackground-container可见默认背景色为主题默认色rgb(250, 250, 249)。这些断言与 Playwright 端到端测试 agentic-chat.spec.ts 高度一致该测试用page.getByPlaceholder(Type a message)验证输入框可见并断言三个起始建议按钮Write a sonnet、Tell me a joke、Is 17 prime?均渲染出来。发送消息与响应发送基础消息如 Hello验证 Agent 返回文本消息。E2E 测试中助手响应通过data-testidcopilot-assistant-message定位器断言超时设置为 30 秒await input.fill(Say hello in one word.); await input.press(Enter); await expect( page.locator([data-testidcopilot-assistant-message]).first(), ).toBeVisible({ timeout: 30000 });这个copilot-assistant-message是 CopilotKit 聊天组件在流式渲染助手消息时自动写入的测试定位标识QA 清单与 Playwright 测试共享同一断言契约这正是文档即规范、测试即证明的体现。多轮对话保持上下文E2E 测试还验证了多轮上下文保持先发送 My name is Alice.等待建议按钮重新出现表示流式结束、界面就绪再发送 What name did I just give you?断言第二条助手响应包含 Alice。QA 文档中对应步骤是验证 Agent 知道用户名 Bob见下文 Agent Context 小节。特性专项检查Suggestions 建议按钮QA 文档要求验证两个建议按钮可见Change background 建议按钮Generate sonnet 建议按钮。点击 Change background 建议后验证建议要么填充输入框、要么直接发送消息。这一行为由前端建议注册机制控制。以仓库中 frontend-tools 的建议配置 为例可见其完整形态useConfigureSuggestions({ suggestions: [ { title: Sunset theme, message: Make the background a sunset gradient. }, { title: Forest theme, message: Switch to a deep green forest gradient. }, { title: Cosmic theme, message: Make it a navy → magenta cosmic gradient. }, ], available: always, });而 agentic-chat 演示自身的三条建议定义在 suggestions.ts通过useConfigureSuggestions注册available: always表示建议按钮持续可用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, });建议按钮的点击行为遵循 CopilotKit 默认交互点击建议后消息会注入输入框或直接发送具体行为由组件的当前配置决定。建议按钮的出现时机也常被 E2E 测试当作流式响应结束的就绪信号。前端工具Frontend Toolchange_backgroundQA 步骤要求向 Agent 发送 Change the background to a sunset gradient然后验证背景容器样式从默认值发生变化且change_background工具返回成功状态。前端注册useFrontendTool背景切换是典型的Frontend Tool前端工具场景工具的执行权在浏览器端由useFrontendTool注册。仓库中完整的实现位于 frontend-tools 页面useFrontendTool({ name: change_background, description: Change the page background. Accepts any valid CSS background value — colors, linear or radial gradients, etc., parameters: z.object({ background: z .string() .describe(The CSS background value. Prefer gradients.), }), handler: async ({ background }) { setBackground(background); return { status: success }; }, });要点拆解name必须与后端暴露给 Agent 的工具名一致这里是change_backgroundAgent 才能通过函数调用发起该工具parameters使用Zod schema描述参数QA 消息中的 sunset gradient 会被 Agent 转化为参数background的合法 CSS 渐变值handler在浏览器中执行返回{ status: success }即对应 QA 文档中验证 change_background 工具返回成功状态的断言依据。背景容器与默认值背景容器组件定义在 background.tsxexport const DEFAULT_BACKGROUND #4f46e5; export function Background({ background, children }) { return ( div >tool_choice( required if self.state.copilotkit.actions and self.state.messages and self.state.messages[-1].get(role) user else auto ),Flow 不会在后端伪造工具结果——工具调用事件通过 AG-UI 协议流向浏览器由 CopilotKit 在浏览器端执行 handler再用权威结果恢复对话。这一设计保证了 QA 中背景变化即时生效、工具返回 success的可验证性。路由映射代理路由在 copilotkit route 中把frontend_tools这一 Agent 名映射到/frontend-tools端点agents[frontend_tools] createAgent(/frontend-tools);而agentic_chat走默认的中性聊天端点/chatcreateAgent()默认路径。渲染工具Render Tool天气卡片QA 步骤要求输入 Whats the weather in Tokyo?验证加载状态显示Loading weather...data-testidweather-info-loadingWeatherCard 渲染data-testidweather-info包含城市名、摄氏温度、湿度百分比、英里/小时风速、天气状况文本。前端注册useRenderTool天气卡片的核心实现位于 tool-rendering 页面通过useRenderTool将get_weather工具与自定义 React 组件绑定useRenderTool( { name: get_weather, parameters: z.object({ location: z.string() }), render: ({ parameters, result, status }) { const loading status ! complete; const parsed parseJsonResultWeatherResult(result); return ( WeatherCard loading{loading} location{parameters?.location ?? parsed.city ?? } temperature{parsed.temperature} humidity{parsed.humidity} windSpeed{parsed.wind_speed} conditions{parsed.conditions} / ); }, }, [], );关键机制status字段区分加载态status ! complete与完成态对应 QA 中的 loading 断言与卡片数据断言WeatherCard接收loading属性——加载中显示 Loading weather...对应weather-info-loadingtestid完成后显示城市、温度°C、湿度%、风速mph与天气状况对应weather-infotestidparseJsonResult工具函数见 _shared/parse-json-result.ts负责把后端返回的 JSON 字符串安全解析为结构化对象。后端工具定义后端get_weather工具定义在 tool_rendering.py采用 LiteLLM/OpenAI 函数调用格式并要求位置名完整拼写如 San Francisco 而非 SFGET_WEATHER_TOOL { type: function, function: { name: get_weather, description: ( Get current weather for a location. Always call this tool when the user asks about weather. Ensure the location is fully spelled out (e.g. San Francisco, not SF). ), parameters: { type: object, properties: { location: {type: string, description: The city or location to get weather for.} }, required: [location], }, }, }Flow 内部以循环方式在本地执行后端工具get_weather等并将每一条响应文本或工具调用通过copilotkit_stream流式输出。测试驱动方面headless-complete 的 E2E 测试同样断言了天气卡片的完整渲染路径见 headless-complete.spec.ts与 QA 清单形成交叉印证。温度单位等展示细节QA 中Temperature in degrees C与Wind speed in mph的展示细节由WeatherCard组件的实现决定验证时只需关注卡片中对应字段已渲染且值非空即可不同演示实现可能在不同单位/字段顺序上存在差异应以被验证页面的实际组件为准。Agent ContextAgent 上下文注入QA 步骤要求验证 Agent 知道用户名是Bob通过useAgentContext提供询问 What is my name? 时 Agent 回答 Bob。前端注入useAgentContext仓库中 readonly-state-agent-context 页面 展示了useAgentContext的典型用法——它把应用侧的状态以描述 值的形式发布到 Agent 运行时随每次请求进入 Agent 的上下文useAgentContext({ description: The currently logged-in users display name, value: userName, }); useAgentContext({ description: The users IANA timezone (used when mentioning times), value: userTimezone, }); useAgentContext({ description: The users recent activity in the app, newest first, value: recentActivity, });同理agent-config 演示 用它把tone、expertise、responseLength等配置透传给 Agent。QA 中 Bob 对应的实现即是在页面内useAgentContext({ description: user name, value: Bob })。后端透传机制从源码结构看上下文进入模型提示词的关键在于 chat_flow.py 中的ChatStateAG-UI 桥接层会把RunAgentInput.context放到 state 的context字段但CopilotKitState本身未声明该字段pydantic 在校验时会丢弃它因此必须显式声明class ChatState(CopilotKitState): CopilotKitState plus the AG-UI request context. context: list[Any] Field(default_factorylist)随后 Flow 把 state排除 messages 与 copilotkit 字段序列化为 JSON 注入系统提示词state self.state.model_dump(exclude{messages, copilotkit}) state_context json.dumps(state, defaultstr, sort_keysTrue) ... content: f{self.system_prompt}\n\nApplication context: {state_context}因此 QA 中询问用户名得到 Bob能成立是因为上下文已作为Application context拼入系统提示词且系统提示词要求在后续轮次中保留用户所选专有名词的原始拼写并在用户询问时逐字复述见BASE_CHAT_PROMPT。异常处理与边界验证QA 文档的第三部分覆盖三类边界情况发送空消息——应被优雅处理不崩溃、不报错正常使用期间无控制台报错发送超长消息——UI 不应破版。这些属于通用前端健壮性检查。从实现看CopilotChat组件内置了空输入禁用/忽略机制无内容时不提交超长消息则依赖消息列表的滚动容器与文本换行处理。建议在验证时打开浏览器 DevTools 控制台观察网络与 JS 错误并在超长消息后检查输入框、消息气泡、建议按钮区域是否保持正常布局。预期结果Expected Results验收标准QA 文档给出的最终验收标准是验收项标准聊天加载3 秒内完成Agent 响应10 秒内返回背景变化工具执行后即时生效天气卡片所有数据字段均渲染界面无 UI 错误或布局破损需要说明的是这些时间阈值3 秒 / 10 秒是针对该演示部署环境的经验性 SLA。其中背景变化即时生效有明确的实现支撑前端工具 handler 在浏览器本地执行setBackground无需等待下一次网络往返天气卡片字段完整由useRenderTool的 render 函数在status complete后读取解析后的结果字段决定。E2E 测试中对应使用了更宽松的超时如助手消息 30 秒QA 人工验收则可按文档标准执行。从 QA 到测试文档清单与 Playwright 的对应关系将 QA 文档与仓库测试对照可以形成一张完整的人工验收 → 自动化测试映射表QA 步骤自动化测试证据输入框占位符、建议按钮可见agentic-chat.spec.tsgetByPlaceholder(Type a message)、三个建议按钮断言发送消息收到响应同文件Say hello in one word. 用例断言copilot-assistant-message可见点击建议触发消息同文件Tell me a joke 点击用例多轮上下文保持同文件Alice 名字用例断言第二条响应含 Alice天气卡片渲染headless-complete.spec.ts 天气卡片用例推理链变体agentic-chat-reasoningagentic-chat-reasoning.spec.ts 及对应 QA 文档延伸阅读Agentic Chat 演示说明该演示的最小架构说明Provider、Chat surface、Suggestions前端工具 READMEFrontend Tool 的完整讲解工具渲染 READMEuseRenderTool与 catch-all 渲染器运行入口pnpm dev同时启动 Next.js3000 端口与 Uvicorn 后端8000 端口环境变量示例AGENT_URL、OPENAI_API_KEY等配置集成清单 manifest.yaml该集成的特性清单agentic-chat、tool-rendering、hitl 等【免费下载链接】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），仅供参考