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. Runtime（@copilotkit/runtime，v2 符号位于 @copilotkit/runtime/v2 下）——服务端。托管 Agent、处理 SSE/Intelligence 传输、中间件、转录。
2. Core（@copilotkit/core）——共享状态管理、工具注册表、建议引擎。应用不直接导入。
3. React（@copilotkit/react-core，v2 符号位于 @copilotkit/react-core/v2 下）——Provider、聊天组件、hooks。重新导出 @ag-ui/client 中的所有内容，因此应用只需一次导入。

工作流

1. 设置 Runtime（服务端）

创建一个 CopilotRuntime（或显式的 CopilotSseRuntime / CopilotIntelligenceRuntime），并通过 createCopilotHonoHandler（Hono）或 createCopilotExpressHandler（Express）暴露它。

import {
  CopilotRuntime,
  createCopilotHonoHandler,
} from "@copilotkit/runtime/v2";
import { LangGraphAgent } from "@copilotkit/runtime/langgraph";
import { handle } from "hono/vercel";

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

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

// Multi-route (the default): export every method the runtime serves.
// useThreads needs them all — rename via PATCH, delete via DELETE; archive
// uses the already-exported POST.
export const GET = handle(app);
export const POST = handle(app);
export const PATCH = handle(app);
export const DELETE = handle(app);

2. 用 Provider 包裹你的应用（客户端）

使用 CopilotKit provider（来自 @copilotkit/react-core/v2）。它是 v1 和 v2 之间的兼容桥梁，并且是旧版 CopilotKitProvider 的严格超集——所有 CopilotKitProvider 的 props 都可在它上面使用。

import { CopilotKit } from "@copilotkit/react-core/v2";

function App() {
  return (
    // No useSingleEndpoint: the provider negotiates the transport, so this
    // works against a multi-route handler (the default) and a single-route one
    // alike. Pass the prop only to pin one mode deliberately.
    <CopilotKit runtimeUrl="/api/copilotkit">
      <YourApp />
    </CopilotKit>
  );
}

3. 添加聊天 UI

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

import { CopilotChat } from "@copilotkit/react-core/v2";

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

4. 注册前端工具

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

import { useFrontendTool } from "@copilotkit/react-core/v2";
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-core/v2";

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

6. 处理 Agent 中断

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

import { useInterrupt } from "@copilotkit/react-core/v2";

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-core/v2";
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 事件，支持渲染 + 可选的处理函数/enabled 谓词
useHumanInTheLoop	注册一个工具，暂停执行直到用户通过渲染的 UI 作出响应
useRenderTool	为工具调用注册渲染器（按名称或通配符 "*"）
useDefaultRenderTool	使用内置可展开卡片 UI 注册通配符 "*" 渲染器
useRenderToolCall	内部 Hook，返回一个函数，用于为给定工具调用解析正确的渲染器
useRenderActivityMessage	内部 Hook，用于按类型渲染活动消息
useRenderCustomMessages	内部 Hook，用于渲染自定义消息装饰器
useSuggestions	读取当前建议列表并控制重新加载/清除
useConfigureSuggestions	注册静态或动态（大模型生成）的建议配置
useThreads	列出、重命名、归档和删除 CopilotKit Intelligence 线程

快速参考：组件

组件	用途
CopilotKit	根提供者（来自 @copilotkit/react-core/v2）——配置运行时 URL、请求头、Agent、错误处理器
CopilotChat	连接到 Agent 的完整聊天界面（内联布局）
CopilotPopup	带切换按钮的浮动弹窗聊天
CopilotSidebar	带切换按钮的可折叠侧边栏聊天
CopilotChatView	无头聊天视图，为消息视图、输入、滚动、建议提供插槽
CopilotChatInput	带发送/停止/转录控制的聊天输入文本域
CopilotChatMessageView	渲染消息列表
CopilotChatSuggestionView	渲染建议胶囊

快速参考：运行时

所有 v2 运行时符号均从 @copilotkit/runtime/v2 导入（createCopilotExpressHandler 从 @copilotkit/runtime/v2/express 导入）。

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