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

ワークフロー

1. ランタイムをセットアップする（サーバー）

CopilotRuntime（または明示的な CopilotSseRuntime / CopilotIntelligenceRuntime）を作成し、createCopilotHonoHandler（Hono）または createCopilotExpressHandler（Express）を使って公開します。

import {
  CopilotRuntime,
  createCopilotHonoHandler,
} from "@copilotkit/runtime/v2";
import { LangGraphAgent } from "@copilotkit/runtime/langgraph";
import { handle } from "hono/vercel";

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

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

// Multi-route (the default): export every method the runtime serves.
// useThreads needs them all — rename via PATCH, delete via DELETE; archive
// uses the already-exported POST.
export const GET = handle(app);
export const POST = handle(app);
export const PATCH = handle(app);
export const DELETE = handle(app);

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

@copilotkit/react-core/v2 の CopilotKit プロバイダーを使用します。これは v1 と v2 間の互換性ブリッジであり、従来の CopilotKitProvider のすべての機能を含む上位互換です。すべての CopilotKitProvider のプロパティをそのまま使用できます。

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

function App() {
  return (
    // No useSingleEndpoint: the provider negotiates the transport, so this
    // works against a multi-route handler (the default) and a single-route one
    // alike. Pass the prop only to pin one mode deliberately.
    <CopilotKit runtimeUrl="/api/copilotkit">
      <YourApp />
    </CopilotKit>
  );
}

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

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

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

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

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

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

import { useFrontendTool } from "@copilotkit/react-core/v2";
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-core/v2";

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

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

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

import { useInterrupt } from "@copilotkit/react-core/v2";

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-core/v2";
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 イベントを、レンダーとオプションのハンドラー／enabled 判定関数で処理します
useHumanInTheLoop	レンダリングされた UI からユーザーが応答するまで実行を一時停止するツールを登録します
useRenderTool	ツール呼び出し用のレンダラーを（名前またはワイルドカード "*" で）登録します
useDefaultRenderTool	組み込みの展開可能なカード UI を使用する、ワイルドカード "*" のレンダラーを登録します
useRenderToolCall	指定されたツール呼び出しに適したレンダラーを解決する関数を返す内部フック
useRenderActivityMessage	種類ごとにアクティビティメッセージをレンダリングする内部フック
useRenderCustomMessages	カスタムメッセージのデコレーターをレンダリングする内部フック
useSuggestions	現在の候補リストを読み取り、再読み込み／クリアを制御します
useConfigureSuggestions	静的または動的（LLM 生成）の候補設定を登録します
useThreads	CopilotKit Intelligence のスレッドを一覧表示、名前変更、アーカイブ、削除します

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

コンポーネント	用途
CopilotKit	ルートプロバイダー（@copilotkit/react-core/v2 から）-- ランタイム URL、ヘッダー、エージェント、エラーハンドラーを設定します
CopilotChat	エージェントに接続されたチャットインターフェース（インラインレイアウト）
CopilotPopup	切り替えボタン付きのフローティングポップアップでチャットを表示します
CopilotSidebar	切り替えボタン付きの折りたたみ可能なサイドバーでチャットを表示します
CopilotChatView	メッセージ表示、入力、スクロール、候補用のスロットを備えたヘッドレスチャットビュー
CopilotChatInput	送信／停止／文字起こしのコントロールを備えたチャット入力用テキストエリア
CopilotChatMessageView	メッセージ一覧をレンダリングします
CopilotChatSuggestionView	候補のピルをレンダリングします

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

v2 のランタイムシンボルはすべて @copilotkit/runtime/v2 からインポートします（createCopilotExpressHandler は @copilotkit/runtime/v2/express からインポートします）。

エクスポート	目的
CopilotRuntime	自動検出するランタイム（SSE または Intelligence に処理を委譲）
CopilotSseRuntime	明示的な SSE モードのランタイム
CopilotIntelligenceRuntime	永続スレッドに対応した Intelligence モードのランタイム
createCopilotHonoHandler	すべての CopilotKit ルートを含む Hono アプリを作成
createCopilotExpressHandler	すべての CopilotKit ルートを含む Express ルーターを作成
CopilotKitIntelligence	CopilotKit Intelligence クライアントの設定