copilotkit-develop

CopilotKit v2 開発スキル

ライブドキュメント（MCP）

このプラグインには、ライブの CopilotKit ドキュメントとソースコードを検索するための search-docs および search-code ツールを提供する MCP サーバー（copilotkit-docs）が含まれています。

• Claude Code： プラグインの .mcp.json によって自動設定されるため、セットアップは不要です。
• Codex： 手動での設定が必要です。セットアップ手順については、copilotkit-debug スキルを参照してください。

アーキテクチャの概要

CopilotKit v2 は AG-UI プロトコル（@ag-ui/client / @ag-ui/core）を基盤としています。スタックは次の 3 層で構成されています。

1. Runtime（@copilotkit/runtime）-- サーバー側です。エージェントをホストし、SSE/Intelligence トランスポート、ミドルウェア、文字起こしを処理します。
2. Core（@copilotkit/core）-- 状態管理、ツールレジストリ、提案エンジンを共有します。アプリから直接インポートすることはありません。
3. React（@copilotkit/react）-- プロバイダー、チャットコンポーネント、フックを提供します。@ag-ui/client のすべてを再エクスポートするため、アプリで必要なインポートは 1 つだけです。

ワークフロー

1. ランタイムを設定する（サーバー）

CopilotRuntime（または明示的な CopilotSseRuntime / CopilotIntelligenceRuntime）を作成し、createCopilotEndpoint（Hono）または createCopilotEndpointExpress（Express）を通じて公開します。

import { CopilotRuntime, createCopilotEndpoint } from "@copilotkit/runtime";
import { LangGraphAgent } from "@ag-ui/langgraph";

const runtime = new CopilotRuntime({
  agents: {
    myAgent: new LangGraphAgent({ /* ... */ }),
  },
});

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

2. プロバイダーでアプリをラップする（クライアント）

import { CopilotKitProvider } from "@copilotkit/react";

function App() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <YourApp />
    </CopilotKitProvider>
  );
}

3. チャット UI を追加する

<CopilotChat>、<CopilotPopup>、または <CopilotSidebar> を使用します。

import { CopilotChat } from "@copilotkit/react";

function ChatPage() {
  return <CopilotChat agentId="myAgent" />;
}

4. フロントエンドツールを登録する

エージェントがブラウザー内の関数を呼び出せるようにします。

import { useFrontendTool } from "@copilotkit/react";
import { z } from "zod";

useFrontendTool({
  name: "highlightCell",
  description: "Highlight a spreadsheet cell",
  parameters: z.object({ row: z.number(), col: z.number() }),
  handler: async ({ row, col }) => {
    highlightCell(row, col);
    return "done";
  },
});

5. アプリケーションコンテキストを共有する

実行時データをエージェントに提供します。

import { useAgentContext } from "@copilotkit/react";

useAgentContext({
  description: "The user's current shopping cart",
  value: cart, // any JSON-serializable value
});

6. エージェントの割り込みを処理する

エージェントが人間からの入力を待つために一時停止したときに処理します。

import { useInterrupt } from "@copilotkit/react";

useInterrupt({
  render: ({ event, resolve }) => (
    <div>
      <p>{event.value.question}</p>
      <button onClick={() => resolve({ approved: true })}>Approve</button>
    </div>
  ),
});

7. チャット内にツール呼び出しを表示する

ツールの実行時にカスタム UI を表示します。

import { useRenderTool } from "@copilotkit/react";
import { z } from "zod";

useRenderTool({
  name: "searchDocs",
  parameters: z.object({ query: z.string() }),
  render: ({ status, parameters, result }) => {
    if (status === "executing") return <Spinner>Searching {parameters.query}...</Spinner>;
    if (status === "complete") return <Results data={result} />;
    return <div>Preparing...</div>;
  },
}, []);

クイックリファレンス：フック

フック	目的
useFrontendTool	エージェントがブラウザー内で呼び出せるツールを登録します
useComponent	React コンポーネントをチャットに表示するツールとして登録します（useFrontendTool を使いやすくするラッパーです）
useAgentContext	JSON にシリアライズ可能なアプリケーションの状態をエージェントと共有します
useAgent	エージェント ID に対応する AbstractAgent インスタンスを取得し、メッセージ／状態／実行ステータスの変更を購読します
useInterrupt	エージェントからの on_interrupt イベントを、レンダリングとオプションのハンドラー／フィルターで処理します
useHumanInTheLoop	レンダリングされた UI を通じてユーザーが応答するまで実行を一時停止するツールを登録します
useRenderTool	ツール呼び出しのレンダラーを登録します（名前またはワイルドカード "*" を指定）
useDefaultRenderTool	組み込みの展開可能なカード UI を使うワイルドカード "*" レンダラーを登録します
useRenderToolCall	指定されたツール呼び出しに適切なレンダラーを解決する関数を返す内部フックです
useRenderActivityMessage	種類に応じてアクティビティメッセージをレンダリングする内部フックです
useRenderCustomMessages	カスタムメッセージデコレーターをレンダリングする内部フックです
useSuggestions	現在の提案リストを読み取り、再読み込み／クリアを制御します
useConfigureSuggestions	静的または動的（LLM が生成する）提案設定を登録します
useThreads	Intelligence プラットフォームのスレッドを一覧表示、名前変更、アーカイブ、削除します

クイックリファレンス：コンポーネント

コンポーネント	目的
CopilotKitProvider	ルートプロバイダーです。ランタイム URL、ヘッダー、エージェント、エラーハンドラーを設定します
CopilotChat	エージェントに接続された完全なチャットインターフェースです（インラインレイアウト）
CopilotPopup	切り替えボタン付きのフローティングポップアップでチャットを表示します
CopilotSidebar	切り替えボタン付きの折りたたみ可能なサイドバーでチャットを表示します
CopilotChatView	メッセージビュー、入力、スクロール、提案用のスロットを備えたヘッドレスなチャットビューです
CopilotChatInput	送信／停止／文字起こしコントロール付きのチャット入力テキストエリアです
CopilotChatMessageView	メッセージリストをレンダリングします
CopilotChatSuggestionView	提案をピル形式でレンダリングします

クイックリファレンス：ランタイム

エクスポート	目的
CopilotRuntime	自動検出ランタイム（SSE または Intelligence に処理を委譲します）
CopilotSseRuntime	SSE モード専用ランタイム
CopilotIntelligenceRuntime	永続スレッドを備えた Intelligence モードのランタイム
createCopilotEndpoint	CopilotKit のすべてのルートを含む Hono アプリを作成します
createCopilotEndpointExpress	CopilotKit のすべてのルートを含む Express ルーターを作成します
CopilotKitIntelligence	Intelligence プラットフォームのクライアント設定