Back to Details

runtime

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CopilotKit Runtime

CopilotKit Runtime

@copilotkit/runtime
is the server half of CopilotKit: it accepts AG-UI protocol requests, dispatches them to an 
AbstractAgent
(built-in or external), runs the stream through an 
AgentRunner
, and responds as Server-Sent Events.
This SKILL.md is the index. Read the reference under 
references/
that matches your task — do not try to absorb the whole package from this file.
@copilotkit/runtime
是CopilotKit的服务端组件：它接收AG-UI协议请求，将请求分发至
AbstractAgent
（内置或外部），通过
AgentRunner
处理流，并以Server-Sent Events的形式响应。
本SKILL.md是索引文件。请阅读与你的任务匹配的
references/
下的参考文档——不要试图从本文件中了解整个包的所有内容。

Mental Model — the three dictionaries you hand to 
CopilotRuntime

核心模型——传递给
CopilotRuntime
的三个配置项

ts
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
});
You then mount it:
ts
import { createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});
export default { fetch: handler };
ts
new CopilotRuntime({
  agents, // Record<string, AbstractAgent>     — 请查看wiring-external-agents或built-in-agent文档
  runner, // AgentRunner（可选）            — 请查看agent-runners文档
  intelligence, // CopilotKitIntelligence（可选） — 请查看intelligence-mode文档（自动配置runner）
  mcpApps, // McpAppsConfig（可选）          — 请查看wiring-mcp-apps-middleware文档
  a2ui, // A2UIConfig（可选）             — 请查看packages/a2ui-renderer相关文档
  hooks, // { onRequest, onBeforeHandler }    — 请查看middleware文档
  beforeRequestMiddleware,
  afterRequestMiddleware, // 旧版方式 — 请查看middleware文档
  transcription, // TranscriptionService（可选）  — 请查看transcription文档
});
随后挂载运行：
ts
import { createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});
export default { fetch: handler };

When to load which reference

不同任务对应参考文档

TaskReference
Mounting on any fetch-native server (Cloudflare Workers, Bun, Deno, Vercel Edge, Next.js App Router, React Router v7, TanStack Start) or delegating from Express/Node
references/setup-endpoint.md
Auth / logging / rate-limit / request-scoped guards via 
hooks.onRequest
/ 
hooks.onBeforeHandler
(preferred) or legacy 
beforeRequestMiddleware
/ 
afterRequestMiddleware
references/middleware.md
Choosing between 
InMemoryAgentRunner
, 
SqliteAgentRunner
, or a custom subclass — including thread-locking semantics and the runner/Intelligence mutual exclusion
references/agent-runners.md
(+ 
-in-memory.md
, 
-sqlite.md
, 
-custom.md
for backend-specific detail)
Enabling durable threads + realtime websocket via CopilotKit Cloud (Intelligence is Cloud-only, not self-hostable)
references/intelligence-mode.md
Voice transcription — implementing a 
TranscriptionService
subclass for the 
/transcribe
endpoint
references/transcription.md
Instantiating 
BuiltInAgent
— Simple Mode (classic) or Factory Mode with TanStack AI (preferred AG-UI-compliant default), AI SDK, or custom factory
references/built-in-agent.md
(+ 
-factory-modes.md
, 
-helper-utilities.md
, 
-model-identifiers.md
)
Defining server-side tools via 
defineTool
for 
BuiltInAgent.config.tools
(Simple Mode only)
references/server-side-tools.md
Wiring an external agent framework into 
CopilotRuntime({ agents })
references/wiring-external-agents.md
(index) + per-framework refs (
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
)
Wiring MCP Apps (runtime-level middleware, not an agent)
references/wiring-mcp-apps-middleware.md
任务参考文档
在任意原生基于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 Cloud启用持久化线程+实时WebSocket（Intelligence为仅云端可用功能，不支持自托管）
references/intelligence-mode.md
语音转录——为
/transcribe
端点实现
TranscriptionService
子类
references/transcription.md
实例化
BuiltInAgent
——简单模式（经典版）或推荐的AG-UI兼容默认方式（TanStack AI工厂模式）、AI SDK或自定义工厂
references/built-in-agent.md
（+ 
-factory-modes.md
、
-helper-utilities.md
、
-model-identifiers.md
）
通过
defineTool
为
BuiltInAgent.config.tools
定义服务端工具（仅适用于简单模式）
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

Invariants and gotchas (load-once, before any reference)

固定规则与注意事项（先阅读，再查看其他参考文档）

  • createCopilotRuntimeHandler
    is the canonical primitive. 
    createCopilotExpressHandler
    / 
    createCopilotHonoHandler
    exist but are avoid at all costs — delegate from Express/Hono routes to the fetch primitive instead.
  • publicLicenseKey
    is the canonical provider-side field. 
    publicApiKey
    is a deprecated alias — expect to see it in legacy code, emit the canonical name in new code.
  • Intelligence mode auto-wires 
    IntelligenceAgentRunner
    . Passing both 
    runner
    and 
    intelligence
    to 
    CopilotRuntime
    is rejected at construction.
  • Intelligence mode targets CopilotKit Cloud (
    api.cloud.copilotkit.ai
    ) and is not self-hostable.
  • hooks.onRequest
    runs before 
    beforeRequestMiddleware
    (hook-based middleware wins for Response short-circuits). 
    beforeRequestMiddleware
    runs after 
    hooks.onRequest
    (see 
    fetch-handler.ts:136-147
    ).
  • identifyUser
    (Intelligence) does not forward thrown 
    Response
    objects — convert to 500. Gate auth rejection in 
    hooks.onRequest
    , which does forward Responses.
  • agents__unsafe_dev_only
    and 
    selfManagedAgents
    are dev-only aliases of each other; do not reach for them in production. Either signals that the SPA is in dev mode.
  • createCopilotRuntimeHandler
    是标准基础组件。
    createCopilotExpressHandler
    /
    createCopilotHonoHandler
    虽存在，但务必避免使用——建议从Express/Hono路由转发请求至基于fetch的基础组件。
  • publicLicenseKey
    是标准的提供者端字段。
    publicApiKey
    是已废弃的别名——旧代码中可能会出现，新代码请使用标准名称。
  • 智能模式会自动配置
    IntelligenceAgentRunner
    。同时向
    CopilotRuntime
    传递
    runner
    和
    intelligence
    会在构造时被拒绝。
  • 智能模式针对CopilotKit Cloud（
    api.cloud.copilotkit.ai
    ），不支持自托管。
  • hooks.onRequest
    在
    beforeRequestMiddleware
    之前运行（基于钩子的中间件优先响应短路）。
    beforeRequestMiddleware
    在
    hooks.onRequest
    之后运行（详见
    fetch-handler.ts:136-147
    ）。
  • identifyUser
    （智能模式）不会转发抛出的
    Response
    对象——需转换为500状态码。请在
    hooks.onRequest
    中处理认证拒绝，该钩子会转发Response。
  • agents__unsafe_dev_only
    和
    selfManagedAgents
    是彼此的开发环境专用别名；生产环境请勿使用。这两个字段均表示SPA处于开发模式。

Reading order for a first-time reader

首次阅读顺序

  1. setup-endpoint
    — the primitive.
  2. built-in-agent
    or pick one from 
    wiring-external-agents
    — the agent.
  3. agent-runners
    — production persistence choice.
  4. Optional: 
    middleware
    , 
    intelligence-mode
    , 
    server-side-tools
    , 
    transcription
    .
  1. setup-endpoint
    — 基础组件说明。
  2. built-in-agent
    或 从
    wiring-external-agents
    中选择一个框架 — Agent配置说明。
  3. agent-runners
    — 生产环境持久化方案选择。
  4. 可选：
    middleware
    、
    intelligence-mode
    、
    server-side-tools
    、
    transcription
    。