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 名前空間を使用します。v2 API は、公開済みパッケージのサブパスエクスポートとして提供されています。

同じ Next.js アプリにフロントエンドとバックエンドがある場合：

npm install @copilotkit/react-core @copilotkit/runtime hono

フロントエンドのみの場合：

npm install @copilotkit/react-core

バックエンドランタイムのみの場合：

npm install @copilotkit/runtime hono

独立した Express バックエンドの場合は、hono の代わりに Express アダプターの依存関係をインストールしてください。

npm install @copilotkit/runtime express dotenv zod
npm install -D @types/express tsx typescript

（createCopilotExpressHandler は内部で CORS を有効にするため、cors を自分でインストールする必要はありません。dotenv と zod はサンプルアセットで使用されます。）

ステップ 2：ランタイムモードを選び、ランタイムを設定する

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

ランタイムコードを書く前に、モードを決めてください。 モードによってランタイムの構築方法が変わるため、後から変更するとこのファイルを書き直すことになります。

モード	スレッドの状態	次の場合に選択します
Managed Intelligence（推奨）	永続化、ホスト型	再起動後も保持されるスレッド、ホスト型のイングレス、ダッシュボード、または Channels が必要な場合
セルフホスト SSE	メモリ内、再起動時に消失	ホスト型の依存関係を避け、永続化を自分で管理する場合

ユーザーに希望するモードを尋ね、デフォルトは managed Intelligence にします。選択に必要な前提条件を明確に伝えてください。

Managed Intelligence には CopilotKit アカウント（無料。npx copilotkit login を実行するとブラウザーが開きます）とプロジェクト API キーが必要です。その代わり、スレッドは再起動やデプロイ後も保持され、ダッシュボードを利用できるほか、Slack／Teams Channels も使えるようになります。Channels は SSE モードでは利用できません。

セルフホスト SSE には AI プロバイダーのキー以外は必要ありません。スレッドの状態はリクエストを処理したプロセスのメモリ内に保存されるため、再起動時に失われ、レプリカ間で共有されません。このスキルの機能はすべて SSE モードで利用できます。これはサポート対象の方法であり、行き止まりではありません。

ユーザーが managed Intelligence を選んだ場合は、以下の Intelligence ランタイム用コードブロックを使い、ステップ 6 も完了してください。SSE を選んだ場合は、SSE 用コードブロックを使い、ステップ 6 のサーバー側の接続設定は省略してください。

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

1. 複数ルート（Hono） — createCopilotHonoHandler を使用します。キャッチオールルート（Next.js では [[...slug]]）が必要です。各操作（run、connect、stop、info、transcribe、threads）には、それぞれ独自の HTTP パスが割り当てられます。
2. 単一ルート（Hono または Express） — createCopilotHonoHandler({ ..., mode: "single-route" }) または createCopilotExpressHandler({ ..., mode: "single-route" }) を使用します。すべての操作は、メソッドの多重化を行う単一の POST エンドポイントを経由します。

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

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

import {
  CopilotRuntime,
  createCopilotHonoHandler,
  InMemoryAgentRunner,
  BuiltInAgent,
} from "@copilotkit/runtime/v2";
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 = createCopilotHonoHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);
// PATCH/DELETE are used by thread operations (useThreads); export them too
// so the multi-route handler can serve them when you enable Intelligence/threads.
export const PATCH = handle(app);
export const DELETE = handle(app);

Managed Intelligence を使う Next.js App Router

上記と同じファイル、同じハンドラーを使います。異なるのはランタイムの構築方法だけです。Intelligence モードを選択するのは intelligence であり、これを使うには identifyUser が必要です。

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

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

const intelligence = new CopilotKitIntelligence({
  // Server-side secret. `apiUrl`/`wsUrl` default to CopilotKit's managed
  // platform, so most projects set only the key.
  apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
});

const runtime = new CopilotRuntime({
  agents: { default: agent },
  intelligence,
  // REQUIRED in Intelligence mode: it decides whose threads these are. Resolve a
  // real authenticated user from the request -- with a hardcoded id, every visitor
  // shares one thread history.
  identifyUser: (request) => resolveUserFromSession(request),
});

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

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

重要な注意事項：

• runner は渡さないでください。 Intelligence モードでは IntelligenceAgentRunner が自動的に設定されます。InMemoryAgentRunner を渡すと、スレッドがメモリ内に保持されます。
• identifyUser は省略できません。 これはスレッドの所有権の境界となります。() => ({ id: "demo", name: "Demo" }) のようなスタブは、ローカルでの簡易な試作には問題ありませんが、複数ユーザーが利用する環境では不適切です。
• apiUrl と wsUrl は別々のホストです。 デフォルトはそれぞれ https://api.intelligence.copilotkit.ai と wss://realtime.intelligence.copilotkit.ai です。realtime プレーンは、スキームを入れ替えても API プレーンから導出できません。そのため、両方とも上書きするか、どちらも上書きしないでください。 片方だけを上書きすると、2 つのプレーンが異なるデプロイ先を指すことになります。

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

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

import {
  CopilotRuntime,
  createCopilotHonoHandler,
  InMemoryAgentRunner,
  BuiltInAgent,
} from "@copilotkit/runtime/v2";
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 = createCopilotHonoHandler({
  runtime,
  basePath: "/api/copilotkit",
  mode: "single-route",
});

export const POST = handle(app);

フロントエンドプロバイダーが自動的にこの方式をネゴシエートします。単一ルートのトランスポートを明示的に固定する場合に限り、プロバイダーに useSingleEndpoint を設定してください（ステップ 3 を参照）。

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

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

import express from "express";
import { CopilotRuntime, BuiltInAgent } from "@copilotkit/runtime/v2";
import { createCopilotExpressHandler } from "@copilotkit/runtime/v2/express";

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

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

const app = express();

app.use(
  "/api/copilotkit",
  createCopilotExpressHandler({
    runtime,
    basePath: "/",
    mode: "single-route",
  }),
);

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

複数ルートの Express では、mode オプションを省略してください（複数ルートがデフォルトです）。createCopilotExpressHandler は、どちらのスタイルにも同じファクトリーを使用します（@copilotkit/runtime/v2/express からインポートします）。

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

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

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

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

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

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

npm install hono @hono/node-server

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

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

どのプロバイダーコンポーネントを使えばよいですか？ 必ず @copilotkit/react-core/v2 からインポートした CopilotKit を使用してください。これは v1 と v2 の互換性を保つブリッジであり、他のプロバイダー API の機能をすべて含んでいます。パッケージのルート（レガシー v1）からの CopilotKit や、/v2 からの CopilotKitProvider（機能の一部のみを含む）は使用しないでください。

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

import "@copilotkit/react-core/v2/styles.css";

Next.js App Router

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

"use client";

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

export default function Home() {
  return (
    // No useSingleEndpoint: the provider negotiates the transport, so it
    // matches the multi-route backend above (the default) or a single-route
    // one. Pass the prop only to pin one mode deliberately.
    <CopilotKit runtimeUrl="/api/copilotkit">
      <div style={{ height: "100vh" }}>
        <CopilotChat />
      </div>
    </CopilotKit>
  );
}

外部ランタイムへの接続

ランタイムが別のサーバー（例：ポート 4000 の Express）で実行されている場合：

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

useSingleEndpoint を省略すると、プロバイダーがトランスポートをネゴシエートするため、どちらのハンドラーモードでも動作します。シングルルートトランスポート（createCopilotHonoHandler、または mode: "single-route" を指定した createCopilotExpressHandler）に固定する場合のみ true に設定してください。マルチルートの REST ルートに固定する場合は false に設定してください。

CopilotKit の主要な props

Prop	Type	Description
runtimeUrl	string	CopilotKit ランタイムエンドポイントの URL
useSingleEndpoint	boolean	省略するとトランスポートをネゴシエートします（どちらのハンドラーモードでも動作します）。true はシングルルートに、false はマルチルートに固定します
headers	Record<string, string> | (() => Record<string, string>)	すべてのリクエストに付加するカスタムヘッダーです。関数形式の場合、リクエストごとに評価されます（動的な認証トークンに便利です）。
credentials	RequestCredentials	Fetch の認証情報モードです（例：Cookie を使用する場合は "include"）。
showDevConsole	boolean	開発者コンソールを表示します。省略するとデフォルトの動作になり、localhost でのみ表示されます。
renderToolCalls	ReactToolCallRenderer[]	ツール呼び出し UI 用のカスタムレンダラー
frontendTools	ReactFrontendTool[]	フロントエンドで定義するツール（useFrontendTool の宣言的な代替手段）
onError	(event) => void	グローバルエラーハンドラー

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

CopilotKit には、あらかじめ構築された 3 種類のチャットレイアウトがあります（すべて @copilotkit/react-core/v2 からインポートします）。

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

サイドバーを使った例：

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

<CopilotKit runtimeUrl="/api/copilotkit" useSingleEndpoint={false}>
  <YourApp />
  <CopilotSidebar
    defaultOpen
    width="420px"
    labels={{
      modalHeaderTitle: "AI Assistant",
      chatInputPlaceholder: "Ask me anything...",
    }}
  />
</CopilotKit>;

Step 5: 環境変数を設定する

プロバイダーの API キーは秘密情報です。環境変数に保存し、ソースコードに直接記述したり、バージョン管理にコミットしたりしないでください。.env.local（Next.js）または .env ファイルを作成します。

OPENAI_API_KEY=<your-openai-api-key>

キーがコミットされないように、.gitignore で環境変数ファイル（.env、.env.local、.env*.local）が除外されていることを確認してください。本番環境では、チェックインされたファイルではなく、プラットフォームのシークレットマネージャー（Vercel／Netlify の環境変数、AWS Secrets Manager など）を通じてキーを設定します。

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

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

apiKey を明示的に渡す必要がある場合は、必ず環境変数を参照してください（apiKey: process.env.OPENAI_API_KEY）。キーの値を直接記述しないでください。

Step 6: CopilotKit Intelligence に接続する

Step 2 でセルフホストの SSE を選択した場合に限り、このステップをスキップしてください。

Intelligence に必要な認証情報は 1 つだけで、サーバー側に置かれます。ブラウザーに渡ることはなく、プロバイダーのプロパティで設定するものでもありません。

認証情報	保存場所	秘密情報？	用途
プロジェクト API キー（cpk-...）	サーバーのみ	はい	ランタイムが Intelligence に対して認証します

publicApiKey や publicLicenseKey は使用しないでください。これらはランタイムのないクライアントを CopilotKit Cloud に接続するためのもので、別の製品です。

1. サインインしてプロジェクトを作成します。

   npx copilotkit login
   npx copilotkit project select
   

   login はブラウザーを開き、ローカルの CLI セッションを保存します。project select はホスト型プロジェクトを選択または作成し、その情報を .copilotkit/project.json に記録します。バージョンによってコマンドが異なる場合は、npx copilotkit --help で利用可能なコマンドを確認してください。

2. サーバー側のプロジェクト API キーを設定します。 project select によって 1 つ発行されます。また、ダッシュボードからコピーすることもできます。

   # .env.local (Next.js) or .env
   CPK_INTELLIGENCE_API_KEY=cpk-...
   

   これは秘密情報です。意図的に NEXT_PUBLIC_／VITE_ というプレフィックスを付けていません。プレフィックスを付けると、ブラウザーに送信されてしまいます。このキーは、Step 2 で接続した CopilotKitIntelligence クライアントによって読み取られます。

   CPK_INTELLIGENCE_API_KEY が標準の名前です。copilotkit project select がこの名前でキーを発行し、CopilotKit のすべてのドキュメントでも使用しています。COPILOTKIT_API_KEY は非推奨の別名で、一部の古いサンプルで引き続き使われています。

3. 接続を確認します。

   npx copilotkit verify
   

   プロジェクトが選択されているか、キーが読み込まれて認証されるか、ランタイムが実際にその認証情報を使用しているか、保存済みスレッドに必要なスレッドルートをランタイムが提供しているかを確認できます。

4. スレッドが実際に永続化されることを確認します。 メッセージを送信し、開発サーバーを再起動してから再読み込みします。スレッドが残っているはずです。残っていない場合、ランタイムはまだ SSE モードです。intelligence が渡されていること、また runner で上書きされていないことを確認してください。

Intelligence で利用できる機能、接続のための CLI フロー、オプトアウトの方法については、references/telemetry-setup.md を参照してください。

Slack または Microsoft Teams への接続

チャネルを使うと、エージェントが Slack または Teams で回答できます。チャネルには Intelligence ランタイムと、長時間稼働するホストが必要です。SSE モードでは channels を利用できません。また、チャネルを有効にすると永続的な接続が開かれます。

この機能には copilotkit-channels スキルを使用してください。Channel の宣言方法、長時間稼働するホストの要件、独自に有効化を開始するマウントと、明示的な channels.ready() 呼び出しを待つマウントについて説明しています。この手順の配線を基に構築できます。

新しいマネージド Teams アプリの場合は、まず Intelligence で Channel のドラフトを作成し、推奨されているブラウザー発行の Fast CLI コマンド（channels add --project-id … --channel-id … --adapter teams --provision）または、対になる Guided 手動手順を使用してください。Azure Bot のリソースをスキャフォールディングしたり、Microsoft の認証情報、カスタムアイコン、生成されたパッケージをプロジェクトに配置したりしないでください。プロバイダーの 作成してインストール済み という結果は、このコード側の作業とは別です。統合を最初から最後まで検証するには、ホストが稼働しており、実際に Teams でやり取りできる必要があります。

ステップ 7：セットアップを検証する

1. 開発サーバーを起動します
2. ブラウザーでアプリを開きます
3. チャット UI が表示され、ランタイムに接続されることを確認します
4. テストメッセージを送信します。AI の応答が返ってくるはずです
5. ランタイムの情報エンドポイントを確認し、利用可能なエージェントが返されることを確かめます。マルチルートのハンドラーでは GET /api/copilotkit/info を使用します。シングルルートのハンドラー（mode: "single-route"、例：Express の例）では、ベースパスへの POST と本文 { "method": "info" } を使用します（通常の GET ではエージェント情報は返されません。Hono のシングルルートハンドラーは 405 を返し、Express のシングルルートルーターには GET ルートがないため、404 にフォールスルーします）

セキュリティに関する注意事項

実際のデプロイを設定する際は、次の点に注意してください。

• シークレットはサーバー側で環境変数として管理します。 プロバイダーの API キー（OPENAI_API_KEY など）は、サーバー上のランタイム／エージェントによって読み取られます。これらをブラウザーに公開したり、ハードコードしたり、コミットしたりしないでください。環境変数またはシークレットマネージャーに保存します（ステップ 5 を参照）。CopilotKit Intelligence はクライアント側に値を追加しません。認証情報はサーバー上のランタイムによって読み取られます。
• すべてのチャット入力を信頼できないものとして扱います。 チャットメッセージはフロントエンドから CopilotRuntime エンドポイントを経由し、エージェントの LLM コンテキストに渡されます。入力はユーザーが制御でき、プロンプトインジェクションを試みる可能性があります。エージェントが取得したコンテンツ（ウェブページ、ドキュメント、ツールの結果など）を介した間接的なインジェクションも含まれます。モデルがシステムプロンプトの意図どおりにしか動作しないと想定しないでください。
• サーバー側のツールには最小限の権限を与えます。 defineTool の execute 関数は、サーバーの権限で実行されます。すべての引数を検証し（zod の parameters スキーマが最初の関門です）、各ツールの操作範囲を必要最小限に絞ってください。また、機密性の高い操作（データベースへの書き込み、支払い、ファイルアクセス）については、モデルが正しく呼び出したと信頼するのではなく、execute 関数内で独自に認可を適用してください。
• ランタイムのエンドポイントを認証します。 ランタイムのルートは、デフォルトで公開 HTTP エンドポイントです。認証済みのユーザーのみがエージェントを操作し、プロバイダーのクレジットを消費できるよう、アプリの認証をこのエンドポイントの前に設けてください。

クイックリファレンス

パッケージ一覧

パッケージ	目的
@copilotkit/react-core	React コンポーネント、フック、プロバイダー（@copilotkit/react-core/v2 からインポート）
@copilotkit/runtime	ランタイム、エンドポイントファクトリー、エージェントランナー、BuiltInAgent、defineTool（@copilotkit/runtime/v2 からインポート）
@copilotkit/shared	共通ユーティリティ、ロガー、型

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

関数	インポート	フレームワーク	モード
createCopilotHonoHandler	@copilotkit/runtime/v2	Next.js App Router、Hono 単体	"multi-route"（デフォルト）または mode: "single-route"
createCopilotExpressHandler	@copilotkit/runtime/v2/express	Express 単体	"multi-route"（デフォルト）または mode: "single-route"

createCopilotEndpoint、createCopilotEndpointSingleRoute、createCopilotEndpointExpress、createCopilotEndpointSingleRouteExpress は、上記の 2 つのファクトリーの非推奨エイリアスです。mode オプションを指定してハンドラーファクトリーを使用してください。

ランタイムクラス

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

Channels には Intelligence ランタイムと長時間実行されるホストが必要です。 copilotkit-channels スキルを参照してください。

エージェントランナー

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

サポート対象のモデル（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-6、anthropic/claude-sonnet-4-5、anthropic/claude-opus-4-8、anthropic/claude-haiku-4-5

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

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