# Quickstart

> Run a Google Antigravity agent behind CopilotKit.

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

Use this prompt to connect your Google Antigravity 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 />

This quickstart gives you two working paths:

- **Start from scratch** to scaffold the full Google Antigravity showcase.
- **Use an existing agent** to expose your own Google Antigravity agent over AG-UI and connect it to a React app.

## Prerequisites [#prerequisites]

Before you begin, you'll need the following:

- Node.js 20+
- Python 3.10+
- `uv` for Python dependency management
- A Gemini API key, as `GEMINI_API_KEY`

<Callout type="info" title="Why GEMINI_API_KEY and not GOOGLE_API_KEY?">
  `google-antigravity`'s Go harness calls Gemini itself, and `GEMINI_API_KEY`
  is the only name it reads. A project that already has `GOOGLE_API_KEY`, as
  ADK projects do, still fails on its first chat turn, because building the
  agent needs no key. To send the same Gemini requests to another
  Gemini-compatible server, such as a gateway, pass the adapter an `endpoint`
  (`GeminiAPIEndpoint(base_url=...)`); the harness wants the key there too.
</Callout>

## Getting started [#getting-started]

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

    <TailoredContent className="step" id="agent">
      <TailoredContentOption
        id="starter"
        title="Start from scratch"
        description="Scaffold the canonical Google Antigravity starter."
      >
        <Step>
          ### Run the CLI [#run-the-cli]

          ```bash
          npx copilotkit@latest init --framework antigravity
          ```

          <Callout type="info" title="If the CLI does not list Google Antigravity yet">
            Until the CLI catalog gains this entry, clone the CopilotKit
            repository and copy `examples/integrations/antigravity` — it is a
            complete Next.js app plus Python agent server with the same
            layout the CLI scaffolds.
          </Callout>

          The starter contains three pieces:

          - `agent/main.py` - the FastAPI app built with the adapter's `create_antigravity_app`, mounting one `AntigravityAgent` with a weather tool
          - `src/app/api/copilotkit/[[...slug]]/route.ts` - the CopilotKit runtime route that proxies to the agent with `HttpAgent`
          - `src/app/page.tsx` - a page demonstrating a frontend tool, a rendered backend tool, and a human-in-the-loop picker
        </Step>

        <Step>
          ### Configure your environment [#configure-your-environment]

          Create a `.env` file in the generated project root:

          ```plaintext title=".env"
          GEMINI_API_KEY=your_gemini_api_key
          ```

          The runtime route defaults to `AGENT_URL=http://localhost:8000`, which is where the starter's FastAPI agent server listens.
        </Step>

        <Step>
          ### Install dependencies [#install-dependencies]

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

          `npm install` also runs the agent's `uv sync` (postinstall), so the
          Python side — including the Antigravity SDK, whose wheel bundles
          the Go harness binary — is installed too. Make sure `uv` is on your
          `PATH` before running it.
        </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 starts both the Next.js app and the Python agent server.
        </Step>
      </TailoredContentOption>

      <TailoredContentOption
        id="bring-your-own"
        title="Use an existing agent"
        description="I already have a Google Antigravity agent and want to add CopilotKit."
      >
        <Step>
          ### Install the required Python packages [#install-the-required-python-packages]

          From your agent project, install the Google Antigravity SDK, its AG-UI
          adapter and FastAPI:

          ```bash
          uv add google-antigravity ag-ui-antigravity fastapi uvicorn
          ```
        </Step>

        <Step>
          ### Configure your agent environment [#configure-your-agent-environment]

          Create a `.env` file for the process that runs your Antigravity agent. This example uses Antigravity's native Gemini path, so it needs `GEMINI_API_KEY`:

          ```plaintext title=".env"
          GEMINI_API_KEY=your_gemini_api_key
          ```
        </Step>

        <Step>
          ### Expose Google Antigravity over AG-UI [#expose-google-antigravity-over-ag-ui]

          CopilotKit talks to agents over AG-UI. The adapter's `create_antigravity_app` builds a FastAPI app that streams AG-UI events straight from the harness — you don't hand-roll the event loop yourself.

          ```python title="main.py"
          import os

          from ag_ui_antigravity import AntigravityAgent, create_antigravity_app

          agent = AntigravityAgent(
              model="gemini-2.5-flash",
              api_key=os.environ["GEMINI_API_KEY"],
              system_instructions="You are a helpful assistant embedded in a CopilotKit app.",
              # The harness does real file and shell work scoped to these
              # directories, so always set this. Keep the path short — a long,
              # high-entropy path makes the model reproduce it wrongly in tool
              # calls (see Troubleshooting below).
              workspaces=["/srv/agents/w1"],
          )

          app = create_antigravity_app(agent, path="/")


          @app.get("/health")
          async def health() -> dict[str, str]:
              return {"status": "ok"}
          ```

          Start it and confirm the health check:

          ```bash
          uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000
          curl http://localhost:8000/health
          ```

          <Callout type="info" title="Already serving the agent from a FastAPI app?">
            Keep your app and add the AG-UI route to it instead of building a new one.
            `add_antigravity_fastapi_endpoint` mounts the same endpoint `create_antigravity_app`
            serves, on the `FastAPI` instance you already have:

            ```python
            from ag_ui_antigravity import AntigravityAgent, add_antigravity_fastapi_endpoint

            add_antigravity_fastapi_endpoint(app, agent, path="/agui")
            ```

            Point the runtime's `HttpAgent` at that path, e.g. `http://localhost:8000/agui`.
            Your existing routes keep working alongside it.
          </Callout>
        </Step>

        <Step>
          ### Create your frontend [#create-your-frontend]

          CopilotKit works with any React app. This example uses Next.js App Router:

          ```bash
          npx create-next-app@latest frontend
          cd frontend
          npm install @copilotkit/runtime @copilotkit/react-core @ag-ui/client@1.0.2
          ```
        </Step>

        <Step>
          ### Add the CopilotKit runtime route [#add-the-copilotkit-runtime-route]

          Create `app/api/copilotkit/route.ts` in your Next.js app. It registers your Antigravity agent as an AG-UI `HttpAgent`.

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

          const runtime = new CopilotRuntime({
            agents: {
              antigravity_agent: new HttpAgent({
                url: process.env.AGENT_URL ?? "http://localhost:8000",
              }),
            },
          });

          const handler = createCopilotRuntimeHandler({
            runtime,
            basePath: "/api/copilotkit",
            mode: "single-route",
          });

          export const POST = (req: NextRequest) => handler(req);
          ```
        </Step>

        <Step>
          ### Mount CopilotKit in React [#mount-copilotkit-in-react]

          Wrap your app with `CopilotKit` and target the agent name you registered in the runtime route.

          ```tsx title="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="antigravity_agent">
                    {children}
                  </CopilotKit>
                </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`. The per-frontend guides at `/react-spa`, `/vue`,
            `/angular` and `/react-native` each show that setup.
          </Callout>

          Add a chat surface:

          ```tsx title="app/page.tsx"
          "use client";

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

          export default function Page() {
            return (
              <main>
                <CopilotSidebar />
              </main>
            );
          }
          ```
        </Step>

        <Step>
          ### Start the UI [#start-the-ui]

          Keep the FastAPI agent server running, then start the frontend in a second terminal:

          ```bash
          npm run dev
          ```
        </Step>
      </TailoredContentOption>
    </TailoredContent>
  </Step>

  <Step>
    ### Verify the integration [#verify-the-integration]

    Open `http://localhost:3000` and ask:

    ```plaintext
    Tell me in one sentence what this app can do.
    ```

    If the chat streams a response, CopilotKit is connected to your Google Antigravity agent.

    <Accordions className="mb-4">
      <Accordion title="Troubleshooting">
        - If the runtime cannot reach the agent, check that the FastAPI server is running on `http://localhost:8000` or set `AGENT_URL` in the frontend.
        - If the agent refuses to start or every chat turn fails with "a Gemini API key is required", set `GEMINI_API_KEY`. `GOOGLE_API_KEY` is not read.
        - If a tool call looks like it's hanging, check whether it's a frontend tool: those park as an awaited coroutine across HTTP runs until the browser resolves them, so nothing happens server-side until your UI responds.
        - If a run fails mid-tool-call with a vague "invalid tool call" error, check your `workspaces` path length. A long, high-entropy path (like a generated temp directory) makes the model reproduce it wrongly and causes intermittent failures — use something short and stable instead.
      </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](/google-antigravity/inspector).
    </Step>

</Steps>
