CopilotKit完全ガイド｜React/Angularで作るAIエージェント & AG-UI Protocol解説

CopilotKit/CopilotKit

agent ai-agent copilot generative-ui ag-ui react typescript langgraph

2026.05.08 1分

CopilotKit完全ガイド｜React/Angularで作るAIエージェント & AG-UI Protocol解説 - AIツール日本語解説 | AI Heartland

AG-UI Protocolという業界標準を握り、Google・LangChain・AWS・Microsoft・Mastra・PydanticAIに採用された事実上のフロントエンド層。useAgentフックでAIエージェントの状態とUIを双方向同期でき、Generative UIで「AIが画面ごと作る」体験を最短で実装できる。

ReactアプリにAIエージェントを差し込みたい開発者が直面する最大の壁は「LLMからのストリームをUIにどう橋渡しするか」だ。チャットUIだけなら自作で十分だが、ツールコール結果をその場でレンダリングし、エージェント側の状態をフロントと共有し、必要なら人間の確認を待つ──ここまでくると車輪を再発明する余裕は無い。CopilotKit（CopilotKit/CopilotKit） は、その隙間を埋めるためにGitHub Star 30,866・Fork 3,978まで成長したフロントエンド・スタックで、AG-UI Protocolという「エージェントとUIの間の標準プロトコル」を策定した張本人でもある。

AIエージェント全般のフレームワーク選定は AIエージェントフレームワーク完全比較2026：LangGraph・CrewAI・AutoGen・Mastra徹底解説を参照してほしい。

この記事では、CopilotKitの構成・useAgentフックの使い方・Generative UIの3形態・LangGraph連携・v1.50以降に進んだAG-UIネイティブ化の意味を、公式README・公式ドキュメント・リリースノートから整理する。「AIに画面ごと作らせる」設計の現在地を一気に掴むためのリファレンスとして使ってほしい。

この記事のポイント

CopilotKitはReact/Angular用のAIコパイロット・ライブラリ。AG-UI Protocolを策定し、Google・LangChain・AWS・Microsoft・Mastra・PydanticAIに採用された事実上のフロントエンド共通層
v1.50以降はuseAgentフックが提供され、任意のAG-UI互換エージェントへ「フレームワーク非依存」で接続できる。LangGraphもCrewAIもMastraも同じコードで扱える
Generative UIにはStatic（AG-UI）/Declarative（A2UI v0.9）/Open-Ended（MCP Apps & Open JSON）の3形態があり、用途に応じて使い分ける設計
v1.57で「Threads」タブ・registerProxiedAgent・IntelligenceIndicatorが追加され、実プロダクトでの観測性と運用品質が一段引き上げられた

CopilotKitとは何か：Reactにエージェントを織り込むためのフレームワーク

CopilotKitは「フルスタックのエージェント駆動アプリケーション」を作るためのSDKだ。READMEの自己紹介に従えば「best-in-class SDK for building full-stack agentic applications, Generative UI, and chat applications」と表現される領域を担う。@copilotkit/react-core と @copilotkit/react-ui の2パッケージを入れるだけで、チャットUI・ツールコール結果のUIレンダリング・エージェント状態の同期・Human-in-the-Loopの4機能が揃う。

主要機能は公式READMEに以下のように整理されている。

Chat UI：メッセージのストリーミング・ツールコール・エージェントの応答を扱うReactベースのチャットインターフェース
Backend Tool Rendering：エージェントがバックエンドのツールを呼び出し、その結果を「UIコンポーネント」としてクライアントに直接描画させる
Generative UI：ユーザーの意図とエージェントの状態に応じて、UIコンポーネントを実行時に生成・更新する
Shared State：エージェントとUIコンポーネントの双方が同じ状態に対して読み書きできる同期レイヤー
Human-in-the-Loop：エージェントが処理を一時停止して、ユーザーの入力・確認・編集を待ってから再開する仕組み

検証環境: Node.js 20 LTS / Next.js 15 / React 19 / CopilotKit v1.57.0 / 確認日 2026-05-07。npx copilotkit@latest initが@copilotkit/react-core・@copilotkit/react-ui・@copilotkit/runtimeを最新版で導入し、CopilotKitプロバイダの設定を雛形として書き出すところまで動作確認済み。

v1.57までのリリースで何が変わったのか

CopilotKitの直近のリリースは「AG-UIネイティブ化 → パッケージ統合 → 観測性・運用機能」の3段で進化してきた。GitHubの公式リリースノートを縦に読むと、各バージョンの位置付けは次のように整理できる。

バージョン	公開時期	主要な変化
v1.50.x	2025-12	プロジェクト全体をAG-UIネイティブに再構築。`useAgent`フックを導入
v1.55.3	2026-04	`@copilotkitnext/` を `@copilotkit/` に統合（v2は`/v2`サブパス）。A2UI v0.9 + Open Generative UI対応
v1.56.0	2026-04	単一の`debug`フラグでフルスタックにPII-safeログ。LangGraphプリビルドのstate streaming対応
v1.56.5	2026-04	LangGraph state injection（`ExposeStateOption`）、画像添付の80×80サムネ表示、Express 4/5互換
v1.57.0	2026-05	Web InspectorにThreadsタブ。`registerProxiedAgent`API、`IntelligenceIndicator`の自動マウント、OAuth-gated MCP HTTP向け`requiresUser`フラグ

特に重要なのが v1.50 と v1.55.3 だ。前者は「同じCopilotKitでもAG-UI互換ならどんなエージェントでも繋がる」という思想転換で、後者は分裂していた next 系パッケージを本流に統合してDXを単純化した。v1.57は「Threadsタブで会話履歴・エージェント状態・イベントストリームを一覧できる」という、本番運用に直結する観測性が乗ってきたバージョンだ。

AG-UI Protocolとは：エージェント↔UIの双方向ランタイム

AG-UIは「Agent-User Interaction Protocol」の略で、ユーザーアプリと任意のエージェント・バックエンドの間に張る双方向ランタイム接続を定義する。CopilotKitはこのプロトコルの策定者で、READMEには「Adopted by Google, LangChain, AWS, Microsoft, Mastra, PydanticAI, and more」と明記されている。つまり、フロントエンドからは1つのプロトコル仕様に沿って実装すれば、バックエンドのエージェント実装が何であっても繋ぎ替えが効く。

flowchart LR subgraph FE["フロントエンド (React/Angular)"] UI["UIコンポーネント
useAgent / useCoAgent"] CK["CopilotKit Provider
状態同期・イベント購読"] end subgraph PROTO["AG-UI Protocol"] EV["イベントストリーム
(messages, state, tool_calls)"] ST["共有状態
(SharedState)"] HIL["Human-in-the-Loop
(interrupt / resume)"] end subgraph BE["エージェント・バックエンド"] LG["LangGraph"] CW["CrewAI"] MA["Mastra"] PA["PydanticAI"] AS["AWS Agents"] end UI <--> CK CK <--> EV CK <--> ST CK <--> HIL EV <--> LG EV <--> CW EV <--> MA EV <--> PA EV <--> AS

このアーキテクチャの実利は3つある。第一に「フレームワーク非依存」──LangGraphで書いたエージェントを後からMastraに置き換えても、フロント側のコードはほとんど触らずに済む。第二に「ストリーミング・ツールコール・状態同期が標準化」──各バックエンドのSDK差分を吸収しなくていい。第三に「第三者がAG-UI互換のエージェントを公開できる」──マーケットプレイス的な拡張性を持つ。useAgentはAG-UIだけに依存するため、同一のUIコードが任意のAG-UIエンドポイントに対して動く。

Generative UIの3形態：Static / Declarative / Open-Ended

公式READMEではGenerative UIを次の3つのタイプに分類している。CopilotKitのGenerative UI仕様は2025年末から急速に整備が進んだ領域で、用途とコントロール度合いに応じて使い分けるのが基本設計だ。

タイプ	仕様名	何を生成するか	開発者の自由度	主な用途
Static	AG-UI Protocol	事前に定義済みのコンポーネントへの「埋め込みデータ」	最も高い（自前定義）	プロダクト固有のUIに合わせた埋め込み
Declarative	A2UI v0.9	スキーマ駆動の宣言的UI（フォーム・リスト・カード）	中程度（スキーマ準拠）	業務アプリ・社内ツール
Open-Ended	MCP Apps & Open JSON	エージェントが任意のJSONを返し、サンドボックス側で解釈	最も低い（実行時生成）	MCP拡張・チャット内のアドホックUI

Static型はCopilotKitのuseCopilotActionやrenderAndWaitForResponseを使う実装で、開発者が用意したコンポーネントにエージェントが「データを差し込む」モデルだ。Declarative型はA2UI v0.9のスキーマに準拠したJSONをエージェントが返し、CopilotKit側のレンダラがその通りにフォームやカードを描画する。Open-Ended型は最も野心的で、MCP Appsという仕組みを介してサンドボックス内で任意のUIを動的に組み立てる。CopilotKit v1.55.3では「BYOC (Bring Your Own Catalog)」と呼ばれる仕組みでサンドボックス・レンダリングをセキュアに抑え込めるようになった。

5分で動かす：CopilotKit初期セットアップ

最短ルートは公式CLIだ。新規プロジェクトにはcreate、既存プロジェクトにはinitを使う。READMEに掲載されているコマンドをそのまま使う。

# 新規プロジェクト（フレームワーク指定）
npx copilotkit@latest create -f next-openai

# 既存プロジェクトに組み込む
npx copilotkit@latest init

このCLIは(1)コアパッケージのインストール、(2)CopilotKitプロバイダの設定、(3)エージェントとUIを繋ぐルーティング、(4)サンプルコードまで一気に整える。Next.js + LangGraphを選んだ場合、/api/copilotkitにRuntime Handlerが配置され、フロントの<CopilotKit>はそこを向く。

最低限のNext.js統合コードは次の通りだ（公式ドキュメントの構造を再構成したもの）。

// app/layout.tsx
import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ja">
      <body>
        <CopilotKit runtimeUrl="/api/copilotkit" agent="my_agent">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}

// app/page.tsx
"use client";
import { CopilotChat } from "@copilotkit/react-ui";

export default function Page() {
  return (
    <CopilotChat
      labels=
      className="h-screen"
    />
  );
}

// app/api/copilotkit/route.ts
import { CopilotRuntime, OpenAIAdapter, copilotRuntimeNextJSAppRouterEndpoint } from "@copilotkit/runtime";
import OpenAI from "openai";

const openai = new OpenAI();
const runtime = new CopilotRuntime();

export const POST = async (req: Request) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter: new OpenAIAdapter({ openai }),
    endpoint: "/api/copilotkit",
  });
  return handleRequest(req);
};

これで「画面右下にチャットUIが出て、OpenAIモデルと会話できる」最小構成が完成する。ここから先、useCopilotActionでアプリ固有のツールを公開し、useCopilotReadableでアプリ状態をエージェントに読ませ、useAgent/useCoAgentでエージェントの状態をフロントと双方向に共有していく流れになる。

4つの主要フック：useAgent / useCoAgent / useCopilotAction / useCopilotReadable

CopilotKitの設計を理解する近道は、提供される4つのフックの責務を分けて見ることだ。

// useAgent — AG-UIネイティブな低レベル制御（v1.50以降）
import { useAgent } from "@copilotkit/react-core";

const { agent } = useAgent({ agentId: "my_agent" });

return (
  <div>
    <h1>{agent.state.city}</h1>
    <button onClick={() => agent.setState({ city: "NYC" })}>Set City</button>
  </div>
);

useAgentはAG-UIプロトコルだけに依存する素のフックで、エージェントのイベントストリームに購読し、メッセージと共有状態のローカルモデルを保持する。useCoAgentはuseAgentを内包した高レベルAPIで、CopilotKit由来の追加機能（自動UI同期・チャット連携など）を含む。新規実装で「とにかく細かく制御したい」場合はuseAgent、CopilotKitの世界に乗っかるならuseCoAgentを選ぶ。

// useCopilotAction — アプリの「動詞」をエージェントに公開する
import { useCopilotAction } from "@copilotkit/react-core";

useCopilotAction({
  name: "addTodo",
  description: "タスクを追加する",
  parameters: [
    { name: "title", type: "string", description: "タスク名", required: true },
    { name: "due", type: "string", description: "ISO 8601" },
  ],
  handler: async ({ title, due }) => {
    await fetch("/api/todos", { method: "POST", body: JSON.stringify({ title, due }) });
    return "ok";
  },
});

useCopilotActionはアプリ側の「動詞」をツールとしてエージェントに公開する。エージェントは自然言語の指示からこのアクションを呼び出せるため、UIに対するコマンドパレットを丸ごとAIに任せられる。renderやrenderAndWaitForResponseを併用すれば、ツールの実行結果をUIコンポーネントとして直接表示することもでき、これがStatic型Generative UIの実体になる。

// useCopilotReadable — アプリ状態をエージェントに読ませる
import { useCopilotReadable } from "@copilotkit/react-core";

useCopilotReadable({
  description: "現在ログイン中のユーザー",
  value: { id: user.id, name: user.name, plan: user.plan },
});

useCopilotReadable({
  description: "選択中のフィルター",
  value: filters,
});

useCopilotReadableはアプリ状態をエージェント側のコンテキストに流し込む仕組みで、各useCopilotReadableのvalueはAG-UI経由でエージェントに送られる。RAG的な「外部知識」ではなく、現在画面で何を見ているのかというセッション状態を渡すのに使う。

LangGraph連携と他のエージェント・フレームワーク

CopilotKitの最大の強みは「LangGraphとの一級市民の統合」を持ちつつも、それに縛られないことだ。v1.56でstate streamingがプリビルド版LangGraphエージェントでも標準化され、v1.56.5ではExposeStateOptionによるLangGraph state injectionがミドルウェアレイヤーに追加された。

公式ドキュメント上のクイックスタート（docs.copilotkit.ai/langgraph/quickstart）はLangGraphを前提にしている一方で、CrewAI・Mastra・PydanticAIといった他のフレームワークもAG-UIエンドポイントを公開すれば同じUI側コードで動く。これは前述の「AG-UIネイティブ化」がもたらす最大の運用メリットで、バックエンドのエージェント・フレームワークが頻繁に入れ替わる現場ほど効いてくる。

LLM側の選定（Claude / GPT / Gemini / ローカルモデル）はLLM完全ガイド2026：オープンソースLLM・量子化・推論最適化を最短理解で扱っているので、モデル戦略と合わせて読むと全体像が掴みやすい。

競合フレームワークとの比較

「ReactにAIを差し込む」領域で参照されることが多いのは Vercel AI SDK、Microsoft Copilot Studio、LangChain.js のChatbotテンプレート、独自実装の4種類だ。それぞれの守備範囲をCopilotKitと並べて比べておく。

観点	CopilotKit	Vercel AI SDK	Copilot Studio	独自実装
ライセンス	MIT	Apache 2.0	プロプライエタリ	—
主な利用層	フロント + エージェント連携	フロント + LLM呼び出し	ノーコード/SaaS	フルスクラッチ
Generative UI仕様	AG-UI / A2UI / MCP Apps を網羅	RSCベース	プラットフォーム独自	自作
エージェント・FW結合	LangGraph / CrewAI / Mastra / PydanticAI	LangChain中心	Microsoft Copilot系	任意
Human-in-the-Loop	公式サポート	限定的	あり	自作
共有状態の同期	`useCoAgent`で双方向	RSC側で擬似的	限定的	自作
プロトコル標準化	AG-UI策定者	自社実装	独自	—
観測ツール	Threadsタブ・debugフラグ	OpenTelemetry	Power Platform	—

CopilotKitは「アプリ内蔵型のエージェントUIを、できる限り標準仕様の上で組む」という立ち位置だ。Vercel AI SDKがLLM呼び出しのDXに寄っているのに対し、CopilotKitはエージェント・ワークフローと共有状態に重心がある。「単発のチャット」ならVercel AI SDK、「ステートフルなエージェントを画面に常駐させる」ならCopilotKit、と覚えておくと選びやすい。

v1.57の新機能：Threadsタブ・registerProxiedAgent・IntelligenceIndicator

v1.57で追加された機能は、開発体験よりも本番運用の品質に効くものが多い。Web Inspectorに新設された「Threads」タブでは、(1) 過去会話の履歴、(2) 各時点のエージェント状態、(3) AG-UIで流れたイベントストリーム、の3軸を一画面で確認できる。本番でユーザーから「あの時の挙動がおかしい」と言われたとき、再現に必要な情報がほぼ揃う。

registerProxiedAgent APIは、サーバー側で定義済みのランタイムエージェントに対して、フロントエンド側のエージェントをマウントするための仕組みだ。マルチテナントなアプリで、テナントごとに異なるエージェント設定を切り替えるユースケースに直接効く。IntelligenceIndicatorはインテリジェンス（AIが何かしている状態）が設定されているときに自動でマウントされるUIで、ユーザーに「AIが処理中である」ことを明示的に伝える役割を持つ。OAuthが必要なMCP HTTPサーバ向けのrequiresUserフラグも同時に追加された。

アンチパターンと運用上の注意

最後に、CopilotKitを実プロダクトに入れるときに踏みやすいワナを整理しておく。

実装でハマりやすいポイント

useCopilotReadableに巨大データを流し込む — トークンを食い潰す。要約 or RAGに移すべき領域
useCopilotActionをUI状態だけに使う — 副作用のある「動詞」を公開する設計が本筋。状態取得はuseCopilotReadable
Generative UIのOpen-Ended型を信頼境界の内側で使う — サンドボックス・レンダリング前提。BYOC catalogsで明示的に許可
Human-in-the-Loopを「同期API」と勘違いする — interrupt → resumeのライフサイクルを設計に入れる
v1とv2のパッケージ混在 — v1.55.3でv2は/v2サブパスに統合済み。@copilotkitnext/*は古い名前空間

特に「useCopilotReadableに巨大データ」の問題は実プロダクトで頻発する。CopilotKitのreadableはエージェントのコンテキストにそのまま積まれるため、テーブル全件をそのまま流すとトークンが指数的に膨らむ。フィルター済みの行・要約・IDだけ渡してエージェント側でツール経由で取りに行く設計が本筋だ。

CopilotKitが向いている／向いていないユースケース

公式ポジショニングと実装可能性から、CopilotKitが特に効くのは次のような構造を持つアプリだ。

画面ごとにコンテキストが変わる業務アプリ：フィルター・選択行・ロールに応じてエージェントの振る舞いを変えたい
ステートフルなマルチターン作業：データの一覧 → 絞り込み → 編集 → 確認 → コミット、という流れをエージェントに任せたい
エージェント・FWを将来差し替える可能性がある場合：AG-UIで切り離しておけば、LangGraphからMastraへの移行がフロントエンド変更なしに可能
MCPサーバーをそのまま画面に出したい：Open-Ended Generative UIで動的UIをレンダ

逆に、(1)単発のRAGチャットボットだけ欲しい、(2)Pythonのみで完結したい、(3)WordPressに埋めるブログ用ボット、といったケースではVercel AI SDKや他の軽量実装で十分なことが多い。CopilotKitは「エージェントが画面のファーストクラス市民である」前提のアプリでこそ真価を発揮する。

まとめ

CopilotKitを採用する判断軸

AG-UI Protocolが業界標準として広がる現状で、フロントエンド側を1つに揃える「保険」として最も合理的な選択肢
useAgentでフレームワーク非依存にしておけば、バックエンドのエージェント実装の進化に振り回されない
Generative UIの3形態（Static / Declarative / Open-Ended）を理解しておくと、見た目の派手さに釣られず適切な抽象を選べる
v1.57のThreadsタブ・registerProxiedAgent・IntelligenceIndicatorで本番運用品質が一段上がった。観測性を要件に入れるなら最新版を採用したい
useCopilotReadableに巨大データを流さない・Open-EndedはBYOCで境界を引く──この2点を守れば実装でハマるリスクは大きく下がる

CopilotKitは「ChatGPT風UIをアプリに入れる」域を超えて、「エージェントとUIの双方向ランタイム」を標準仕様の上で組むためのフロントエンド・スタックに育った。AG-UIをGoogle・LangChain・AWS・Microsoft・Mastra・PydanticAIが採用した現状は、フロントエンド側でこのプロトコル互換性を確保しておく価値が高いことを示している。React/AngularでAIエージェント体験を作るなら、まずはnpx copilotkit@latest createで公式テンプレートを動かし、AG-UIの考え方とフックの責務分担に慣れるところから始めるのが最短だ。