CopilotKit 入門 : バックエンド – Copilot ランタイム

Posted on by Masashi Okumura

Copilot ランタイムは、フロントエンドアプリケーションを AI エージェントを接続するバックエンドレイヤーです。クイックスタートでセットアップされ、CopilotKit を使用するための推奨方法です。

CopilotKit : バックエンド – Copilot ランタイム

作成 : Masashi Okumura (@classcat.com)
作成日時 : 04/21/2026
バージョン : v1.56.2

* 本記事は docs.copilotkit.ai の以下のページ等を参考にしています :

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。

 

 

CopilotKit : バックエンド – Copilot ランタイム

Copilot ランタイムは、フロントエンドを AI エージェントに接続するバックエンドであり、認証、ミドルウェア、ルーティング、等の機能を提供します。

Copilot ランタイムは、フロントエンドアプリケーションを AI エージェントを接続するバックエンドレイヤーです。クイックスタート でセットアップされ、CopilotKit を使用するための推奨方法です。

 

ランタイムのセットアップ

ランタイムは、バックエンドに追加する軽量なサーバー・エンドポイントです。Next.js を使用した最小限の例を以下に示します :

app/api/copilotkit/route.ts

import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { NextRequest } from "next/server";

const serviceAdapter = new ExperimentalEmptyAdapter();

const runtime = new CopilotRuntime({
  agents: {
    // your agents go here
  },
});

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

そして、フロントエンドがエンドポイントを指すようにします :

<CopilotKit runtimeUrl="/api/copilotkit">
  <YourApp />
</CopilotKit>

 

エージェント

ランタイムは複数のエージェント・タイプをサポートしています。BuiltInAgent は主要なエージェントクラスです :

  • シンプルモード : model 文字列を渡すだけで、CopilotKit がすべてを処理します。迅速なセットアップに最適です。

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

  • ファクトリーモード：独自の AI SDK、TanStack AI、またはカスタム LLM バックエンドをもちこめます。完全な制御が必要な場合に最適です。ファクトリーモード を参照してください。

 

デフォルトエージェント

“default” という名前でエージェントを登録すると、CopilotKit の事前組み込み済み UI コンポーネントは、フロントエンドでの追加設定なしに自動的にそれを使用します。これは、プライマリエージェントが1つだけで、すべての場所で agentId を指定したくない場合に便利です。

app/api/copilotkit/route.ts

const runtime = new CopilotRuntime({
  agents: {
    // This agent will be used automatically by CopilotPopup, CopilotSidebar, etc.
    "default": new HttpAgent({ url: "https://my-agent.example.com" }),
  },
});

複数のエージェントを登録した場合、特定のエージェントが選択されない限り、”default” のエージェントがチャットを強化するものとなります。他のエージェントは、agentId を useAgent または事前構築済みコンポーネントに渡すことで使用できます。

 

ランタイムが提供するもの

認証とセキュリティ

ランタイムはサーバー上で動作する ので、エージェント通信はサーバー側で行われます。これにより、認証の強制、リクエストの検証、API キーを安全に保持するために信頼できる環境が確保されます。ランタイムを使用すると、エージェントのエンドポイントが認証されていないアクセスにさらされないように、安全なデフォルト設定が適用されます。

 

AG-UI ミドルウェア

AG-UI プロトコル は、ログ記録、ガードレール、リクエスト変換、等を行うためのミドルウェア層（agent.use）をサポートしています。ランタイムはサーバー側で実行されるため、このミドルウェアはクライアントによる改ざんが不可能な信頼できる環境で実行されます。

 

エージェント・ルーティング

ランタイムに複数のエージェントを登録すると、検出 (discovery) とルーティングを自動的に処理します。フロントエンドは、各エージェントの存在する場所やアクセス方法の詳細を知る必要はありません。

 

プレミアム機能

スレッド、可観測性、インスペクターなどの機能は、ランタイムを通じて提供されます。これらの機能により、会話の永続化、監視、デバッグ機能がすぐに利用できます。

 

組み込みミドルウェア

ランタイムは、各エージェントで .use() を手動で呼び出すことなく、CopilotRuntime 上で直接有効化できる 2 つのファーストクラスのミドルウェア・オプションをサポートしています。

 

A2UI

登録済みのすべてのエージェントに A2UIMiddleware を自動的に適用するには、”a2ui: {}” を渡します :

app/api/copilotkit/route.ts

const runtime = new CopilotRuntime({
  agents: { default: myAgent },
  a2ui: {},  // enables A2UI rendering for all agents
});

特定のエージェントのみにスコープを絞るには、エージェントのリストを渡します :

a2ui: { agents: ["my-agent"] }

フロントエンドでは、A2UI レンダラーが自動的にアクティブ化されるため、追加の設定は不要です。デフォルトのテーマを上書きしたい場合は、<CopilotKit> に a2ui prop を渡してください :

<CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ theme: myCustomTheme }}>
  {children}
</CopilotKit>

 

mcpApps

mcpApps を渡すと、すべてのエージェントの MCP サーバーを単一の場所から設定できます :

app/api/copilotkit/route.ts

const runtime = new CopilotRuntime({
  agents: { default: myAgent },
  mcpApps: {
    servers: [
      { type: "http", url: "http://localhost:3108/mcp", serverId: "my-server" },
    ],
  },
});

各サーバーエントリは、オプションで agentId フィールドを受け取り、これはスコープをサーバーから単一のエージェントに限定します。指定しない場合、サーバーはすべてのエージェントから利用可能です。

 

以上