copilotkit-agent-runner

Open-source LangGraph thread history persistence for CopilotKit. Restore chat history on page refresh with your own LangGraph deployment.

The Problem

Building a chat app with CopilotKit and LangGraph? You've probably noticed:

• Page refresh = empty chat - All messages disappear
• Thread switching loses context - No automatic history restoration
• No persistence of agent state - Users lose context

CopilotKit's default runtime doesn't automatically fetch historical messages from LangGraph's checkpoint system. This package adds that capability.

The Solution

With this package:

• Chat history restored on page load
• Seamless thread switching
• Agent state preserved
• Works with any LangGraph deployment (LangGraph Cloud, self-hosted)
• MIT licensed, open-source

Installation

Step 1: Set these environment variables:

# Required
LANGGRAPH_DEPLOYMENT_URL=https://your-deployment.langchain.com

# Optional (for authentication)
LANGSMITH_API_KEY=your-api-key

Step 2:

npm install
npm run dev

cd examples/nextjs-copilotkit
npm install
npm run dev

The app should be running on localhost:3000

Using the local build (e.g. in the BOL app)

If this package lives in your repo (e.g. Docs/copilotkit-with-history) and you want FullStack to use the local build with the latest fixes:

# From repo root
cd Docs/copilotkit-with-history && pnpm install && pnpm run build && cd ../..
cd FullStack && pnpm add file:../Docs/copilotkit-with-history

Then restart your dev server. To switch back to the published package: pnpm add [email protected] (or latest).

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Credits

Created by Elisha Kramer.

Inspired by the need for thread history persistence in CopilotKit + LangGraph applications.