Quickstart
Turn your LangGraph agent into an agent-native application in 10 minutes.
Start with your coding agent
Use this prompt to connect your LangGraph agent to CopilotKit and verify a working conversation. Your coding agent will follow this guide in your project, or you can work through the manual steps below.
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.
Prerequisites
Before you begin, you'll need the following:
- An OpenAI API key
- Node.js 20+
- Your favorite package manager
- (Optional) A LangSmith API key - only required if using an existing LangGraph agent
Getting started
Set up CopilotKit Intelligence
Sign in to cloud-hosted Intelligence. Cloud-hosted setup uses a server-side project API key and does not issue COPILOTKIT_LICENSE_TOKEN. You will connect the app after you create it below.
Run Intelligence locally instead
You can also run Intelligence in Docker on your own machine. The CopilotKit CLI sets up the local stack and connects your app to it. Read Evaluate Intelligence locally for the steps and the supported preview scope.
Choose your starting point
You can either start fresh with our starter template or integrate CopilotKit into your existing LangGraph agent.
Run our CLI
npx copilotkit@latest createThe CLI walks you through:
- Project name
- CopilotKit Intelligence: persistent threads and the inspector. Choose Yes to scaffold a project pre-wired for the platform (the CLI walks you through sign-up, or you can create an account first), or No for a standard LangGraph setup.
- Framework: pick LangGraph (Python) or LangGraph (JavaScript).
Install dependencies
npm installConfigure your environment
Copy the example file in the project root. The agent reads this file too, because its langgraph.json points at ../.env.
cp .env.example .envThen add your OpenAI API key to .env:
OPENAI_API_KEY=your_openai_api_keyGet your OpenAI API key
Using Anthropic or Google instead
Both starters (Python and JavaScript) read the model from COPILOTKIT_AGENT_MODEL as <provider>:<model>. The provider is openai, anthropic or google. The starters already install the Anthropic and Google model packages, so you do not change any code. To use Claude, set these two values in .env:
ANTHROPIC_API_KEY=your_anthropic_api_key
COPILOTKIT_AGENT_MODEL=anthropic:claude-sonnet-4-6Get your Anthropic API key
For Google, set GOOGLE_API_KEY and use google:<model>. COPILOTKIT_AGENT_MODEL applies to every model call in the agent.
Start chatting
Your AI agent is now ready to use. Try asking it some questions:
Can you tell me a joke?Can you help me understand AI?What do you think about React?Connection refused from the runtime
-
Check the port. Without
--port, the LangGraph CLI listens on2024. This guide pins8123with--port 8123. TheLANGGRAPH_DEPLOYMENT_URLof the runtime (or its fallback) must name the port that the agent uses. -
Keep
localhostin the URL. Do not use a literal IP. The loopback address that reaches the agent depends on the CLI.0.0.0.0is a bind-all address for a server, never a valid target in a client URL.langgraph dev(the Pythonlanggraph-clipackage) defaults to--host 127.0.0.1, so bothhttp://127.0.0.1:8123andhttp://localhost:8123reach it.http://[::1]:8123does not reach it, because the server does not listen on IPv6.
"graph is nullish" (TypeScript agents)
The LangGraph CLI fails to load your graph.
- Run
npx @langchain/langgraph-cli devfrom the folder that holdslanggraph.json. - Make sure that the export name in
langgraph.jsonmatches your code. For example,"sample_agent": "./src/agent.ts:graph"needsexport const graph = ...insrc/agent.ts. - Run
npm installin your agent directory.
The agent does not answer
- Make sure that the
envfield inlanggraph.jsonpoints to your.envfile. - Make sure that
OPENAI_API_KEYis set in the.envfile. - If you use an existing agent, set your LangSmith API key too.
- Make sure that the runtime endpoint path matches the
runtimeUrlin your CopilotKit provider.
Open Inspector and confirm setup
On localhost, click the Inspector button in the corner of the app.
- Open Inspect, then Agent. Your agent is listed.
- Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
- Open Rich Threads. The list is unlocked (Intelligence is on), or locked with Copy setup prompt (Intelligence is off).
More detail: Inspector.
Deploying to AWS?
If you're planning to deploy your LangGraph agent to AWS Bedrock AgentCore, see the AgentCore deploy guide.
What's next?
Now that you have your basic agent setup, explore these advanced features:
Implement Human in the Loop
Allow your users and agents to collaborate together on tasks.
Utilize Shared State
Learn how to synchronize your agent's state with your UI's state, and vice versa.
Add some generative UI
Render your agent's progress and output in the UI.
Setup frontend actions
Give your agent the ability to call frontend tools, directly updating your application.
How is this guide?