Quickstart
Run a Google Antigravity agent behind CopilotKit.
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+
uvfor 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 antigravityIf 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'screate_antigravity_app, mounting oneAntigravityAgentwith a weather toolsrc/app/api/copilotkit/[[...slug]]/route.ts- the CopilotKit runtime route that proxies to the agent withHttpAgentsrc/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:
GEMINI_API_KEY=your_gemini_api_keyThe runtime route defaults to AGENT_URL=http://localhost:8000, which is where the starter's FastAPI agent server listens.
Install dependencies
npm installnpm 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 devThis 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.
- If the runtime cannot reach the agent, check that the FastAPI server is running on
http://localhost:8000or setAGENT_URLin 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_KEYis 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
workspacespath 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 Inspect, then Agent. Your agent is listed.
- Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
- Open Rich Threads. The list is unlocked (Intelligence is on), or locked with Copy setup prompt (Intelligence is off).
More detail: Inspector.
How is this guide?