CopilotKit：构建 Agent-Native 应用的 React SDK

本文介绍 CopilotKit，一个用于构建全栈 Agent 应用的开源 SDK。它提供了生成式 UI、共享状态管理和人机协作工作流等功能，帮助开发者快速构建智能应用界面。

项目简介

CopilotKit 是一个专注于构建 Agent-Native 应用的前端 SDK，支持 React 和 Angular 框架。该项目由 CopilotKit 团队开发维护，是 AG-UI 协议的主要推动者。截至目前，该项目在 GitHub 上已获得 28.9k stars 和 3.7k forks，主要使用 TypeScript (92%) 和 Python (4.1%) 编写。

AG-UI 协议已被 Google、LangChain、AWS、Microsoft、Mastra、PydanticAI 等知名公司和框架采用。

核心特性

• Chat UI：基于 React 的聊天界面，支持消息流式传输、工具调用和 Agent 响应
• Backend Tool Rendering：Agent 可以调用后端工具，直接在客户端渲染 UI 组件
• Generative UI：Agent 能够根据用户意图和 Agent 状态在运行时动态生成和更新 UI 组件
• Shared State：同步状态层，Agent 和 UI 组件可以实时读写
• Human-in-the-Loop：Agent 可以暂停执行，请求用户输入、确认或编辑后再继续

技术栈

• TypeScript (92%) - 主要开发语言
• Python (4.1%) - Python SDK 支持
• CSS (2.7%) - 样式处理
• React/Angular - 支持的 UI 框架
• LangGraph/CrewAI - Agent 框架集成

安装指南

新项目

npx copilotkit@latest create -f <framework>

支持的框架包括：next, react, remix, angular, svelte 等。

现有项目

npx copilotkit@latest init

执行后会自动完成：

• CopilotKit 核心包安装
• Provider 配置（上下文、状态和 hooks）
• Agent <> UI 连接配置
• 部署准备

快速开始

基础用法示例

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

function MyComponent() {
  // 程序化访问和控制 Agent
  const { agent } = useAgent({
    agentId: "my_agent"
  });

  // 渲染和更新 Agent 状态
  return (
    <div>
      <h1>{agent.state.city}</h1>
      <button onClick={() => agent.setState({ city: "NYC" })}>
        Set City
      </button>
    </div>
  );
}

使用 AG-UI 创建项目

npx create-ag-ui-app my-agent-app

Generative UI 模式

CopilotKit 支持三种 Generative UI 类型：

1. Static (AG-UI Protocol)

基于 AG-UI 协议的静态 UI 渲染，适用于预定义的组件。

2. Declarative (A2UI)

声明式 UI 生成，通过结构化描述让 Agent 理解如何渲染界面。

3. Open-Ended (MCP Apps & Open JSON)

开放式 UI 生成，支持 MCP 应用和开放式 JSON 格式，提供最大的灵活性。

工作原理

CopilotKit 将 UI、Agent 和工具连接到一个统一的交互循环中：

1. 用户交互 → 触发 Agent 执行
2. Agent 处理 → 调用工具或生成响应
3. UI 渲染 → 根据 Agent 状态动态更新界面
4. 状态同步 → 共享状态在 UI 和 Agent 之间实时同步

这实现了：

• 向用户请求输入的 Agent
• 渲染 UI 的工具
• 跨步骤和会话的有状态工作流

集成支持

CopilotKit 与主流 Agent 框架深度集成：

• LangGraph - LangChain 的 Agent 编排框架
• CrewAI - 多 Agent 协作框架
• Mastra - TypeScript Agent 框架
• PydanticAI - Python Agent 框架

社区与支持

• 官方文档: https://docs.copilotkit.ai
• Discord 社区: https://discord.gg/6dffbvGU3D
• Copilot Cloud: https://cloud.copilotkit.ai
• LinkedIn: https://www.linkedin.com/company/copilotkit/
• X/Twitter: https://x.com/copilotkit

贡献指南

CopilotKit 欢迎各种形式的贡献：

• 代码贡献：参考 CONTRIBUTING.md
• 文档贡献：文档贡献指南
• 创建示例应用
• 在社区中分享使用经验

项目链接

• GitHub 仓库: https://github.com/CopilotKit/CopilotKit
• 官方文档: https://docs.copilotkit.ai
• NPM 包: https://www.npmjs.com/package/@copilotkit/react-core
• Generative UI 示例: https://github.com/CopilotKit/generative-ui
• AG-UI 协议: https://github.com/ag-ui-protocol/ag-ui

许可证

本项目采用 MIT 许可证 开源。