Connect Intelligence in 5 minutes
Connect an existing CopilotKit app to Intelligence and store persistent threads in a cloud-hosted project.
Overview
You want AG-UI Streams, User Memory, Automatic Learning, Channels, and Product Analytics on the app you already have. Intelligence adds that layer. Your frontend and your agent stay where they are.
Keep your existing thread storage and native persistence configured. Intelligence automatically records its own copy of supported AG-UI interaction history as conversations run through the connected runtime. See what Intelligence records and the existing LangGraph app example.
You are done when Inspector shows that Intelligence is connected and shows your first saved thread. A React Native app has no Inspector. Confirm the thread in the cloud-hosted project instead.
TypeScript is the default runtime. It can run with or without Intelligence. Python, Go, Ruby, and C#/.NET runtimes require Intelligence, either cloud-hosted or self-hosted. Pick the language of your runtime server below; your agent framework and frontend stay the same.
Start with your coding agent
Use this prompt to set up Intelligence in a new or existing app. Tell your coding agent which runtime language, agent framework, and frontend you want to use.
Open your coding agent in your project's folder, or in an empty folder for a new app.This runs in a coding agent on your computer.
Set it up manually
Before you start, have a working CopilotKit frontend and agent. The TypeScript tab connects your existing runtime; the other tabs mount a native runtime in front of an agent that already serves AG-UI over HTTP. Use your agent's AG-UI URL, not the CopilotKit runtime URL.
Select an Intelligence project
Sign in from your app directory. Then select the project that will store your threads.
npx copilotkit@latest login
npx copilotkit@latest project selectproject select creates a project API key and writes it to .env as CPK_INTELLIGENCE_API_KEY. Put that key in the environment of the process that runs your CopilotKit runtime. The command output does not print the key. Read it from .env.
CPK_INTELLIGENCE_API_KEY=cpk-...The CLI writes .env in the directory where you run the command. If your runtime process loads a different file, copy the key into that file. A value that the host already sets stays as it is.
Keep the key on the server. Do not put it in a variable that the frontend build sends to the browser.
Connect your runtime
Choose your runtime language. The selection also applies to the self-hosted settings below. These examples use multi-route HTTP endpoints in every language.
Keep your existing TypeScript runtime and agent registration. Install the current package if you have not already:
npm install @copilotkit/runtimeAdd an Intelligence client. The client is the same for every agent framework.
import {
CopilotKitIntelligence,
CopilotRuntime,
} from "@copilotkit/runtime/v2";
// Create the Intelligence client with your project API key. Keep this key on the server.
const intelligence = new CopilotKitIntelligence({
apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
});
const runtime = new CopilotRuntime({
agents,
// Pass the Intelligence client to the runtime
intelligence,
// Identify the user from a verified session or token
identifyUser: async (request) => {
const user = await authenticateApplicationUser(request);
if (!user) throw new Error("Unauthorized");
return { id: user.id, name: user.name };
},
});Use your existing authentication
authenticateApplicationUser represents your server-side authentication function. It must return the user from a verified session or token. The Runtime requires identifyUser to associate web threads with that user.
If no trusted user identity exists, add authentication before you continue. A fixed identity is suitable only for a local, single-user demo.
Protect every Runtime route before production
identifyUser names the caller, but it is not an authentication gate. Use the handler's onRequest hook to reject unauthenticated requests. The runtime checks thread ownership on every thread route, including threads/events, threads/state, and agent/stop, with the user that identifyUser returns. Follow the thread authorization guide for the onRequest pattern.
A web runtime requires identifyUser. A Channels-only runtime has no web surface. Pass a non-empty channels array instead.
The runtime reads the key from the client you pass. It does not read the key from the environment on its own. apiKey is the only required field. You do not pass an organization id or a project id.
An existing runtime that already has a runner
An open-source runtime often passes runner. That option chooses where runs are stored. Intelligence stores the runs itself. Remove runner when you add intelligence.
const runtime = new CopilotRuntime({
agents,
runner: new InMemoryAgentRunner(),
intelligence,
identifyUser,
});TypeScript rejects both options together. A JavaScript runtime throws this error:
Intelligence Runtime auto-wires its own `runner`; passing `runner` alongside
`intelligence` is not supported.You can keep runner and omit intelligence. The runtime then stays in SSE mode, and Threads in Inspector stay locked. See AgentRunner and persistence.
Keep the other runtime options that you already pass, such as mcpApps, a2ui, and openGenerativeUI. They apply to the agent on each run, and they work the same way with intelligence. For an app that uses MCP Apps, see MCP Apps with Intelligence.
Mount the TypeScript handler
Create one handler and mount it for all runtime subpaths and HTTP methods in the server you already use. For Next.js, use a catch-all route:
import { createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
const handler = createCopilotRuntimeHandler({
runtime,
basePath: "/api/copilotkit",
});
export const GET = handler;
export const POST = handler;
export const PATCH = handler;
export const DELETE = handler;Use this handler in the same module as the configured runtime above. It accepts a Web Request and returns a Web Response. For Express, Hono, and other hosts, use the TypeScript server adapter guide.
TypeScript also supports mode: "single-route". If your existing app uses that mode, keep its single POST route and matching frontend transport. That option does not apply to the other runtime languages.
Connect your frontend
Point your frontend provider at the runtime base path. Use /api/copilotkit if your frontend proxies that path to the runtime. For a separate local server, use http://localhost:8200/api/copilotkit and allow your frontend's exact origin in the runtime's CORS configuration.
Keep your existing application authentication headers or session. The examples below connect to a TypeScript runtime. For a Python, Go, Ruby, or C#/.NET runtime from the tabs above:
- Set the runtime URL to
http://localhost:8200/api/copilotkit. - Uncomment the
headersline. It sends a local application token:Authorization: Bearer <APP_AUTH_TOKEN>. - Replace
<APP_AUTH_TOKEN>with the same local token you configured on the server. This development token is notCPK_INTELLIGENCE_API_KEY. - Before deployment, replace the local token scheme with your application's authentication.
Point CopilotKitProvider at the runtime base path and wrap your existing app.
<script setup lang="ts">
import { CopilotKitProvider } from "@copilotkit/vue/v2";
import YourApp from "./YourApp.vue";
</script>
<template>
<!-- Native runtime: add :headers="{ Authorization: 'Bearer <APP_AUTH_TOKEN>' }" -->
<CopilotKitProvider runtime-url="http://localhost:8200/api/copilotkit">
<YourApp />
</CopilotKitProvider>
</template>Confirm the connection
Start the runtime and check discovery at {runtimeUrl}/info. For a Next.js TypeScript handler on port 3000:
curl --fail http://localhost:3000/api/copilotkit/infoFor the native examples, use http://localhost:8200/api/copilotkit/info.
The response should report mode: "intelligence" and your registered agent. Discovery alone does not prove persistence; create and inspect a thread next.
Start your app and open it on localhost. Click the Inspector button (Kite icon) in the corner of the app.
- Open Home. Make sure that Intelligence connected appears beside What's going on.
- Return to your app and send one message to create a thread.
- Open Rich Threads in Inspector. Your new thread must appear in the list.
- Open the thread. Make sure that Messages contains the message that you sent.
If Home does not show Intelligence connected, or Threads is locked, the setup is incomplete. Follow the action shown in Inspector or review the Inspector setup states.
A chat reply does not prove that the key is in use. An SSE runtime replies with the key unread. Use the Inspector check above, or open the thread in the cloud-hosted project.
Self-hosted deployments
All runtimes default to cloud-hosted Intelligence. For self-hosting, replace the endpoint settings in your selected runtime's configuration. Keep the project key and authentication from the setup above. Use the public addresses that your runtime and browser can reach.
Set both apiUrl and wsUrl on CopilotKitIntelligence. Pass a bare WebSocket base; the client appends /runner and /client.
const intelligence = new CopilotKitIntelligence({
apiUrl: "https://api.intelligence.internal",
wsUrl: "wss://realtime.intelligence.internal",
apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
});Do not append /api to the API host or /websocket to either WebSocket URL. The clients add those path segments. Setting only some endpoints can leave requests split between your deployment and cloud-hosted Intelligence.
Install steps are on Self-host on Kubernetes and Self-host on ECS.
Troubleshooting
In TypeScript, check that intelligence was passed to CopilotRuntime; otherwise it stays in SSE mode. The other runtimes have no SSE-only fallback. Check their server diagnostics and Intelligence endpoint settings.
CPK_INTELLIGENCE_API_KEY is empty, or it belongs to another project. Copy the key from the .env that project select wrote into the environment of the runtime process. Then restart the runtime.
Check every endpoint in the self-hosted settings above. The realtime host differs from the API host. Native runtimes need separate /runner and /client URLs; TypeScript uses the bare wsUrl.
apiUrl included an /api suffix. Remove /api from apiUrl.
This is a TypeScript configuration error: runner and intelligence are both set. Intelligence wires its own runner.
How is this guide?