CopilotKit + LangGraph (Python)

A starter template for building AI agents using LangGraph (Python) and CopilotKit, with optional CopilotKit Intelligence for durable conversation threads.

Architecture

This project is a monorepo with three services:

Service	Port	Description
Frontend (apps/app)	3000	Vite + React app with CopilotKit chat UI
BFF (apps/bff)	4000	Hono server running the CopilotKit runtime
Agent (apps/agent)	8123	Python LangGraph agent

When threads are enabled, additional infrastructure runs via Docker Compose:

Service	Port	Description
PostgreSQL	5432	Thread and event storage
Redis	6379	Session/cache
Intelligence	4201, 4401	All-in-one CopilotKit Intelligence container (app-api on 4201, realtime-gateway on 4401, plus thread-culler and db-migrations, under s6-overlay).

Prerequisites

• Node.js 18+
• Python 3.12+
• npm 10+
• OpenAI API Key
• Docker (for threads/intelligence support)

Getting Started

1. Install dependencies:

npm install

2. Set up environment variables:

cp .env.example .env

Edit .env and add your OpenAI API key.

3. Get a license key (if you don't already have one):

copilotkit license -n my-project

This authenticates you and issues a COPILOTKIT_LICENSE_TOKEN. Add it to your .env.

4. Start all services:

npm run dev

This starts Docker Compose infrastructure first, then starts the frontend, BFF, and agent concurrently.

The infrastructure step pulls ghcr.io/copilotkit/intelligence/composite — a single container that runs app-api, realtime-gateway, thread-culler, and the db-migrations oneshot together under s6-overlay supervision. The per-service images remain available at ghcr.io/copilotkit/intelligence/{app-api,realtime-gateway,thread-culler,db-migrations} if you'd rather run them separately.

You can also run each piece directly:

npm run dev:infra
npm run dev:app
npm run dev:bff
npm run dev:agent

After infrastructure is already running, use the app, BFF, and agent commands directly when you only need to restart one service.

Removing Threads

To strip out threads/intelligence and use this as a plain CopilotKit + LangGraph demo:

Frontend

• Delete apps/app/src/components/threads-drawer/ (the entire directory)
• Revert apps/app/src/App.tsx to remove the ThreadsDrawer component and the thread-aware layout wrapper. The app should go back to:

import { CopilotChat, CopilotKitProvider } from "@copilotkit/react-core/v2";
import { ExampleLayout } from "@/components/example-layout";
import { ExampleCanvas } from "@/components/example-canvas";
import { useGenerativeUIExamples, useExampleSuggestions } from "@/hooks";
import { ThemeProvider } from "@/hooks/use-theme";

function HomePage() {
  useGenerativeUIExamples();
  useExampleSuggestions();

  return (
    <ExampleLayout
      chatContent={
        <CopilotChat input={{ disclaimer: () => null, className: "pb-6" }} />
      }
      appContent={<ExampleCanvas />}
    />
  );
}

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

BFF

• In apps/bff/src/server.ts, remove the CopilotKitIntelligence import and configuration block. Change the CopilotRuntime options:
  • Remove intelligence
  • Remove identifyUser
  • Remove licenseToken
• Switch the endpoint back to the non-v2 API if desired (or keep v2 without intelligence — both work)

Infrastructure

• Delete docker-compose.yml and docker/init-db/
• Remove the INTELLIGENCE_* variables from .env / .env.example if you are no longer using CopilotKit Intelligence

Summary of files to touch

Action	Path
Delete	apps/app/src/components/threads-drawer/
Edit	apps/app/src/App.tsx
Edit	apps/bff/src/server.ts
Delete	docker-compose.yml
Delete	docker/init-db/
Edit	.env.example

Documentation

• CopilotKit Docs
• LangGraph Docs

License

MIT