フレームワーク

CopilotKit入門:AG-UIプロトコルでAgentをWeb/Slack/Teamsに繋ぐ

36.8K starsを集めるCopilotKitは単なるReactチャットUIではなく、AG-UIプロトコルを通じてAgentとフロントエンドを統一的に接続する中間層である。

文字サイズ

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の価値はフロントエンド層にあるので、活用しないなら入れるだけ無駄。

参考リンク

出典: https://github.com/CopilotKit/CopilotKit