Connect Intelligence in 5 minutes

Connect an existing CopilotKit app to Intelligence and store persistent threads in a cloud-hosted project.

You want to persist conversations reliably in production, improve your agents over time, understand their performance with AI analytics, and inspect every thread, event, and state change. CopilotKit Intelligence adds these capabilities to your existing app without changing your frontend or agent framework.

You are done when Inspector shows that Intelligence is connected and displays your first saved thread. React Native apps confirm the thread in the hosted Intelligence project because React Native does not include Inspector.

Start with your coding agent#

If your app already has a working CopilotKit agent and frontend, use this prompt to configure the remaining Intelligence pieces.

Finish setup with your coding agent

Copy this prompt. Your agent will inspect your app, make the required Runtime changes, and verify Rich Threads.

Set it up manually#

Before you start, make sure that you have a CopilotKit app with a working agent, runtime, and frontend.

Select an Intelligence project#

Terminal

npx copilotkit@latest login
npx copilotkit@latest project select

project select writes a project API key to .env as CPK_INTELLIGENCE_API_KEY. Keep this key on the server.

Connect your runtime#

Construct the Intelligence client. Then pass it and your existing user lookup to CopilotRuntime.

Your CopilotKit runtime

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. You must also enforce thread ownership for threads/events, threads/state, and agent/stop. Follow the thread authorization guide for the complete pattern.

Expose the thread routes#

Use the multi-route handler. Mount the complete runtime subtree. Export GET, POST, PATCH, and DELETE.

app/api/copilotkit/[[...slug]]/route.ts

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;

This example uses a Next.js catch-all route, but the fetch-based handler works with any server that uses standard Web Request and Response objects. For another server, use the runtime adapter guide.

Use the multi-route frontend transport#

Point your frontend provider at the runtime base path.

Add the runtimeUrl prop to your CopilotKitProvider. The provider uses the multi-route transport to send messages, events, and state to the runtime.

Your CopilotKit provider

import { CopilotKitProvider } from "@copilotkit/react-core/v2";

export function App() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <YourApp />
    </CopilotKitProvider>
  );
}

Confirm the connection#

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 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.

Intelligence is connected

Your runtime stores new conversations in Intelligence. Browser apps can inspect their messages, events, and state in Inspector. React Native apps can inspect them in the hosted Intelligence project.