CopilotKit快速入门实战：用运行时与React核心构建完整实用AI Copilot

CopilotKit 是什么？

提起为应用接入 AI Copilot，许多人第一反应是“加个聊天框就行”。但 CopilotKit 真正要解决的问题远不止于此——它回答的是“如何将 AI 深度融入你的产品体系”。

如果你期望具备以下能力：

• AI 能够感知当前页面的上下文信息
• AI 能够调用你的业务逻辑与功能
• AI 能够与前端状态实现联动
• AI 能够根据场景灵活切换不同的 agent

那么，CopilotKit 显然比从零开始拼装要高效得多。

两个核心模块

要深入理解 CopilotKit，首先需要掌握它的两大核心模块：

1. runtime
2. react-core

两者的分工非常明确：

• runtime 是后端运行环境，负责接收请求、注册 agent、执行工具调用、连接模型或工作流
• react-core 是前端接入层，负责将 React 应用与 runtime 对接，并将页面上下文和操作暴露给 Copilot

简而言之：

• runtime 决定了 AI 在后端的运行方式
• react-core 决定了 AI 在前端能看到什么、能做什么

runtime 是什么？

@copilotkit/runtime 是服务端入口。前端发起的每一次 Copilot 请求，最终都会由 runtime 来处理。

它通常承担以下职责：

• 暴露一个 API 路由
• 注册一个或多个 agent
• 将请求转发给模型、Agent 或工作流
• 执行工具调用或 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 可以包含以下工具：

• 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 });
        },
      },
    },
  },
});

用户只需说一句：“帮我查一下 Acme Corp 最近的动态，然后创建一个跟进任务”。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
• 让页面上下文、状态和操作可以暴露给 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 将前端上下文和操作暴露给 AI

这样做的好处是，AI 不再只是一个悬浮的聊天框，而是成为系统中真正可用的一层能力。如果你的目标是打造一个能理解页面、能调用业务、能按场景切换角色的应用内 Copilot，那么 CopilotKit 的整体设计非常值得参考。