Quickstart - Copilotkit

Prerequisites

Before you begin, you'll need the following:

OpenAI API key

Getting started

<Steps> <TailoredContent className="step" id="path" header={ <div> <p className="text-xl font-semibold">Do you already have a Pydantic AI Agent?</p> <p className="text-base"> You can either create a new project quickly or bring your existing agent into CopilotKit. </p> </div> } > <TailoredContentOption id="create" title="Start from scratch" description="I don't have an agent yet, but want to get started quickly." icon={} > <Step> ### Run our CLI

            ```bash
            npx copilotkit@latest create -f pydantic-ai
            ```
        </Step>
        <Step>
            ### Install dependencies
            ```package-install
            ```
            <Callout type="info">
                This will also install your agent's python dependencies! If you have trouble, try running `npm run install:agent` instead.
            </Callout>
        </Step>
        <Step>
            ### Mount your OpenAI API key
            Your agent will need an LLM to talk to. This example uses OpenAI, but you can use any LLM provider you want.

            ```bash
            export OPENAI_API_KEY=your_openai_api_key
            ```

            Or set it in your agent's `.env` file.

            ```plaintext title="agent/.env"
            OPENAI_API_KEY=your_openai_api_key
            ```
        </Step>
        <Step>
            ### Run your agent
            Now you can run your agent and UI together in the same terminal!

            ```bash
            npm run dev
            ```
        </Step>
    </TailoredContentOption>
    <TailoredContentOption
        id="exiting-agent"
        title="Use an existing agent"
        description="I already have a Pydantic AI Agent and want to use it with CopilotKit."
        icon={<PydanticAIIcon className="w-4 h-4 text-bold" />}
    >
        <Step>
            ### Add necessary dependencies
            Pydantic AI's integration relies on [AG-UI](https://docs.ag-ui.com/), as such
            you'll need to install it into your project.

            Our examples will also use uvicorn to run the agent.

            ```sh
            pip install 'pydantic-ai-slim[ag-ui]' uvicorn
            ```
        </Step>
        <Step>
            ### Expose your agent as an AG-UI ASGI application

            ```python title="agent.py"
            from pydantic_ai import Agent

            agent = Agent('openai:gpt-4.1', instructions='Be fun!')
            app = agent.to_ag_ui()

            # If you want the server to run on invocation, you can do the following:
            if __name__ == "__main__":

            // 1. You can use any service adapter here for multi-agent support. We use
            //    the empty adapter since we're only using one agent.
            const serviceAdapter = new ExperimentalEmptyAdapter();

            // 2. Create the CopilotRuntime instance and utilize the PydanticAI AG-UI
            //    integration to setup the connection.
            const runtime = new CopilotRuntime({
              agents: {
                // Our AG-UI endpoint URL
                "my_agent": new HttpAgent({ url: "http://localhost:8000/" }),
              }
            });

            // 3. Build a Next.js API route that handles the CopilotKit runtime requests.
            export const POST = async (req: NextRequest) => {
              const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
                runtime,
                serviceAdapter,
                endpoint: "/api/copilotkit",
              });

              return handleRequest(req);
            };
           ```
        </Step>
        <Step>
            ### Setup the CopilotKit provider
            The CopilotKit provide component is responsible for managing the session with your current agent. Typically,
            users will wrap their entire application in the CopilotKit provider.

            ```tsx title="app/layout.tsx"

            export default function RootLayout({ children }: { children: ReactNode }) {
              return (
                <html lang="en">
                  <body>
                    <CopilotKit runtimeUrl="/api/copilotkit" agent="my_agent">
                      {children}
                    </CopilotKit>
                  </body>
                </html>
              );
            }
            ```
        </Step>
        <Step>
            ### Setup the Copilot UI
            The last step is to use CopilotKit's UI components to render the chat interaction with your agent. In most situations,
            this is done alongside your core page components, e.g. in your `page.tsx` file.

            ```tsx title="page.tsx"
            // [!code highlight:2]

            export function YourApp() {
            return (
                <main>
                <h1>Your main content</h1>
                <CopilotSidebar
                    labels={{
                        modalHeaderTitle: "Popup Assistant",
                        welcomeMessageText: "Hi! I'm connected to an agent. How can I help?",
                    }}
                />
                </main>
            );
            }
            ```

            <Callout type="info">
                Looking for other chat component options? Check out our [Agentic Chat UI](/pydantic-ai/prebuilt-components) guide.
            </Callout>
        </Step>
    </TailoredContentOption>
</TailoredContent>
<Step>
    ### 🎉 Talk to your agent!

    Congrats! You've successfully integrated a Pydantic AI Agent chatbot to your application. To start, try asking a few questions to your agent.

    ```
    Can you tell me a joke?
    ```

    ```
    Can you help me understand AI?
    ```

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

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

    <Accordions className="mb-4">
        <Accordion title="Having trouble?">
            - Try changing the host to `0.0.0.0` or `127.0.0.1` instead of `localhost`.
        </Accordion>
    </Accordions>
</Step>

</Steps>

What's next?

You've now got a Pydantic AI Agent running in CopilotKit! Now you can start exploring the various ways that CopilotKit can help you build power agent native applications.