copilotkit__copilotkit/packages/runtime

CopilotKit - Runtime

✨ Why CopilotKit?

• Minutes to integrate - Get started quickly with our CLI
• Framework agnostic - Works with React, Next.js, AGUI and more
• Production-ready UI - Use customizable components or build with headless UI
• Built-in security - Prompt injection protection
• Open source - Full transparency and community-driven

🧑‍💻 Real life use cases

Deploy deeply-integrated AI assistants & agents that work alongside your users inside your applications.

🏆 Featured Examples

Documentation

To get started with CopilotKit, please check out the documentation.

Intelligence identity and Memory

An Intelligence Runtime supports web only, Channels only, or both. Web routes need identifyUser(request). Each Channel has its own identifyUser policy in createChannel. A Channels-only Runtime omits the web callback and exposes no functional web routes.

const runtime = new CopilotRuntime({
  agents,
  intelligence,
  identifyUser: authenticateApplicationUser,
  channels: [supportChannel],
  memory: {
    access: async ({ request, user, consumer }) => {
      const role = await roleFor(request, user);
      if (role === "blocked") return null;
      return consumer === "client"
        ? { user: "read", project: "none" }
        : { user: "read-write", project: "read" };
    },
  },
});

The callback runs once per web request. Its user owns ordinary web Threads and is reused for agent and browser Memory policy. Adding memory exposes the browser Memory routes and agent tools under the same policy. A denial returns 403; a policy error fails the request. Omitting memory hides the browser routes and does not attach Memory tools.

exposeMemoryRoutes and CopilotKitIntelligence({ enableEnterpriseLearning: true }) remain for one compatibility window. New code should use memory.access.

Highly experimental ACP agent

AcpAgent translates stable ACP v1 into AG-UI. Intelligence authenticates the relay and stores its raw ACP frames and remote session ID. The external deployment owns the ACP process, workspace access, credentials, and lifecycle.

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

const intelligence = new CopilotKitIntelligence({
  apiKey: process.env.COPILOTKIT_API_KEY!,
});

const identifyUser = async (request: Request) => {
  const user = await authenticateApplicationUser(request);
  return { id: user.id, name: user.name };
};

const runtime = new CopilotRuntime({
  intelligence,
  identifyUser,
  agents: async ({ request }) => {
    const user = await identifyUser(request);
    return {
      coding: new AcpAgent({
        intelligence,
        userId: user.id,
        runtimeInstanceId: "rti_external_01",
        agentId: "coding-agent",
        cwd: "/workspace",
      }),
    };
  },
});

The external relay connects to Intelligence with the same runtimeInstanceId and agentId. An uncertain write on the live channel retries with the same sender ID. Any socket, channel, or endpoint-process loss ends that transport. A later run starts at the journal high-water mark and loads the durable remote ACP session when the agent supports session/load; it does not replay an outcome-unknown prompt into a new ACP SDK connection.

The cwd selector crosses the relay inside the raw ACP session/new or session/load frame and is stored by Intelligence. Do not put credentials in it. This client sends no MCP server definitions and advertises no filesystem or terminal access; deployment-local relay code must own those capabilities.

Permission requests fail closed with ACP's cancelled outcome by default. A long-lived runtime with sticky routing may set permissionMode: "live" to emit AG-UI permission interrupts. Resume must then reach the same live AcpAgent instance or one of its clones. The request expires after five minutes by default; permissionTimeoutMs can set a shorter bound. A second overlapping permission request fails closed. Do not enable this mode in a multi-replica or serverless runtime until the app has a durable routing contract.

Analytics & Privacy

CopilotKit uses Scarf for anonymous usage analytics to help improve the product. Scarf handles all privacy compliance and does not store raw IP addresses. This helps us understand how CopilotKit is being used and prioritize improvements.

Opting Out

To disable analytics, set the environment variable:

export COPILOTKIT_TELEMETRY_DISABLED=true

Or use the DO_NOT_TRACK standard:

export DO_NOT_TRACK=1