react-core

CopilotKit React Core

@copilotkit/react-core は、CopilotKit の React フロントエンド側です。プロバイダーをマウントし、SSE 経由でランタイムと AG-UI 通信を行う（または SPA モードでは CopilotKit Intelligence と直接通信する）ほか、あらゆるインタラクション面に対応するフックを提供します。

この SKILL.md はインデックスです。タスクに合った references/ 内のリファレンスを読んでください。このファイルだけでパッケージ全体を把握しようとしないでください。

メンタルモデル — 組み合わせて使う3つのシェル

1. プロバイダーシェル — ルート、またはその近くに配置する CopilotKit プロバイダー（@copilotkit/react-core/v2 からインポートします。Next.js App Router では "use client" の中に配置します）。runtimeUrl（必須）、headers、credentials、properties、onError、debug、enableInspector を保持します。
2. チャットシェル — CopilotChat／CopilotPopup／CopilotSidebar、または組み合わせて使う CopilotChatView とスロットプリミティブ（CopilotChatInput、CopilotChatMessageView など）。すべてのチャットコンポーネントは @copilotkit/react-core/v2 から提供されます。CopilotPanel は存在しません — よくある誤った生成内容です。
3. フックシェル — プロバイダー配下の任意のコンポーネント内で、useAgent、useFrontendTool、useRenderTool などを呼び出します。すべてのフックで、エージェント単位の登録に使用する省略可能な { agentId } を指定できます。

どのリファレンスをいつ読み込むか

タスク	リファレンス
CopilotKit プロバイダーをマウントし、runtimeUrl をランタイムに設定し、RSC の境界ルールを確認する	references/provider-setup.md
CopilotChat / CopilotPopup / CopilotSidebar を配置し、スロットプリミティブで CopilotChatView を構成する	references/chat-components.md
useAttachments によるファイル／画像の添付 — ドラッグ＆ドロップ、クリック、貼り付け、カスタムアップロード	references/attachments.md
クライアント側のデバッグツール — enableInspector、debug プロパティ、遅延読み込みされるウェブインスペクター	references/debug-mode.md
エージェントを読み取る／サブスクライブする（useAgent）、グローバルコンテキストをプッシュする（useAgentContext）	references/agent-access.md
宣言されたエージェントの機能に基づいて UI の表示を制御する（useCapabilities）	references/capabilities.md
マルチエージェント UI を構築する（パネルごとの useAgent、エージェントスコープのツール、キーによる再マウントのパターン）	references/switching-agents.md（具体的なレイアウトについては switching-agents-recipes.md）
永続的な Intelligence スレッドを一覧表示／名前変更／アーカイブ／削除する（useThreads）	references/threads.md（ランタイムの Intelligence モードが必要です）
ブラウザー側のツールを登録する（useFrontendTool）	references/client-side-tools.md
ツールごとの UI をレンダリングする（useRenderTool、useComponent、useDefaultRenderTool、useRenderToolCall）	references/rendering-tool-calls.md
ユーザーの承認を得てからツールの実行を許可する（useHumanInTheLoop）	references/human-in-the-loop.md
動的または静的な候補のピルを設定する（useConfigureSuggestions、useSuggestions）	references/suggestions.md
チャット以外のアクティビティメッセージをレンダリングする（useRenderActivityMessage）	references/rendering-activity-messages.md
特定のメッセージの前後にカスタム UI を挿入する（useRenderCustomMessages）	references/custom-message-renderers.md

不変条件と注意点（参照する前に一度だけ読み込んでください）

• runtimeUrl は必須です。指定しない場合、プロバイダーは本番環境でエラーをスローします。CopilotKit Intelligence はプロバイダーではなく、ランタイムで設定します。
• agents__unsafe_dev_only と selfManagedAgents は、開発環境専用の相互に置き換え可能なエイリアスです。本番環境での使用には適していません。 サポートされている SPA の方法については、packages/a2ui-renderer または spa-without-runtime ライフサイクルスキルを参照してください。
• CopilotPanel は存在しません。v2 のチャットコンポーネントは react-core/v2 から提供されます。react-ui ではありません（v2 の react-ui は CSS のみです）。
• useAgents() フックは存在しません。copilotkit.subscribe({ onAgentsChanged }) でエージェントを検出してください。
• useRenderToolCall は（カスタムのチャットサーフェス向けの）リゾルバーであり、登録用のフックではありません。useRenderTool / useComponent / useDefaultRenderTool で登録してください。
• UI キットの検出ルール — render またはツール呼び出しの UI では、素の JSX を記述する前に、必ず利用者の shadcn / MUI / Chakra / Ant / Mantine のプリミティブを再利用してください。これは client-side-tools、rendering-tool-calls、human-in-the-loop のすべてに適用されます。
• ツール呼び出しの status 値はキャメルケースです：'inProgress' | 'executing' | 'complete'。進行中の引数は Partial<T> です。
• useHumanInTheLoop で合成されるハンドラーは、必ず respond(result) を呼び出す必要があります（拒否する場合も含みます）。呼び出さないと、エージェントの実行が停止したままになります。Executing ステータス以外では respond は undefined です。実行中にアンマウントすると、実行は中断されます。
• Intelligence モード以外では、useThreads は 'Runtime URL is not configured' エラーになります。
• useAgent は { agent, isReady } を返します。isReady が false の間、agent は仮の代替インスタンスであり、/info の解決時に実際のインスタンスへ置き換えられます。その際、agent の参照が変わり、これに依存するすべてのエフェクトが再実行されます。agent をキーにしたエフェクト内で、アプリの状態（相関マップ、処理中のリクエスト記録など）を初期化しないでください。
• React の key は、その配下にあるすべての状態を破棄します。key={activeAgent} / key={threadId} は、その状態を実際に所有する最小のサブツリーに設定してください。レイアウトレベルのプロバイダーに設定すると、無関係なアプリの状態まで気付かないうちに消去されます。また、Intelligence を接続している場合は、マウント後にスレッド ID が非同期で変わるため、操作の途中で再実行されます。
• v1 → v2 の移行に伴う名称変更：useCopilotAction → useFrontendTool + useHumanInTheLoop、imageUploadsEnabled → attachments。v1-to-v2-migration ライフサイクルスキルを参照してください。

初めて読む方のための推奨順序

1. provider-setup — プロバイダーをマウントします。
2. chat-components — チャットサーフェスを接続します。
3. agent-access — エージェントと通信します。
4. client-side-tools + rendering-tool-calls — ツール呼び出しの UI を追加します。
5. その他の機能は、必要に応じて確認してください。