CopilotKit 入门：用 Runtime 和 React Core 搭建真正可用的 AI Copilot

CopilotKit 是什么？

CopilotKit 是一个给应用接入 AI Copilot 的框架。它解决的不是“做一个聊天框”，而是“怎么把 AI 真正接进你的产品”。

如果你要的能力包括这些：

• AI 能感知当前页面上下文
• AI 能调用你的业务能力
• AI 能和前端状态联动
• AI 能按不同场景切换不同 agent

那 CopilotKit 会比从零拼装更省事。

两个核心模块

CopilotKit 最值得先理解的是两个模块：

1. runtime
2. react-core

分工很清楚：

• runtime：后端运行时，负责接请求、注册 agent、执行 tool、连接模型或工作流
• react-core：前端接入层，负责把 React 应用接到 runtime，并把页面上下文和 action 暴露给 Copilot

可以简单理解为：

• runtime 决定 AI 在后端怎么跑
• react-core 决定 AI 在前端能看到什么、能做什么

runtime 是什么？

@copilotkit/runtime 是服务端入口。前端发起一次 Copilot 请求，最终都要落到 runtime。

它通常做这几件事：

• 暴露一个 API 路由
• 注册一个或多个 agent
• 把请求转发给模型、Agent 或工作流
• 执行 tool / MCP 能力
• 把结果返回给前端

Example: 最小 runtime

下面是一个最小示意：

import { CopilotRuntime } from "@copilotkit/runtime";
import { copilotRuntimeHandler } from "@copilotkit/runtime/nextjs";

const runtime = new CopilotRuntime({
  agents: {
    default: {
      // 这里接你的 agent
    },
  },
});

export const { GET, POST } = copilotRuntimeHandler(runtime);

这段代码的重点只有一句话：先创建 runtime，再把它暴露成前端可调用的接口。

runtime 里可以定义多个 agent

这是 CopilotKit 很实用的一点。runtime 不是只能挂一个 agent，它更像一个 agent 注册中心。

如果你的系统里有多个场景，就可以定义多个 agent：

• salesAgent
• reportAgent
• docAgent
• workflowAgent

Example: 一个 runtime 挂多个 agent

import { CopilotRuntime } from "@copilotkit/runtime";
import { copilotRuntimeHandler } from "@copilotkit/runtime/nextjs";

const runtime = new CopilotRuntime({
  agents: {
    salesAgent: {
      // 处理 CRM、客户跟进、销售建议
    },
    reportAgent: {
      // 处理报表分析、数据总结
    },
    docAgent: {
      // 处理知识库检索、文档问答
    },
    workflowAgent: {
      // 处理审批、任务执行、流程操作
    },
  },
});

export const { GET, POST } = copilotRuntimeHandler(runtime);

这样做的好处很直接：

• 每个 agent 的职责更清楚
• 提示词、权限、工具集可以分开管理
• 前端可以在不同页面选择不同 agent

比如：

• CRM 页面用 salesAgent
• 数据看板页面用 reportAgent
• 帮助中心用 docAgent
• 审批流页面用 workflowAgent

如果你在一个系统里定义了 10 个 agent，那么完全可以在 10 个不同入口分别用最合适的 agent，而不是让所有页面都共用一个“万能助手”。

Agent 里可以定义 Tool、MCP

定义 agent 之后，下一步就是定义它的能力。

一个 agent 通常不只是名字不同，它背后还会挂这些东西：

• Prompt / Instructions
• Tool
• MCP
• 可访问的数据源

可以这样理解：

• Agent：负责推理和决策
• Tool：负责执行具体动作
• MCP：负责把外部系统能力标准化接进来

Tool 是什么？

Tool 就是 agent 能调用的动作。

例如一个销售 agent 可以有这些 tool：

• searchCustomers
• getCustomerActivity
• createFollowupTask
• sendFollowupEmail

Example: 给 agent 挂业务 tool

const runtime = new CopilotRuntime({
  agents: {
    salesAgent: {
      // instructions: "你是一个销售助手",
      tools: {
        searchCustomers: async ({ keyword }) => {
          return await crmApi.searchCustomers(keyword);
        },
        getCustomerActivity: async ({ customerId }) => {
          return await crmApi.getCustomerActivity(customerId);
        },
        createFollowupTask: async ({ customerId, content }) => {
          return await crmApi.createTask({ customerId, content });
        },
      },
    },
  },
});

用户说一句：

agent 就可以：

1. 调 getCustomerActivity
2. 总结记录
3. 调 createFollowupTask

这时候它就不只是“会回答”，而是“能执行”。

MCP 是什么？

如果 Tool 更像你自己定义的动作，那 MCP 更像一套标准化的外部能力接入方式。

适合 MCP 的场景通常是：

• 接知识库
• 接搜索服务
• 接代码仓库
• 接浏览器工具
• 接一整套企业内部服务

Example: Agent 同时拥有 Tool 和 MCP

const runtime = new CopilotRuntime({
  agents: {
    docAgent: {
      // instructions: "你是一个文档助手",
      tools: {
        getInternalDoc: async ({ id }) => {
          return await docsApi.getById(id);
        },
      },
      mcpServers: {
        knowledgeBase: {
          // 这里接 MCP server
        },
      },
    },
  },
});

一般可以这样取舍：

• 明确的内部业务动作，用 Tool
• 一整类外部能力接入，用 MCP

react-core 是什么？

@copilotkit/react-core 是 React 侧的接入层。写新代码时，我更建议直接用 V2 接口，也就是从 @copilotkit/react-core/v2 导入。

它主要做三件事：

• 提供 CopilotKit 上下文
• 配置 runtimeUrl
• 让页面上下文、状态、action 可以暴露给 Copilot

Example: 在根节点接入 CopilotKit

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

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit">
      {children}
    </CopilotKit>
  );
}

做完这一步，前端和后端就接通了。

前端怎么选择不同 agent？

当后端 runtime 注册了多个 agent 之后，前端就可以按页面切换。

Example: CRM 页面使用 salesAgent

export default function CustomerPage() {
  return (
    <CopilotSidebar
      defaultAgent="salesAgent"
      labels={{
        title: "Sales Copilot",
        initial: "可以帮你总结客户状态、生成跟进建议",
      }}
    />
  );
}

Example: 报表页面使用 reportAgent

export default function DashboardPage() {
  return (
    <CopilotSidebar
      defaultAgent="reportAgent"
      labels={{
        title: "Report Copilot",
        initial: "可以帮你分析指标变化、总结异常波动",
      }}
    />
  );
}

这类写法的核心价值在于：同一个系统里，不同页面可以有不同的 AI 角色。

react-core 的关键价值：把页面上下文交给 AI

只把聊天框接上去还不够，真正有价值的是让 AI 理解当前页面。

比如在客户详情页，你可能希望 AI 知道：

• 当前客户是谁
• 当前客户最近的订单情况
• 当前销售正在查看哪个 tab

Example: 暴露当前客户上下文

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

export default function CustomerDetailPage() {
  const customer = {
    id: "c_123",
    name: "Acme Corp",
    stage: "negotiation",
    lastOrderAmount: 24000,
  };

  useAgentContext({
    description: "Current customer detail",
    value: customer,
  });

  return <CustomerDetail customer={customer} />;
}

这样用户问：

AI 就不是在“盲答”，而是在读当前页面上下文之后再回答。

react-core 也可以暴露前端 action

除了读上下文，Copilot 还可以触发前端动作。

Example: 让 AI 帮用户切换 Tab

import { useState } from "react";
import { useFrontendTool } from "@copilotkit/react-core/v2";
import { z } from "zod";

export default function CustomerTabs() {
  const [activeTab, setActiveTab] = useState("overview");

  useFrontendTool({
    name: "switchCustomerTab",
    description: "Switch customer detail tab",
    parameters: z.object({
      tab: z.string().describe("Target tab name"),
    }),
    handler: async ({ tab }) => {
      setActiveTab(tab);
    },
  });

  return <Tabs value={activeTab} onValueChange={setActiveTab} />;
}

这样用户说：

Copilot 不只是回复“你可以点击订单页”，而是真的可以调用 action 去切换页面状态。

总结

如果只看表面，CopilotKit 像是在帮你接一个 AI 助手；但真正有价值的地方，是它把应用内 AI 的结构拆清楚了。

• 用 runtime 统一承接请求和组织多个 agent
• 用 agent 拆分不同业务角色
• 用 Tool 和 MCP 给 agent 接能力
• 用 react-core 把前端上下文和 action 暴露给 AI

这样做的好处是，AI 不再只是一个悬浮聊天框，而是系统里真正可用的一层能力。

如果你的目标是做一个能理解页面、能调用业务、能按场景切换角色的应用内 Copilot，那 CopilotKit 的整体设计是很值得参考的。