Quickstart

Build agents that get smarter with every use.

Rich Threads keep messages, generative UI, and tool activity available across sessions and devices.

Learning turns real usage into skills that improve your agent.

Build a new agent or bring one you already have. Any frontend, any backend.

Prerequisites#

Before you begin, you'll need the following:

An OpenAI API key
Node.js 20+
Your favorite package manager
A LangGraph Platform API key - only required if deploying to the Deep Agent platform

Getting started#

Create a free account#

Sign up for a free developer account for CopilotKit Intelligence to get a license key. You'll use it later to enable persistent threads and the inspector.

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

If you don't already have a Node.js project set up, create one using npm:

mkdir my-agent
cd my-agent
npm init -y

Add necessary dependencies#

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

uv add deepagents copilotkit langchain-openai

Add the deepagents, @langchain/langgraph, @copilotkit/sdk-js, and @langchain/openai packages:

npm install deepagents @langchain/langgraph @copilotkit/sdk-js @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-4o",
    tools=[get_weather],
    middleware=[CopilotKitMiddleware()], # for frontend tools and context
    system_prompt="You are a helpful research assistant.",
)

Then to test and deploy with Deep Agent, 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"
}

Create a simple Deep Agent:

agent.ts

import { createDeepAgent } from "deepagents";
import { copilotkitMiddleware } from "@copilotkit/sdk-js/langgraph";
import { tool } from "langchain";
import { z } from "zod";

const getWeather = tool(
    async ({ location }) => `The weather in ${location} is sunny.`,
    {
        name: "get_weather",
        description: "Get the weather for a given location.",
        schema: z.object({ location: z.string().describe("The location to get the weather for") }),
    }
);

export const agent = createDeepAgent({
    model: "openai:gpt-4o",
    tools: [getWeather],
    middleware: [copilotkitMiddleware],
    systemPrompt: "You are a helpful research assistant.",
});

Then to test and deploy with Deep Agent, create a langgraph.json:

touch langgraph.json

langgraph.json

{
    "node_version": "20",
    "dependencies": ["."],
    "package_manager": "npm",
    "graphs": {
        "sample_agent": "./agent.ts:agent"
    },
    "env": ".env"
}

When setting up the Copilot Runtime in the next steps, select the Deep Agent tab.

Add the ag-ui-langgraph, fastapi, and uvicorn packages:

uv add ag-ui-langgraph fastapi uvicorn

Create a Deep Agent and expose it as an AG-UI endpoint:

main.py

from ag_ui_langgraph import add_langgraph_fastapi_endpoint
from copilotkit import CopilotKitMiddleware, LangGraphAGUIAgent
from deepagents import create_deep_agent
from fastapi import FastAPI
from langgraph.checkpoint.memory import MemorySaver

app = FastAPI()

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-4o",
    tools=[get_weather],
    middleware=[CopilotKitMiddleware()], # for frontend tools and context
    system_prompt="You are a helpful research assistant.",
    checkpointer=MemorySaver()
)

add_langgraph_fastapi_endpoint(
    app=app,
    agent=LangGraphAGUIAgent(
        name="sample_agent",
        description="An example agent to use as a starting point for your own agent.",
        graph=agent,
    ),
    path="/",
)

def main():
    """Run the uvicorn server."""
    import uvicorn
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8123,
        reload=True,
    )

if __name__ == "__main__":
    main()

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-ui @copilotkit/react-core @copilotkit/runtime

Setup Copilot Runtime#

Create an API route to connect CopilotKit to your Deep Agent:

mkdir -p app/api/copilotkit && touch app/api/copilotkit/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.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;

app/api/copilotkit/[[...slug]]/route.ts

import {
  CopilotKitIntelligence,
  CopilotRuntime,
  createCopilotRuntimeHandler,
} from "@copilotkit/runtime/v2";
import { LangGraphHttpAgent } from "@copilotkit/runtime/langgraph";

const runtime = new CopilotRuntime({
    agents: {
        sample_agent: new LangGraphHttpAgent({
url: process.env.LANGGRAPH_DEPLOYMENT_URL || "http://localhost:8123",
        }),
    },
    intelligence: new CopilotKitIntelligence({
      apiKey: process.env.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;

The runtime reads the license key from step 1. Add it to the app that serves this route:

.env.local

INTELLIGENCE_API_KEY=your_license_key

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/layout.tsx

import { CopilotKit } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

// ...

export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
        <html lang="en">
            <body>
                <CopilotKit runtimeUrl="/api/copilotkit" agent="sample_agent" useSingleEndpoint={false}>
                    {children}
                </CopilotKit>
            </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#

npx @langchain/langgraph-cli dev --port 8123 --no-browser

uv run main.py

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 Step 7 to match.

Start your UI#

In a separate terminal, navigate to your frontend directory and start the development server:

cd frontend && npm run dev

cd frontend && pnpm dev

cd frontend && yarn dev

cd frontend && bun dev

Open Inspector and confirm setup#

On localhost, click the Inspector button in the corner of the app.

Open Agents, then Agent. Your agent is listed.
Send a chat message. Open Agents, then AG-UI Events. Events are moving.
Open Threads. The list is unlocked (Intelligence is on), or locked with Enable Intelligence (Intelligence is off).

More detail: Inspector.