@copilotkit/runtime 1.71.0 → 1.71.1

package/skills/runtime/references/setup-endpoint.md

@@ -1,503 +0,0 @@
-# CopilotKit Runtime Endpoint
-
-`createCopilotRuntimeHandler` is the strongly-preferred primitive. It returns a
-`(Request) => Promise<Response>` that works in every fetch-native runtime and can be
-delegated to from Express/Hono/Node. Avoid `createCopilotExpressHandler` and
-`createCopilotHonoHandler` in new code.
-
-## Setup
-
-Minimal runtime on any fetch server (Bun, Deno, Cloudflare Workers, Vercel Edge):
-
-```typescript
-import {
-  CopilotRuntime,
-  createCopilotRuntimeHandler,
-  BuiltInAgent,
-  convertInputToTanStackAI,
-} from "@copilotkit/runtime/v2";
-import { chat } from "@tanstack/ai";
-import { openaiText } from "@tanstack/ai-openai";
-
-const runtime = new CopilotRuntime({
-  agents: {
-    default: new BuiltInAgent({
-      type: "tanstack",
-      factory: ({ input, abortController }) => {
-        const { messages, systemPrompts } = convertInputToTanStackAI(input);
-        return chat({
-          adapter: openaiText("gpt-4o"),
-          messages,
-          systemPrompts,
-          abortController,
-        });
-      },
-    }),
-  },
-});
-
-export const handler = createCopilotRuntimeHandler({
-  runtime,
-  basePath: "/api/copilotkit",
-  cors: true,
-});
-
-// Bun / Deno / Vercel Edge:
-//   Bun.serve({ fetch: handler });
-//   Deno.serve(handler);
-// Cloudflare Workers:
-//   export default { fetch: handler };
-```
-
-## Core Patterns
-
-### React Router v7 framework mode
-
-```typescript
-// app/routes/api.copilotkit.$.tsx
-import type { Route } from "./+types/api.copilotkit.$";
-import {
-  CopilotRuntime,
-  createCopilotRuntimeHandler,
-  BuiltInAgent,
-  convertInputToTanStackAI,
-} from "@copilotkit/runtime/v2";
-import { chat } from "@tanstack/ai";
-import { openaiText } from "@tanstack/ai-openai";
-
-const runtime = new CopilotRuntime({
-  agents: {
-    default: new BuiltInAgent({
-      type: "tanstack",
-      factory: ({ input, abortController }) => {
-        const { messages, systemPrompts } = convertInputToTanStackAI(input);
-        return chat({
-          adapter: openaiText("gpt-4o"),
-          messages,
-          systemPrompts,
-          abortController,
-        });
-      },
-    }),
-  },
-});
-
-const handler = createCopilotRuntimeHandler({
-  runtime,
-  basePath: "/api/copilotkit",
-});
-
-export async function loader({ request }: Route.LoaderArgs) {
-  return handler(request);
-}
-export async function action({ request }: Route.ActionArgs) {
-  return handler(request);
-}
-```
-
-### Next.js App Router
-
-```typescript
-// app/api/copilotkit/[...slug]/route.ts
-import {
-  CopilotRuntime,
-  createCopilotRuntimeHandler,
-  BuiltInAgent,
-  convertInputToTanStackAI,
-} from "@copilotkit/runtime/v2";
-import { chat } from "@tanstack/ai";
-import { openaiText } from "@tanstack/ai-openai";
-
-const runtime = new CopilotRuntime({
-  agents: {
-    default: new BuiltInAgent({
-      type: "tanstack",
-      factory: ({ input, abortController }) => {
-        const { messages, systemPrompts } = convertInputToTanStackAI(input);
-        return chat({
-          adapter: openaiText("gpt-4o"),
-          messages,
-          systemPrompts,
-          abortController,
-        });
-      },
-    }),
-  },
-});
-
-const handler = createCopilotRuntimeHandler({
-  runtime,
-  basePath: "/api/copilotkit",
-});
-
-export const GET = handler;
-export const POST = handler;
-export const OPTIONS = handler;
-```
-
-### Cloudflare Workers with env-sourced keys
-
-Workers don't expose `env` at module scope, so build the runtime + handler lazily on the
-first request and cache them in module-scoped variables. `openaiText(model, config)` does
-NOT accept an `apiKey` in its config (it auto-reads `OPENAI_API_KEY` from env) — for an
-explicit key, use `createOpenaiChat(model, apiKey, config?)`.
-
-```typescript
-// worker.ts
-import {
-  CopilotRuntime,
-  createCopilotRuntimeHandler,
-  BuiltInAgent,
-  convertInputToTanStackAI,
-} from "@copilotkit/runtime/v2";
-import { chat } from "@tanstack/ai";
-import { createOpenaiChat } from "@tanstack/ai-openai";
-
-interface Env {
-  OPENAI_API_KEY: string;
-}
-
-type Handler = (request: Request) => Promise<Response>;
-let handler: Handler | undefined;
-
-function getHandler(env: Env): Handler {
-  if (handler) return handler;
-  const runtime = new CopilotRuntime({
-    agents: {
-      default: new BuiltInAgent({
-        type: "tanstack",
-        factory: ({ input, abortController }) => {
-          const { messages, systemPrompts } = convertInputToTanStackAI(input);
-          return chat({
-            adapter: createOpenaiChat("gpt-4o", env.OPENAI_API_KEY),
-            messages,
-            systemPrompts,
-            abortController,
-          });
-        },
-      }),
-    },
-  });
-  handler = createCopilotRuntimeHandler({
-    runtime,
-    basePath: "/api/copilotkit",
-    cors: true,
-  });
-  return handler;
-}
-
-export default {
-  fetch(request: Request, env: Env) {
-    return getHandler(env)(request);
-  },
-};
-```
-
-### Delegate from Express / Hono to the fetch primitive
-
-Do not use `createCopilotExpressHandler` / `createCopilotHonoHandler`.
-
-```typescript
-// Express — requires Node 18.17+ for Readable.fromWeb + fetch body: req
-import express from "express";
-import { Readable } from "node:stream";
-import type { ReadableStream as WebReadableStream } from "node:stream/web";
-import {
-  CopilotRuntime,
-  createCopilotRuntimeHandler,
-} from "@copilotkit/runtime/v2";
-
-const app = express();
-const runtime = new CopilotRuntime({
-  agents: {
-    /* ... */
-  } as any,
-});
-const handler = createCopilotRuntimeHandler({
-  runtime,
-  basePath: "/api/copilotkit",
-});
-
-app.all("/api/copilotkit/*", async (req, res) => {
-  const url = new URL(req.url, `http://${req.headers.host}`);
-  // `body: req` + `duplex: "half"` lets us stream the Node IncomingMessage
-  // into a Web Request without buffering (Node 18.17+).
-  const webReq = new Request(url, {
-    method: req.method,
-    headers: req.headers as any,
-    body: ["GET", "HEAD"].includes(req.method!) ? undefined : req,
-    duplex: "half",
-  } as any);
-  const webRes = await handler(webReq);
-  res.status(webRes.status);
-  webRes.headers.forEach((v, k) => res.setHeader(k, v));
-  // Stream the response body through — required for SSE on
-  // /agent/*/run and /agent/*/connect. Buffering via arrayBuffer()
-  // would collapse the stream and deliver all events at end-of-stream.
-  if (webRes.body) {
-    Readable.fromWeb(webRes.body as unknown as WebReadableStream).pipe(res);
-  } else {
-    res.end();
-  }
-});
-
-app.listen(3000);
-```
-
-```typescript
-// Hono — already speaks Request/Response
-import { Hono } from "hono";
-import {
-  CopilotRuntime,
-  createCopilotRuntimeHandler,
-} from "@copilotkit/runtime/v2";
-
-const app = new Hono();
-const runtime = new CopilotRuntime({
-  agents: {
-    /* ... */
-  } as any,
-});
-const handler = createCopilotRuntimeHandler({
-  runtime,
-  basePath: "/api/copilotkit",
-});
-
-app.all("/api/copilotkit/*", (c) => handler(c.req.raw));
-
-export default app;
-```
-
-### Route table
-
-Multi-route mode (default) exposes: `GET /info`, `POST /agent/:agentId/run`,
-`GET /agent/:agentId/connect`, `POST /agent/:agentId/stop/:threadId`, `POST /transcribe`,
-`GET/POST /threads`, `GET /threads/subscribe`, `PATCH /threads/:threadId`,
-`POST /threads/:threadId/archive`, `DELETE /threads/:threadId`,
-`GET /threads/:threadId/messages`. Thread routes are only wired when Intelligence mode
-is configured.
-
-Single-route mode exposes a single `POST basePath` that accepts
-`{ method, params, body }` envelopes — use when behind a strict reverse proxy.
-
-## Common Mistakes
-
-### CRITICAL Using createCopilotExpressHandler / createCopilotHonoHandler in new code
-
-Wrong:
-
-```typescript
-import { createCopilotExpressHandler } from "@copilotkit/runtime/v2/express";
-app.use(
-  "/api/copilotkit",
-  createCopilotExpressHandler({ runtime, basePath: "/api/copilotkit" }),
-);
-```
-
-Correct:
-
-```typescript
-import { Readable } from "node:stream";
-import type { ReadableStream as WebReadableStream } from "node:stream/web";
-import { createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
-const handler = createCopilotRuntimeHandler({
-  runtime,
-  basePath: "/api/copilotkit",
-});
-app.all("/api/copilotkit/*", async (req, res) => {
-  // Requires Node 18.17+ (Readable.fromWeb + duplex: "half")
-  const webReq = new Request(new URL(req.url, `http://${req.headers.host}`), {
-    method: req.method,
-    headers: req.headers as any,
-    body: ["GET", "HEAD"].includes(req.method!) ? undefined : req,
-    duplex: "half",
-  } as any);
-  const webRes = await handler(webReq);
-  res.status(webRes.status);
-  webRes.headers.forEach((v, k) => res.setHeader(k, v));
-  // Stream, don't buffer — /agent/*/run is SSE.
-  if (webRes.body) {
-    Readable.fromWeb(webRes.body as unknown as WebReadableStream).pipe(res);
-  } else {
-    res.end();
-  }
-});
-```
-
-The Express and Hono adapters are a discouraged surface — the maintainer flags them as
-"avoid at all costs." They pull in heavier dependencies, add framework binding, and make
-it harder to port. The fetch handler works from any Express/Hono route.
-
-Source: `packages/runtime/src/v2/runtime/core/fetch-handler.ts:1-27`; maintainer Phase 4d.
-
-### CRITICAL Instantiating Express handler without basePath
-
-Wrong:
-
-```typescript
-app.use(createCopilotExpressHandler({ runtime }));
-```
-
-Correct:
-
-```typescript
-const handler = createCopilotRuntimeHandler({
-  runtime,
-  basePath: "/api/copilotkit",
-});
-app.all("/api/copilotkit/*", (req, res) => {
-  /* delegate as shown above */
-});
-```
-
-`normalizeBasePath` throws `"basePath must be provided for Express endpoint"` at mount time
-and crashes the server.
-
-Source: `packages/runtime/src/v2/runtime/endpoints/express.ts:161`.
-
-### HIGH Using framework adapter on Workers / Bun / Deno
-
-Wrong:
-
-```typescript
-// Cloudflare Worker
-import { createCopilotHonoHandler } from "@copilotkit/runtime/v2/hono";
-export default app;
-```
-
-Correct:
-
-```typescript
-import { createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
-const handler = createCopilotRuntimeHandler({
-  runtime,
-  basePath: "/api/copilotkit",
-});
-export default { fetch: (req: Request) => handler(req) };
-```
-
-Adapters bundle Node polyfills unnecessarily in fetch-native runtimes.
-
-Source: `packages/runtime/src/v2/runtime/core/fetch-handler.ts:1-27`.
-
-### HIGH Returning a Response from beforeRequestMiddleware
-
-Wrong:
-
-```typescript
-new CopilotRuntime({
-  agents,
-  beforeRequestMiddleware: async () =>
-    new Response("Unauthorized", { status: 401 }),
-});
-```
-
-Correct:
-
-```typescript
-const handler = createCopilotRuntimeHandler({
-  runtime,
-  basePath: "/api/copilotkit",
-  hooks: {
-    onRequest: ({ request }) => {
-      if (!request.headers.get("authorization")) {
-        throw new Response("Unauthorized", { status: 401 });
-      }
-    },
-  },
-});
-```
-
-Only `Request | void` returns are honored. Any other return is ignored. Responses must be
-thrown.
-
-Source: `packages/runtime/src/v2/runtime/core/fetch-handler.ts:148-156`.
-
-### MEDIUM Calling multi-route paths against a single-route handler
-
-Wrong:
-
-```typescript
-// handler = createCopilotRuntimeHandler({ mode: "single-route", ... })
-fetch("/api/copilotkit/agent/x/run", {
-  method: "POST",
-  body: JSON.stringify(input),
-});
-```
-
-Correct:
-
-```typescript
-fetch("/api/copilotkit", {
-  method: "POST",
-  body: JSON.stringify({
-    method: "agent/run",
-    params: { agentId: "x" },
-    body: input,
-  }),
-});
-// On the client, pair with <CopilotKit useSingleEndpoint /> from "@copilotkit/react-core/v2".
-```
-
-Single-route expects a POST envelope with `{ method, params, body }`; URL-pattern calls 404.
-
-Source: `packages/runtime/src/v2/runtime/core/fetch-handler.ts:86-90,350-401`.
-
-### MEDIUM Double-layering CORS in Express
-
-Wrong:
-
-```typescript
-import cors from "cors";
-app.use(cors());
-app.use(
-  createCopilotExpressHandler({ runtime, basePath, cors: { origin: "..." } }),
-);
-```
-
-Correct:
-
-```typescript
-// Pick one — handler's cors option OR your own cors(), not both:
-const handler = createCopilotRuntimeHandler({
-  runtime,
-  basePath: "/api/copilotkit",
-  cors: { origin: "https://my.app" },
-});
-app.all("/api/copilotkit/*", (req, res) => {
-  /* delegate as above */
-});
-```
-
-Both layers add CORS headers and the duplicates break strict browser enforcement.
-
-Source: `packages/runtime/src/v2/runtime/endpoints/express.ts:100-143`.
-
-### HIGH Mixing v1 and v2 import paths
-
-Wrong:
-
-```typescript
-import { CopilotRuntime } from "@copilotkit/runtime";
-import { createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
-```
-
-Correct:
-
-```typescript
-import {
-  CopilotRuntime,
-  createCopilotRuntimeHandler,
-} from "@copilotkit/runtime/v2";
-```
-
-Both v1 and v2 APIs compile together but route through different implementations. Always
-use the `/v2` subpath in v2 code.
-
-Source: `packages/runtime/src/v2/index.ts`.
-
-## See also
-
-- `copilotkit/middleware` — hook lifecycle into this handler
-- `copilotkit/agent-runners` — pair with a persistent runner for production
-- `copilotkit/intelligence-mode` — thread routes flip on when Intelligence is configured