copilotkit--copilotkit/skills/runtime/references/middleware.md

CopilotKit Runtime Middleware

Two coexisting middleware surfaces:

• hooks (preferred, newer) — pass to createCopilotRuntimeHandler({ hooks }). Route-aware via onBeforeHandler({ route }). Throw a Response to short-circuit.
• beforeRequestMiddleware / afterRequestMiddleware (legacy) — pass to new CopilotRuntime({ ... }). Runs after hooks.onRequest but before routing (see fetch-handler.ts:136-147 for exact order). Pre-routing only.

Use hooks for new code.

Setup

import {
  CopilotRuntime,
  createCopilotRuntimeHandler,
} from "@copilotkit/runtime/v2";

const runtime = new CopilotRuntime({
  agents: {
    /* ... */
  } as any,
});

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  hooks: {
    onRequest: async ({ request }) => {
      const token = request.headers.get("authorization");
      if (!token) throw new Response("Unauthorized", { status: 401 });
    },
    onBeforeHandler: async ({ route, request }) => {
      if (route.method === "agent/run" && route.agentId === "admin") {
        const user = await verifyAdminToken(
          request.headers.get("authorization"),
        );
        if (!user) throw new Response("Forbidden", { status: 403 });
      }
    },
    onResponse: async ({ response }) => {
      const headers = new Headers(response.headers);
      headers.set("x-copilot-version", "2.0");
      return new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers,
      });
    },
    onError: async ({ error, route }) => {
      console.error("[copilotkit]", route?.method, error);
    },
  },
});

async function verifyAdminToken(
  header: string | null,
): Promise<{ id: string } | null> {
  if (!header) return null;
  // delegate to your auth lib
  return { id: "admin" };
}

export default { fetch: handler };

Core Patterns

Reject unauthenticated requests at the runtime boundary

createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  hooks: {
    onRequest: ({ request }) => {
      const token = request.headers.get("authorization");
      if (!token?.startsWith("Bearer ")) {
        throw new Response(JSON.stringify({ error: "unauthorized" }), {
          status: 401,
          headers: { "content-type": "application/json" },
        });
      }
    },
  },
});

Route-aware authorization

Use onBeforeHandler — the route object carries method, agentId, and (for thread/stop methods) threadId.

createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  hooks: {
    onBeforeHandler: async ({ route, request }) => {
      if (route.method === "agent/run" && route.agentId === "billing") {
        const ok = await canAccessBilling(request);
        if (!ok) throw new Response("Forbidden", { status: 403 });
      }
    },
  },
});

async function canAccessBilling(request: Request): Promise<boolean> {
  // delegate to your policy engine
  return true;
}

Rate-limit by calling an external limiter from the hook

Delegate to a dedicated lib — do not implement a rate limiter inline.

import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(60, "1 m"),
});

createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  hooks: {
    onRequest: async ({ request }) => {
      const userId = request.headers.get("x-user-id") ?? "anon";
      const { success } = await ratelimit.limit(userId);
      if (!success) throw new Response("Too Many Requests", { status: 429 });
    },
  },
});

Non-blocking telemetry on response

afterRequestMiddleware runs non-blocking (errors inside only log). Do not await heavy work that the user's response waits on.

import { CopilotRuntime } from "@copilotkit/runtime/v2";

const runtime = new CopilotRuntime({
  agents: {
    /* ... */
  } as any,
  afterRequestMiddleware: async ({ threadId, messages }) => {
    // fire-and-forget; do not await heavy work that blocks response
    void queue.enqueue({ type: "chat", threadId, messages });
  },
});

Common Mistakes

HIGH Returning a Response instead of throwing

Wrong:

new CopilotRuntime({
  agents,
  beforeRequestMiddleware: async () =>
    new Response("Unauthorized", { status: 401 }),
});

Correct:

new CopilotRuntime({
  agents,
  beforeRequestMiddleware: async ({ request }) => {
    if (!request.headers.get("authorization")) {
      throw new Response("Unauthorized", { status: 401 });
    }
  },
});

The middleware contract returns Request | void. Returning a Response corrupts the request object — fetch-handler.ts:140-147 assigns any truthy return value back to request, so the router then tries to read request.method / request.headers.get(...) from the Response and downstream handling blows up. Always throw a Response to short-circuit; never return one.

Source: packages/runtime/src/v2/runtime/core/fetch-handler.ts:140-156.

MEDIUM Defaulting to beforeRequestMiddleware when hooks are preferred

Wrong:

new CopilotRuntime({
  agents,
  beforeRequestMiddleware: async ({ request, path }) => {
    if (path.includes("/agent/admin/")) {
      /* check admin auth */
    }
  },
});

Correct:

const runtime = new CopilotRuntime({ agents });
const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  hooks: {
    onBeforeHandler: ({ route, request }) => {
      if (route.method === "agent/run" && route.agentId === "admin") {
        /* ... */
      }
    },
  },
});

Both surfaces coexist. For new code the hook API on createCopilotRuntimeHandler is preferred — onBeforeHandler receives typed route info, so you don't string-match paths.

Source: packages/runtime/src/v2/runtime/core/hooks.ts:84-117; maintainer Phase 4c.

MEDIUM Route-specific auth in global beforeRequestMiddleware

Wrong:

new CopilotRuntime({
  agents,
  beforeRequestMiddleware: async ({ path, request }) => {
    if (path.includes("/agent/admin/")) {
      /* ... */
    }
  },
});

Correct:

createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  hooks: {
    onBeforeHandler: ({ route, request }) => {
      if (route.method === "agent/run" && route.agentId === "admin") {
        /* ... */
      }
    },
  },
});

beforeRequestMiddleware fires before routing, so no route info exists yet — string-matching paths is fragile. onBeforeHandler fires after routing with typed route.method, route.agentId.

Source: packages/runtime/src/v2/runtime/core/hooks.ts:94-103.

MEDIUM Blocking on afterRequestMiddleware

Wrong:

new CopilotRuntime({
  agents,
  afterRequestMiddleware: async ({ response, threadId, messages }) => {
    await heavyAnalytics(response, threadId, messages);
  },
});

Correct:

new CopilotRuntime({
  agents,
  afterRequestMiddleware: async ({ response, threadId, messages }) => {
    void queue.enqueue({ type: "chat", threadId, messages, response });
  },
});

The afterRequestMiddleware callback receives { runtime, response, path, messages?, threadId?, runId? } — all these fields are always available (messages/threadId/runId are populated from the SSE stream when present, undefined otherwise). The hook runs non-blocking via .catch() so errors only log and any heavy awaited work can be lost on process exit — fire-and-forget is the intended shape.

Source: packages/runtime/src/v2/runtime/core/fetch-handler.ts:225-234.

MEDIUM Passing a webhook URL string as middleware

Wrong:

new CopilotRuntime({
  agents,
  beforeRequestMiddleware: "https://hooks.example/auth" as any,
});

Correct:

new CopilotRuntime({
  agents,
  beforeRequestMiddleware: async ({ request }) => {
    await fetch("https://hooks.example/auth", {
      method: "POST",
      body: request.headers.get("authorization") ?? "",
    });
  },
});

Webhook-URL middleware is dead code in v2 — the runtime logs "Unsupported beforeRequestMiddleware value – skipped" and does nothing. Only function middleware is wired.

Source: packages/runtime/src/v2/runtime/core/middleware.ts:72-87.

HIGH Implementing auth / rate-limit inside CopilotKit middleware

Wrong:

new CopilotRuntime({
  agents,
  beforeRequestMiddleware: async ({ request }) => {
    // hand-rolling a token-bucket rate limiter inline with Redis calls...
  },
});

Correct:

import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(60, "1 m"),
});

new CopilotRuntime({
  agents,
  beforeRequestMiddleware: async ({ request }) => {
    const { success } = await ratelimit.limit(
      request.headers.get("x-user-id") ?? "anon",
    );
    if (!success) throw new Response("Too Many Requests", { status: 429 });
  },
});

Auth, rate-limiting, and observability are server-framework concerns. CopilotKit middleware is the hook to invoke them, not a replacement.

Source: maintainer interview (Phase 2c).

See also

• copilotkit/setup-endpoint — hooks are passed to createCopilotRuntimeHandler
• copilotkit/go-to-production — production checklist lists auth/rate-limit wiring
• copilotkit/debug-and-troubleshoot — onError telemetry pattern