基于 Claude Agent SDK 的最简 Agentic ChatCopilotKit 纯聊天界面从零搭建指南【免费下载链接】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 仓库中claude-sdk-typescript集成示例里的Agentic Chat演示展开它是 CopilotKit 提供的最简单对话形态一个纯文本 Agent 聊天界面前端由CopilotKitCopilotChat组合而成后端由 Claude Agent SDKTypeScript驱动的独立进程承载两者通过 AG-UI 协议以 SSE 流式通信。读完本文你将掌握如何用runtimeUrl与agent属性把页面挂接到运行时、如何用CopilotChat渲染完整聊天 UI、如何用useConfigureSuggestions注入快捷建议并能从源码层面理解 token 级流式响应在前后端之间的完整链路。演示概览CopilotKit 的最小聊天面在showcase/integrations/claude-sdk-typescript这一集成示例中Agentic Chat 演示 刻意保持最小化——它不涉及工具调用、生成式 UI、人机协作或多模态只解决一个问题如何在熟悉的消息界面里与一个由 Claude 驱动的 Agent 进行自然对话。演示的三大核心体验自然对话Natural Conversation在标准聊天界面中与 Copilot 对话输入框、消息列表一应俱全流式响应Streaming ResponsesAssistant 消息通过 AG-UI 协议逐 token流式到达前端用户可以看到回复逐字生成无需等待完整输出建议芯片Suggestion Chips输入框下方渲染了一个可点击的起始建议一键发起对话。如何与演示交互进入演示页面后有两种启动对话的方式直接点击建议芯片Suggestion Chip立即发送对应消息在输入框内键入自己的提示词。README 中给出了三个可以直接尝试的示例提示词Write a short sonnet about AI写一首关于 AI 的短十四行诗Explain the difference between an LLM and an agent解释 LLM 与 Agent 的区别Give me three ideas for a weekend project给出三个周末项目的点子这些提示词覆盖了创意写作、概念解释与头脑风暴三类典型对话场景配合流式输出可以直观感受 Claude 逐字生成的效果。前端接线Provider 与 Chat 组件Agentic Chat 的整个前端只有两个文件逻辑高度集中。首先是页面入口 page.tsx其核心代码如下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 /; }Provider 两个关键属性runtimeUrl与agentCopilotKit组件负责把整个页面“接线”wire到运行时这里出现两个决定性的属性runtimeUrl/api/copilotkit指向 Next.js 中代理到 Agent 的 API 路由。所有 AG-UI 请求run、state等都会发送到这个地址再由运行时转发给真正的 Agent 后端agentagentic_chat从运行时注册的多个 Agent 中选中名为agentic_chat的 Claude 后端。从源码可以确认API 路由 route.ts 里同时注册了agentic_chat与agentic-chat两个名字后者用于兼容旧的命名它们都指向同一个默认透传 Agent。值得注意的是页面中CopilotChat还额外传了agentIdagentic_chat而 Provider 上的agent属性用于运行时路由选择。从 useConfigureSuggestions 的源码 可以看到Hook 内部解析目标 Agent 时会优先使用CopilotChatConfiguration提供的agentId缺省时才回退到DEFAULT_AGENT_ID——这正是这个演示中两者保持一致的原因。Chat 表面CopilotChatCopilotChat是一个开箱即用的完整聊天组件一行代码即可渲染出包含输入框、消息列表、流式渲染的整套聊天 UIreturn CopilotChat agentIdagentic_chat /;它属于copilotkit/react-core/v2的预构建组件隐藏了连接运行时、维护消息状态、处理流式增量、渲染发送中指示器typing indicator等全部细节。对于“只要一个能说话的聊天框”的场景它是最直接的答案需要完全自控界面时同一包内还有 headless 方案参见同目录下的headless-simple、headless-complete等演示。建议芯片useConfigureSuggestions的静态配置建议芯片由 suggestions.ts 中的自定义 Hook 提供use 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, }); }配置项语义与底层实现useConfigureSuggestions是 CopilotKit v2 建议系统的前端入口其实现位于 use-configure-suggestions.tsx。结合源码可以归纳出这里用到的两个关键配置suggestions一个Suggestion数组每条包含title芯片上显示的快捷标题与message点击后实际发送给 Agent 的完整消息。Hook 内部会对静态建议做归一化处理normalizeStaticSuggestions为每条建议补上默认的isLoading: false字段available控制建议的可用时机。此演示设为always即始终展示。源码显示当available disabled时Hook 会直接丢弃配置、不向运行时注册任何建议。配置的内部流转可以概括为Hook 把配置序列化后调用copilotkit.addSuggestionsConfig(...)注册到全局 CopilotKit 上下文随即触发copilotkit.reloadSuggestions(agentId)刷新对应 Agent 的建议集并在组件卸载时通过removeSuggestionsConfig清理。由于该演示的目标 Agent 是聊天实际使用的agentic_chat静态建议会稳定地出现在聊天输入框下方成为可点击的快捷入口。useConfigureSuggestions还支持动态建议配置中带instructions指令时走DynamicSuggestionsConfig分支需要真实 Agent 存在才会生成这是 Agentic Chat 之外更高阶的用法本演示未启用。后端链路API 路由 → AG-UI 流式传输Next.js 运行时路由前端把请求发往/api/copilotkit对应的 route.ts 是整条链路的枢纽。它做了三件事创建运行时通过createCopilotRuntimeHandler与CopilotRuntime构建 AG-UI 运行时basePath设为/api/copilotkit模式为single-route单一路由承载所有 AG-UI 端点注册 Agent 映射把agentic_chat等数十个 Agent 名逐一映射到后端 Agent 实例。Agentic Chat 对应的是默认透传实例见下文的createAgent()健康检查GET请求返回运行状态、AGENT_URL、Agent 可达性以及ANTHROPIC_API_KEY是否已设置等诊断信息。其核心注册逻辑为const AGENT_URL process.env.AGENT_URL || http://localhost:8000; function createAgent() { return createClaudeHttpAgent(${AGENT_URL}/); }即 Claude 后端作为独立的 TypeScript 进程运行在 8000 端口CopilotKit 运行时通过 AG-UI 协议把请求代理给它。这里关键的一点是Agentic Chat 走的是默认透传pass-through路径——claude-http-agent.ts 基于ag-ui/client的HttpAgent把请求原样转发到http://localhost:8000/Agent 本身不持有专用工具同文件中还包含 aimock 上下文支持当ANTHROPIC_BASE_URL或AIMOCK_URL包含aimock时附加x-aimock-context请求头用于本地录制/回放测试。Express Agent 服务器AG-UI 事件编码与流式输出后端进程由 agent_server.ts 实现它基于 Express 启动默认监听0.0.0.0:8000端口由AGENT_PORT或默认值8000决定。Agentic Chat 命中的是根路径处理器// Default pass-through agent. app.post(/, makeAgentHandler());makeAgentHandler()是整个示例中所有“无专属后端”演示共用的工厂函数它完整展示了 AG-UI 流式协议的服务端实现SSE 响应头设置Content-Type: text/event-stream、Cache-Control: no-cache与Connection: keep-alive事件编码借助ag-ui/encoder的EventEncoder通过emit()把 AG-UI 事件序列化为 SSE 帧写回响应消息转换buildAnthropicMessages把 AG-UI 的Message[]映射为 Anthropic Messages API 的MessageParam[]含多模态 content parts 与工具调用的双向映射buildTools则把 AG-UI 工具定义转换为 Claude 的input_schema格式默认系统提示词未指定时使用DEFAULT_SYSTEM_PROMPT You are a helpful AI assistant powered by Anthropics Claude.这正是 Agentic Chat 后端的行为模型选择默认模型由CLAUDE_MODEL || ANTHROPIC_MODEL || claude-opus-4-8解析并通过normalizeAnthropicModel做别名归一化若用户消息携带图片/文档附件会自动切换到CLAUDE_VISION_MODEL视觉模型。逐 token 流式协议的事件序列流式响应的“逐 token”效果在源码中可以精确还原。处理 Claudemessages.stream事件流时服务端依次发出以下 AG-UI 事件连接建立后立即发送RUN_STARTED携带runId与threadId二者缺省时由服务端用randomUUID()生成收到首个text_delta时发出TEXT_MESSAGE_STARTmessageId、role: assistant每个text_delta都转化为一条TEXT_MESSAGE_CONTENT携带本次增量文本delta——这就是前端逐字渲染的来源若模型发起工具调用还会发出TOOL_CALL_START/TOOL_CALL_ARGS增量 JSON 参数等事件Agentic Chat 本身不使用工具但协议通道是同一套。从makeAgentHandler的代码可以确认每个文本 content block 都拥有独立的 AG-UI 消息生命周期START→CONTENT→END因此多段文本轮次在协议层面互不干扰。前端CopilotChat消费这些增量事件在消息气泡中实时更新文本。本地运行与依赖在showcase/integrations/claude-sdk-typescript目录下package.json 定义了开发脚本dev: concurrently \next dev --turbopack\ \npx tsx --watch src/agent_server.ts\即一条命令同时启动两个进程Next.js 前端应用与独立运行的 Express Agent 服务器后端通过tsx --watch支持热重载。运行前需确保以下环境变量可用可通过.env.local提供agent_server.ts会优先加载它ANTHROPIC_API_KEY调用 Claude 的凭证缺失时/health与运行时路由会明确标记NOT SETAGENT_URL可选Agent 后端地址默认http://localhost:8000CLAUDE_MODEL/ANTHROPIC_MODEL可选指定模型默认claude-opus-4-8AGENT_PORT/AGENT_HOST可选后端监听端口与地址默认8000/0.0.0.0。依赖方面前端与运行时侧的关键包为copilotkit/react-core、copilotkit/runtime均 1.68.2协议层使用ag-ui/client/ag-ui/core/ag-ui/encoder0.0.57模型调用侧为anthropic-ai/sdk与anthropic-ai/claude-agent-sdk。仓库根目录提供pnpm-workspace.yaml可从仓库根通过pnpm安装依赖后在示例目录内启动。扩展阅读与相关源码Agentic Chat 是理解 CopilotKit 前后端通信模型的最佳起点之后可以沿着以下路径继续深入同套后端的进阶演示showcase/integrations/claude-sdk-typescript/src/app/demos/目录下还有tool-rendering、gen-ui-agent、headless-complete等演示它们复用同一个 Express 后端但走/tool-rendering、/gen-ui-agent等专属端点见 agent_server.ts 中app.post的路由注册对比可理解“透传”与“后端持有工具”两种模式的区别建议系统实现use-configure-suggestions.tsx 及packages/react-core/src/v2/hooks/__tests__/use-configure-suggestions.e2e.test.tsx覆盖了静态/动态建议的完整行为AG-UI 协议消息转换与事件编码分别位于 agent_server.ts 的buildAnthropicMessages与EventEncoder调用处这是协议两侧事实上的参考实现。总的来说Agentic Chat 演示用最少的代码勾勒出了 CopilotKit 的完整骨架前端用CopilotKitCopilotChat挂接运行时后端用 Express AG-UI 编码器逐 token 回推事件中间由runtimeUrl与agent完成路由。掌握这一条链路就掌握了向 CopilotKit 添加任何自定义 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），仅供参考 基于 Claude Agent SDK 的最简 Agentic Chat：CopilotKit 纯聊天界面从零搭建指南
基于 Claude Agent SDK 的最简 Agentic ChatCopilotKit 纯聊天界面从零搭建指南【免费下载链接】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 仓库中claude-sdk-typescript集成示例里的Agentic Chat演示展开它是 CopilotKit 提供的最简单对话形态一个纯文本 Agent 聊天界面前端由CopilotKitCopilotChat组合而成后端由 Claude Agent SDKTypeScript驱动的独立进程承载两者通过 AG-UI 协议以 SSE 流式通信。读完本文你将掌握如何用runtimeUrl与agent属性把页面挂接到运行时、如何用CopilotChat渲染完整聊天 UI、如何用useConfigureSuggestions注入快捷建议并能从源码层面理解 token 级流式响应在前后端之间的完整链路。演示概览CopilotKit 的最小聊天面在showcase/integrations/claude-sdk-typescript这一集成示例中Agentic Chat 演示 刻意保持最小化——它不涉及工具调用、生成式 UI、人机协作或多模态只解决一个问题如何在熟悉的消息界面里与一个由 Claude 驱动的 Agent 进行自然对话。演示的三大核心体验自然对话Natural Conversation在标准聊天界面中与 Copilot 对话输入框、消息列表一应俱全流式响应Streaming ResponsesAssistant 消息通过 AG-UI 协议逐 token流式到达前端用户可以看到回复逐字生成无需等待完整输出建议芯片Suggestion Chips输入框下方渲染了一个可点击的起始建议一键发起对话。如何与演示交互进入演示页面后有两种启动对话的方式直接点击建议芯片Suggestion Chip立即发送对应消息在输入框内键入自己的提示词。README 中给出了三个可以直接尝试的示例提示词Write a short sonnet about AI写一首关于 AI 的短十四行诗Explain the difference between an LLM and an agent解释 LLM 与 Agent 的区别Give me three ideas for a weekend project给出三个周末项目的点子这些提示词覆盖了创意写作、概念解释与头脑风暴三类典型对话场景配合流式输出可以直观感受 Claude 逐字生成的效果。前端接线Provider 与 Chat 组件Agentic Chat 的整个前端只有两个文件逻辑高度集中。首先是页面入口 page.tsx其核心代码如下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 /; }Provider 两个关键属性runtimeUrl与agentCopilotKit组件负责把整个页面“接线”wire到运行时这里出现两个决定性的属性runtimeUrl/api/copilotkit指向 Next.js 中代理到 Agent 的 API 路由。所有 AG-UI 请求run、state等都会发送到这个地址再由运行时转发给真正的 Agent 后端agentagentic_chat从运行时注册的多个 Agent 中选中名为agentic_chat的 Claude 后端。从源码可以确认API 路由 route.ts 里同时注册了agentic_chat与agentic-chat两个名字后者用于兼容旧的命名它们都指向同一个默认透传 Agent。值得注意的是页面中CopilotChat还额外传了agentIdagentic_chat而 Provider 上的agent属性用于运行时路由选择。从 useConfigureSuggestions 的源码 可以看到Hook 内部解析目标 Agent 时会优先使用CopilotChatConfiguration提供的agentId缺省时才回退到DEFAULT_AGENT_ID——这正是这个演示中两者保持一致的原因。Chat 表面CopilotChatCopilotChat是一个开箱即用的完整聊天组件一行代码即可渲染出包含输入框、消息列表、流式渲染的整套聊天 UIreturn CopilotChat agentIdagentic_chat /;它属于copilotkit/react-core/v2的预构建组件隐藏了连接运行时、维护消息状态、处理流式增量、渲染发送中指示器typing indicator等全部细节。对于“只要一个能说话的聊天框”的场景它是最直接的答案需要完全自控界面时同一包内还有 headless 方案参见同目录下的headless-simple、headless-complete等演示。建议芯片useConfigureSuggestions的静态配置建议芯片由 suggestions.ts 中的自定义 Hook 提供use 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, }); }配置项语义与底层实现useConfigureSuggestions是 CopilotKit v2 建议系统的前端入口其实现位于 use-configure-suggestions.tsx。结合源码可以归纳出这里用到的两个关键配置suggestions一个Suggestion数组每条包含title芯片上显示的快捷标题与message点击后实际发送给 Agent 的完整消息。Hook 内部会对静态建议做归一化处理normalizeStaticSuggestions为每条建议补上默认的isLoading: false字段available控制建议的可用时机。此演示设为always即始终展示。源码显示当available disabled时Hook 会直接丢弃配置、不向运行时注册任何建议。配置的内部流转可以概括为Hook 把配置序列化后调用copilotkit.addSuggestionsConfig(...)注册到全局 CopilotKit 上下文随即触发copilotkit.reloadSuggestions(agentId)刷新对应 Agent 的建议集并在组件卸载时通过removeSuggestionsConfig清理。由于该演示的目标 Agent 是聊天实际使用的agentic_chat静态建议会稳定地出现在聊天输入框下方成为可点击的快捷入口。useConfigureSuggestions还支持动态建议配置中带instructions指令时走DynamicSuggestionsConfig分支需要真实 Agent 存在才会生成这是 Agentic Chat 之外更高阶的用法本演示未启用。后端链路API 路由 → AG-UI 流式传输Next.js 运行时路由前端把请求发往/api/copilotkit对应的 route.ts 是整条链路的枢纽。它做了三件事创建运行时通过createCopilotRuntimeHandler与CopilotRuntime构建 AG-UI 运行时basePath设为/api/copilotkit模式为single-route单一路由承载所有 AG-UI 端点注册 Agent 映射把agentic_chat等数十个 Agent 名逐一映射到后端 Agent 实例。Agentic Chat 对应的是默认透传实例见下文的createAgent()健康检查GET请求返回运行状态、AGENT_URL、Agent 可达性以及ANTHROPIC_API_KEY是否已设置等诊断信息。其核心注册逻辑为const AGENT_URL process.env.AGENT_URL || http://localhost:8000; function createAgent() { return createClaudeHttpAgent(${AGENT_URL}/); }即 Claude 后端作为独立的 TypeScript 进程运行在 8000 端口CopilotKit 运行时通过 AG-UI 协议把请求代理给它。这里关键的一点是Agentic Chat 走的是默认透传pass-through路径——claude-http-agent.ts 基于ag-ui/client的HttpAgent把请求原样转发到http://localhost:8000/Agent 本身不持有专用工具同文件中还包含 aimock 上下文支持当ANTHROPIC_BASE_URL或AIMOCK_URL包含aimock时附加x-aimock-context请求头用于本地录制/回放测试。Express Agent 服务器AG-UI 事件编码与流式输出后端进程由 agent_server.ts 实现它基于 Express 启动默认监听0.0.0.0:8000端口由AGENT_PORT或默认值8000决定。Agentic Chat 命中的是根路径处理器// Default pass-through agent. app.post(/, makeAgentHandler());makeAgentHandler()是整个示例中所有“无专属后端”演示共用的工厂函数它完整展示了 AG-UI 流式协议的服务端实现SSE 响应头设置Content-Type: text/event-stream、Cache-Control: no-cache与Connection: keep-alive事件编码借助ag-ui/encoder的EventEncoder通过emit()把 AG-UI 事件序列化为 SSE 帧写回响应消息转换buildAnthropicMessages把 AG-UI 的Message[]映射为 Anthropic Messages API 的MessageParam[]含多模态 content parts 与工具调用的双向映射buildTools则把 AG-UI 工具定义转换为 Claude 的input_schema格式默认系统提示词未指定时使用DEFAULT_SYSTEM_PROMPT You are a helpful AI assistant powered by Anthropics Claude.这正是 Agentic Chat 后端的行为模型选择默认模型由CLAUDE_MODEL || ANTHROPIC_MODEL || claude-opus-4-8解析并通过normalizeAnthropicModel做别名归一化若用户消息携带图片/文档附件会自动切换到CLAUDE_VISION_MODEL视觉模型。逐 token 流式协议的事件序列流式响应的“逐 token”效果在源码中可以精确还原。处理 Claudemessages.stream事件流时服务端依次发出以下 AG-UI 事件连接建立后立即发送RUN_STARTED携带runId与threadId二者缺省时由服务端用randomUUID()生成收到首个text_delta时发出TEXT_MESSAGE_STARTmessageId、role: assistant每个text_delta都转化为一条TEXT_MESSAGE_CONTENT携带本次增量文本delta——这就是前端逐字渲染的来源若模型发起工具调用还会发出TOOL_CALL_START/TOOL_CALL_ARGS增量 JSON 参数等事件Agentic Chat 本身不使用工具但协议通道是同一套。从makeAgentHandler的代码可以确认每个文本 content block 都拥有独立的 AG-UI 消息生命周期START→CONTENT→END因此多段文本轮次在协议层面互不干扰。前端CopilotChat消费这些增量事件在消息气泡中实时更新文本。本地运行与依赖在showcase/integrations/claude-sdk-typescript目录下package.json 定义了开发脚本dev: concurrently \next dev --turbopack\ \npx tsx --watch src/agent_server.ts\即一条命令同时启动两个进程Next.js 前端应用与独立运行的 Express Agent 服务器后端通过tsx --watch支持热重载。运行前需确保以下环境变量可用可通过.env.local提供agent_server.ts会优先加载它ANTHROPIC_API_KEY调用 Claude 的凭证缺失时/health与运行时路由会明确标记NOT SETAGENT_URL可选Agent 后端地址默认http://localhost:8000CLAUDE_MODEL/ANTHROPIC_MODEL可选指定模型默认claude-opus-4-8AGENT_PORT/AGENT_HOST可选后端监听端口与地址默认8000/0.0.0.0。依赖方面前端与运行时侧的关键包为copilotkit/react-core、copilotkit/runtime均 1.68.2协议层使用ag-ui/client/ag-ui/core/ag-ui/encoder0.0.57模型调用侧为anthropic-ai/sdk与anthropic-ai/claude-agent-sdk。仓库根目录提供pnpm-workspace.yaml可从仓库根通过pnpm安装依赖后在示例目录内启动。扩展阅读与相关源码Agentic Chat 是理解 CopilotKit 前后端通信模型的最佳起点之后可以沿着以下路径继续深入同套后端的进阶演示showcase/integrations/claude-sdk-typescript/src/app/demos/目录下还有tool-rendering、gen-ui-agent、headless-complete等演示它们复用同一个 Express 后端但走/tool-rendering、/gen-ui-agent等专属端点见 agent_server.ts 中app.post的路由注册对比可理解“透传”与“后端持有工具”两种模式的区别建议系统实现use-configure-suggestions.tsx 及packages/react-core/src/v2/hooks/__tests__/use-configure-suggestions.e2e.test.tsx覆盖了静态/动态建议的完整行为AG-UI 协议消息转换与事件编码分别位于 agent_server.ts 的buildAnthropicMessages与EventEncoder调用处这是协议两侧事实上的参考实现。总的来说Agentic Chat 演示用最少的代码勾勒出了 CopilotKit 的完整骨架前端用CopilotKitCopilotChat挂接运行时后端用 Express AG-UI 编码器逐 token 回推事件中间由runtimeUrl与agent完成路由。掌握这一条链路就掌握了向 CopilotKit 添加任何自定义 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），仅供参考