Quickstart

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.

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.

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#

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

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.

Getting started#

Choose your starting point#

Run the CLI#

npx copilotkit@latest init --framework antigravity

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.

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

Configure your environment#

Create a .env file in the generated project root:

.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.

Install dependencies#

npm install

pnpm install

yarn install

bun install

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.

Start the development server#

npm run dev

pnpm dev

yarn dev

bun dev

This starts both the Next.js app and the Python agent server.

Verify the integration#

Open http://localhost:3000 and ask:

Tell me in one sentence what this app can do.

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

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.

Open Inspector and confirm setup#

On localhost, click the Inspector button in the corner of the app.

Open Agents, then Agent. Your agent is listed.
Send a chat message. Open Agents, then AG-UI Events. Events are moving.
Open Rich Threads. The list is unlocked (Intelligence is on), or locked with Enable Intelligence (Intelligence is off).

More detail: Inspector.