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.

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

Add necessary dependencies

Add the deepagents, langchain-openai, and copilotkit packages:

uv add deepagents copilotkit langchain-openai

Create your Deep Agent

Create a simple Deep Agent:

main.py
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
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:

.env
OPENAI_API_KEY=your_openai_api_key
Other 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 frontend

Install CopilotKit packages

npm install @copilotkit/react-core @copilotkit/runtime @ag-ui/client@1.0.2

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

app/api/copilotkit/[[...slug]]/route.ts
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:

Terminal
npx copilotkit@latest project select

The command writes the server-side project API key to .env. The runtime reads it here:

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

app/providers.tsx
"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:

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:

app/page.tsx
"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-browser

Your 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 dev

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

  1. Open Inspect, then Agent. Your agent is listed.
  2. Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
  3. 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?