Use this prompt to connect your Agno 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.
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.
Update your agent file to expose it as an AG-UI ASGI application:
main.py
from agno.agent import Agentfrom agno.models.openai import OpenAIChatfrom agno.os import AgentOSfrom agno.os.interfaces.agui import AGUIagent = 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 an API route to connect CopilotKit to your Agno agent:
app/api/copilotkit/[[...slug]]/route.ts
import { CopilotKitIntelligence, CopilotRuntime, createCopilotRuntimeHandler,} from "@copilotkit/runtime/v2";import { AgnoAgent } from "@ag-ui/agno";const runtime = new CopilotRuntime({ agents: { my_agent: new AgnoAgent({ url: "http://localhost:8000/agui" }), }, 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;
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.
Wrap your application with the CopilotKit provider:
app/providers.tsx
"use client";import { CopilotKit } from "@copilotkit/react-core/v2";export function Providers({ children }: { children: React.ReactNode }) { return ( <CopilotKit runtimeUrl="/api/copilotkit" agent="my_agent" useSingleEndpoint={false}> {children} </CopilotKit> );}
app/layout.tsx is a server component and cannot import the provider
directly, so it renders your client file instead:
app/layout.tsx
import { Providers } from "./providers"; import "@copilotkit/react-core/v2/styles.css";import './globals.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.