最近你可能听过一个新的AG-UI（Agent-User InteractionProtocol）协议：定义了前端UI和后端Agent之间的集成标准。不过与MCP/A2A协议不同的是，AG-UI是从实际产品中提炼出来的标准。这个产品就是CopilotKit：一个强大的、用来集成前端UI与后端Agent的开源神器，也是AG-UI协议的参考实现。

本篇将结合实例，为你深入展示 CopilotKit 的核心能力。你不仅能掌握这一实用新工具，更能真正理解 AG-UI 协议的落地应用，摆脱停留在表面的概念认知。

• CopilotKit与AG-UI初探
• 构建一个CopilotKit的演示Demo
• CopilotKit能力之：前后端State共享
• CopilotKit能力之：调用前端“工具”
• CopilotKit能力之：基于Agent的生成式UI
• CopilotKit能力之：HITL（人类参与流程）
• 其他与总结

我们分成两篇一步步介绍（源代码见文末）。

01 CopilotKit与AG-UI初探

【挑战在哪里】

MCP简化了Agent与工具间的集成；A2A则专注于Agent与Agent之间的互操作。但在实际应用中，还有一类集成：Agent与前端UI间的集成。这里的集成并非简单的通过FastAPI来调用Agent可以解决。比如：

一个财务分析助手，不仅需要在后台调用大模型和数据库，还需要在前端实时渲染逐步生成的分析报告、动态更新图表、插入交互式的问答面板，让用户可以点击“深入分析”或“重新计算”按钮。这要求 UI 和 Agent 之间能以流式、事件驱动的方式同步状态，而不仅仅是一问一答的API调用。

AG-UI协议与CopilotKit正是为了满足这种高频、细粒度、双向的人机协作需求而诞生。它们能够让开发者构建出真正嵌入UI应用、感知上下文、实时协同的智能体，而不仅仅是一个在后台提供文本答案的API服务。

【AG-UI协议】

AG-UI协议连接的目标就是前端UI（代表客户）与后端AI智能体，对它们之间的通信、事件、协作等进行标准化。AG-UI与MCP、A2A之间的区别与关系非常清晰：

【CopilotKit】

CopilotKit 可以被看作 AG-UI 协议实现的一个框架。它提供了完整的前后端集成方案，使开发者能够快速将 AI Copilot引入应用，包括：TypeScript/React 前端组件库、Python/Node SDK、以及可选的云端代理服务等。

简单来说，CopilotKit 让你的应用可以在前端无缝嵌入一个 AI Copilot（聊天窗口、副驾驶面板等），并与后端任意 Agent 保持交互 。它支持目前主流的智能体框架（LangGraph、LlamaIndex、CrewAI等），并且开箱即用地支持事件流、多路 Agent、可插拔工具、HITL、生成式UI等高级功能 。

接下来将通过一个实际的例子，演示如何一步步利用 CopilotKit 快速集成一个前端 AI 助手和后端 AI Agent，并深入体验其核心能力。

02 构建一个CopilotKit的演示Demo

我们通过一个实际的Demo来演示CopilotKit的能力。该Demo架构如下：

主要包括三个部分：

• 后端Agent：使用LangGraph构建的一个Workflow智能体。
• 前端应用：使用React+TS构建简单的Demo（也可以是你的现成应用）。
• Copilot助手：使用CopilotKit给前端应用嵌入的智能助手。

【后端Agent准备与启动】

准备一个简单的LangGraph Agent，这里交给它两个Tool，一个用来Web搜索，一个模拟查询天气。将该Agent保存在agent.py，并可以导出使用。

为了让Agent与前端UI实现通信和调用，我们仍然需要FastAPI。但这里需要使用CopilotKIt提供的FastAPI集成工具进行配置，方法如下：

...
from copilotkit.integrations.fastapi import add_fastapi_endpoint
from copilotkit import CopilotKitRemoteEndpoint, LangGraphAgent
from sample_agent.agent import graph
app = FastAPI()

#创建一个copilot的远程端点，将前面创建的Agent加入即可 
sdk = CopilotKitRemoteEndpoint(
    agents=[
        LangGraphAgent(
            name="sample_agent",
            description="一个模拟智能体",
            graph=graph,
        )
    ],
)
add_fastapi_endpoint(app, sdk, "/copilotkit")
...

注意这里的sample_agent.agent就是导入上面创建好的Agent。

接着正常启动（uvicorn.run）FastAPI服务即可：

【前端应用准备与启动】

接着来准备前端UI应用。你使用现成的ReactTS应用。这里我们直接用Next.js脚手架创建一个全新的React应用：

npx create-next-app@latest

我们对app/page.tsx稍作美化，让前端主页面展示如下：

现在你可以启动这个Next.js应用，并在浏览器中观察效果。

【集成AI Copilot】

现在给这个前端UI增加AI Copilot，并实现与后端Agent的基本互动。

步骤1：安装依赖包

给前端安装CopilotKit依赖包：

npm install @copilotkit/react-ui @copilotkit/react-core
npm install @copilotkit/runtime class-validator

步骤2：增加路由到后端Agent

目的：让后面上Copilot的请求能够被发送到后端Agent。

方法：在app/api/copilotkit目录下增加route.ts文件，核心部分如下：

...
const runtime = new CopilotRuntime({
  remoteEndpoints: [{url: "http://localhost:8080/copilotkit"},],
});

exportconst POST = async (req: NextRequest) => {
const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });
return handleRequest(req);
};

注意这里http://.../copilotkit就是上面FastAPI配置的端点。

步骤3：配置全局 CopilotKit 功能

目的：让应用中的页面都可以使用CopilotKit创建Copilot。

方法：在app/layout.tsx文件中的RootLayout函数中配置CopilotKit组件即可：

<CopilotKit
  agent="sample_agent"  
  runtimeUrl="/api/copilotkit"
  showDevConsole={false}
>
  {children}
</CopilotKit>

注意这里agent是后端agent的名字；runtimeUrl与前面的路由匹配。

步骤4：给页面增加Copilot

现在我们可以给任何页面（这里只有一个主页面page.tsx）增加Copilot界面，与Agent对话，实现智能交互体验。你可以选择sidebar（边栏）、popup（弹出式）、chat（聊天）等多种UI形式。这里我们添加一个popup形式的Copilot到主页。

在app/page.tsx中添加一个CopilotPopup的UI组件即可：

...
export defaultfunctionYourApp() {
return (
    <>
    <Home/> 
    <CopilotPopup
      defaultOpen={true}
      instructions={"你是个智能助手，尽可能用已有的知识回答问题"}
      labels={{
        title: "智能AI Copilot",
        initial: `
  #  您好！
  我是你的智能Copilot。..........
        `
      }}
    /> 
    </>
  );
}
...

前端效果测试

OK！这就是全部工作。你无需设计对话的UI、无需调试CSS、无需实现对后端Agent的调用、无需考虑流式展现...等等一系列问题。

打开主页面，会发现右下角有一个popup按钮，点击后出现Chat界面，简单测试：

接下来我们将探索CopilotKit的更多能力。

03 CopilotKit能力之：State共享

【什么是State（状态）共享】

我们知道LangGraph的Agent会维护一个内部的自定义状态（State），用来在工作流运行期间传递与同步信息。借助CopilotKit，你可以实现在前端UI与后端Agent之间自动双向同步与共享这个自定义的State信息。

注意这里的前端UI并不仅仅是Copilot的Chat界面，而是整个应用。

【实例展示】

现在对上面的Demo做增强，来展示后端Agent状态如何实时同步到前端UI上展示。

步骤1：定义Agent的State

我们在后端Agent的State中增加一个信息用来保存搜索工具的调用历史：

class AgentState(MessagesState):
    search_history: list[str] = [] # 搜索历史记录

然后在Agent的LLM调用节点中判断如果产生了搜索工具的调用需求，就增加一条搜索记录。大致如下）：

...
    # 如果是搜索工具，保存搜索历史
    if response.tool_calls[0].get("name") in ["tavily-search"]:
           search_history = state.get("search_history", [])
           search_query = response.tool_calls[0].get("args", {})
           search_history.append(search_query["query"])
           updated_state["search_history"] = search_history
    
    return Command(goto="tool_node", update=updated_state)
...

步骤2：前端Hook设置

现在我们想把这个后端State中的搜索历史实时展示在前端UI上，只需要使用CopilotKit提供的useCoAgent这个hook函数（hook是前端React框架的状态管理机制）即可：

...
type AgentState = {
 search_history: string[],
}

function Home() {

 #使用useCoAgent hook函数
const {state, setState} = useCoAgent<AgentState>({
    name: "sample_agent",
    initialState: {
      search_history: []
    },
  })

 #在UI部分使用state
return (
<div>
  ...{state.search_history}
</div>

这段代码中：

• 定义与后端Agent匹配的AgentState，有一个对应的search_history
• 使用用useCoAgent设置前端状态，提供后端Agent名称与初始状态
• 接着就可以在UI部分使用state.search_history来直接展示后端State

前端效果测试

在Copilot的Chat界面中提出两个需要Web搜索的问题，很快就可以在左边的UI上看到后端Agent在调用工具时的搜索关键词，它被自动同步到了前端！

【更多功能】

以上展示了将后端Agent状态同步到前端。相反，你也可以将前端设置的状态实时更新给后端Agent使用，这是一种双向同步的机制。可以很方便的用到这些场景：

• 用户在前端UI上更改Agent设置，这些设置被自动同步给Agent。比如：更改Agent回复的语言或风格。
• 后端Agent运行时将当前进度保存到状态中，前端可以实时的获取并渲染Agent的运行状态，而不只是“加载中...”。

04 CopilotKit能力之：调用前端“工具”

【什么是前端工具】

Agent的基本能力之一是工具（Tool）的使用，CopilotKit可以让后端的LangGraph Agent拥有一项神奇的能力：它不仅可以调用后端设置的工具（比如搜索、访问数据库、MCP），还可以调用前端定义的UI“工具”（比如更改样式）！

【实例展示】

我们继续增强上面的Demo来展示这种能力。

步骤1：注册前端“工具”

使用useCopilotAction hook来注册一个前端Action。比如，我们创建一个前端Action向用户弹出简单的Alert消息：

useCopilotAction({
  name: "sayHello", // Action 名称，Agent 将通过此名称来调用工具
  description: "向指定用户问好", // 对该 Action 的描述（供 Agent 理解用途）
  parameters: [ // 定义参数列表
    { name: "name", type: "string", description: "要问好的对象名字" }
  ],
  render: "正在发送问候...", // (可选) 执行时在Chat中显示的提示文本
  handler: async ({ name }) => { // 定义具体执行逻辑的函数（异步支持）
        alert(`Hello, ${name}!`); // 这里在浏览器弹出提示框
    return('问候已发送给' + name); // 返回给Agent的结果
    }
});

这个Action是不是非常像开发Agent时定义的工具呢？

上面代码在前端注册了一个名为 "sayHello" 的 Copilot 动作：它需要一个字符串参数 name。我们提供了 handler 函数，当 Agent 触发该工具时，handler 会被调用，在浏览器中弹出问候信息。render: "正在发送问候..." 则用于在 Chat 界面上显示一个临时消息提示，让用户知道Agent正在执行“问好”操作。

步骤2：给后端Agent添加工具

首先，你需要让Agent的State从CopilotState派生而不是之前LangGraph提供的MessagesState，其他无需改变：

from copilotkit import CopilotKitState
class AgentState(CopilotKitState):
    search_history: list[str] = [] # 搜索历史记录

其次，将前端Action作为工具给Agent使用。我们的例子中是通过LLM绑定：

...
# 3. 绑定工具到模型
model_with_tools = model.bind_tools(
    [
        *state["copilotkit"]["actions"], # CopilotKit actions
        *all_tools, # 其他后端的工具
    ],
)

这里只需要一行代码，就可以从State中获得前端的Action，并作为工具交给Agent使用。

前端效果测试

现在我们在前端Copilot的Chat界面中测试一个问题：

Agent 在理解意图后，会选择调用我们定义的前端sayHello 工具，并传入参数 { "name": "张三" }。前端CopilotKit 收到工具调用事件后，就会执行注册的 handler：

与此同时，CopilotKit 会把执行结果反馈给后端Agent，Agent 随后继续生成并在Chat界面显示结果：

注意我们并没有在后端 Agent 明确编写任何关于前端工具的逻辑：CopilotKit 自动完成了前端 Action 的注册和后端 Agent 之间的协议对接。

【更多功能】

前端工具的用法可以很灵活。除了像 alert 这样的简单动作外，你可以让 Agent 调用前端的导航功能（切换路由页面）、控制播放器组件播放/暂停、触发前端验证逻辑等。例如你可以注册一个 "highlightText" 工具，让 Agent 可以请求高亮页面上的某段文本；或注册 "openModal" 工具，Agent 可调用它弹出一个对话框呈现额外信息。通过这些前端工具，AI 助手可以真正影响并参与到用户界面的操作中去，实现人机协作的新范式。

我们将在下篇继续探索CopilotKit另外两项能力：基于Agent的前端生成式UI，以及HITL（人类参与流程）。

源代码地址：

https://github.com/pingcy/copilot-ai-demo