runtime

CopilotKit Runtime

@copilotkit/runtime は CopilotKit のサーバー側です。AG-UI プロトコルの リクエストを受け付け、AbstractAgent（組み込みまたは外部）に振り分け、 AgentRunner を通じてストリームを実行し、Server-Sent Events として応答します。

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

メンタルモデル — CopilotRuntime に渡す3つの辞書

new CopilotRuntime({
  agents, // Record<string, AbstractAgent>     — see wiring-external-agents or built-in-agent
  runner, // AgentRunner (optional)            — see agent-runners
  intelligence, // CopilotKitIntelligence (optional) — see intelligence-mode (auto-wires runner)
  mcpApps, // McpAppsConfig (optional)          — see wiring-mcp-apps-middleware
  a2ui, // A2UIConfig (optional)             — see packages/a2ui-renderer skill
  hooks, // { onRequest, onBeforeHandler }    — see middleware
  beforeRequestMiddleware,
  afterRequestMiddleware, // legacy — see middleware
  transcription, // TranscriptionService (optional)  — see transcription
});

次に、これをマウントします。

import { createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});
export default { fetch: handler };

どのリファレンスを読むべきか

タスク	リファレンス
あらゆる Fetch ネイティブサーバー（Cloudflare Workers、Bun、Deno、Vercel Edge、Next.js App Router、React Router v7、TanStack Start）へのマウント、または Express/Node からの委譲	references/setup-endpoint.md
hooks.onRequest / hooks.onBeforeHandler（推奨）または従来の beforeRequestMiddleware / afterRequestMiddleware を使用した認証／ロギング／レート制限／リクエストスコープのガード	references/middleware.md
InMemoryAgentRunner、SqliteAgentRunner、カスタムサブクラスの選択 — スレッドロックのセマンティクスと、runner/Intelligence の相互排他を含む	references/agent-runners.md（バックエンド固有の詳細は -in-memory.md、-sqlite.md、-custom.md を参照）
CopilotKit Intelligence（セルフホスト不可のマネージドサービス）による永続スレッドとリアルタイム WebSocket の有効化	references/intelligence-mode.md
音声の文字起こし — /transcribe エンドポイント用の TranscriptionService サブクラスの実装	references/transcription.md
BuiltInAgent のインスタンス化 — Simple Mode（従来型）、または TanStack AI（AG-UI 準拠の推奨デフォルト）、AI SDK、カスタムファクトリーを使用する Factory Mode	references/built-in-agent.md（-factory-modes.md、-helper-utilities.md、-model-identifiers.md も参照）
BuiltInAgent.config.tools 用の defineTool によるサーバーサイドツールの定義（Simple Mode のみ）	references/server-side-tools.md
外部エージェントフレームワークを CopilotRuntime({ agents }) に接続	references/wiring-external-agents.md（インデックス）と、フレームワークごとのリファレンス（wiring-mastra.md、wiring-langgraph.md、wiring-crewai-crews.md、wiring-crewai-flows.md、wiring-pydantic-ai.md、wiring-adk.md、wiring-llamaindex.md、wiring-agno.md、wiring-aws-strands.md、wiring-ms-agent-framework.md、wiring-ag2.md、wiring-a2a.md）
MCP Apps の接続（エージェントではなく、ランタイムレベルのミドルウェア）	references/wiring-mcp-apps-middleware.md

不変条件と注意点（参照前に一度だけ読み込む）

• createCopilotRuntimeHandler が標準のプリミティブです。createCopilotExpressHandler と createCopilotHonoHandler もありますが、絶対に使用しないでください。代わりに、Express／Hono のルートから fetch プリミティブへ委譲してください。
• Intelligence の認証情報はサーバー側にあります。CLI は CPK_INTELLIGENCE_API_KEY をランタイムの環境変数に書き込みます。クライアント側のキーは使用しません。
• Intelligence モードでは IntelligenceAgentRunner が自動的に接続されます。CopilotRuntime に runner と intelligence の両方を渡すと、インスタンスの構築時に拒否されます。
• Intelligence モードはマネージドの CopilotKit Intelligence サービス（api.cloud.copilotkit.ai）を対象としており、セルフホストできません。
• hooks.onRequest は beforeRequestMiddleware より先に実行されます（Response によるショートサーキットではフックベースのミドルウェアが優先されます）。beforeRequestMiddleware は hooks.onRequest の後に実行されます（fetch-handler.ts:136-147 を参照）。
• Intelligence の identifyUser は、スローされた Response オブジェクトを転送しません。500 に変換してください。認証拒否の処理は、Response を転送する hooks.onRequest で行ってください。
• agents__unsafe_dev_only と selfManagedAgents は、互いに別名として使える開発専用の機能です。本番環境では使用しないでください。どちらを指定しても、SPA が開発モードであることを示します。

初めて読む人向けの順序

1. setup-endpoint — プリミティブ。
2. built-in-agent または wiring-external-agents から選択 — エージェント。
3. agent-runners — 本番環境での永続化方法の選択。
4. 任意：middleware、intelligence-mode、server-side-tools、transcription。