如何学习 AG-UI 和 CopilotKit

🚀 一、AG-UI 是什么？怎么学？

AG-UI（Agent UI）是一套 专门给 AI 应用 做前端 UI 的组件库，用来：

做聊天界面（Chat UI）
用户指令栏（Taskbar）
动态卡片 / 流水线（Actions + Results）
和 AI 状态同步的控件（Copilot Views）

你可把它理解成：

"适用于 AI App 的 Tailwind + AntD + ChatGPT UI 的组合"

🌟 学习目标

你需要先掌握三件事：

装起来
跑一个 Chat 界面
理解它如何和 CopilotKit 共享状态

📘 学 AG-UI 的学习路线

第 1 步：从示例开始（最快的入门方式）

官网 Example 里有非常简单的 Demo：

👉 https://github.com/singlestore-labs/ag-ui/tree/main/examples

你可以直接

复制代码

git clone https://github.com/singlestore-labs/ag-ui
cd ag-ui/examples/chat
npm install
npm run dev

10 分钟就能跑起来一个类似 ChatGPT 的 UI。

第 2 步：学会 4 个核心组件（最重要）

组件	作用
`<AGChat />`	聊天消息列表 UI
`<AGInput />`	输入框（支持快捷键）
`<AGButton />`	按钮（风格和 ChatGPT 类似）
`<AGTaskbar />`	右上角的任务栏（让用户给 AI 下指令）

你只要先学 <AGChat> 和 <AGInput> 就够了。

第 3 步：把 UI 和 CopilotKit 接起来

AG-UI 本身不带 AI，它通过 CopilotKit 提供数据。

你需要这样用：

复制代码

const { messages, sendMessage } = useCopilotChat();

<AGChat messages={messages} />

<AGInput
  onSubmit={(text) => sendMessage(text)}
/>

只学这部分，就能做一个"像 ChatGPT 的 React 小应用"。

第 4 步：阅读官方文档

AG-UI 文档较短，但非常实用：

👉 https://ag-ui.com

重点看：

Chat UI
Taskbar
Views（和 CopilotKit 绑定状态）

🚀 二、CopilotKit 是什么？怎么学？

CopilotKit 是一个 让 React 组件、状态、页面内容自动变成大模型 Prompt 的框架。

你可以把它理解成：

"自动把你页面的 Context 提供给大模型的中间层"

非常适合做：

AI 助手（Dashboard、后台系统、流程助手）
AI 改写、总结、规划
AI 自动操作 UI

📘 CopilotKit 的学习路线

第 1 步：跑一个最小 Demo

复制代码

npm install @copilotkit/react @copilotkit/openai

写一个：

复制代码

import { CopilotProvider, useCopilotChat } from "@copilotkit/react";

function Chat() {
  const { messages, sendMessage } = useCopilotChat();

  return (
    <>
      {messages.map(m => <div>{m.role}: {m.content}</div>)}
      <input onKeyDown={(e) => e.key === "Enter" && sendMessage(e.target.value)} />
    </>
  );
}

export default function App() {
  return (
    <CopilotProvider config={{ model: "gpt-4o" }}>
      <Chat />
    </CopilotProvider>
  );
}

这就能和大模型对话了！

第 2 步：学会 useCopilotReadable（暴露状态给 AI）

复制代码

useCopilotReadable(
  { cart: cartList, user: userInfo },
  { name: "app_context" }
);

AI 就能"看到"你的页面状态，并为你做任务，例如：

请把购物车里最贵的商品删除。

你不用写逻辑，AI 会根据 readable state 做推理。

第 3 步：学 useCopilotActions（让 AI 调用你的函数）

复制代码

useCopilotAction({
  description: "增加商品数量",
  parameters: { id: "string" },
  handler: ({ id }) => {
    increaseCart(id);
  }
});

AI 现在可以：

帮我把商品 123 的数量加 1

它会自动调用你给它的函数。

这是 CopilotKit 最强大的地方。

第 4 步：学如何和 AG-UI 集成

AG-UI 的很多组件，如 Taskbar、Views，都是为 CopilotKit 设计的。

这两者结合后，可以做到：

AI 阅读你的页面
AI 修改你的 React 状态
AI 执行任务
AI 在 UI 上呈现任务结果

完整例子在：

👉 https://github.com/CopilotKit/examples

🔥 三、最佳学习顺序（新手到熟练）

适合你当前能力的路线 👇

✅ 第 1 天：跑通 Demo

跑 AG-UI chat 示例
跑 CopilotKit minimal chat 示例
学会 sendMessage

✅ 第 2 天：加入 Context（页面状态 → AI 见）

useCopilotReadable 暴露一个简单状态
让 AI 根据你的状态做总结

✅ 第 3 天：让 AI 操作 UI（Actions）

useCopilotActions 调用一个函数
让 AI 修改 React useState
加入 AG-UI Views 展示执行步骤

这时你基本已经具备 "独立做一个 AI 应用" 的能力。

🚀 四、项目目录结构（最推荐的标准结构）

复制代码

my-ai-app/
│
├── src/
│   ├── app/
│   │   ├── App.tsx
│   │   └── routes.tsx
│   │
│   ├── components/
│   │   ├── ChatUI/
│   │   │   ├── AIChat.tsx
│   │   │   └── UserInput.tsx
│   │   └── Taskbar/
│   │       └── AITaskbar.tsx
│   │
│   ├── copilot/
│   │   ├── copilot-provider.tsx
│   │   ├── readable.ts     // 暴露页面状态给 AI
│   │   └── actions.ts      // AI 可调用的函数
│   │
│   ├── pages/
│   │   ├── Home/
│   │   │   ├── Home.tsx
│   │   │   └── store.ts    // 页面级状态
│   │   ├── MathAI/
│   │   │   └── MathAI.tsx  // 数学 AI
│   │   └── DashboardAI/
│   │       └── Dashboard.tsx
│   │
│   ├── styles/
│   ├── main.tsx
│   └── vite-env.d.ts
│
├── index.html
├── package.json
└── vite.config.ts

🚀 五、安装依赖（最小完备）

复制代码

npm install react react-dom
npm install @copilotkit/react @copilotkit/openai
npm install ag-ui

🚀 六、创建 CopilotProvider（应用核心）

📌 src/copilot/copilot-provider.tsx

javascript 复制代码

import { CopilotProvider } from "@copilotkit/react";
import { OpenAIAdapter } from "@copilotkit/openai";

export const AIProvider = ({ children }: { children: React.ReactNode }) => {
  return (
    <CopilotProvider
      runtimeUrl="/api/copilot" 
      agent={{
        model: "gpt-4o-mini",
      }}
      adapters={[
        new OpenAIAdapter({
          apiKey: import.meta.env.VITE_OPENAI_KEY
        })
      ]}
    >
      {children}
    </CopilotProvider>
  );
};

然后你在 main.tsx 包起来：

javascript 复制代码

root.render(
  <AIProvider>
    <App />
  </AIProvider>
);

🚀 七、创建 AI 可读状态（readable state）

📌 src/copilot/readable.ts

javascript 复制代码

import { useCopilotReadable } from "@copilotkit/react";

export const useAIReadable = (cart: any[], user: any) => {
  useCopilotReadable(
    {
      cart,
      user,
      cartCount: cart.length
    },
    { name: "app_state" }
  );
};

AI 现在能看到：

用户信息
购物车内容
商品数量

🚀 八、AI 可执行动作（Actions）

📌 src/copilot/actions.ts

javascript 复制代码

import { useCopilotAction } from "@copilotkit/react";

export const useAIActions = (addItem: Function, removeItem: Function) => {
  // 增加商品
  useCopilotAction({
    name: "add_item",
    description: "Add an item to the shopping cart",
    parameters: {
      id: "string",
      name: "string"
    },
    handler: async ({ id, name }) => {
      addItem({ id, name });
      return `${name} added to cart.`;
    }
  });

  // 删除商品
  useCopilotAction({
    name: "remove_item",
    description: "Remove an item by id",
    parameters: {
      id: "string"
    },
    handler: async ({ id }) => {
      removeItem(id);
      return `Item ${id} removed.`;
    }
  });
};

AI 现在可以：

"帮我把 iPhone 加到购物车里"

"删除购物车中 id 为 123 的商品"

🚀 九、AG-UI 聊天组件

📌 src/components/ChatUI/AIChat.tsx

javascript 复制代码

import { AGChat } from "ag-ui";
import { useCopilotChat } from "@copilotkit/react";

export default function AIChat() {
  const { messages } = useCopilotChat();
  return <AGChat messages={messages} />;
}

📌 输入组件：UserInput.tsx

javascript 复制代码

import { AGInput } from "ag-ui";
import { useCopilotChat } from "@copilotkit/react";

export default function UserInput() {
  const { sendMessage } = useCopilotChat();

  return (
    <AGInput
      placeholder="输入内容让 AI 帮你做事"
      onSubmit={(text) => sendMessage(text)}
    />
  );
}

🚀 十、AG-UI 任务栏（Taskbar，让用户下指令）

📌 src/components/Taskbar/AITaskbar.tsx

javascript 复制代码

import { AGTaskbar } from "ag-ui";
import { useCopilotChat } from "@copilotkit/react";

export default function AITaskbar() {
  const { sendMessage } = useCopilotChat();
  return (
    <AGTaskbar
      items={[
        { title: "总结购物车", onClick: () => sendMessage("总结购物车内容") },
        { title: "推荐商品", onClick: () => sendMessage("给我推荐两个商品") },
      ]}
    />
  );
}

🚀 十一、将全部组合成 App

📌 src/pages/Home/Home.tsx

javascript 复制代码

import { useState } from "react";
import AIChat from "@/components/ChatUI/AIChat";
import UserInput from "@/components/ChatUI/UserInput";
import AITaskbar from "@/components/Taskbar/AITaskbar";
import { useAIReadable } from "@/copilot/readable";
import { useAIActions } from "@/copilot/actions";

export default function Home() {
  const [cart, setCart] = useState<any[]>([]);
  const user = { id: 1, name: "Alice" };

  const addItem = (item: any) => setCart([...cart, item]);
  const removeItem = (id: string) =>
    setCart(cart.filter((item) => item.id !== id));

  // AI 读取状态
  useAIReadable(cart, user);

  // AI 可以执行动作
  useAIActions(addItem, removeItem);

  return (
    <div className="h-screen flex flex-col">
      <AITaskbar />
      <div className="flex-1 overflow-auto">
        <AIChat />
      </div>
      <UserInput />
    </div>
  );
}

现在你的产品已经具备：

✔ AI 聊天

✔ 页面状态可见

✔ AI 能调用函数

✔ 可交互的任务栏

✔ 像 ChatGPT 的界面

这是完整的最小 AI 应用架构。