CopilotKit：讓 AI 成為你應用程式中的智慧夥伴，關鍵教學指南

引言：AI 助手時代的來臨

還記得十年前，我們對「智能助手」的想像嗎？那時的 Siri 和 Google Assistant 只能回答簡單問題，執行基本指令。而今天，AI 助手已經可以深度整合到我們的應用程式中，理解複雜上下文，執行專業任務，甚至主動提供建議。這不再是科幻電影中的場景，而是我們正在經歷的技術革命。

身為開發者，你是否曾想過：「如何讓我的應用程式擁有類似 GitHub Copilot 那樣的 AI 助手功能？」或者「如何讓 AI 不只是一個聊天機器人，而是真正融入應用程式的工作流程？」

好消息是，這一切現在變得前所未有地簡單。今天我要向你介紹的 CopilotKit，正是為解決這些問題而生的開源框架。它讓你能夠輕鬆地將 AI 助手整合到 React 應用中，打造真正智能化的使用者體驗。

在這篇文章中，我將帶你深入了解 CopilotKit 的方方面面，從基礎概念到實戰應用，再到進階技巧。無論你是 AI 整合的新手，還是尋找更高效工具的資深開發者，這篇指南都能幫助你快速掌握 CopilotKit，並將其應用到你的專案中。

準備好了嗎？讓我們一起踏上這段 AI 助手開發之旅！

CopilotKit 是什麼？

想像一下，你正在開發一個複雜的 Web 應用程式，突然靈光一閃：「要是能在應用中加入一個像 GitHub Copilot 那樣的 AI 助手，幫助用戶完成任務，該有多好？」但隨即你可能會想到：「這需要深厚的 AI 知識、複雜的後端架構、繁瑣的前端整合…」

別擔心，CopilotKit 正是為解決這個問題而誕生的。

核心概念與設計理念

CopilotKit 是一個開源的 React 框架，專為打造深度整合的 AI 助手和代理人而設計。它不只是一個聊天機器人工具，而是一套完整的解決方案，讓 AI 能夠真正「理解」你的應用程式，並與用戶一起協作完成任務。

CopilotKit 的核心理念是「AI 不應該只是一個獨立的聊天窗口，而應該是應用程式的一部分」。它讓 AI 能夠：

了解應用程式的上下文：AI 可以讀取和理解應用中的數據和狀態
執行應用程式中的操作：不只是回答問題，還能實際執行功能
生成動態 UI 元素：根據對話內容動態生成和更新界面
提供結構化的自動完成：不只是文本，還能自動完成結構化數據

這種設計理念使 CopilotKit 成為真正意義上的「AI 助手框架」，而非簡單的「聊天機器人工具」。

與其他 AI 整合框架的比較

市場上已有不少 AI 整合工具，CopilotKit 如何脫穎而出？讓我們來看一個比較表：

框架	主要特點	適用場景	學習曲線	前端整合	代理人支持
CopilotKit	深度整合、前端 RAG、生成式 UI	React 應用、企業級產品	中等	原生支持	完整支持
Langchain.js	強大的 LLM 鏈和工具	通用 AI 應用	較高	需自行整合	基礎支持
Vercel AI SDK	簡單易用、流式傳輸	Next.js 應用	較低	部分支持	有限支持
Botpress	對話流程管理	客服機器人	中等	需自行整合	有限支持

可以看到，CopilotKit 在前端整合和代理人支持方面具有明顯優勢，特別適合需要深度 AI 整合的 React 應用。

主要功能與特色一覽

CopilotKit 提供了一系列強大功能，讓 AI 助手開發變得簡單高效：

無頭 UI 與預構建組件：提供完全可控的無頭 UI 和高度可定制的預構建組件
前端 RAG（檢索增強生成）：讓 AI 能夠讀取和理解應用中的數據
知識庫整合：輕鬆連接外部知識庫，增強 AI 回答能力
前端動作與生成式 UI：AI 可以執行前端操作並生成動態 UI 元素
結構化自動完成：為任何內容提供智能的結構化自動完成
CoAgents：支持應用內的 LangGraph 代理人，實現複雜的多步驟任務

這些功能共同構成了一個強大的 AI 助手開發生態系統，讓開發者能夠根據自己的需求靈活選擇和組合。

適用場景與限制

CopilotKit 特別適合以下場景：

企業級 SaaS 應用：為複雜的企業應用添加智能助手功能
數據分析工具：創建能理解和解釋數據的 AI 助手
內容創作平台：提供智能寫作和編輯建議
客戶支持系統：打造能夠理解產品知識的智能客服
教育和學習平台：創建個性化的 AI 學習助手

當然，任何技術都有其限制。CopilotKit 目前主要針對 React 應用，如果你使用其他前端框架，可能需要額外的適配工作。此外，雖然 CopilotKit 簡化了 AI 整合，但你仍需要有基本的 React 知識和 AI 概念理解。

快速入門：設置你的第一個 AI 助手

好了，理論知識已經足夠，是時候動手實踐了！接下來，我將帶你一步步設置你的第一個 CopilotKit AI 助手。

環境準備與安裝

首先，確保你已經有一個 React 專案。如果沒有，可以使用 Create React App 或 Next.js 快速創建一個：

# 使用 Create React App
npx create-react-app my-copilot-app
cd my-copilot-app

# 或使用 Next.js
npx create-next-app my-copilot-app
cd my-copilot-app

接下來，安裝 CopilotKit 相關套件：

npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/react-textarea

這三個套件分別提供：

@copilotkit/react-core：核心功能和 hooks
@copilotkit/react-ui：預構建的 UI 組件
@copilotkit/react-textarea：智能文本區域組件

基本配置與 API 金鑰設置

安裝完成後，我們需要設置 CopilotKit 提供者和 API 金鑰。在你的應用入口文件（通常是 App.js 或 _app.js）中添加以下代碼：

import { CopilotKit } from "@copilotkit/react-core";
import { CopilotPopup } from "@copilotkit/react-ui";

function App() {
  return (
    <CopilotKit 
      apiKey="your-copilot-cloud-api-key" // 從 Copilot Cloud 獲取
      // 或者使用自定義後端
      // apiUrl="your-custom-backend-url"
    >
      <YourApp />
      <CopilotPopup
        instructions="你是一個有用的助手，幫助用戶使用這個應用程式。"
        labels={{ title: "AI 助手", initial: "需要幫忙嗎？" }}
      />
    </CopilotKit>
  );
}

你可以從 Copilot Cloud 獲取免費的 API 金鑰，或者設置自己的後端服務。

最簡單的 AI 助手實現範例

現在，讓我們實現一個最簡單的 AI 助手功能。假設我們有一個待辦事項應用，我們希望 AI 助手能夠幫助用戶管理任務。

首先，我們需要讓 AI 了解應用中的任務數據：

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

function TodoList({ todos }) {
  // 讓 AI 了解待辦事項列表
  useCopilotReadable({
    description: "用戶的待辦事項列表",
    value: todos,
  });
  
  return (
    <div>
      <h2>待辦事項</h2>
      <ul>
        {todos.map(todo => (
          <li key={todo.id}>{todo.text}</li>
        ))}
      </ul>
    </div>
  );
}

接下來，我們讓 AI 能夠添加新任務：

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

function TodoApp() {
  const [todos, setTodos] = useState([]);
  
  // 讓 AI 能夠添加新任務
  useCopilotAction({
    name: "addTodo",
    description: "添加一個新的待辦事項",
    parameters: [
      { name: "text", type: "string", description: "待辦事項內容" }
    ],
    handler: ({ text }) => {
      const newTodo = { id: Date.now(), text };
      setTodos([...todos, newTodo]);
      return { success: true, message: `已添加：${text}` };
    }
  });
  
  return <TodoList todos={todos} />;
}

就這麼簡單！現在你的 AI 助手已經能夠讀取待辦事項列表，並且添加新的任務。用戶可以通過聊天窗口與 AI 互動，例如說「幫我添加一個任務：明天下午三點開會」，AI 就會自動調用 addTodo 動作。

常見問題與解決方案

在實際開發中，你可能會遇到一些常見問題：

AI 無法正確理解應用上下文
- 解決方案：確保使用 useCopilotReadable 提供足夠的上下文信息，並添加清晰的描述
動作執行失敗
- 解決方案：檢查參數類型是否正確，確保處理函數能夠處理各種邊緣情況
UI 組件樣式不符合應用風格
- 解決方案：使用 CopilotKit 提供的樣式自定義選項，或者使用無頭 UI 模式自行構建界面
回應延遲過長
- 解決方案：考慮使用流式傳輸模式，並優化後端處理邏輯

記住，AI 助手的質量很大程度上取決於你提供的上下文和指令。花時間優化這些元素，將顯著提升用戶體驗。

CopilotKit 核心功能詳解

現在你已經了解了 CopilotKit 的基礎知識，並成功實現了一個簡單的 AI 助手。接下來，讓我們深入探討 CopilotKit 的核心功能，看看它如何幫助你打造更強大的 AI 體驗。

聊天介面與對話管理

CopilotKit 提供了靈活的聊天介面選項，從預構建組件到完全自定義的無頭 UI：

預構建組件：

import { CopilotPopup, CopilotSidebar } from "@copilotkit/react-ui";

// 彈出式聊天窗口
<CopilotPopup 
  instructions="你是一個有用的助手，幫助用戶使用這個應用程式。"
  labels={{ title: "AI 助手", initial: "需要幫忙嗎？" }}
/>

// 側邊欄聊天界面
<CopilotSidebar 
  instructions="你是一個有用的助手，幫助用戶使用這個應用程式。"
  labels={{ title: "AI 助手" }}
/>

無頭 UI：

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

function CustomChatUI() {
  const { 
    visibleMessages, 
    appendMessage, 
    setMessages,
    isLoading,
    // 更多控制選項...
  } = useCopilotChat();
  
  return (
    <div className="custom-chat">
      {visibleMessages.map(msg => (
        <div key={msg.id} className={`message ${msg.role}`}>
          {msg.content}
        </div>
      ))}
      {/* 自定義輸入框和發送按鈕 */}
    </div>
  );
}

無頭 UI 模式給了你完全的自由，可以打造符合你應用風格的聊天體驗。

前端 RAG (檢索增強生成)

RAG（檢索增強生成）是現代 AI 應用的重要技術，它讓 AI 能夠基於特定知識回答問題。CopilotKit 創新地將 RAG 帶到了前端：

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

// 讓 AI 了解用戶資料
function UserProfile({ user, transactions, preferences }) {
  useCopilotReadable({
    description: "當前登入用戶的個人資料",
    value: user,
  });
  
  useCopilotReadable({
    description: "用戶的交易歷史",
    value: transactions,
  });
  
  useCopilotReadable({
    description: "用戶的偏好設置",
    value: preferences,
  });
  
  // 渲染用戶界面...
}

這樣，AI 就能夠回答關於用戶資料、交易歷史和偏好設置的問題，而無需你手動編寫每一種可能的查詢邏輯。

對於更複雜的知識庫需求，CopilotKit 還提供了知識庫整合：

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

// 連接外部知識庫
useCopilotKnowledgebase({
  documents: myDocumentsArray, // 文檔數組
  // 或者使用 API
  apiUrl: "your-knowledge-base-api",
});

動作執行與生成式 UI

CopilotKit 的一個強大特性是允許 AI 執行動作並生成動態 UI：

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

// 定義 AI 可以執行的動作
useCopilotAction({
  name: "appendToSpreadsheet",
  description: "向當前電子表格添加行",
  parameters: [
    { 
      name: "rows", 
      type: "object[]", 
      attributes: [
        { 
          name: "cells", 
          type: "object[]", 
          attributes: [
            { name: "value", type: "string" }
          ] 
        }
      ] 
    }
  ],
  // 動態渲染 UI
  render: ({ status, args }) => (
    <Spreadsheet data={canonicalSpreadsheetData(args.rows)} />
  ),
  // 執行實際操作
  handler: ({ rows }) => setSpreadsheet({
    ...spreadsheet,
    rows: [...spreadsheet.rows, ...canonicalSpreadsheetData(rows)]
  }),
});

這個功能特別強大，因為它不只是讓 AI 執行操作，還能根據操作結果動態生成 UI 元素。想像一下，用戶說「幫我創建一個顯示本月銷售數據的圖表」，AI 就能生成並顯示這個圖表！

結構化自動完成

除了聊天界面，CopilotKit 還提供了結構化自動完成功能，類似於 GitHub Copilot 的代碼建議：

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

// 在電子表格中提供智能建議
function SpreadsheetEditor() {
  const { suggestions } = useCopilotStructuredAutocompletion(
    {
      instructions: `根據推斷的用戶意圖，自動完成或修改電子表格行。`,
      value: { rows: spreadsheet.rows.map((row) => ({ cells: row })) },
      enabled: !!activeCell && !spreadsheetIsEmpty,
    },
    [activeCell, spreadsheet]
  );
  
  // 使用建議更新 UI...
}

這個功能可以應用於各種場景，從代碼編輯器到表單填寫，為用戶提供智能的自動完成建議。

CoAgents：應用內 LangGraph 代理人

CopilotKit 最先進的功能之一是 CoAgents，它讓你能夠在應用中使用 LangGraph 代理人：

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

// 創建一個基本代理人
function WeatherAgent() {
  const { agentState } = useCoAgent({ 
    name: "weather_agent", 
    initialState: { location: "台北" } 
  });
  
  // 渲染代理人生成的 UI
  useCoAgentStateRender({
    name: "weather_agent",
    render: ({ state }) => <WeatherDisplay {...state.weather_data} />,
  });
  
  // 組件其餘部分...
}

代理人可以執行複雜的多步驟任務，例如收集信息、做出決策、調用外部 API，並生成動態 UI。這使得 CopilotKit 能夠支持真正智能的應用內助手。

實戰案例：打造智能應用

理論知識已經足夠，現在讓我們看看 CopilotKit 如何應用於實際場景。以下是幾個實戰案例，展示了 CopilotKit 的強大功能。

表單填寫助手

傳統的表單填寫往往是單調乏味的。使用 CopilotKit，我們可以將其轉變為自然的對話體驗：

function IntelligentForm() {
  const [formData, setFormData] = useState({
    name: "",
    email: "",
    address: "",
    // 更多字段...
  });
  
  // 讓 AI 了解當前表單狀態
  useCopilotReadable({
    description: "當前表單數據",
    value: formData,
  });
  
  // 讓 AI 能夠填寫表單
  useCopilotAction({
    name: "fillFormField",
    description: "填寫表單字段",
    parameters: [
      { name: "field", type: "string", description: "字段名稱" },
      { name: "value", type: "string", description: "字段值" }
    ],
    handler: ({ field, value }) => {
      if (field in formData) {
        setFormData({ ...formData, [field]: value });
        return { success: true };
      }
      return { success: false, message: "未知字段" };
    }
  });
  
  // 表單渲染...
}

有了這個助手，用戶可以說「我的名字是王小明，電子郵件是 xiaoming@example.com」，AI 就會自動填寫相應字段。

資料視覺化儀表板助手

數據分析通常需要專業知識。使用 CopilotKit，我們可以創建一個能夠理解數據並生成視覺化的 AI 助手：

function DashboardAssistant({ data }) {
  // 讓 AI 了解數據
  useCopilotReadable({
    description: "儀表板數據集",
    value: data,
  });
  
  // 讓 AI 生成圖表
  useCopilotAction({
    name: "createChart",
    description: "創建數據圖表",
    parameters: [
      { name: "type", type: "string", description: "圖表類型 (line, bar, pie)" },
      { name: "title", type: "string", description: "圖表標題" },
      { name: "dataKeys", type: "string[]", description: "要顯示的數據鍵" }
    ],
    render: ({ args }) => (
      <ChartComponent 
        type={args.type} 
        title={args.title} 
        data={data} 
        keys={args.dataKeys} 
      />
    ),
    handler: ({ type, title, dataKeys }) => {
      // 保存圖表配置...
      return { success: true };
    }
  });
  
  // 儀表板渲染...
}

用戶可以直接詢問「顯示過去 30 天的銷售趨勢圖」，AI 就會生成相應的圖表。

財務分析助手

財務數據通常複雜且難以理解。使用 CopilotKit，我們可以創建一個能夠分析交易並提供見解的助手：

function FinancialAssistant({ transactions }) {
  // 讓 AI 了解交易數據
  useCopilotReadable({
    description: "用戶的交易歷史",
    value: transactions,
  });
  
  // 讓 AI 生成財務報告
  useCopilotAction({
    name: "generateFinancialReport",
    description: "生成財務報告",
    parameters: [
      { name: "reportType", type: "string", description: "報告類型 (spending, income, savings)" },
      { name: "timeFrame", type: "string", description: "時間範圍 (week, month, year)" }
    ],
    render: ({ args }) => (
      <FinancialReport 
        type={args.reportType} 
        timeFrame={args.timeFrame} 
        transactions={transactions} 
      />
    ),
    handler: ({ reportType, timeFrame }) => {
      // 生成報告邏輯...
      return { success: true };
    }
  });
  
  // 財務界面渲染...
}

這個助手可以回答「我上個月在餐廳花了多少錢？」或「我的儲蓄趨勢如何？」等問題。

旅行規劃助手

旅行規劃涉及多個步驟和決策。使用 CopilotKit 的 CoAgents 功能，我們可以創建一個智能旅行助手：

function TravelPlanner() {
  // 創建旅行規劃代理人
  const { agentState } = useCoAgent({ 
    name: "travel_agent", 
    initialState: { destination: "", dates: [], budget: 0 } 
  });
  
  // 讓代理人生成行程
  useCoAgentStateRender({
    name: "travel_agent",
    render: ({ state }) => (
      state.itinerary ? 
        <ItineraryDisplay itinerary={state.itinerary} /> : 
        <ItineraryPlaceholder />
    ),
  });
  
  // 讓代理人搜索景點
  useCopilotAction({
    name: "searchAttractions",
    description: "搜索目的地景點",
    parameters: [
      { name: "location", type: "string", description: "位置" },
      { name: "category", type: "string", description: "類別 (sightseeing, food, shopping)" }
    ],
    handler: async ({ location, category }) => {
      // 調用景點 API...
      return { attractions: [...] };
    }
  });
  
  // 旅行規劃界面渲染...
}

用戶可以與這個助手進行自然對話，例如「我想計劃一次去京都的五天旅行，預算是 50,000 元」，助手會引導用戶完成整個規劃過程。

文件分析系統

處理複雜文檔通常需要大量時間。使用 CopilotKit 的多代理人功能，我們可以創建一個文檔分析系統：

function DocumentAnalysisSystem({ document }) {
  // 創建多個專門代理人
  const { agentState: summarizerState } = useCoAgent({ 
    name: "summarizer_agent", 
    initialState: { document } 
  });
  
  const { agentState: analyzerState } = useCoAgent({ 
    name: "analyzer_agent", 
    initialState: { document } 
  });
  
  // 渲染摘要
  useCoAgentStateRender({
    name: "summarizer_agent",
    render: ({ state }) => (
      state.summary ? 
        <DocumentSummary summary={state.summary} /> : 
        <LoadingIndicator />
    ),
  });
  
  // 渲染分析
  useCoAgentStateRender({
    name: "analyzer_agent",
    render: ({ state }) => (
      state.analysis ? 
        <DocumentAnalysis analysis={state.analysis} /> : 
        <LoadingIndicator />
    ),
  });
  
  // 文檔分析界面渲染...
}

這個系統可以同時執行摘要、關鍵點提取、情感分析等多項任務，大大提高文檔處理效率。

進階技巧與最佳實踐

隨著你對 CopilotKit 的深入了解，以下是一些進階技巧和最佳實踐，幫助你打造更出色的 AI 助手體驗。

狀態管理與資料流

在複雜應用中，良好的狀態管理至關重要。以下是 CopilotKit 中管理狀態的最佳實踐：

// 使用 React 上下文共享狀態
const AppContext = createContext();

function AppProvider({ children }) {
  const [appState, setAppState] = useState({
    // 應用狀態...
  });
  
  // 提供更新方法
  const updateState = (newState) => {
    setAppState(prev => ({ ...prev, ...newState }));
  };
  
  return (
    <AppContext.Provider value={{ appState, updateState }}>
      {children}
    </AppContext.Provider>
  );
}

// 在 AI 動作中使用共享狀態
function AIActionComponent() {
  const { appState, updateState } = useContext(AppContext);
  
  useCopilotAction({
    // 動作定義...
    handler: (params) => {
      // 更新共享狀態
      updateState({ /* 新狀態 */ });
      return { success: true };
    }
  });
}

對於更複雜的應用，考慮使用 Redux 或 Zustand 等狀態管理庫，並在 AI 動作中與之集成。

下面是一個使用 Mermaid 圖表來說明 CopilotKit 中的資料流：

自定義 UI 與使用者體驗優化

CopilotKit 提供了高度可定制的 UI 選項：

// 自定義聊天氣泡樣式
<CopilotPopup
  instructions="你是一個有用的助手。"
  labels={{ title: "AI 助手", initial: "需要幫忙嗎？" }}
  className="my-custom-popup"
  bubbleClassName="my-custom-bubble"
  userBubbleClassName="my-custom-user-bubble"
  assistantBubbleClassName="my-custom-assistant-bubble"
/>

// 完全自定義 UI
function CustomChatInterface() {
  const { 
    visibleMessages, 
    appendMessage,
    isLoading 
  } = useCopilotChat();
  
  return (
    <div className="custom-chat-container">
      <div className="message-list">
        {visibleMessages.map(msg => (
          <CustomMessageBubble 
            key={msg.id} 
            role={msg.role} 
            content={msg.content} 
          />
        ))}
        {isLoading && <TypingIndicator />}
      </div>
      <CustomInputBox onSend={text => appendMessage({ role: "user", content: text })} />
    </div>
  );
}

使用者體驗優化技巧：

提供清晰的引導：告訴用戶 AI 助手能做什麼
顯示載入狀態：使用打字動畫或進度指示器
提供錯誤恢復：當 AI 無法完成任務時提供替代選項
漸進式揭示功能：隨著用戶熟悉度增加，逐步介紹更多功能
保持對話上下文：在 UI 中顯示相關的應用狀態

性能優化與快取策略

AI 助手可能會影響應用性能，以下是一些優化技巧：

// 使用記憶化避免不必要的重新渲染
const memoizedValue = useMemo(() => {
  return computeExpensiveValue(dependency);
}, [dependency]);

useCopilotReadable({
  description: "計算結果",
  value: memoizedValue,
});

// 實現簡單的回應快取
function useCachedResponses() {
  const [cache, setCache] = useState({});
  
  const getCachedResponse = (query) => {
    const key = hashString(query);
    return cache[key];
  };
  
  const setCachedResponse = (query, response) => {
    const key = hashString(query);
    setCache(prev => ({ ...prev, [key]: response }));
  };
  
  return { getCachedResponse, setCachedResponse };
}

對於大型應用，考慮使用 IndexedDB 或 localStorage 實現持久化快取。

多代理人協作模式

複雜任務可能需要多個專門代理人協作完成：

// 創建多個代理人
function MultiAgentSystem() {
  // 數據收集代理人
  const { agentState: collectorState } = useCoAgent({ 
    name: "collector_agent", 
    initialState: { /* 初始狀態 */ } 
  });
  
  // 分析代理人
  const { agentState: analyzerState } = useCoAgent({ 
    name: "analyzer_agent", 
    initialState: { /* 初始狀態 */ },
    // 依賴收集代理人的結果
    dependencies: ["collector_agent"]
  });
  
  // 決策代理人
  const { agentState: decisionState } = useCoAgent({ 
    name: "decision_agent", 
    initialState: { /* 初始狀態 */ },
    // 依賴分析代理人的結果
    dependencies: ["analyzer_agent"]
  });
  
  // 代理人協作流程...
}

多代理人協作模式特別適合複雜的工作流程，如數據分析、內容創作或決策支持系統。

安全性與隱私考量

在實現 AI 助手時，安全性和隱私保護至關重要：

敏感數據處理：
- 避免將敏感數據直接傳遞給 AI 模型
- 使用數據遮罩或匿名化技術
用戶同意：
- 明確告知用戶 AI 助手的數據使用方式
- 提供選擇退出或限制數據共享的選項
輸入驗證：
- 驗證 AI 生成的內容，防止注入攻擊
- 實現內容過濾機制
權限控制：
- 限制 AI 助手可以執行的操作範圍
- 對敏感操作實施人工確認機制

// 實現人工確認機制
useCopilotAction({
  name: "sendEmail",
  parameters: [
    { name: "emailContent", type: "string", description: "郵件內容" }
  ],
  // 渲染確認 UI 並等待用戶回應
  renderAndWaitForResponse: ({ args, status, respond }) => (
    <EmailConfirmation
      emailContent={args.emailContent}
      isExecuting={status === "executing"}
      onCancel={() => respond?.({ approved: false })}
      onSend={() => respond?.({ approved: true })}
    />
  ),
  handler: async ({ emailContent }, response) => {
    // 只有在用戶確認後才發送郵件
    if (response?.approved) {
      await sendEmail(emailContent);
      return { success: true };
    }
    return { success: false, message: "用戶取消了操作" };
  }
});

整合外部服務與 API

CopilotKit 的強大之處在於它能夠輕鬆整合外部服務和 API，擴展 AI 助手的能力。

與 OpenAI API 的整合

CopilotKit 默認支持 OpenAI API，你可以自定義模型和參數：

<CopilotKit
  apiKey={process.env.OPENAI_API_KEY}
  chatOptions={{
    model: "gpt-4-turbo",
    temperature: 0.7,
    maxTokens: 2000,
    // 更多選項...
  }}
>
  {/* 應用組件 */}
</CopilotKit>

如果你需要更多控制，可以設置自定義後端：

<CopilotKit
  apiUrl="/api/copilot"
  // 自定義請求頭
  apiHeaders={{
    "X-Custom-Header": "value"
  }}
>
  {/* 應用組件 */}
</CopilotKit>

然後在後端實現自己的處理邏輯：

// Next.js API 路由示例
export default async function handler(req, res) {
  const { messages, context } = req.body;
  
  // 使用 OpenAI API
  const openaiResponse = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`
    },
    body: JSON.stringify({
      model: "gpt-4-turbo",
      messages: [
        { role: "system", content: "你是一個有用的助手。" },
        ...messages
      ],
      temperature: 0.7
    })
  });
  
  const data = await openaiResponse.json();
  res.status(200).json(data);
}

與其他 LLM 提供商的整合

CopilotKit 不限於 OpenAI，你可以整合其他 LLM 提供商：

// 使用 Anthropic Claude API 的後端示例
export default async function handler(req, res) {
  const { messages, context } = req.body;
  
  // 轉換消息格式
  const formattedMessages = messages.map(msg => ({
    role: msg.role === "assistant" ? "assistant" : "user",
    content: msg.content
  }));
  
  // 調用 Anthropic API
  const anthropicResponse = await fetch("https://api.anthropic.com/v1/messages", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.ANTHROPIC_API_KEY
    },
    body: JSON.stringify({
      model: "claude-3-opus-20240229",
      messages: formattedMessages,
      max_tokens: 2000
    })
  });
  
  const data = await anthropicResponse.json();
  
  // 轉換回 CopilotKit 格式
  res.status(200).json({
    choices: [{
      message: {
        role: "assistant",
        content: data.content[0].text
      }
    }]
  });
}

知識庫與向量資料庫連接

對於需要特定領域知識的應用，你可以連接向量資料庫：

// 前端
useCopilotKnowledgebase({
  apiUrl: "/api/knowledge"
});

// 後端 (Next.js API 路由)
import { PineconeClient } from "@pinecone-database/pinecone";
import { OpenAIEmbeddings } from "langchain/embeddings/openai";

export default async function handler(req, res) {
  const { query } = req.body;
  
  // 生成查詢嵌入
  const embeddings = new OpenAIEmbeddings({
    openAIApiKey: process.env.OPENAI_API_KEY
  });
  const queryEmbedding = await embeddings.embedQuery(query);
  
  // 查詢 Pinecone
  const pinecone = new PineconeClient();
  await pinecone.init({
    apiKey: process.env.PINECONE_API_KEY,
    environment: process.env.PINECONE_ENVIRONMENT
  });
  const index = pinecone.Index(process.env.PINECONE_INDEX);
  
  const results = await index.query({
    queryRequest: {
      vector: queryEmbedding,
      topK: 5,
      includeMetadata: true
    }
  });
  
  // 返回相關文檔
  const documents = results.matches.map(match => match.metadata.text);
  res.status(200).json({ documents });
}

第三方服務整合案例

CopilotKit 可以與各種第三方服務整合，擴展 AI 助手的能力：

// 天氣 API 整合
useCopilotAction({
  name: "getWeather",
  description: "獲取指定城市的天氣信息",
  parameters: [
    { name: "city", type: "string", description: "城市名稱" }
  ],
  handler: async ({ city }) => {
    const response = await fetch(
      `https://api.weatherapi.com/v1/current.json?key=${process.env.WEATHER_API_KEY}&q=${city}`
    );
    const data = await response.json();
    return {
      temperature: data.current.temp_c,
      condition: data.current.condition.text,
      humidity: data.current.humidity
    };
  }
});

// 股票數據整合
useCopilotAction({
  name: "getStockPrice",
  description: "獲取指定股票的價格信息",
  parameters: [
    { name: "symbol", type: "string", description: "股票代碼" }
  ],
  handler: async ({ symbol }) => {
    const response = await fetch(
      `https://finnhub.io/api/v1/quote?symbol=${symbol}&token=${process.env.FINNHUB_API_KEY}`
    );
    const data = await response.json();
    return {
      currentPrice: data.c,
      change: data.d,
      percentChange: data.dp
    };
  }
});

// 日曆整合
useCopilotAction({
  name: "createCalendarEvent",
  description: "在用戶日曆中創建事件",
  parameters: [
    { name: "title", type: "string", description: "事件標題" },
    { name: "startTime", type: "string", description: "開始時間 (ISO 格式)" },
    { name: "endTime", type: "string", description: "結束時間 (ISO 格式)" }
  ],
  renderAndWaitForResponse: ({ args, respond }) => (
    <EventConfirmation
      event={args}
      onCancel={() => respond?.({ approved: false })}
      onConfirm={() => respond?.({ approved: true })}
    />
  ),
  handler: async ({ title, startTime, endTime }, response) => {
    if (response?.approved) {
      // 調用日曆 API 創建事件
      // ...
      return { success: true };
    }
    return { success: false, message: "用戶取消了操作" };
  }
});

這些整合使 AI 助手能夠提供更豐富、更實用的功能，從而提升用戶體驗。

未來展望與社群資源

CopilotKit 作為一個活躍的開源項目，正在快速發展。讓我們看看它的未來方向和可用資源。

CopilotKit 的發展路線

根據 CopilotKit 的 GitHub 倉庫和社群討論，以下是一些可能的發展方向：

更多框架支持：除了 React，未來可能會支持 Vue、Angular 等框架
增強的代理人功能：更強大的多代理人協作和推理能力
本地 LLM 支持：整合本地運行的 LLM 模型，提高隱私性和降低成本
更多預構建組件：針對特定場景的專業化 UI 組件
企業級功能：更強的安全性、審計和合規功能

社群貢獻與開源協作

CopilotKit 是一個開源項目，歡迎社群貢獻：

提交問題和功能請求：在 GitHub 倉庫中提交 issue
貢獻代碼：提交 pull request，幫助改進框架
創建插件和擴展：開發與 CopilotKit 兼容的插件
分享使用案例：在社群中分享你的實現和經驗

參與開源協作不僅可以幫助改進 CopilotKit，還能提升你的技術能力和社群影響力。

學習資源與教學推薦

以下是一些學習 CopilotKit 的有用資源：

官方文檔：docs.copilotkit.ai
GitHub 倉庫：github.com/CopilotKit/CopilotKit
示例應用：研究官方提供的示例應用代碼
社群教學：YouTube、Dev.to 和 Medium 上的教學文章
Discord 社群：加入 CopilotKit Discord 社群，與其他開發者交流

結語與行動建議

AI 助手正在改變我們與應用程式互動的方式。CopilotKit 作為一個強大的開源框架，為開發者提供了將 AI 助手整合到應用中的便捷途徑。

如果你正考慮在應用中添加 AI 助手功能，以下是一些行動建議：

從小處開始：先實現一個簡單的聊天界面，然後逐步添加更多功能
關注用戶體驗：確保 AI 助手真正解決用戶問題，而不只是一個花哨的功能
收集反饋：持續收集用戶反饋，不斷改進 AI 助手的能力
保持更新：關注 CopilotKit 的最新發展，及時採用新功能和最佳實踐
參與社群：加入 CopilotKit 社群，分享經驗，尋求幫助

AI 助手不是未來，而是現在。使用 CopilotKit，你可以在幾小時內為應用添加智能助手功能，提升用戶體驗，創造競爭優勢。

開始你的 AI 助手之旅吧！

參考資源

CopilotKit 官方 GitHub 倉庫：https://github.com/CopilotKit/CopilotKit
CopilotKit 官方文檔：https://docs.copilotkit.ai
“Integrate Copilot feature into your React applications using CopilotKit”：https://dev.to/ngviethoang/integrate-copilot-feature-into-your-react-applications-using-copilotkit-2nga
“Agents 101: How to build your first AI Agent in 30 minutes!"：https://www.copilotkit.ai/blog/agents-101-how-to-build-your-first-ai-agent-in-30-minutes
“Easy-Peasy Copilot Creation: A Beginner’s Guide to CopilotKit”：https://blog.stackademic.com/easy-peasy-copilot-creation-a-beginners-guide-to-copilotkit-ceab6a815bcc