AI-Chain
AI Agent Generative UI 開源專案 TypeScript CopilotKit

CopilotKit：把 Agent 事件帶進產品介面的開源 SDK

CopilotKit 將 Generative UI、共享狀態與 Human-in-the-Loop 工作流程整合到產品前端，本文從事件流、架構與工程取捨拆解它如何把 Agent 變成可控制的產品協作者。

分享:
CopilotKit：把 Agent 事件帶進產品介面的開源 SDK

CopilotKit：把 Agent 事件帶進產品介面的開源 SDK

當團隊開始把 LLM Agent 放進產品，最先遇到的通常不是「如何再多接一個模型」，而是另一個更實際的問題：Agent 正在執行什麼？它需要哪些產品資料？使用者要如何確認、修正，或接手一個半自動流程？如果答案只是額外嵌入一個聊天視窗，Agent 仍然和產品本身分離，使用者也很難建立可靠的操作心智模型。

CopilotKit 是一個以 TypeScript 為主的開源專案，定位是 Agent-native application 的前端堆疊。它把 Generative UI、共享狀態，以及 Human-in-the-Loop 工作流程放在同一個產品整合層，並支援 React、Angular、Vue、React Native，以及 Slack 和 Microsoft Teams 等使用場景。這個定位很值得 AI 應用開發者關注：Agent 不再只是回答文字，而是能透過事件和狀態，成為既有介面中的一個協作者。

本文不把 CopilotKit 當成「幫聊天機器人換皮」的元件庫，而是從架構、事件流和實作取捨三個角度，拆解它適合解決什麼問題，以及導入前需要先想清楚什麼。

為什麼 Agent 需要一個前端協定層？

傳統聊天機器人的資料流很直線：使用者輸入文字，後端呼叫模型，前端顯示回覆。但一個真正嵌入產品的 Agent，通常同時需要處理四種資訊：

  • 產品上下文：目前頁面、選取的資料、權限範圍與工作階段狀態。
  • 可執行動作：查詢、更新、建立、刪除，或呼叫需要明確授權的工具。
  • 視覺化結果：表格、表單、進度、圖表，以及與目前畫面一致的 UI。
  • 使用者介入：確認高風險操作、補齊欄位、修改 Agent 草稿，或在例外情況接手。

如果每個產品團隊都自行定義串流事件、工具回傳格式和前端狀態同步，整合成本會快速累積。更麻煩的是，Agent 後端一換框架，前端常常也要跟著重寫。CopilotKit 的核心價值，就是試圖把這些跨前後端的互動模式收斂成可重用的 SDK 和協定邊界。

CopilotKit 的三個核心抽象

1. Generative UI：讓結果成為介面，而不只是文字

Generative UI 的重點不是讓模型自由產生任意 HTML，而是讓 Agent 的輸出可以落到產品預先設計好的元件和互動流程。例如，Agent 判斷使用者想要建立一份報價單，前端可以顯示可編輯的表單；Agent 找到多筆資料，前端可以顯示可排序的結果；Agent 需要確認付款，則先呈現明確的核准操作。

這種設計把「模型的推理」和「產品的呈現」分開。模型負責決定下一步意圖與所需資料，產品仍然掌握元件、權限、驗證和視覺一致性。對工程團隊而言，這比讓模型直接輸出一大段 UI 標記更容易測試，也更容易建立安全邊界。

2. Shared State：讓 Agent 看見正確的產品上下文

只把使用者最後一句話送給模型，往往不足以支援真正的產品操作。Agent 可能需要知道目前選取哪一筆訂單、畫面上的篩選條件，或使用者剛剛在表單輸入了什麼。共享狀態層的目標，是讓前端和 Agent 使用同一份、具明確範圍的上下文，而不是在各處複製一份容易過期的 JSON。

這裡要特別強調「具明確範圍」。共享狀態不是把整個瀏覽器狀態都暴露給模型。實務上應該只公開完成任務所需的欄位，並對個人資料、租戶邊界和權限資訊做最小化處理。CopilotKit 提供同步機制，但資料治理仍然是應用程式負責人的工作。

3. Human-in-the-Loop：把接手點設計成流程的一部分

Agent 的可靠性不只取決於模型回答得好不好，也取決於它何時願意停下來。對刪除資料、寄送通知、提交採購或改變權限等操作，理想流程不是完全自動化，而是讓 Agent 在適當節點提出結構化確認。

Human-in-the-Loop 把這種確認變成正式的工作流程：Agent 可以暫停，UI 顯示原因與影響範圍，使用者選擇核准、修改或取消，然後工作流程再繼續。這個模式也讓稽核和測試更清楚，因為「需要人決定」不再藏在一段自然語言提示裡。

從前端到 Agent 的事件流

可以把一個 CopilotKit 應用想成四層：

  1. 應用介面層：React、Angular、Vue 或 React Native 畫面，以及聊天、表單、圖表等元件。
  2. CopilotKit 用戶端層：管理連線、上下文、動作註冊和 UI 更新。
  3. Agent 執行層：由團隊選擇的 Agent 框架或自建服務，負責模型呼叫、工具使用和工作流程。
  4. 事件協定層：以可攜的事件描述狀態變化、工具呼叫、訊息串流和使用者介入。

CopilotKit README 將 AG-UI Protocol 列為其生態系的一部分。AG-UI 的方向，是用事件導向的方式連接 Agent 與使用者介面，讓不同 Agent 框架可以和不同前端表面溝通。這個邊界很重要：前端不必知道每個後端框架的內部實作，後端也不必為每一種 UI 重複設計傳輸格式。

概念上的事件流如下：

使用者操作
  -> 前端送出訊息、狀態或動作
  -> Agent 讀取允許的上下文並執行推理
  -> Agent 發出訊息、工具、狀態或確認事件
  -> CopilotKit 轉成產品元件可以處理的更新
  -> UI 顯示結果，必要時等待人類決策

這不是把所有邏輯搬到前端。相反地，它把「誰負責執行」和「如何讓使用者看懂並控制執行」分開，讓產品可以保留自己的後端和 Agent 策略。

一個最小整合思路

實際 API 會隨版本與框架而變，正式開發應以官方文件為準。從工程設計角度，一個最小整合至少要先定義三件事：Agent 端點、可公開的上下文，以及可被 Agent 請求的動作。

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

export function App() {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit">
      <ProductWorkspace />
      <CopilotChat />
    </CopilotKit>
  );
}

接著，把上下文和動作設計成最小可用介面，而不是把整個應用物件直接傳給模型：

useCopilotReadable({
  description: "目前使用者正在檢視的訂單摘要",
  value: {
    orderId: order.id,
    status: order.status,
    itemCount: order.items.length,
  },
});

useCopilotAction({
  name: "request_order_cancel",
  description: "提出取消訂單的請求，必須等待使用者確認",
  parameters: [
    { name: "reason", type: "string", description: "取消原因", required: true },
  ],
  handler: async ({ reason }) => {
    // 真正寫入資料前，先由產品 UI 顯示確認畫面。
    return { pending: true, reason };
  },
});

這段程式的重點不在函式名稱，而在責任切分：上下文有描述、有範圍；動作有名稱、有參數、有權限和確認邊界。即使未來更換模型或 Agent 框架，產品層的契約仍然可以維持穩定。

導入時最容易忽略的工程問題

權限不能只靠提示詞

「請不要存取其他租戶資料」不是授權系統。每一個 Agent 動作都應在後端重新驗證使用者、租戶、資源和操作權限；前端公開的狀態只能視為輔助上下文，不能當成安全邊界。

可生成 UI 不等於可任意生成介面

推薦採用受控元件目錄。每個元件定義輸入 schema、可接受的狀態與錯誤處理，Agent 只負責選擇和填入。這樣才能避免模型產生不符合設計系統、無法存取，或在不同瀏覽器表現不一致的介面。

事件要能重播與觀測

串流事件一旦進入正式環境，就需要 request ID、使用者與租戶識別、Agent 版本、工具名稱、耗時、結果狀態，以及人工介入點。沒有這些資料，遇到「模型說已完成但畫面沒更新」時，很難判斷是模型、網路、事件轉換，還是前端狀態管理出了問題。

先測流程，再測回答

對 Agent-native 應用，測試不應只比較文字相似度。更有價值的測試包含：錯誤權限是否被拒絕、危險動作是否一定需要確認、工具失敗後是否能恢復、UI 是否能處理事件順序改變，以及重新整理後是否保留正確狀態。

CopilotKit 適合什麼團隊？

如果團隊已經有一個 React 或其他支援的前端產品，並且希望把 Agent 深度嵌入既有流程，而不是另起一個獨立聊天頁面，CopilotKit 值得列入評估。它特別適合以下情境：內部營運工具、資料分析工作台、客服與工單系統、內容編輯器，以及需要人工核准的流程型應用。

如果需求只是「在網站放一個問答視窗」，直接使用現有聊天元件可能更簡單。CopilotKit 的價值會在上下文、動作、共享狀態和介面更新開始互相影響時才真正顯現；同時，這也代表團隊必須投入事件觀測、權限設計和流程測試，不能只把它當成前端套件安裝完就結束。

結語：Agent 的下一個介面是可控制的產品流程

CopilotKit 值得注意的地方，不只是它支援哪個 UI framework，而是它把 Agent 和產品介面之間的空白，具體化成 Generative UI、Shared State、Human-in-the-Loop 和事件協定。這些抽象讓 Agent 從一個等待提問的聊天視窗，變成可以讀取有限上下文、提出動作、更新介面，並在關鍵時刻交還控制權的產品元件。

但它不會自動解決模型幻覺、資料權限或流程風險。比較務實的導入順序是：先挑一個低風險、可量測的工作流程，明確定義上下文與動作契約，再加入確認、觀測和失敗恢復，最後才擴大到更多頁面與通道。這樣才能把「Agent 能做什麼」轉化為「產品允許 Agent 在什麼邊界內可靠地做什麼」。

參考資料

  • GitHub：https://github.com/CopilotKit/CopilotKit
  • 官方文件：https://docs.copilotkit.ai/
  • AG-UI Protocol：https://github.com/ag-ui-protocol/ag-ui
  • CopilotKit 範例：https://www.copilotkit.ai/examples