CopilotKit入門:AG-UIプロトコルでAgentをWeb/Slack/Teamsに繋ぐ
何解決什么问题
ここ数年、Agent向けバックエンドフレームワークは群雄割拠だ。LangGraph、AutoGen、LlamaIndex、CrewAI——どれを選ぶか考えるだけで頭が痛い。ところがフロントエンド側はずっと放置されてきた。Agentが吐き出すtoken streamをどう描画する?Agentがユーザーに操作確認を求めるには?Agentがフォームやチャートを出したいとき、UIはどう反応する?
こうした質問は10回以上されてきた。LangGraphでAgentを組み、ローカルでは快調に動くのに、Webに繋いだ瞬間に行き詰まる——SSEを自前で書き、tool_callを処理し、中間状態をReactのstateに詰め込む。糊付けコード300行を書いて、やっと本題に入れる。
CopilotKitはAgentとユーザーの中間層を目指している。同じAgentがReact製Webページを駆動しつつ、Slack・Microsoft Teams・iMessageでも動く。Human-in-the-loopの承認フローにも対応する。Agentフレームワークの領域には踏み込まず、「ラストワンマイル」だけを請け負う——Agentの出力を拾い、UIからのフィードバックを返す。
分析時点でリポジトリは36,880 stars、MITライセンス、TypeScript中心でPython Runtimeも提供する。
使い方
npx copilotkit@latest create一発で雛形が手に入り、OpenAIまたはAnthropicのキーを設定すれば動く。
最小コード例:
import { CopilotKit } from "@copilotkit/react-core";
import { CopilotChat } from "@copilotkit/react-ui";
function App() {
return (
<CopilotKit runtimeUrl="/api/copilotkit">
<CopilotChat
instructions="你是一个订单助手,可以调用工具修改订单状态"
labels={{
title: "订单助手",
initial: "你好,问我任何订单问题",
}}
/>
</CopilotKit>
);
}
PythonバックエンドはFastAPIにRuntimeをマウントする:
from copilotkit import CopilotKitSDK, LangGraphAgent
from fastapi import FastAPI
app = FastAPI()
sdk = CopilotKitSDK(
agents=[
LangGraphAgent(
name="order_agent",
graph=my_langgraph,
# 关键:声明前端可调用的 tool
frontend_tools=["update_order_status", "render_invoice"],
)
]
)
app.mount("/api/copilotkit", sdk)
Agentはバックエンドtoolだけでなく「フロントエンドtool」も呼び出せる。例えばupdate_order_status——Agentがこれを呼ぶと、UI側のテーブルで変更行がリアルタイムにハイライトされる。WebSocketでイベントを流して自前でパースする必要はなく、CopilotKitが状態同期を代行する。
仕組み
アーキテクチャは3層構成:
① AG-UIプロトコル層——SSEベースイベントストリームプロトコル。Agentとフロントエンド間の16種類のイベントタイプを定義し、メッセージ・tool呼び出し・状態同期・人間介入リクエストを網羅する。AG-UIはCopilotKitチームが今年7月に寄贈したオープンプロトコルで、Google、LangChain、AWS、Microsoft、Mastra、PydanticAIが採用している。オープンソース主導のAgent通信規格として稀有な存在だ。
② CopilotKit Runtime——NodeまたはPythonバックエンドで、Agentフレームワークを橋渡しする。LangGraph、AutoGen、自作ReActなど問わず、LangGraphAgentやAutogenAgentで包めば、Runtimeが自動的に出力をAG-UIイベントへ変換する。
③ フロントエンドSDK——React、Angular、Vue、React Native、Slack、Microsoft Teams向けのアダプタ層。中核パッケージ@copilotkit/react-coreはnpmパブリックレジストリで配布され、プロトコルイベントを描画可能なUIコンポーネントに変換する。
このアーキテクチャで最も価値を感じるのはAG-UIそのものではなく、Shared Stateだ。Agentとフロントエンドが同じ状態オブジェクトを共有する。AgentはUI状態を読み取れ(「今ユーザーがどの注文を見ているか」など)、UIもAgentの状態変更に反応できる(「Agentが注文を発送済みに変更した」など)。双方向同期で、reconcile処理を手書きする必要はない。
強みと弱み
強み:
- AG-UIはオープンソース主導の数少ないAgent通信規格。Google、AWS、Microsoftが揃って賛同している点はAgent界隈では異例だ。
- マルチプラットフォーム統一は確かに痛い課題。Web、Slack、Teams、iMessageで同じAgentが動かし、再利用されるのはバックエンドロジックであってUIコードではない。
- Generative UI(Agentが動的に表示コンポーネントを決める)はVercel AI SDKより踏み込んでいる。Vercelの
streamUIは主に「token stream描画」を解決するが、CopilotKitはAgentにフォーム・チャート・承認カードといった完全なコンポーネントを能動的に生成させられる。
弱み:
- 日本語ドキュメントが薄い。公式docsは英語優先で、コミュニティ翻訳も断片的。
- Angular、Vue、React Native対応はReactと比べて明らかに弱い。Reactがファーストクラスで、他プラットフォームは動くがAPIが揃っていない。
- 36.8K starsのうちかなりの割合はAG-UIプロトコルの光环であり、実SDKの学習コストはLangChainより高い。LangChainは概念が単純だが、CopilotKitはRuntime・Agent・Tool・Stateの4層を理解する必要があり、初心者には急峻なカーブ。
- 中核パッケージ
@copilotkit/react-coreはgzip後で80KB程度。SDKサイズに敏感な小規模プロジェクトには無視できない数字。
実際に試してみた
公式create雛形を動かし、5分以内にReact + Python FastAPIバックエンドのdemoを立ち上げた。LangGraph Agentを接続し、update_order_statusフロントエンドtoolを呼び出させると、UI側のテーブルで変更行がリアルタイムにハイライトされた。
Shared State同期の遅延は体感ではほぼゼロ。コンソールにタイムスタンプを出してみたところ、Agentがtoolを呼んでからReactコンポーネントがstate更新を受け取るまでの間隔は50ms以内だった。
以前、純粋なLangGraphでSSEストリーム処理を自前実装した時と比べて、糊付けコードが約200行削減できた——主にtool_call解析、中間状態蓄積、エラーリトライ。
意外な発見:CopilotKitのGenerative UIは単なる「token描画」ではなく、Agentに<form>、<button>、<chart>といった完全なコンポーネントを能動生成させる。human-in-the-loopイベントタイプと組み合わせれば、Agentの処理途中で「送信してよろしいですか?」とユーザーに確認し、UIが確認ダイアログを出し、ユーザーがクリックしたらAgentが再開する。この承認フロー用の状態マシンを自前で書く必要はない。
どんな人に向くか
向いているケース:
- ToB SaaSにAIアシスタント機能を追加したいが、Web・Slack・Teamsなど各プラットフォームごとに書き直したくないチーム。CopilotKitの最大の得意領域。
- Generative UI(Agentがフォームやチャートを自分で決めるUI)を実現したい人。
- LangGraph/AutoGenを使いたいがフロントエンド統合でつまずいている人。Runtimeがすでにアダプタを用意している。
向いていないケース:
- チャット画面が欲しいだけの人。Vercel AI SDKの
useChatのほうが軽量で依存も少ない。 - SDKサイズに敏感な小規模プロジェクト(中核パッケージ80KB gzip)。
- マルチプラットフォーム展開しない純粋なCLI/バックエンドのみのAgent。CopilotKitの価値はフロントエンド層にあるので、活用しないなら入れるだけ無駄。
参考リンク
- GitHubリポジトリ:https://github.com/CopilotKit/CopilotKit
- AG-UIプロトコル仕様:リポジトリdocs配下にイベントタイプ定義一式
- npmパッケージ:https://www.npmjs.com/package/@copilotkit/react-core