Quickstart

Prerequisites#

Before you begin, you'll need the following:

An OpenAI API key
Node.js 20+
Python 3.9+
Your favorite package manager

Getting started#

Create a free account#

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

Choose your starting point#

You can either start fresh with our starter template or integrate CopilotKit into your existing Agno agent.

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

Install Agno with AG-UI#

Add Agno and uvicorn to your project:

uv add agno fastapi uvicorn openai ag-ui-protocol

Configure your environment#

Set your OpenAI API key as an environment variable:

export OPENAI_API_KEY=your_openai_api_key

What about other models?

This example uses OpenAI's GPT-4o, but you can modify it to use any language model supported by Agno.

Expose your agent via AG-UI#

Update your agent file to expose it as an AG-UI ASGI application:

main.py

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.os import AgentOS
from agno.os.interfaces.agui import AGUI

agent = Agent(
    model=OpenAIChat(id="gpt-5.4"),
    description="A helpful assistant that can answer questions and provide information.",
    instructions="Be helpful and friendly. Format your responses using markdown where appropriate.",
)

agent_os = AgentOS(agents=[agent], interfaces=[AGUI(agent=agent)])
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="main:app", port=8000, reload=True)

What is AG-UI?

AG-UI is an open protocol for frontend-agent communication. AgentOS with the AGUI interface creates an ASGI app that CopilotKit can connect to.

Create your frontend#

CopilotKit works with any React-based frontend. We'll use Next.js for this example.

npx create-next-app@latest my-copilot-app
cd my-copilot-app

Install CopilotKit packages#

npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/agno

Setup Copilot Runtime#

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

app/api/copilotkit/route.ts

import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { AgnoAgent } from "@ag-ui/agno";
import { NextRequest } from "next/server";

const serviceAdapter = new ExperimentalEmptyAdapter();

const runtime = new CopilotRuntime({
  agents: {
    my_agent: new AgnoAgent({ url: "http://localhost:8000/agui" }),
  }
});

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";
import './globals.css';

// ...

export default function RootLayout({ children }: {children: React.ReactNode}) {
  return (
    <html lang="en">
      <body>
        <CopilotKit runtimeUrl="/api/copilotkit" agent="my_agent">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}

Add the chat interface#

Add the CopilotSidebar component to your page:

app/page.tsx

import { CopilotSidebar } from "@copilotkit/react-core/v2"; 

export default function Page() {
  return (
    <main>
      <h1>Your App</h1>
      <CopilotSidebar />
    </main>
  );
}

Start your agent#

From your agent directory, start the agent server:

cd ..
uv run main.py

Your agent will be available at http://localhost:8000/agui.

Start your UI#

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

cd my-copilot-app
npm run dev

cd my-copilot-app
pnpm dev

cd my-copilot-app
yarn dev

cd my-copilot-app
bun dev

🎉 Start chatting!#

Your AI agent is now ready to use! Navigate to localhost:3000 and try asking it some questions:

Can you tell me a joke?

Can you help me understand AI?

What do you think about React?

Troubleshooting

If you're having connection issues, try using 0.0.0.0 or 127.0.0.1 instead of localhost
Make sure your agent is running on port 8000
Check that your OpenAI API key is correctly set
Verify that the @ag-ui/client package is installed in your frontend

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.

Add some generative UI

Render your agent's progress and output in the UI.

Setup frontend tools

Give your agent the ability to call frontend tools, directly updating your application.