Deep Agents

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 required if deploying to LangSmith Platform

Getting started#

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#

For this agent, we'll just need the deepagents, langchain-openai, and copilotkit packages:

uv add deepagents copilotkit langchain-openai

If you already have a LangGraph agent written, just reference the following code. In this step we create a simple LangGraph agent for the sake of demonstration.

First, we'll create a simple LangGraph agent:

main.py

from deepagents import create_deep_agent
from copilotkit import CopilotKitMiddleware
from langgraph.checkpoint.memory import MemorySaver

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

graph = agent

Then to test and deploy with LangSmith, we'll also need 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"
}

First, add the ag-ui-langgraph, fastapi, and uvicorn packages to your project:

uv add ag-ui-langgraph fastapi uvicorn

Then create a simple LangGraph agent, add a FastAPI app, and build attach our agent as an AG-UI endpoint.

main.py

import os
from fastapi import FastAPI 
import uvicorn

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

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

app = FastAPI()

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

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

What about other models?

The starter template is configured to use OpenAI's GPT-4o by default, but you can modify it to use any language model supported by LangGraph.

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

Setup Copilot Runtime#

Create an API route to connect CopilotKit to your LangGraph agent:

mkdir -p app/api/copilotkit && touch app/api/copilotkit/route.ts

app/api/copilotkit/route.ts

import {
    CopilotRuntime,
    ExperimentalEmptyAdapter,
    copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { LangGraphAgent } from "@copilotkit/runtime/langgraph";
import { NextRequest } from "next/server";

const serviceAdapter = new ExperimentalEmptyAdapter();

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 || "",
        }),
    }
});

export const POST = async (req: NextRequest) => {
    const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
        runtime,
        serviceAdapter,
        endpoint: "/api/copilotkit",
    });

    return handleRequest(req);
};

app/api/copilotkit/route.ts

import {
    CopilotRuntime,
    ExperimentalEmptyAdapter,
    copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { LangGraphHttpAgent } from "@copilotkit/runtime/langgraph";
import { NextRequest } from "next/server";

const serviceAdapter = new ExperimentalEmptyAdapter();

const runtime = new CopilotRuntime({
    agents: {
        sample_agent: new LangGraphHttpAgent({
url:  process.env.LANGGRAPH_DEPLOYMENT_URL || "http://localhost:8123",
        }),
    }
});

export const POST = async (req: NextRequest) => {
    const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
        runtime,
        serviceAdapter,
        endpoint: "/api/copilotkit",
    });

    return handleRequest(req);
};

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">
                    {children}
                </CopilotKit>
            </body>
        </html>
    );
}

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, args, result}) => (
        <details>
            <summary>
                {status === "complete"? `Called ${name}` : `Calling ${name}`}
            </summary>

            <p>Status: {status}</p>
            <p>Args: {JSON.stringify(args)}</p>
            <p>Result: {JSON.stringify(result)}</p>
        </details>
    )})

    return (
        <main>
            <h1>Your App</h1>
            <CopilotSidebar />
        </main>
    );
}

Start your agent#

From your agent directory, start the agent server:

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

cd ..
uv run main.py

Your agent will be available at http://localhost:8123.

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