---
title: Quickstart
description: Turn your ADK Agents into an agent-native application in 10 minutes.
icon: "lucide/Play"
hideTOC: true
---
## Prerequisites

Before you begin, you'll need the following:

- A Google Gemini API key
- Node.js 20+
- Python 3.9+
- Your favorite package manager

## Getting started

<Steps>
    <Step>
        ### Create a free account

        <SignupLink surface="docs_adk_quickstart_step1">Sign up for a free developer account</SignupLink> on our Enterprise Intelligence Platform to get a license key. You'll use it later to enable persistent threads, observability, and the inspector.
    </Step>

    <Step>
        ### Choose your starting point

        You can either start fresh with our starter template or integrate CopilotKit into your existing ADK 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

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

                The CLI walks you through:

                - **Project name**
                - **Enterprise Intelligence Platform** — persistent threads, observability, and the inspector. Choose **Yes** to scaffold a project pre-wired for the platform (the CLI walks you through sign-up, or you can [create an account](https://dashboard.operations.copilotkit.ai/?utm_source=docs&utm_medium=cta&utm_campaign=intelligence&utm_content=docs_cli_prompt) first), or **No** for a standard ADK setup.
                - **Framework** — pick **ADK** when prompted.
            </Step>
            <Step>
                ### Install dependencies

                ```npm
                npm install
                ```
            </Step>
            <Step>
                ### Configure your environment

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

                ```plaintext title="agent/.env"
                GOOGLE_API_KEY=your_google_api_key
                ```

                <Callout type="info" title="What about other models?">
                  The starter template is configured to use Google's Gemini by default, but you can modify it to use any language model supported by ADK.
                </Callout>
            </Step>
            <Step>
                ### 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!

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

                ```
                Set the theme to orange
                ```

                ```
                Write a proverb about AI
                ```

                ```
                Get the weather in SF
                ```

                <Accordions className="mb-4">
                    <Accordion title="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 Google API key is correctly set
                    </Accordion>
                </Accordions>

            </Step>
        </TailoredContentOption>
        <TailoredContentOption
            id="bring-your-own"
            title="Use an existing agent"
            description="I already have an ADK agent and want to add CopilotKit."
        >
            <Step>
                ### 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 ADK with AG-UI

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

                ```bash
                uv add ag-ui-adk google-adk uvicorn fastapi
                ```

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

                Set your Google API key as an environment variable:

                ```bash
                export GOOGLE_API_KEY=your_google_api_key
                ```

                <Callout type="info" title="What about other models?">
                  This example uses Gemini 2.5 Flash, but you can modify it to use any language model supported by ADK.
                </Callout>
            </Step>
            <Step>
                ### 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 ag_ui_adk import ADKAgent, add_adk_fastapi_endpoint
                from google.adk.agents import LlmAgent

                agent = LlmAgent(
                    name="assistant",
                    model="gemini-2.5-flash",
                    instruction="Be helpful and fun!"
                )

                adk_agent = ADKAgent(
                    adk_agent=agent,
                    app_name="demo_app",
                    user_id="demo_user",
                    session_timeout_seconds=3600,
                    use_in_memory_services=True
                )

                app = FastAPI()
                add_adk_fastapi_endpoint(app, adk_agent, path="/")

                if __name__ == "__main__":
                    import uvicorn
                    uvicorn.run(app, host="localhost", port=8000)
                ```
            </Step>
            <Step>
                ### 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

                ```npm
                npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/client
                ```
            </Step>
            <Step>
                ### Setup Copilot Runtime

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

                ```tsx title="app/api/copilotkit/route.ts"
                import {
                  CopilotRuntime,
                  ExperimentalEmptyAdapter,
                  copilotRuntimeNextJSAppRouterEndpoint,
                } from "@copilotkit/runtime";
                import { HttpAgent } from "@ag-ui/client";
                import { NextRequest } from "next/server";

                const serviceAdapter = new ExperimentalEmptyAdapter();

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

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

                  return handleRequest(req);
                };
               ```
            </Step>
            <Step>
                ### Configure CopilotKit Provider

                Wrap your application with the CopilotKit provider:

                ```tsx title="app/layout.tsx"
                import { CopilotKit } from "@copilotkit/react-core/v2"; // [!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] */}
                        <CopilotKit runtimeUrl="/api/copilotkit" agent="my_agent">
                          {children}
                        </CopilotKit>
                      </body>
                    </html>
                  );
                }
                ```
            </Step>
            <Step>
              ### Add the chat interface

              Add the CopilotSidebar component to your page:

              ```tsx title="app/page.tsx"
              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

                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

                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!

                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 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 Google API key is correctly set
                        - Verify that the `@ag-ui/client` package is installed in your frontend
                    </Accordion>
                </Accordions>

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

## What's 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="/adk/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="/adk/shared-state"
    icon={<RepeatIcon />}
  />
  <Card
    title="Add some generative UI"
    description="Render your agent's progress and output in the UI."
    href="/adk/generative-ui/tool-rendering"
    icon={<PaintbrushIcon />}
  />
  <Card
    title="Setup frontend actions"
    description="Give your agent the ability to call frontend tools, directly updating your application."
    href="/adk/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
/>