copilotkit-setup

CopilotKit のセットアップ

前提条件

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

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

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

環境

セットアップを開始する前に、次の項目を確認してください。

1. Node.js >= 18（ランタイムで使用する fetch グローバルが必要です）
2. AI プロバイダーの API キー（次のいずれか：OPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_API_KEY）
3. React ベースのフロントエンド（Next.js App Router、Next.js Pages Router、Vite + React、または Angular）
4. ランタイムを実行できるバックエンド（API ルートを使った同じ Next.js アプリ、またはスタンドアロンの Express/Hono サーバー）

フレームワークの検出

コードを生成する前に、プロジェクトのルートにあるファイルを確認して、プロジェクトのフレームワークを検出してください。判定手順の全体については、references/framework-detection.md を参照してください。

概要：

シグナルとなるファイル	フレームワーク
next.config.{js,ts,mjs} + app/ ディレクトリ	Next.js App Router
next.config.{js,ts,mjs} + pages/ ディレクトリ	Next.js Pages Router
angular.json	Angular
vite.config.{js,ts} + package.json の React 依存関係	Vite + React

セットアップのワークフロー

ステップ 1：パッケージをインストールする

すべてのパッケージで @copilotkit 名前空間を使用します。

フロントエンド（React）パッケージ：

npm install @copilotkit/react @copilotkit/core

ランタイムパッケージ（バックエンド）：

npm install @copilotkit/runtime @copilotkit/agent

フロントエンドと同じ Next.js アプリでランタイムを実行する場合は、4 つのパッケージをまとめてインストールしてください。

スタンドアロンの Express バックエンドでは、Express アダプターの依存関係もインストールしてください。

npm install express cors
npm install -D @types/express @types/cors

ステップ 2：ランタイムを設定する

ランタイムは、エージェントの実行を管理するサーバー側のコンポーネントです。詳細については、references/runtime-architecture.md を参照してください。

エンドポイントのスタイルは 2 種類あります。

1. 複数ルート（Hono） — createCopilotEndpoint を使用します。キャッチオールルート（Next.js では [[...slug]]）が必要です。各操作（run、connect、stop、info、transcribe、threads）に個別の HTTP パスが割り当てられます。
2. 単一ルート（Hono または Express） — createCopilotEndpointSingleRoute または createCopilotEndpointSingleRouteExpress を使用します。すべての操作を、メソッドの多重化を使って単一の POST エンドポイントで処理します。

Next.js App Router（推奨：Hono を使った複数ルート）

src/app/api/copilotkit/[[...slug]]/route.ts を作成します。

import {
  CopilotRuntime,
  createCopilotEndpoint,
  InMemoryAgentRunner,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
import { handle } from "hono/vercel";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
  prompt: "You are a helpful AI assistant.",
});

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
  runner: new InMemoryAgentRunner(),
});

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

export const GET = handle(app);
export const POST = handle(app);

依存関係として hono が必要です。

npm install hono

Next.js App Router（代替：単一ルート）

src/app/api/copilotkit/route.ts を作成します。

import {
  CopilotRuntime,
  createCopilotEndpointSingleRoute,
  InMemoryAgentRunner,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
import { handle } from "hono/vercel";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
  prompt: "You are a helpful AI assistant.",
});

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
  runner: new InMemoryAgentRunner(),
});

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

export const POST = handle(app);

単一ルートを使用する場合は、フロントエンドでプロバイダーに useSingleEndpoint を設定する必要があります（ステップ 3 を参照）。

スタンドアロンの Express サーバー

src/index.ts を作成します。

import express from "express";
import { CopilotRuntime } from "@copilotkit/runtime";
import { createCopilotEndpointSingleRouteExpress } from "@copilotkit/runtime/express";
import { BuiltInAgent, defineTool } from "@copilotkit/agent";
import { z } from "zod";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
});

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
});

const app = express();

app.use(
  "/api/copilotkit",
  createCopilotEndpointSingleRouteExpress({
    runtime,
    basePath: "/",
  }),
);

const port = Number(process.env.PORT ?? 4000);
app.listen(port, () => {
  console.log(`CopilotKit runtime listening at http://localhost:${port}/api/copilotkit`);
});

Express で複数ルートを使用する場合は、代わりに createCopilotEndpointExpress を使用します（@copilotkit/runtime/express からインポートします）。

スタンドアロンの Hono サーバー（Vercel 以外）

import { CopilotRuntime, createCopilotEndpoint } from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
import { serve } from "@hono/node-server";

const runtime = new CopilotRuntime({
  agents: {
    default: new BuiltInAgent({ model: "openai/gpt-4o" }),
  },
});

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

serve({ fetch: app.fetch, port: 8787 });

@hono/node-server が必要です。

npm install hono @hono/node-server

ステップ 3：フロントエンドプロバイダーをセットアップする

アプリケーションを @copilotkit/react の CopilotKitProvider でラップします。

重要： ルートレイアウトでスタイルシートをインポートしてください。

import "@copilotkit/react/styles.css";

Next.js App Router

src/app/page.tsx（またはクライアントコンポーネント）で、次のようにします。

"use client";

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

export default function Home() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <div style={{ height: "100vh" }}>
        <CopilotChat />
      </div>
    </CopilotKitProvider>
  );
}

外部ランタイムへの接続

ランタイムを別のサーバー（例：ポート 4000 で実行する Express）で実行する場合：

<CopilotKitProvider
  runtimeUrl="http://localhost:4000/api/copilotkit"
  useSingleEndpoint
>
  {children}
</CopilotKitProvider>

バックエンドで単一ルートのエンドポイント（createCopilotEndpointSingleRoute または createCopilotEndpointSingleRouteExpress）を使用する場合は、useSingleEndpoint を設定してください。

CopilotKitProvider の主要なプロパティ

Prop	Type	Description
runtimeUrl	string	CopilotKit ランタイムエンドポイントの URL
useSingleEndpoint	boolean	シングルルートエンドポイントを使用する場合は true に設定します
headers	Record<string, string>	すべてのリクエストとともに送信されるカスタムヘッダー
credentials	RequestCredentials	Fetch の認証情報モード（例：Cookie を使用する場合は "include"）
publicApiKey	string	Copilot Cloud の公開 API キー（ホスト型ランタイムを使用する場合）
showDevConsole	boolean | "auto"	開発用インスペクターを表示します（"auto" = 開発時のみ）
renderToolCalls	ReactToolCallRenderer[]	ツール呼び出し UI 用のカスタムレンダラー
frontendTools	ReactFrontendTool[]	フロントエンドで定義するツール（useFrontendTool の宣言的な代替手段）
onError	(event) => void	グローバルエラーハンドラー

ステップ 4：チャット UI コンポーネントを追加する

CopilotKit には、あらかじめ構築されたチャットレイアウトが 3 つ用意されています。

Component	Usage
CopilotChat	インラインチャット。コンテナー全体に表示されます
CopilotSidebar	折りたたみ可能なサイドバーパネル
CopilotPopup	フローティングポップアップウィジェット

サイドバーの例：

<CopilotKitProvider runtimeUrl="/api/copilotkit" showDevConsole="auto">
  <YourApp />
  <CopilotSidebar
    defaultOpen
    width="420px"
    labels={{
      modalHeaderTitle: "AI Assistant",
      chatInputPlaceholder: "Ask me anything...",
    }}
  />
</CopilotKitProvider>

ステップ 5：環境変数を設定する

.env.local（Next.js）または .env ファイルを作成します。

OPENAI_API_KEY=sk-...

BuiltInAgent は、モデルのプレフィックスに基づいて環境変数から API キーを自動的に解決します。

• openai/* モデルは OPENAI_API_KEY を読み取ります
• anthropic/* モデルは ANTHROPIC_API_KEY を読み取ります
• google/* モデルは GOOGLE_API_KEY を読み取ります

必要に応じて、BuiltInAgent に apiKey を直接渡すこともできます。

ステップ 6：クラウドプラットフォームに接続する（テレメトリ）

CopilotKit は、利用状況の把握、製品の改善、より良いサポートの提供のためにテレメトリを使用します。CopilotKit クラウドプラットフォームに接続すると、分析機能やオプションのプレミアム機能を利用できます。

1. CopilotKit クラウドプラットフォームに接続するかどうかをユーザーに確認します（デフォルト：はい）。
2. 接続する場合は、CopilotKit CLI の認証フローを実行します（バージョンによって異なる場合があるため、npx copilotkit --help で正確なコマンドを確認してください）。

   npx copilotkit auth
   

3. 開いたブラウザーでの認証をユーザーに案内します。
4. 認証が完了すると、CLI にライセンスキーが出力されます（形式：ck_...）。
5. ライセンスキーを CopilotKitProvider に追加します。

   <CopilotKitProvider
     runtimeUrl="/api/copilotkit"
     licenseKey="ck_..."
   >
   

   または、環境変数（.env.local または .env の COPILOTKIT_LICENSE_KEY）として保存し、参照します。

   <CopilotKitProvider
     runtimeUrl="/api/copilotkit"
     licenseKey={process.env.NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY}
   >
   

ライセンスキーで有効になる機能やオプトアウトの方法については、references/telemetry-setup.md を参照してください。

ステップ 7：セットアップを確認する

1. 開発サーバーを起動します
2. ブラウザーでアプリを開きます
3. チャット UI が表示され、ランタイムに接続されていることを確認します
4. テストメッセージを送信します。AI の応答が返ってくるはずです
5. ランタイムの /info エンドポイント（GET）を確認し、利用可能なエージェントが報告されていることを確認します

クイックリファレンス

パッケージ一覧

Package	Purpose
@copilotkit/react	React コンポーネント、フック、プロバイダー
@copilotkit/core	コア型、エージェントの抽象化、状態管理
@copilotkit/runtime	サーバーサイドランタイム、エンドポイントファクトリー、エージェントランナー
@copilotkit/agent	BuiltInAgent、defineTool、モデルの解決
@copilotkit/shared	共通ユーティリティ、ロガー、型

エンドポイントファクトリー関数

Function	Import	Protocol	Framework
createCopilotEndpoint	@copilotkit/runtime	マルチルート（Hono）	Next.js App Router、Hono スタンドアロン
createCopilotEndpointSingleRoute	@copilotkit/runtime	シングルルート（Hono）	Next.js App Router
createCopilotEndpointExpress	@copilotkit/runtime/express	マルチルート（Express）	Express スタンドアロン
createCopilotEndpointSingleRouteExpress	@copilotkit/runtime/express	シングルルート（Express）	Express スタンドアロン

ランタイムクラス

クラス	用途
CopilotRuntime	互換性シム。SSE モードまたは Intelligence モードを自動選択します
CopilotSseRuntime	明示的な SSE モード（デフォルト。スレッドはメモリ内に保存されます）
CopilotIntelligenceRuntime	Intelligence モード（永続的なスレッド、リアルタイムイベント）

エージェントランナー

ランナー	説明
InMemoryAgentRunner	デフォルトです。スレッドの状態をプロセスメモリに保存します。開発環境や単一インスタンスのデプロイに適しています。
IntelligenceAgentRunner	CopilotIntelligenceRuntime とともに自動的に使用されます。WebSocket 経由で CopilotKit Intelligence Platform に接続します。

サポートされるモデル（BuiltInAgent）

形式："provider/model-name" 文字列、または Vercel AI SDK の LanguageModel インスタンス。

OpenAI: openai/gpt-5、openai/gpt-5-mini、openai/gpt-4.1、openai/gpt-4.1-mini、openai/gpt-4.1-nano、openai/gpt-4o、openai/gpt-4o-mini、openai/o3、openai/o3-mini、openai/o4-mini

Anthropic: anthropic/claude-sonnet-4.5、anthropic/claude-sonnet-4、anthropic/claude-3.7-sonnet、anthropic/claude-opus-4.1、anthropic/claude-opus-4、anthropic/claude-3.5-haiku

Google: google/gemini-2.5-pro、google/gemini-2.5-flash、google/gemini-2.5-flash-lite

任意の string を指定できます（カスタムモデルや一覧にないモデルの場合）。プロバイダーは / より前のプレフィックスから解析されます。