CopilotKit实战测评：Runtime+React Core搭建AI助手

CopilotKit 到底解决什么问题？

给应用接入 AI Copilot，开发者首先想到往往是加一个聊天框。但 CopilotKit 解决的不是这个——它真正回答的是“如何把 AI 深度且实用地嵌入产品”。

如果你的需求包含以下几点：

• AI 能精准感知当前页面上下文
• AI 能直接调用你的业务接口与数据
• AI 能与前端状态（React state）联动
• AI 能根据不同业务场景切换专属 Agent

那么 CopilotKit 确实比从零搭建省时省力。

两个核心模块拆解

要掌握 CopilotKit，先聚焦两个核心：

1. runtime
2. react-core

职责划分非常明确：

• runtime 是后端运行时，负责接收请求、注册 Agent、执行 Tool、连接 LLM 或工作流
• react-core 是前端接入层，负责将 React 应用连接到 runtime，并将页面上下文和操作暴露给 Copilot

一句话总结：

• runtime 决定 AI 在后端的运行机制
• react-core 决定 AI 在前端的信息可见性与操作能力

runtime 是什么？

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

它的核心职责包括：

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

示例：最小化的 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 实例，然后将其暴露为前端可调用的 API 接口。

runtime 支持注册多个 Agent

这是 CopilotKit 非常实用的设计。runtime 并非只能挂载一个 Agent，它更像一个 Agent 注册中心。如果你的系统存在多种业务场景，可以分别定义对应的 Agent：

• salesAgent
• reportAgent
• docAgent
• workflowAgent

示例：在一个 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

示例：为 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

此时，Agent 不再只是“回答”，而是真正“执行”。

MCP 是什么？

如果说 Tool 是你自定义的操作，那么 MCP 更像一套标准化的外部能力接入协议。适合使用 MCP 的场景包括：

• 集成知识库
• 接入搜索服务
• 连接代码仓库
• 调用浏览器工具
• 对接一整套企业内部服务

示例：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

示例：在根节点接入 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 后，前端可以按页面需求进行切换。

示例：CRM 页面使用 salesAgent

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

示例：报表页面使用 reportAgent

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

这种写法的价值在于：同一套系统内，不同页面可以赋予 AI 不同的角色和知识。

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

仅接入聊天框还不够，真正有意义的是让 AI 理解当前页面。例如在客户详情页，你希望 AI 知道：

• 当前客户的身份
• 当前客户最近的订单动态
• 当前销售正在查看哪个 Tab

示例：暴露当前客户的上下文

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 也能暴露前端操作

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

示例：让 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 不只是回复“你可以点击订单页”，而是实际调用操作去更新页面状态。

总结

表面上看，CopilotKit 是在帮你接入一个 AI 助手；但更深层的价值，在于它清晰梳理了应用内 AI 的架构层次。

• 通过 runtime 统一接收请求并管理多个 Agent
• 通过 agent 拆分不同的业务角色
• 通过 Tool 和 MCP 为 Agent 赋予执行能力
• 通过 react-core 将前端上下文和操作暴露给 AI

这种设计带来的结果是，AI 不再是一个悬浮的聊天框，而成为系统内真正可用的一层能力。如果你的目标是构建一个能理解页面、调用业务、按场景切换角色的应用内 Copilot，那么 CopilotKit 的整体架构值得认真参考。