企业官网建设流程全解析

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组件，仅用极少量代码接入一个 LlamaIndex（AG-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 router（README 中的表述属于沿用的旧描述，实际以源码为准）。

如何交互：从一条提示词开始

页面加载后，用户可以点击输入框下方出现的一个建议芯片，也可以自行输入任意提示词。README 给出了三个可以直接尝试的例子：

• "Write a short sonnet about AI"
• "Explain the difference between an LLM and an agent"
• "Give 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" agent="agentic_chat"> <Chat /> </CopilotKit>

• runtimeUrl="/api/copilotkit"：指向 Next.js 的一个 API 路由（route handler），该路由在服务端代理转发请求到 Python Agent 进程。
• agent="agentic_chat"：选择要连接的 Agent 标识，该标识必须与运行时注册的 agent 名对应。

组件统一从@copilotkit/react-core/v2导入（见 page.tsx），当前仓库锁定的版本为@copilotkit/react-core: 1.68.2（见 package.json）。

CopilotChat：完整的聊天 UI

CopilotChat渲染完整的聊天界面——输入框、消息列表、流式输出——一行即可：

function Chat() { useAgenticChatSuggestions(); return <CopilotChat agentId="agentic_chat" />; }

注意这里的agentId属性与 Provider 上的agent保持一致（都为agentic_chat），这是前端页面实际请求的 Agent 标识（page.tsx 中源码注释也说明了这一点）。

建议芯片：useConfigureSuggestions

useConfigureSuggestions注册静态建议，它们会以可点击芯片的形式渲染在聊天输入框下方：

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( llm=OpenAI(model="gpt-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(model="gpt-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"）创建处理函数，接收请求并转发给 Agent（route.ts）。此外，该路由还提供GET健康检查，返回 Agent 的AGENT_URL与可达性状态（route.ts）。

Python 端（agent_server.py）

后端是独立的 FastAPI 进程（默认端口 8000）。agent_server.py 中，agent_router作为兜底路由在最后挂载到根路径/（catch-all）：

app.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 用四组用例将其固化：

1. 页面加载：断言输入框（placeholderType a message）与三个建议芯片（"Write a sonnet"、"Tell me a joke"、"Is 17 prime?"）可见。
2. 手动输入：填入 "Say hello in one word." 回车后，等待[data-testid="copilot-assistant-message"]出现（30 秒超时）。
3. 点击建议：点击 "Tell me a joke" 芯片后同样等待助手消息出现。
4. 多轮上下文：先告知 "My name is Alice."，待建议重新出现后追问名字，断言第二条回复中包含 "Alice"——验证流式结束后会话上下文被保留。

本地运行方式

该演示属于 showcase/integrations/llamaindex 展示项目的一部分。项目的dev脚本用concurrently同时启动 Next.js（next dev --turbopack）与 Python Agent 服务（uvicorn agent_server:app --port 8000 --reload），见 package.json：

cd showcase/integrations/llamaindex npm run dev

启动后访问/demos/agentic-chat即可体验。运行前需要准备：

• 后端依赖（requirements.txt，含llama-index与llama-index-protocols-ag-ui）；
• OPENAI_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