Quickstart
Get started with Deep Agents and CopilotKit in minutes.
Start with your coding agent
Use this prompt to connect your Deep Agents 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
- A LangSmith API key, only if you deploy the agent to LangGraph Platform
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.
Initialize your agent project
If you don't already have a Python project set up, create one using uv:
uv init my-agent
cd my-agentAdd necessary dependencies
Add the deepagents, langchain-openai, and copilotkit packages:
uv add deepagents copilotkit langchain-openaiCreate your Deep Agent
Create a simple Deep Agent:
from deepagents import create_deep_agent
from copilotkit import CopilotKitMiddleware
def get_weather(location: str):
"""Get weather for a location"""
return f"The weather in {location} is sunny."
agent = create_deep_agent(
model="openai:gpt-6-luna",
tools=[get_weather],
middleware=[CopilotKitMiddleware()], # for frontend tools and context
system_prompt="You are a helpful research assistant.",
)To run the agent with the LangGraph CLI, create a langgraph.json:
touch langgraph.json{
"python_version": "3.12",
"dockerfile_lines": [],
"dependencies": ["."],
"package_manager": "uv",
"graphs": {
"sample_agent": "./main.py:agent"
},
"env": ".env"
}What is AG-UI?
AG-UI is an open protocol for frontend-agent communication. Deep Agents use it to stream state and tool calls to your frontend in real-time.
Configure your environment
Create a .env file in your agent directory and add your OpenAI API key:
OPENAI_API_KEY=your_openai_api_keyOther models
Deep Agents support any model available via LangChain. Change the model parameter in create_deep_agent to switch providers.
Create your frontend
CopilotKit works with any React-based frontend. We'll use Next.js for this example.
npx create-next-app@latest frontend
cd frontendInstall CopilotKit packages
npm install @copilotkit/react-core @copilotkit/runtime @ag-ui/client@1.0.2The FastAPI route below imports HttpAgent from @ag-ui/client.
Version 1.0.2 matches the one @copilotkit/runtime uses.
Setup Copilot Runtime
Create an API route to connect CopilotKit to your Deep Agent:
mkdir -p "app/api/copilotkit/[[...slug]]" && touch "app/api/copilotkit/[[...slug]]/route.ts"Using Next.js is optional
If you'd rather skip the Next.js API proxy, see LangChain's CopilotKit integration guide for how to add a custom CopilotKit route directly to your LangGraph deployment.
import {
CopilotKitIntelligence,
CopilotRuntime,
createCopilotRuntimeHandler,
} from "@copilotkit/runtime/v2";
import { LangGraphAgent } from "@copilotkit/runtime/langgraph";
const runtime = new CopilotRuntime({
agents: {
sample_agent: new LangGraphAgent({
deploymentUrl: process.env.LANGGRAPH_DEPLOYMENT_URL || "http://localhost:8123",
graphId: "sample_agent",
langsmithApiKey: process.env.LANGSMITH_API_KEY || "",
}),
},
intelligence: new CopilotKitIntelligence({
apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
}),
// Threads are per-user. Without this, every visitor shares one history.
identifyUser: (request) => ({
id: request.headers.get("x-user-id") ?? "anonymous",
name: request.headers.get("x-user-name") ?? "Anonymous",
}),
});
const handler = createCopilotRuntimeHandler({
runtime,
basePath: "/api/copilotkit",
});
export const GET = handler;
export const POST = handler;
export const PATCH = handler;
export const DELETE = handler;From this frontend app directory, connect the runtime to an Intelligence project:
npx copilotkit@latest project selectThe command writes the server-side project API key to .env. The runtime reads it here:
CPK_INTELLIGENCE_API_KEY=cpk-...Running without the Intelligence Platform?
Drop the intelligence and identifyUser options and the runtime falls back
to SSE mode with an in-memory runner. Chat still works, but Threads and the
Inspector stay locked and the key is never read. See
Connect your runtime to Intelligence for the
full constructor and how to confirm the key is in use.
Configure CopilotKit Provider
Wrap your application with the CopilotKit provider:
"use client";
import { CopilotKitProvider } from "@copilotkit/react-core/v2";
export function Providers({ children }: { children: React.ReactNode }) {
return (
<CopilotKitProvider runtimeUrl="/api/copilotkit" agentId="sample_agent" useSingleEndpoint={false}>
{children}
</CopilotKitProvider>
);
}Render the provider from app/layout.tsx:
import { Providers } from "./providers";
import "@copilotkit/react-core/v2/styles.css";
// ...
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<Providers>
{children}
</Providers>
</body>
</html>
);
}This relative runtimeUrl assumes Next.js serves the runtime
/api/copilotkit resolves only because Next.js serves your app and the runtime from the
same origin. A client-only frontend has no shared origin, so it needs a standalone runtime
server of its own and an absolute runtimeUrl such as
http://localhost:8200/api/copilotkit. The per-frontend guides at /react-spa, /vue,
/angular and /react-native each show that setup.
Add the chat interface
Add the CopilotSidebar component to your page:
"use client";
import { CopilotSidebar } from "@copilotkit/react-core/v2";
import { useDefaultRenderTool } from "@copilotkit/react-core/v2";
export default function Page() {
useDefaultRenderTool({
render: ({ name, status, parameters, result }) => (
<details>
<summary>
{status === "complete" ? `Called ${name}` : `Calling ${name}`}
</summary>
<p>Status: {status}</p>
<p>Args: {JSON.stringify(parameters)}</p>
<p>Result: {JSON.stringify(result)}</p>
</details>
),
});
return (
<main>
<h1>Your App</h1>
<CopilotSidebar />
</main>
);
}Start your agent
cd ..
npx @langchain/langgraph-cli dev --port 8123 --no-browserYour agent will be available at http://localhost:8123.
If port 8123 is already in use, change the --port flag (or the port= argument
in the FastAPI main.py) and update LANGGRAPH_DEPLOYMENT_URL in the Setup Copilot Runtime step to match.
Start your UI
In a separate terminal, navigate to your frontend directory and start the development server:
cd frontend && npm run devOpen http://localhost:3000 and ask the agent: What is the weather in Paris? The sidebar shows a Called get_weather entry, and the agent replies that the weather in Paris is sunny.
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.
How is this guide?