CopilotKit Agentic Chat 实战：用 CopilotChat 与 LlamaIndex 搭建流式智能对话

CopilotKit Agentic Chat 实战用 CopilotChat 与 LlamaIndex 搭建流式智能对话【免费下载链接】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 开源仓库中 agentic-chat 演示 展开讲解如何在 Next.js 前端用CopilotKitProvider 与CopilotChat组件仅用极少量代码接入一个 LlamaIndexAG-UI 协议Agent 后端实现自然对话、基于 AG-UI 的 token 级流式回复与建议芯片Suggestion Chips。读完本文你将掌握该演示的完整调用链——从页面组件、建议配置、Next.js 运行时代理到 Python Agent 服务——并能直接照搬到自己的项目中。演示概览什么是最小可用的 CopilotKit 聊天界面该演示源码位于 agentic-chat 目录被定义为 The simplest CopilotKit surface即 CopilotKit 最精简的对话形态一个纯粹的 agentic chat——没有富组件渲染、没有共享状态、没有人工审批只有提问→流式回答的闭环。它集中展示了三个核心能力自然对话Natural Conversation在一个熟悉的聊天界面里与你的 Copilot 交流聊天框占位文本为Type a message见 agentic-chat.spec.ts。流式回复Streaming Responses助手消息通过AG-UI协议逐 token 流式到达前端。建议芯片Suggestion Chips聊天输入框下方渲染可点击的快捷建议一键发起对话。需要说明的是该目录中的 README 将后端描述为 LangGraph (Python) agent而从本仓库实际源码看agent.py 的模块说明明确指出这个演示的后端是一个LlamaIndex Workflow通过llama-index-protocols-ag-ui暴露为兼容 AG-UI 的 FastAPI routerREADME 中的表述属于沿用的旧描述实际以源码为准。如何交互从一条提示词开始页面加载后用户可以点击输入框下方出现的一个建议芯片也可以自行输入任意提示词。README 给出了三个可以直接尝试的例子Write a short sonnet about AIExplain the difference between an LLM and an agentGive me three ideas for a weekend project对应到代码里这三个建议实际被定义为三种不同的示例提示见 suggestions.ts写一首关于 AI 的十四行诗、讲一个一句话笑话、论证 17 是否为质数。点击任意芯片即可把对应消息发送给 Agent 并得到流式回复。技术细节从 Provider 到 Chat 组件的完整接线CopilotKit Provider把页面接到运行时CopilotKit组件是整个页面的 Provider负责把 React 树连接到 Copilot 运行时。在 page.tsx 中接线只用了两个属性CopilotKit runtimeUrl/api/copilotkit agentagentic_chat Chat / /CopilotKitruntimeUrl/api/copilotkit指向 Next.js 的一个 API 路由route handler该路由在服务端代理转发请求到 Python Agent 进程。agentagentic_chat选择要连接的 Agent 标识该标识必须与运行时注册的 agent 名对应。组件统一从copilotkit/react-core/v2导入见 page.tsx当前仓库锁定的版本为copilotkit/react-core: 1.68.2见 package.json。CopilotChat完整的聊天 UICopilotChat渲染完整的聊天界面——输入框、消息列表、流式输出——一行即可function Chat() { useAgenticChatSuggestions(); return CopilotChat agentIdagentic_chat /; }注意这里的agentId属性与 Provider 上的agent保持一致都为agentic_chat这是前端页面实际请求的 Agent 标识page.tsx 中源码注释也说明了这一点。建议芯片useConfigureSuggestionsuseConfigureSuggestions注册静态建议它们会以可点击芯片的形式渲染在聊天输入框下方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, });title是芯片上显示的文字message是点击后真正发送给 Agent 的提示内容available: always表示建议始终可用端到端测试正是据此断言多轮对话后建议芯片会重新出现见 agentic-chat.spec.ts。后端LlamaIndex 的 AG-UI 工作流虽然演示名为 Agentic Chat 且 README 提及 LangGraph实际后端是一个LlamaIndex Agent。agent.py 的核心逻辑如下from llama_index.llms.openai import OpenAI from llama_index.protocols.ag_ui.router import get_ag_ui_workflow_router from agents.hitl_in_chat_agent import FixedAGUIChatWorkflow async def _agent_workflow_factory(): wf FixedAGUIChatWorkflow( llmOpenAI(modelgpt-4.1, **_openai_kwargs), frontend_tools[change_background, generate_haiku, generate_task_steps, book_call, show_card, get_weather], backend_tools[query_data, manage_sales_todos, get_sales_todos_tool, schedule_meeting, search_flights, generate_a2ui], system_prompt_AGENT_SYSTEM_PROMPT, initial_state{todos: []}, ) wf.render_only_tool_names {get_weather} return wf agent_router get_ag_ui_workflow_router(workflow_factory_agent_workflow_factory)几个值得注意的工程细节协议get_ag_ui_workflow_router会把 LlamaIndex Workflow 自动封装为完整的AG-UI 协议surface前端通过该协议实现流式 SSE 输出agent.py。LLM默认使用OpenAI(modelgpt-4.1)并支持通过环境变量OPENAI_BASE_URL覆盖 API 地址agent.py。工具划分工具分为frontend_tools前端执行、Agent 仅返回确认与backend_tools服务端执行。缺陷修复代码使用FixedAGUIChatWorkflow来自 hitl_in_chat_agent.py来规避上游库的三个 bug——重复渲染工具调用、缺失parent_message_id、工具结果消息角色错误见 agent.py。运行时代理从 Next.js 路由到 Python 进程Next.js 端/api/copilotkit前端runtimeUrl指向的路由实现在 route.ts。它创建CopilotRuntime并注册多个 agent 名agentic_chat是其中的共享 agent 之一const AGENT_URL process.env.AGENT_URL || http://localhost:8000; function createAgent(subpath: string ) { return new HttpAgent({ url: ${AGENT_URL}${subpath}/run }); }agentic_chat位于sharedAgentNames列表会被映射到默认后端无子路径。随后通过createCopilotRuntimeHandler以single-route模式basePath: /api/copilotkit创建处理函数接收请求并转发给 Agentroute.ts。此外该路由还提供GET健康检查返回 Agent 的AGENT_URL与可达性状态route.ts。Python 端agent_server.py后端是独立的 FastAPI 进程默认端口 8000。agent_server.py 中agent_router作为兜底路由在最后挂载到根路径/catch-allapp.include_router(agent_router) # Shared agent for the rest of the demos注释明确说明Shared agent for the rest of the demos (must be last:/is a catch-all)agent_server.py因此所有未使用专用子路径的 Agent 标识包括agentic_chat都会命中这个共享工作流。端到端验证Playwright 测试守护的最小契约agentic-chat的契约是原生聊天端到端可用agentic-chat.spec.ts 用四组用例将其固化页面加载断言输入框placeholderType a message与三个建议芯片Write a sonnet、Tell me a joke、Is 17 prime?可见。手动输入填入 Say hello in one word. 回车后等待[data-testidcopilot-assistant-message]出现30 秒超时。点击建议点击 Tell me a joke 芯片后同样等待助手消息出现。多轮上下文先告知 My name is Alice.待建议重新出现后追问名字断言第二条回复中包含 Alice——验证流式结束后会话上下文被保留。本地运行方式该演示属于 showcase/integrations/llamaindex 展示项目的一部分。项目的dev脚本用concurrently同时启动 Next.jsnext dev --turbopack与 Python Agent 服务uvicorn agent_server:app --port 8000 --reload见 package.jsoncd showcase/integrations/llamaindex npm run dev启动后访问/demos/agentic-chat即可体验。运行前需要准备后端依赖requirements.txt含llama-index与llama-index-protocols-ag-uiOPENAI_API_KEY环境变量后端默认调用gpt-4.1可选OPENAI_BASE_URL与AGENT_URL默认http://localhost:8000。小结Agentic Chat 演示展示了 CopilotKit 的最小可用聊天范式前端一行CopilotChat 一个CopilotKitProvider后端一个get_ag_ui_workflow_router封装的工作流中间由 Next.js 路由以 AG-UI 协议桥接。全部接线不过几十行代码却完整覆盖了自然对话、流式输出与建议芯片三项核心能力。对于想要快速验证 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），仅供参考