runtime

CopilotKit Runtime

@copilotkit/runtime 是 CopilotKit 的服务端部分：它接收 AG-UI 协议请求，将其分派给 AbstractAgent（内置或外部），通过 AgentRunner 运行流，并以 Server-Sent Events 形式响应。

本 SKILL.md 是索引。请阅读 references/ 下与你的任务匹配的参考文档——不要试图从本文件吸收整个包。

心智模型——你交给 CopilotRuntime 的三个字典

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）
通过 defineTool 为 BuiltInAgent.config.tools 定义服务端工具（仅限 Simple Mode）	references/server-side-tools.md
将外部 Agent 框架接入 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（运行时级中间件，而非 Agent）	references/wiring-mcp-apps-middleware.md

不变量与注意事项（在任何参考之前，先一次性加载）

• createCopilotRuntimeHandler 是权威原语。createCopilotExpressHandler / createCopilotHonoHandler 虽然存在，但务必避免使用——应改为从 Express/Hono 路由委托到 fetch 原语。
• Intelligence 凭据位于服务端。命令行会将 CPK_INTELLIGENCE_API_KEY 写入运行时的环境；不涉及任何客户端密钥。
• Intelligence 模式会自动装配 IntelligenceAgentRunner。同时向 CopilotRuntime 传入 runner 和 intelligence 会在构造时被拒绝。
• Intelligence 模式面向托管的 CopilotKit Intelligence 服务（api.cloud.copilotkit.ai），且不可自托管。
• hooks.onRequest 在 beforeRequestMiddleware 之前运行（对于 Response 短路，基于 hook 的中间件优先）。beforeRequestMiddleware 在 hooks.onRequest 之后运行（见 fetch-handler.ts:136-147）。
• identifyUser（Intelligence）不会转发抛出的 Response 对象——请转换为 500。将认证拒绝逻辑放在 hooks.onRequest 中，它会转发 Responses。
• agents__unsafe_dev_only 和 selfManagedAgents 是彼此仅限开发环境的别名；不要在生产环境使用它们。任何一者都表明 SPA 处于开发模式。

首次阅读者的阅读顺序

1. setup-endpoint —— 原语。
2. built-in-agent 或从 wiring-external-agents 中挑选一个 —— Agent。
3. agent-runners —— 生产环境持久化选择。
4. 可选：middleware、intelligence-mode、server-side-tools、transcription。