# Quickstart

> Turn your LlamaIndex Agents into an agent-native application in 10 minutes.

## Start with your coding agent [#start-with-your-coding-agent]

Use this prompt to connect your LlamaIndex 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.

<PageAgentPrompt />

## Prerequisites [#prerequisites]

Before you begin, you'll need the following:

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

## Getting started [#getting-started]

<Steps>
    <Step>
        ### Set up CopilotKit Intelligence [#set-up-copilotkit-intelligence]

        <SignupLink surface="docs_llamaindex_quickstart_step1">Sign in to cloud-hosted Intelligence</SignupLink>. You will connect the app after you create it below.
    </Step>

    <Step>
        ### Choose your starting point [#choose-your-starting-point]

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

        <TailoredContent
            className="step"
            id="agent"
        >
        <TailoredContentOption
            id="starter"
            title="Start from scratch"
            description="Get started quickly with our ready-to-go starter application."
        >
            <Step>
                ### Run our CLI [#run-our-cli]

                ```bash
                npx copilotkit@latest create
                ```

                The CLI walks you through:

                - **Project name**
                - **CopilotKit Intelligence**: persistent threads and the Inspector. Choose **Yes** for a project that is wired to Intelligence. Choose **No** for a standard LlamaIndex setup. If you choose **Yes**, the CLI walks you through sign-up.
                - **Framework**: pick **LlamaIndex** when prompted.
            </Step>
            <Step>
                ### Install dependencies [#install-dependencies]

                ```npm
                npm install
                ```
            </Step>
            <Step>
                ### Configure your environment [#configure-your-environment]

                Create a `.env` file in your agent directory and add your OpenAI API key:

                ```plaintext title="agent/.env"
                OPENAI_API_KEY=your_openai_api_key
                ```

                <Callout type="info" title="What about other models?">
                  The starter template uses OpenAI's `gpt-6-luna` by default, but you can modify it to use any language model supported by LlamaIndex.
                </Callout>
            </Step>
            <Step>
                ### Start the development server [#start-the-development-server]

                <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
                    <Tab value="npm">
                        ```bash
                        npm run dev
                        ```
                    </Tab>
                    <Tab value="pnpm">
                        ```bash
                        pnpm dev
                        ```
                    </Tab>
                    <Tab value="yarn">
                        ```bash
                        yarn dev
                        ```
                    </Tab>
                    <Tab value="bun">
                        ```bash
                        bun dev
                        ```
                    </Tab>
                </Tabs>

                This will start both the UI and agent servers concurrently.
            </Step>
            <Step>
                ### Start chatting [#start-chatting]

                Your AI agent is now ready to use. Navigate to `localhost:3000` and start prompting it:

                ```
                What tools do you have access to?
                ```

                ```
                What do you think about React?
                ```

                ```
                Show me some cool things you can do!
                ```

                <Accordions className="mb-4">
                    <Accordion title="Troubleshooting">
                        - If the chat cannot connect to the agent, use `0.0.0.0` or `127.0.0.1` instead of `localhost`.
                        - If the chat shows a connection error, make sure that the `agent` lines in the `npm run dev` output show `Uvicorn running on http://127.0.0.1:9000`.
                        - If the `agent` lines show an OpenAI `AuthenticationError`, make sure that `OPENAI_API_KEY` in `agent/.env` holds a valid key.
                    </Accordion>
                </Accordions>

            </Step>

    <Step>
        ### Open Inspector and confirm setup [#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](/llamaindex/inspector).
    </Step>

        </TailoredContentOption>
        <TailoredContentOption
            id="bring-your-own"
            title="Use an existing agent"
            description="I already have a LlamaIndex agent and want to add CopilotKit."
        >
            <Step>
                ### Initialize your agent project [#initialize-your-agent-project]

                If you don't already have a Python project set up, create one using `uv`:

                ```bash
                uv init my-agent
                cd my-agent
                ```
            </Step>
            <Step>
                ### Install LlamaIndex with AG-UI [#install-llamaindex-with-ag-ui]

                Add LlamaIndex with AG-UI support and uvicorn to your project:

                ```bash
                uv add llama-index llama-index-llms-openai-like llama-index-protocols-ag-ui fastapi uvicorn
                ```

                <Callout type="info" title="What is AG-UI?">
                  AG-UI is an open protocol for frontend-agent communication. The `llama-index-protocols-ag-ui` package provides LlamaIndex integration that CopilotKit can connect to.
                </Callout>
            </Step>
            <Step>
                ### Configure your environment [#configure-your-environment-1]

                Set your OpenAI API key as an environment variable:

                ```bash
                export OPENAI_API_KEY=your_openai_api_key
                ```

                <Callout type="info" title="What about other models?">
                  This example uses OpenAI's `gpt-6-luna`. To use another model, change `OpenAI(model=...)`, or use another LLM class that LlamaIndex supports.
                </Callout>
            </Step>
            <Step>
                ### Expose your agent via AG-UI [#expose-your-agent-via-ag-ui]

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

                ```python title="main.py"
                from fastapi import FastAPI
                from llama_index.llms.openai_like import OpenAILike
                from llama_index.protocols.ag_ui.router import get_ag_ui_workflow_router

                # Initialize the LLM
                llm = OpenAILike(
                    model="gpt-6-luna",
                    context_window=1_050_000,
                    is_chat_model=True,
                    is_function_calling_model=True,
                    additional_kwargs={"reasoning_effort": "none"},
                )

                # Create the AG-UI workflow router
                agentic_chat_router = get_ag_ui_workflow_router(
                    llm=llm,
                    system_prompt="You are a helpful AI assistant with access to various tools and capabilities.",
                )

                # Create FastAPI app
                app = FastAPI(
                    title="LlamaIndex Agent",
                    description="A LlamaIndex agent integrated with CopilotKit",
                    version="1.0.0"
                )

                # Include the router
                app.include_router(agentic_chat_router)

                # Health check endpoint
                @app.get("/health")
                async def health_check():
                    return {"status": "healthy", "agent": "llamaindex"}

                if __name__ == "__main__":
                    import uvicorn
                    uvicorn.run(app, host="localhost", port=8000)
                ```
            </Step>
            <Step>
                ### Create your frontend [#create-your-frontend]

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

                ```bash
                npx create-next-app@latest my-copilot-app
                cd my-copilot-app
                ```
            </Step>
            <Step>
                ### Install CopilotKit packages [#install-copilotkit-packages]

                ```npm
                npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/llamaindex
                ```
            </Step>
            <Step>
                ### Add the Copilot Runtime route [#add-the-copilot-runtime-route]

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

                ```tsx title="app/api/copilotkit/[[...slug]]/route.ts" doctest="component"
                import {
                  CopilotKitIntelligence,
                  CopilotRuntime,
                  createCopilotRuntimeHandler,
                } from "@copilotkit/runtime/v2";
                import { LlamaIndexAgent } from "@ag-ui/llamaindex";

                const runtime = new CopilotRuntime({
                  agents: {
                    my_agent: new LlamaIndexAgent({ url: "http://localhost:8000/run" }),
                  },
                  // [!code highlight:9]
                  intelligence: new CopilotKitIntelligence({
                    apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
                  }),
                  // Demo only: the browser sends no x-user-id header, so all visitors share
                  // one "anonymous" history. Before you deploy, return the verified session user.
                  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:

                ```bash title="Terminal"
                npx copilotkit@latest project select
                ```

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

                ```plaintext title=".env"
                CPK_INTELLIGENCE_API_KEY=cpk-...
                ```

                <Callout type="info" title="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](/llamaindex/intelligence/quickstart) for the
                  full constructor and how to confirm the key is in use.
                </Callout>
            </Step>
            <Step>
                ### Configure CopilotKit Provider [#configure-copilotkit-provider]

                Wrap your application with the CopilotKit provider:

                ```tsx title="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>
                  );
                }
                ```

                Render `Providers` around your app in `app/layout.tsx`:

                ```tsx title="app/layout.tsx"
                import { Providers } from "./providers"; // [!code highlight]
                import "@copilotkit/react-core/v2/styles.css";
                import './globals.css';

                // ...

                export default function RootLayout({ children }: {children: React.ReactNode}) {
                  return (
                    <html lang="en">
                      <body>
                        {/* [!code highlight:3] */}
                        <Providers>
                          {children}
                        </Providers>
                      </body>
                    </html>
                  );
                }
                ```

                <Callout type="info" title="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`. See the [React SPA](/llamaindex/react-spa), [Vue](/vue),
                  [Angular](/angular), and [React Native](/react-native) guides for that setup.
                </Callout>
            </Step>
            <Step>
              ### Add the chat interface [#add-the-chat-interface]

              Add the CopilotSidebar component to your page:

              ```tsx title="app/page.tsx"
              "use client"; // [!code highlight]

              import { CopilotSidebar } from "@copilotkit/react-core/v2"; // [!code highlight:1]

              export default function Page() {
                return (
                  <main>
                    <h1>Your App</h1>
                    {/* [!code highlight:1] */}
                    <CopilotSidebar />
                  </main>
                );
              }
              ```
            </Step>
            <Step>
                ### Start your agent [#start-your-agent]

                From your agent directory, start the agent server:

                ```bash
                uv run main.py
                ```

                Your agent will be available at `http://localhost:8000`.
            </Step>
            <Step>
                ### Start your UI [#start-your-ui]

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

                <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
                    <Tab value="npm">
                        ```bash
                        cd my-copilot-app
                        npm run dev
                        ```
                    </Tab>
                    <Tab value="pnpm">
                        ```bash
                        cd my-copilot-app
                        pnpm dev
                        ```
                    </Tab>
                    <Tab value="yarn">
                        ```bash
                        cd my-copilot-app
                        yarn dev
                        ```
                    </Tab>
                    <Tab value="bun">
                        ```bash
                        cd my-copilot-app
                        bun dev
                        ```
                    </Tab>
                </Tabs>
            </Step>
            <Step>
                ### Start chatting [#start-chatting-1]

                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?
                ```

                <Accordions className="mb-4">
                    <Accordion title="Troubleshooting">
                        - If the chat cannot connect to the agent, use `0.0.0.0` or `127.0.0.1` instead of `localhost`.
                        - If the chat shows a connection error, make sure that the agent terminal prints `Uvicorn running on http://localhost:8000`.
                        - If the agent terminal shows an OpenAI `AuthenticationError`, make sure that you exported `OPENAI_API_KEY` in the terminal that runs the agent.
                        - If the build fails with `Module not found: Can't resolve '@ag-ui/llamaindex'`, install `@ag-ui/llamaindex` in your frontend.
                    </Accordion>
                </Accordions>

            </Step>

    <Step>
        ### Open Inspector and confirm setup [#open-inspector-and-confirm-setup-1]

        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](/llamaindex/inspector).
    </Step>

        </TailoredContentOption>
    </TailoredContent>
    </Step>
</Steps>

## What's next? [#whats-next]

Now that you have your basic agent setup, explore these advanced features:

<Cards>
  <Card
    title="Implement Human in the Loop"
    description="Allow your users and agents to collaborate together on tasks."
    href="/llamaindex/human-in-the-loop"
    icon={<UserIcon />}
  />
  <Card
    title="Utilize the Shared State"
    description="Learn how to synchronize your agent's state with your UI's state, and vice versa."
    href="/llamaindex/shared-state"
    icon={<RepeatIcon />}
  />
  <Card
    title="Add some generative UI"
    description="Render your agent's progress and output in the UI."
    href="/llamaindex/generative-ui/tool-rendering"
    icon={<PaintbrushIcon />}
  />
  <Card
    title="Add frontend tools"
    description="Give your agent the ability to call frontend tools, directly updating your application."
    href="/llamaindex/frontend-tools"
    icon={<WrenchIcon />}
  />
</Cards>

<video
  src="https://cdn.copilotkit.ai/docs/copilotkit/images/coagents/chat-example.mp4"
  className="rounded-lg shadow-xl"
  loop
  playsInline
  controls
  autoPlay
  muted
/>
