copilotkit-develop

CopilotKit v2 开发技能

实时文档（MCP）

此插件包含一个 MCP 服务（copilotkit-docs），提供 search-docs 和 search-code 工具，用于查询 CopilotKit 的实时文档和源代码。

• Claude Code： 插件会通过 .mcp.json 自动完成配置，无需进行设置。
• Codex： 需要手动配置。请参阅 copilotkit-debug 技能中的设置说明。

架构概览

CopilotKit v2 基于 AG-UI 协议（@ag-ui/client / @ag-ui/core）构建。技术栈分为三层：

1. 运行时（@copilotkit/runtime）——服务端。托管 Agent，处理 SSE/Intelligence 传输、中间件和转录。
2. 核心（@copilotkit/core）——共享状态管理、工具注册表和建议引擎。应用不会直接导入它。
3. React（@copilotkit/react）——Provider、聊天组件和 hooks。重新导出 @ag-ui/client 中的所有内容，因此应用只需一次导入。

工作流

1. 设置运行时（服务端）

创建 CopilotRuntime（或显式创建 CopilotSseRuntime / CopilotIntelligenceRuntime），并通过 createCopilotEndpoint（Hono）或 createCopilotEndpointExpress（Express）将其公开。

import { CopilotRuntime, createCopilotEndpoint } from "@copilotkit/runtime";
import { LangGraphAgent } from "@ag-ui/langgraph";

const runtime = new CopilotRuntime({
  agents: {
    myAgent: new LangGraphAgent({ /* ... */ }),
  },
});

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

2. 使用 Provider 包装应用（客户端）

import { CopilotKitProvider } from "@copilotkit/react";

function App() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <YourApp />
    </CopilotKitProvider>
  );
}

3. 添加聊天界面

使用 <CopilotChat>、<CopilotPopup> 或 <CopilotSidebar>：

import { CopilotChat } from "@copilotkit/react";

function ChatPage() {
  return <CopilotChat agentId="myAgent" />;
}

4. 注册前端工具

让 Agent 在浏览器中调用函数：

import { useFrontendTool } from "@copilotkit/react";
import { z } from "zod";

useFrontendTool({
  name: "highlightCell",
  description: "Highlight a spreadsheet cell",
  parameters: z.object({ row: z.number(), col: z.number() }),
  handler: async ({ row, col }) => {
    highlightCell(row, col);
    return "done";
  },
});

5. 共享应用上下文

向 Agent 提供运行时数据：

import { useAgentContext } from "@copilotkit/react";

useAgentContext({
  description: "The user's current shopping cart",
  value: cart, // any JSON-serializable value
});

6. 处理 Agent 中断

当 Agent 暂停以等待人工输入时：

import { useInterrupt } from "@copilotkit/react";

useInterrupt({
  render: ({ event, resolve }) => (
    <div>
      <p>{event.value.question}</p>
      <button onClick={() => resolve({ approved: true })}>Approve</button>
    </div>
  ),
});

7. 在聊天中渲染工具调用

在工具执行时显示自定义 UI：

import { useRenderTool } from "@copilotkit/react";
import { z } from "zod";

useRenderTool({
  name: "searchDocs",
  parameters: z.object({ query: z.string() }),
  render: ({ status, parameters, result }) => {
    if (status === "executing") return <Spinner>Searching {parameters.query}...</Spinner>;
    if (status === "complete") return <Results data={result} />;
    return <div>Preparing...</div>;
  },
}, []);

快速参考：Hooks

Hook	用途
useFrontendTool	注册 Agent 可在浏览器中调用的工具
useComponent	将 React 组件注册为在聊天中渲染的工具（useFrontendTool 的便捷封装）
useAgentContext	与 Agent 共享可序列化为 JSON 的应用状态
useAgent	获取指定 Agent ID 的 AbstractAgent 实例；订阅消息、状态和运行状态的变化
useInterrupt	处理 Agent 发出的 on_interrupt 事件，支持渲染以及可选的处理器/筛选器
useHumanInTheLoop	注册一个工具，该工具会暂停执行，直到用户通过渲染的 UI 作出响应
useRenderTool	注册工具调用的渲染器（按名称或使用通配符 "*"）
useDefaultRenderTool	使用内置的可展开卡片 UI 注册通配符 "*" 渲染器
useRenderToolCall	内部 Hook，返回一个函数，用于解析给定工具调用对应的渲染器
useRenderActivityMessage	用于按类型渲染活动消息的内部 Hook
useRenderCustomMessages	用于渲染自定义消息装饰器的内部 Hook
useSuggestions	读取当前建议列表，并控制重新加载/清除
useConfigureSuggestions	注册静态或动态（由大模型生成）的建议配置
useThreads	列出、重命名、归档和删除 Intelligence 平台会话

快速参考：组件

组件	用途
CopilotKitProvider	根 Provider——配置运行时 URL、请求头、Agent 和错误处理器
CopilotChat	连接到 Agent 的完整聊天界面（内嵌布局）
CopilotPopup	带切换按钮的浮动弹窗聊天界面
CopilotSidebar	带切换按钮的可折叠侧边栏聊天界面
CopilotChatView	无头聊天视图，提供消息视图、输入框、滚动和建议的插槽
CopilotChatInput	聊天输入文本区域，带发送/停止/转录控件
CopilotChatMessageView	渲染消息列表
CopilotChatSuggestionView	渲染建议标签

快速参考：运行时

导出项	用途
CopilotRuntime	自动检测运行时（委托给 SSE 或 Intelligence）
CopilotSseRuntime	显式 SSE 模式运行时
CopilotIntelligenceRuntime	支持持久化线程的 Intelligence 模式运行时
createCopilotEndpoint	创建包含所有 CopilotKit 路由的 Hono 应用
createCopilotEndpointExpress	创建包含所有 CopilotKit 路由的 Express 路由器
CopilotKitIntelligence	Intelligence 平台客户端配置