DEV Community: Romin Irani

The Antigravity Loop: From Chat to Autonomous Engineering

Romin Irani — Fri, 10 Jul 2026 07:18:37 +0000

How to go from pair-programming with AI to fully hands-off autonomous engineering and when each mode actually shines

Infographic generated by NotebookLM

Introduction

Here’s a scenario most developers know: you’re building a feature, and you ask an AI assistant to help. You type a prompt, read the response, type another prompt, read, type, read. Twenty exchanges later, the feature works. Your fingers are tired, but you’re happy.

Now imagine a different scenario: you write a single, detailed brief, like handing a spec to a senior engineer and walk away. You come back 30 minutes later to find the feature fully implemented, tested, deployed, and documented. Your fingers barely moved.

Both of these are real ways to work with Google Antigravity. The first is Chat Mode , which is conversational, interactive, real-time. The second is Goal Mode , which is autonomous, hands-off, mission-driven.

Most developers live exclusively in the first. This post will show you when, why, and how to use the second mode i.e. the Goal mode and to get there with the right kind of requirements. This post is not about which mode is better than the other, rather it is an exploration of which modes are best suited to which scenarios.

What Exactly Are These Modes?

Before diving into examples, let’s be precise about what each mode means in Antigravity:

Chat Mode (The Default)

You type a message. The agent responds. You type again. The conversation proceeds turn by turn. The agent might edit files, run commands, or search the web, but it waits for your input after each step. You see every change as it happens and can redirect immediately.

Think of it like: Pair programming with a colleague sitting next to you. You’re both looking at the screen, talking through every decision.

Planning Mode (The Middle Ground)

When you ask for something architecturally significant, Antigravity automatically shifts into planning mode. It researches your codebase, creates a detailed implementation_plan.md artifact, and presents it with a "Proceed" button. Nothing changes in your code until you approve. After approval, it executes the plan and creates a walkthrough artifact, summarizing what it did.

Think of it like: Hiring a contractor. They survey the site, give you a detailed quote and plan, and only start work after you sign off.

Goal Mode (/goal)

You prefix your prompt with /goal. The agent enters a persistent execution loop: research → plan → execute → verify → fix → repeat. It doesn't stop to ask you questions. It handles errors on its own. It may spawn sub-agents for parallel work. It only reports back when it's done (or when it's genuinely stuck and needs human input).

Think of it like: Assigning a ticket to a senior engineer. You write the requirements, set the acceptance criteria, and check back when you get the “PR ready for review” notification.

The Spectrum of Autonomy

These modes aren’t a binary switch, they’re a dial:

For each of the above modes, let us look at Human control v/s Agent autonomy, as shown below:

Another way to understand these modes is to understand what the roles of a human v/s Agent are i.e. who is in control during a specific mode and what is each mode best suited for.

Example 1: Chat Mode — Quick Fixes and Exploration

When to use: The task is trivial, you want to learn something, or you’re not sure what you want yet.

Scenario A: Fix a Bug

Fix the typo in README.md — "recieve" should be "receive"

What happens: The agent makes the single edit and shows you the diff. Done in a few seconds (hopefully). No plan, no artifact, no ceremony.

Scenario B: Understand Your Code

Explain how the authentication middleware works in server.js. 
Walk me through the flow step by step.

What happens: The agent reads the file, locates the middleware, and gives you a clear explanation with references to the relevant functions. It doesn’t change anything — it’s pure exploration. This is something Goal Mode may not be good at, since there is no “deliverable” to verify.

Scenario C: Brainstorm Ideas

What are some ways I could improve the onboarding flow in this app? 
The current sign-up takes 4 steps.

What happens: The agent analyzes your codebase, understands the current flow, and proposes improvements with rationale. This is inherently interactive, you want to react, ask follow-ups, and refine. Chat mode is perfect.

Why Chat Mode Is Right Here

These tasks share a common trait: you can’t pre-specify the outcome. You don’t know what the agent will say about your code. You don’t know which brainstormed ideas will resonate. You need to see intermediate results before deciding what’s next.

Rule of thumb: If the next step depends on seeing this step’s output, use chat.

Example 2: Guided Chat — Building Features Interactively

When to use: You know the feature you want, but the implementation details should be driven by conversation.

Real-World Example: Adding Dark Mode

Prompt 1: "Add a dark mode toggle to the header. Use CSS custom 
           properties for theming. Save the preference to 
           localStorage so it persists."

[Agent implements the toggle, CSS variables, localStorage logic]

Prompt 2: "That works, but the transition is jarring. Add a 300ms 
           ease on all color properties."

[Agent adds smooth transition CSS]

Prompt 3: "The icons in the sidebar aren't switching colors. They're 
           using hardcoded hex values."

[Agent finds and replaces the hardcoded colors with CSS variables]

Total interaction: 3 prompts, ~5 minutes of your attention. Each prompt built on seeing the result of the previous one.

Why Guided Chat Is Right Here

You could have written all three requirements upfront as a goal. But you didn’t know about the jarring transition or the hardcoded icon colors until you saw the first implementation. The iterative nature of guided chat lets you discover requirements as you go.

This is the most common mode for day-to-day feature development. You have a general direction, but the details emerge through interaction.

Example 3: Planning Mode — Architectural Changes

When to use: The change is significant enough that you want to review the approach before any code changes happen.

Scenario: Adding Firebase Authentication

Add Google Sign-In to the app using Firebase Authentication.
Only authenticated users should see the main content. 
Show a login screen with a Google sign-in button for unauthenticated users.

What happens automatically:

Research phase: The agent audits your codebase. It finds your existing HTML structure, identifies where the login gate should go, checks if any Firebase SDKs are already loaded, and reviews your current routing.
Plan creation: The agent creates an implementation_plan.md covering:

Which Firebase SDKs to add
Where to insert the auth state listener
How to gate the main content behind onAuthStateChanged
Security considerations (Firestore rules, protected routes)
Proposed file changes with estimated line numbers

3. Review checkpoint: The plan appears as an artifact with a “ Proceed ” button. You read exactly what’s going to change before a single line of code is modified.

4. Execution: After you click “ Proceed ,” the agent executes all steps, verifies the login flow works, and creates a walkthrough artifact summarizing what changed.

The critical difference from Goal Mode: the human review checkpoint at step 3. Nothing changes in your code until you approve.

Why Planning Mode Is Right Here

Authentication is a cross-cutting concern. It touches your HTML structure, JavaScript logic, security rules, and potentially your deployment config. If the agent had started editing without a plan, a wrong assumption about your routing could cascade into a broken app. The plan gives you a chance to catch issues before they become problems.

How Planning Mode Gets Triggered

You don’t explicitly ask for it, though you could. Antigravity decides based on the scope of your request and this is what I have typically observed:

Simple fixes → direct execution
New features → may or may not plan (depends on complexity)
Architectural changes, migrations, multi-file refactors → almost always plans

If you want a plan for something the agent would normally just do, say: “Create a plan for this before implementing.”

Example 4: Goal Mode — The Power Move

When to use: The task is well-defined, you’ve pre-answered every decision, and you want to walk away.

The Transition Point: Chat vs. Goal

Let’s compare two approaches to the same task: migrating a REST API integration from fetch to a typed SDK with error handling.

Approach A: Chat Mode (interactive, ~30 minutes)

Exchange 1: "I want to replace raw fetch calls with the 
              official SDK. Where are all the API calls?"
Exchange 2: [Reviews list] "Start with the user endpoints."
Exchange 3: [Reviews changes] "The error handling isn't matching 
              our pattern. Use the AppError class."
Exchange 4: [Reviews fix] "Good. Now do the products endpoints."
Exchange 5: [Reviews changes] "You missed the pagination helper."
Exchange 6: [Reviews fix] "Now the orders endpoints."
Exchange 7: [Reviews changes] "The types are wrong on the 
              response object."
Exchange 8: [Reviews fix] "Looks good. Run the tests."

Total time: ~30 minutes of continuous attention across 8 exchanges.

Approach B: Goal Mode (autonomous, ~5 minutes of your time)

**/goal**

Replace all raw fetch() API calls with the official TypeScript SDK.

## Current State
- API calls are in src/api/*.ts (users.ts, products.ts, orders.ts)
- Raw fetch with manual JSON parsing
- Error handling is inconsistent across files
- Types are defined in src/types/api.ts

## Requirements
1. Install @acme/sdk@^3.0 via npm
2. Replace every fetch() call with the equivalent SDK method
3. Use the existing AppError class (src/utils/errors.ts) for 
   all error handling
4. Ensure all response types match src/types/api.ts
5. Handle pagination using SDK's built-in paginator
6. Remove unused fetch utility functions from src/utils/http.ts

## Constraints
- Don't change any component code that calls these API functions
- Keep the same function signatures (callers shouldn't need to change)
- Don't modify existing types — adapt SDK responses to match them

## Verification
- npm run typecheck passes with zero errors
- npm run test passes (all existing tests should still work)
- grep 'fetch(' src/api/ → zero results
- grep 'AppError' src/api/ → at least one result per file

Total time: ~5 minutes to write the prompt. Walk away.

What the agent does autonomously:

1. Research → Reads all files in src/api/, catalogs every fetch call
2. Plan → Maps each fetch call to its SDK equivalent
3. Execute → Installs SDK, rewrites all three files
4. Verify → Runs typecheck → finds 2 type mismatches → fixes them
5. Re-verify → Runs tests → one test fails due to mock changes → 
                fixes the mock → all tests pass
6. Final grep → Confirms zero remaining fetch() calls
7. Report → Creates walkthrough summarizing all changes

The key difference: in Goal Mode, the type mismatches and failing test would have been caught and fixed automatically during the verify-fix loop. In Chat Mode, those same issues required two more exchanges of your time.

Example 5: Goal Mode — Multi-Component Feature

Here’s a more complex goal prompt:

**/goal**

Add a real-time admin dashboard to the web application.

## Requirements

### Navigation
- Add a "Dashboard" link in the sidebar, visible only to admin users
- Create a new route /admin/dashboard
- Include three tabs: "Users", "Activity", "Revenue"

### Users Tab
- Total registered users (count)
- New users this week (count with trend arrow)
- User growth chart (last 12 weeks, inline SVG bar chart)
- Top 10 most active users (sorted by login count)

### Activity Tab
- Actions per day chart (last 30 days, SVG line chart)
- Most common actions (table with percentages)
- Error rate (percentage with color indicator)

### Revenue Tab
- Monthly revenue chart (last 6 months, SVG bar chart)
- Average order value
- Top selling products (table)

### Design
- Use the existing design system (Tailwind CSS classes)
- Match the existing card component style
- Dark mode compatible
- Responsive — usable on tablet and desktop
- Animate chart elements on render

### Data
- Query existing Firestore collections: users, events, orders
- Use real-time onSnapshot listeners for live updates
- Admin check: user.role === 'admin'

### Constraints
- No external charting libraries (pure SVG)
- Admin-only: gate with role check, redirect non-admins
- Don't modify existing routes or components

### Verification
- Dashboard only accessible when user.role === 'admin'
- All three tabs render without console errors
- Charts display correctly with sample data
- Responsive at 768px viewport width
- npm run build succeeds

What makes this a good goal prompt:

Every decision is pre-made (no “should I use Chart.js?” ambiguity)
Data sources are specified (which collections, which fields)
Visual style is pinned to existing conventions
Verification is concrete and testable
Constraints prevent scope creep

Anatomy of a Great Goal Prompt

An effective /goal prompt should ideally have these sections:

**/goal**  

[One-line summary of what you want]

## Current State
What exists today. Tech stack, file locations, relevant architecture.

## Requirements
Numbered list of specific, concrete deliverables.

## Constraints  
What NOT to do. Boundaries. Style rules. "Don't touch X."

## Verification
How the agent knows it's done. Tests to run, greps to check, 
behavior to validate.

The Decision Pre-Answer Rule

For every place where you’d normally say “yes, do that” or “no, use the other approach” in a chat conversation, pre-answer it in the goal prompt.

What to Include in Verification

Verification criteria are what separate a sub-optimal goal prompt from a good one. Think of them as acceptance tests:

Without verification criteria, the agent has no way to self-correct. It can’t enter the fix-verify loop because there’s no “verify” step defined.

Spec-Driven Development: The Bigger Idea

If the structure of a goal prompt i.e. current state, requirements, constraints, verification looks familiar, it should. It’s a specification. And what we’re really doing with /goal is something that we as software engineers have aspired to for decades now: writing a spec that executes itself.

The Old Way vs. The New Way

Traditional software development has always involved specifications, but there was a gap between the spec and the code:

In the traditional flow, the spec is a communication artifact , it tells a human what to build, and the human translates it into code. The translation step is where most bugs are born: misunderstandings, missed edge cases, things the spec assumed were obvious.

In spec-driven development with Antigravity, the spec is an execution artifact. It doesn’t just describe what to build, it directly drives the building. The “translation step” still exists (the agent interprets your spec), but the feedback loop is immediate: if the agent misinterprets something, the verification step catches it, and the agent self-corrects.

What Makes a Spec Executable?

Not every spec works as a goal prompt. The difference between a traditional spec and an executable spec is verifiability. Compare:

The left column is what humans interpret. The right column is what agents can verify. When every line in your spec has a corresponding check, you’ve written an executable specification.

The Spec as the Single Source of Truth

Here’s where it gets powerful. In traditional development, the spec, the code, and the tests are three separate artifacts that can drift apart. The spec says one thing, the code does another, and the tests check a third.

With a goal prompt:

The spec is the prompt and it defines requirements, constraints, and verification.
The code is generated from the spec by the agent, not by manual translation.
The tests are embedded in the spec as verification criteria that run automatically.

There’s one artifact instead of three. And when you need to change behavior, you update the spec and re-run it. You don’t separately update the requirements doc, then the code, then the tests.

Leveling Up: Composable Specs

Once you’re comfortable with single goal prompts, you can compose them into multi-phase specifications. This is a possibility and you should try it.

Phase 1 Spec: Authentication
  → Verification: users can sign in, auth state persists, 
    protected routes redirect

Phase 2 Spec: Data Layer (depends on Phase 1)
  → Verification: CRUD operations work, security rules enforce 
    auth, real-time updates sync

Phase 3 Spec: UI Dashboard (depends on Phase 2)
  → Verification: charts render, admin gate works, 
    responsive layout, no console errors

Each phase is a self-contained, verifiable spec. Phase 2 doesn’t start until Phase 1’s verification passes. This is dependency-ordered, verified, incremental development and each phase can run autonomously.

The Implication for Teams

Spec-driven development changes how teams coordinate. Instead of:

Product manager writes a PRD
Engineer reads the PRD and writes code
QA reads the PRD and writes tests
Everyone argues about what the PRD actually meant

You get:

Product manager and engineer co-write an executable spec
The spec runs and produces code, tests, and verification in one pass
Review shifts from “does this code match the spec?” to “is this spec correct?”

The bottleneck moves from implementation to specification quality. And that’s a much better bottleneck to have, because it’s a thinking bottleneck, not a typing bottleneck.

The Slash Commands You Should Know

Beyond /goal, Antigravity offers several slash commands that sit at different points on the autonomy spectrum:

/grill-me — The Bridge from Chat to Goal

This is arguably the most important slash command to understand, because it solves the hardest problem in autonomous execution: how do you know what you don’t know?

When you sit down to write a /goal prompt, you need to pre-answer every decision the agent would otherwise ask you about. But for complex tasks, you don't know what all those decisions are. You don't know what you haven't considered. That's where /grill-me comes in.

/grill-me I want to add multi-tenancy to my SaaS app

The agent reads your codebase, understands the current architecture, and then interviews you with a series of targeted questions — not generic ones, but questions specific to your code and your situation:

Agent: I've reviewed your app. Here are the key decisions we need 
       to make before I can build this:

1. DATA ISOLATION: Your Firestore is currently a single database.
   Should each tenant get:
   a) Separate Firestore databases (strongest isolation, higher cost)
   b) Separate top-level collections per tenant (moderate isolation)  
   c) A tenantId field on every document (simplest, weakest isolation)

2. URL STRATEGY: Currently your app runs on app.example.com.
   Should tenants get:
   a) Subdomains (acme.app.example.com)
   b) Path-based routing (app.example.com/acme)
   c) Shared URL with tenant selected after login

3. AUTH BOUNDARY: Your Firebase Auth is project-wide. Should:
   a) Users be scoped to a single tenant
   b) Users be able to belong to multiple tenants
   c) Admin users have cross-tenant access

4. DATA ON DELETE: When a tenant is removed, should their data be:
   a) Hard deleted immediately
   b) Soft deleted with a 30-day recovery window
   c) Archived to Cloud Storage

5. EXISTING USERS: You have 340 users in production. How should 
   they be assigned to tenants during migration?

You answer each question. The agent follows up on ambiguous answers. By the end of the interview — typically 5–10 minutes — you’ve surfaced every decision that would have been a blocking question during an autonomous run.

From Interview to Executable Spec

Here’s the key: your answers from /grill-me become your goal prompt. The interview output maps directly to the spec structure:

Without /grill-me, you'd discover these decisions the hard way — either by writing an incomplete goal prompt that the agent guesses at (badly), or by having a long chat session where you gradually realize what you missed. /grill-me front-loads all of that discovery into a structured interview.

Think of it this way: Chat is exploration. /grill-me is structured discovery. /goal is execution. The best specs come from running /grill-me first.

/learn — Persist Patterns

/learn

After a productive chat session, use /learn to capture successful patterns. The agent creates a persistent rule or skill so future sessions (including autonomous runs) benefit from what you discovered interactively. For example, after figuring out your project's error handling pattern through chat, /learn saves it so the agent follows the same pattern in future /goal runs.

/browser — Web Automation

/browser Go to https://ai.google.dev and find the current pricing 
for Gemini 2.5 Flash. Summarize it in a table.

The agent launches a browser, navigates pages, reads content, clicks links, fills forms, and takes screenshots. Useful for:

Verifying deployed web apps look correct
Scraping documentation into structured formats
Testing user flows end-to-end
Filling out forms and capturing results

/schedule — Recurring Tasks

/schedule Run the test suite every morning at 9am and report any failures

Sets up cron-based agent execution. The agent runs autonomously on a schedule without any intervention. Useful for:

Health checks on deployed services
Periodic report generation
Automated data syncs

The Self-Correction Loop: How Autonomous Runs Actually Work

When you use /goal, the agent enters a persistent loop:

This isn’t just a flowchart, it’s the difference between chat and goal mode.

Here’s a concrete example:

The “Remove Deprecated Feature” Scenario

Imagine you ask the agent to remove a feature. Let’s say, an old notification system that’s been replaced. In Chat Mode , you’d say:

Remove the notification bell feature from the app.

The agent removes the HTML, the JS functions, and the CSS. But let’s say that it misses two stale references:

initNotifications() is still called in the app's startup() function
notificationCount is still referenced in the user profile component

These cause runtime errors. You catch them by testing, report them back, and the agent fixes them one at a time across two more exchanges. Three total interactions to complete what should have been one task.

In Goal Mode with proper verification:

/goal
Remove the deprecated notification bell feature.

## Requirements
- Remove notification bell HTML from the header
- Remove all notification JS functions
- Remove notification CSS styles
- Remove notification-related state variables

## Verification
- grep -ri 'notification' src/ → zero results (excluding 
  this prompt and git history)
- npm run build succeeds
- No console errors on page load
- App loads normally for both regular and admin users

The verify step catches the stale references. The fix step removes them. The re-verify step confirms a clean build. The two extra chat exchanges become zero — the loop handles them automatically.

What Self-Correction Looks Like

During an autonomous run, the agent:

Runs a command → command fails → reads the error → fixes the code → retries
Deploys → deployment fails → checks the error log → fixes the config → redeploys
Greps for leftover code → finds stale references → removes them → re-greps
Runs the test suite → 2 tests fail → reads the assertion errors → fixes the code → re-runs tests

This is the core advantage of autonomous execution — it doesn’t just run your code, it runs your tests and fixes its own mistakes.

When Autonomy Fails: Anti-Patterns to Avoid

Goal Mode isn’t magic. Here are real failure modes and how to avoid them. The suggestions given are with a best intention.

Anti-Pattern 1: The Vague Goal

❌ Bad:

/goal Make the app better

Why it fails: “Better” is not a verification criterion. The agent will make changes, but it has no way to know when to stop or whether its changes are improvements.

✅ Good:

/goal Add loading spinners to all async buttons. Show a spinner 
icon and "Working..." text while operations run. Disable buttons 
during processing to prevent double-clicks.

## Verification
- All async buttons show spinners during their operations
- Buttons are disabled while processing
- Spinners disappear after completion or error
- No console errors

Anti-Pattern 2: The Under-Constrained Goal

❌ Bad:

/goal Add charts to the dashboard

Why it fails: Should it use Chart.js, D3, or inline SVG? What data should the charts show? What colors? This forces the agent to make design decisions that you’ll likely want to override.

✅ Good: Pre-answer every design decision — specify the chart approach (inline SVG, no external libraries), data sources (which collections/arrays), visual style (match existing design system), and include concrete verification criteria.

Anti-Pattern 3: The Goal That Needs Discussion

❌ Bad:

/goal Redesign the entire UI to be more modern

Why it fails: “Modern” is subjective. The agent will make choices you disagree with, but since it’s running autonomously, it’ll make all of them before you see any of them. Use chat or /grill-me first to align on the direction.

✅ Better approach:

1. Start with chat: "What would a more modern UI look like for this app?"
2. Discuss options, agree on direction
3. Then use /goal with specific design tokens, colors, and patterns

Anti-Pattern 4: Missing Verification

❌ Bad:

/goal 

Remove the notification feature from the app

## Requirements
- Remove notification HTML
- Remove notification JS functions
- Remove notification variables

Why it fails: No verification step. The agent removes what you listed, but doesn’t check for stale references, the very type of bug that’s easiest to catch with a simple grep.

✅ Good:

## Verification  
- grep -ri 'notification' src/ → zero results
- npm run build succeeds
- No console errors on page load

Anti-Pattern 5: The Goal That’s Too Large

❌ Bad:

/goal 

Build a complete e-commerce platform with user auth,
product catalog, shopping cart, checkout, payment processing, 
order management, admin dashboard, and email notifications

Why it fails: Too many interacting components. If the auth system has a subtle bug, it cascades into everything else. The agent can’t isolate failures when 8 subsystems are being built simultaneously.

✅ Better: Break it into phases:

Phase 1: /goal Add user authentication with Google Sign-In
Phase 2: /goal Add product catalog with Firestore backend
Phase 3: /goal Add shopping cart with real-time sync
Phase 4: /goal Add checkout and payment processing

Each phase can be verified independently before moving to the next. You might want to even use /grill-me before coming up with the /goal at each of the phases.

When to Use Which Mode: The Decision Matrix

The Litmus Test

If you can write down every decision the agent would need to make, use /goal . If you'd need to see intermediate results before deciding, use _ **_chat** .

The Hybrid Approach

In practice, the best workflow is often:

For example:

You chat to understand your codebase’s auth patterns
Use /grill-me to surface edge cases you haven't considered ("what about expired tokens? rate limiting? session management?")
Chat a bit more to decide on the approach
Write the spec as a goal prompt, let /goal execute it autonomously while you focus on something else, and then
Review the walkthrough and diff when it's done.

Practical Tips for Better Autonomous Runs

1. Start with Chat, Graduate to Goal

Your first time building a feature? Use chat to understand the patterns. The second time you build something similar? Write a goal prompt based on what you learned.

2. Use /grill-me Before Writing Complex Goals

Not sure if you’ve thought of everything? The agent interviews you with targeted questions to surface decisions you haven’t considered. Then use the answers to write a comprehensive goal prompt.

3. Include File Paths in Goal Prompts

Don’t make the agent guess where things are:

❌ "Update the main app file"
✅ "Update src/App.tsx and src/components/Header.tsx"

4. Name Your Data Structures

If the agent needs to work with existing code, tell it the variable names:

❌ "Use the product list"
✅ "Use the productCatalog[] array from src/data/products.ts"

5. Specify the Deploy Target

If deployment is part of the goal, be explicit:

❌ "Deploy it"
✅ "Deploy to Firebase Hosting project my-project-id"

6. Use /learn After a Chat Session

After a productive chat session, /learn persists successful patterns so future goal runs benefit from what you discovered interactively.

7. Set Permissions for Autonomous Runs

For autonomous runs, pre-configure permissions so the agent doesn’t block waiting for approval:

Tool Execution Policy : always-proceed (the agent runs commands without asking)
Trusted Workspaces : Add your project directory so file operations proceed automatically

⚠️ Only use always-proceed in trusted workspaces where you're comfortable with the agent running commands autonomously.

The Bigger Picture: How Developer Roles Are Shifting

The distinction between chat and autonomous execution isn’t just a UX feature, it reflects a fundamental shift in what it means to “write code.”

In the chat era , the developer is a typist-thinker hybrid. You think about what to build, type the code, think about what broke, type the fix. Your value is split between knowing what to do and doing it.

In the autonomous era , the developer is a specification writer and reviewer. You think about what to build, write a precise spec, and review the output. Your value shifts entirely to judgment, knowing what to build, how to verify it, and how to catch subtle errors in AI-generated code.

This isn’t a loss. It’s a liberation. The mental model shifts from:

Think → Type → Debug → Type → Test → Type → Deploy → Type

To:

Think → Specify → Review → Deploy

The “typing” — the mechanical act of translating intent into code — is the part that gets automated. The thinking, specifying, and reviewing are the parts that remain uniquely human. And those are, arguably, the most intellectually rewarding parts. I hope we have consensus there though some would like to debate what is actually rewarding to them and I will respect that.

Summary

The transition from chat to autonomous execution isn’t about trust — it’s about specification clarity. When you can write down exactly what you want, including constraints and verification criteria, you’ve written a goal prompt. When you can’t yet, chat your way there first.

Start small. Try a /goal on your next well-understood task. See what happens. Then gradually increase the scope as you build confidence in your prompt engineering.

The dial goes from “fix this typo” to “build this entire feature.” Your job is to figure out, for each task, where to set it.

A quick table summary to end this article:

The Hackathon Security Guide: How to Vibe-Code Without Burning Down Your Project

Romin Irani — Thu, 09 Jul 2026 06:33:32 +0000

TL;DR — Every year, tens of millions of secrets are leaked to public repos. Automated bots exploit them within minutes_. This guide gives you the tools, code patterns, and checklists to ship fast_ and ship safe.

Infographic generated by NotebookLM

Why This Guide Exists

Let’s talk about numbers first. The numbers are staggering. According to GitGuardian’s State of Secrets Sprawl 2025 report, 23.8 million new hardcoded secrets were leaked on public GitHub repositories in 2024, a 25% increase over the previous year. These numbers are likely to only increase in each successive report.

A recent post from Harsh Dattani, who leads the Developer Ecosystems Team in India, does indicate that not paying attention to security might even cost you a chance at the Hackathon.

LinkedIn Post Reference: https://www.linkedin.com/posts/harshdattani_hackathons-buildwithai-cybersecurity-share-7480839977141071872-tVJq

In the age of “vibe coding”, where we rapidly prompt LLMs to stitch together boilerplate, frontends, and backend connections, it’s incredibly easy to blindly accept generated code, commit it, and leave the front door wide open. AI coding assistants are continously improving and it is less likely that they would frequently generate code with hardcoded placeholder keys that look harmless but become live attack vectors the moment you paste in your real credentials and push. Chances are high that in your hurry to get the entries across the finish line, you end up taking certain shortcuts and hardcode keys and credentials. And worse, you submit that along with your source code, pushed most likely in a public Github repository, as your final entry.

The attacks mentioned are not hypothetical. Automated bots crawl GitHub 24/7. They can detect and exploit a leaked AWS key within minutes of a commit. The most likely aftereffect … spinning up crypto-mining clusters on your account that can run up tens of thousands of dollars in charges overnight. And unlike ransomware, crypto-mining attacks are designed to be silent, they won’t announce themselves until you check your billing dashboard.

This guide is an attempt to be your comprehensive blueprint to ensure your team builds safely, avoids massive surprise cloud bills, and doesn’t get disqualified right before the finish line.

Part 1: What Gets Leaked — The Threat Map

Before your next commit, audit your codebase for every category below. First-time coders frequently focus only on “API keys” but miss entire classes of sensitive data.

1. Cloud Provider Credentials & Service Accounts

Automated bots harvest these 24/7 from GitHub and immediately spin up massive, expensive crypto-mining clusters in your name. A single leaked GCP Service Account Key or AWS root key can generate thousands of $$$ in charges within hours.

2. Database Connection Strings

Raw connection URIs with embedded plaintext passwords grant the entire internet read, write, and delete permissions to your database.

# These patterns should NEVER appear in source code:
mongodb+srv://admin:MySecretPass123@cluster0.abc123.mongodb.net
postgresql://postgres:HackathonAdmin2026@db.supabase.co:5432/main
redis://default:sUp3rS3cr3t@redis-12345.c1.us-east-1-2.ec2.cloud.redislabs.com:6379
mysql://root:password@localhost:3306/hackathon_db

3. OAuth Secrets, Tokens & Webhook URLs

4. Communication & Messaging Service Credentials

Twilio SIDs, SendGrid API keys, Mailgun tokens, Firebase Cloud Messaging keys … these leaked communication credentials let attackers send high-volume spam under your identity, potentially getting your accounts permanently banned.

5. The Forgotten Config Files

These files are committed by accident more often than any hardcoded string:

6. The Git History Trap

Deleting a secret from your file and making a new commit does NOT remove it. The secret is still fully visible in your Git commit history. Unless the history is explicitly purged, attackers can trivially recover it.

This is one of the most common mistakes. You realize a key was hardcoded, you delete it, you commit the fix and you think you’re safe. You are not. Every previous commit is a permanent snapshot. We cover how to properly purge history later in the article.

Part 2: Code Blueprints — 14 Framework Examples (Before & After)

Don’t leave configuration to chance. Here are some ways to safely manage secrets across popular frameworks.

1. Gemini / Google GenAI SDK (Python)

❌ Vulnerable:

from google import genai
client = genai.Client(api_key="AIzaSyA1B2C3D4E5F6G7H8I9J0K_LeakedKey")

✅ Secure:

import os
from google import genai
client = genai.Client(api_key=os.environ.get("GEMINI_API_KEY"))

📝 Add to **.env:**

GEMINI_API_KEY=your_gemini_api_key_here

Vector Databases (Pinecone / AI Apps)

❌ Vulnerable:

from pinecone import Pinecone
pc = Pinecone(
     api_key="pcsk_7a8b9c_secret_production_key",
     host="https://my-index-12345.svc.us-east-1-aws.pinecone.io"
)

✅ Secure:

import os
from pinecone import Pinecone

pc = Pinecone(
    api_key=os.environ.get("PINECONE_API_KEY"),
    host=os.environ.get("PINECONE_HOST")
)

📝 Add to **.env:**

PINECONE_API_KEY=your_pinecone_api_key_here
PINECONE_HOST=https://your-index.svc.region.pinecone.io

Frontend Framework Keys (Vite / React)

❌ Vulnerable (firebase.js):

export const firebaseConfig = {
  apiKey: "AIzaSyAsDfGhJkL123456_FakeFirebaseKey",
  authDomain: "hackathon-app.firebaseapp.com",
  projectId: "hackathon-app-123"
};

✅ Secure:

export const firebaseConfig = {
  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID
};

📝 Add to **.env:**

VITE_FIREBASE_API_KEY=your_firebase_api_key_here
VITE_FIREBASE_AUTH_DOMAIN=your-app.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id

Firebase API keys are designed to be public identifiers , not authorization secrets. They route requests to your project — the real security comes from Firebase Security Rules and App Check. However, you should still:

Restrict your API key in the Google Cloud Console (HTTP referrer restrictions, API restrictions)
Never use allow read, write: if true; in production Security Rules
Enable App Check to block unauthorized clients

Even though the key is “public,” an unrestricted key can be abused for quota theft or to access other Google APIs enabled on your project.

LLM API Providers (Gemini / Groq / OpenAI)

❌ Vulnerable:

from google import genai

client = genai.Client(api_key="AIzaSyA1B2C3D4E5F6G7H8I9J0K_LeakedKey")
response = client.models.generate_content(model="gemini-2.5-flash", contents="Hello!")

✅ Secure:

import os
from google import genai

client = genai.Client(api_key=os.environ.get("GEMINI_API_KEY"))
response = client.models.generate_content(model="gemini-2.5-flash", contents="Hello!")

📝 Add to **.env:**

GEMINI_API_KEY=your_gemini_api_key_here

Cloud Object Storage (Google Cloud Storage / AWS S3)

❌ Vulnerable:

from google.cloud import storage

# DANGER: Loading a service account key file that gets committed to Git
client = storage.Client.from_service_account_json("service-account-key.json")
bucket = client.bucket("my-hackathon-bucket")

✅ Secure (environment variables):

import os
from google.cloud import storage

# Point to the key file via environment variable (file itself is in .gitignore)
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = os.environ.get("GCP_SA_KEY_PATH", "")
client = storage.Client()
bucket = client.bucket(os.environ.get("GCS_BUCKET_NAME"))

✅✅ Best Practice (Application Default Credentials — zero keys in code):

from google.cloud import storage

# The SDK automatically picks up credentials from:
# 1. Attached service account (on Compute Engine, Cloud Run, Cloud Functions)
# 2. GOOGLE_APPLICATION_CREDENTIALS environment variable
# 3. gcloud auth application-default login (local dev)
# No keys needed in code at all.
client = storage.Client()

Add to **.env:**

# Google Cloud
GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json
GCS_BUCKET_NAME=your-bucket-name

# AWS (if applicable)
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key

Prefer Application Default Credentials (ADC) over service account key files entirely. If you’re running on a Compute Engine VM, Cloud Run service, or Cloud Function, attach a service account directly. The SDK picks up temporary credentials automatically — no key files to leak.

Chat Webhooks (Discord / Slack Bots)

❌ Vulnerable:

const DISCORD_WEBHOOK = "https://discord.com/api/webhooks/123456789/AbCdEfGhIjKlMnOpQrStUvWxYz";
await axios.post(DISCORD_WEBHOOK, { content: "New User Registered!" });

✅ Secure:

const DISCORD_WEBHOOK = process.env.DISCORD_WEBHOOK_URL;

Communication Gateways (Twilio SMS)

❌ Vulnerable:

from twilio.rest import Client

account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_raw_auth_token_value_here'
client = Client(account_sid, auth_token)

✅ Secure:

import os
from twilio.rest import Client

account_sid = os.environ.get('TWILIO_ACCOUNT_SID')
auth_token = os.environ.get('TWILIO_AUTH_TOKEN')
client = Client(account_sid, auth_token)

Database ORM Frameworks (Prisma Schema)

❌ Vulnerable (schema.prisma):

datasource db {
  provider = "postgresql"
  url = "postgresql://postgres:HackathonAdminPassword2026@db.supabase.co:5432/main"
}

✅ Secure:

datasource db {
  provider = "postgresql"
  url = env("DATABASE_URL")
}

📝 Add to **.env:**

DATABASE_URL=postgresql://user:password@localhost:5432/my_db

Maps & Geocoding SDKs (Google Maps)

❌ Vulnerable:

<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB4_X_yZ12345&callback=initMap" async defer></script>

✅ Secure (server-side injection at build time):

For Vite , load the key in JavaScript rather than hardcoding it in HTML:

// maps-loader.js
const script = document.createElement('script');
script.src = `https://maps.googleapis.com/maps/api/js?key=${import.meta.env.VITE_MAPS_API_KEY}&callback=initMap`;
script.async = true;
script.defer = true;
document.head.appendChild(script);

For Next.js , use server-side rendering:

// pages/map.js
export async function getServerSideProps() {
  return { props: { mapsKey: process.env.GOOGLE_MAPS_API_KEY } };
}

export default function MapPage({ mapsKey }) {
  return <script src={`https://maps.googleapis.com/maps/api/js?key=${mapsKey}&callback=initMap`} async defer />;
}

Always restrict Maps API keys in the Google Cloud Console. Set HTTP referrer restrictions to your domain(s) so the key is useless if scraped from your page source.

Development Bypass Routes (Backdoors)

❌ Vulnerable:

app.post('/api/login', (req, res) => {
    if (req.body.username === "judge_tester" && req.body.password === "SuperSecretBypass!!!") {
        return res.json({ token: "mock_jwt_token_admin" });
    }
});

✅ Secure:

app.post('/api/login', (req, res) => {
    // Test bypass only exists in development mode
    if (process.env.NODE_ENV === 'development' &&
        req.body.username === process.env.TEST_USER &&
        req.body.password === process.env.TEST_PASS) {
        return res.json({ token: generateTestToken() });
    }
    // ... real authentication logic
});

Even with environment variables, shipping backdoors is risky. If NODE_ENV is accidentally left as development in production, the bypass is live. Consider removing test login routes entirely before submission, or use a dedicated feature flag service.

Django / Flask Secret Keys (Python)

❌ Vulnerable (settings.py):

SECRET_KEY = 'django-insecure-super-secret-key-that-should-not-be-here'

✅ Secure:

import os

SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY')
if not SECRET_KEY:
    raise ValueError("DJANGO_SECRET_KEY environment variable is not set!")

Payment Integrations (Stripe)

❌ Vulnerable:

const stripe = require('stripe')('sk_live_51H1234567890abcdefghijklmnopqrs');

✅ Secure:

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

Stripe live keys (sk_live_...) provide full access to your payment processing. A leaked key can expose customer payment data and transaction history. Use test keys (sk_test_...) during development, and even those should be in environment variables.

Docker Compose Secrets

❌ Vulnerable (docker-compose.yml):

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: MyHackathonPassword123
      POSTGRES_USER: admin
  app:
    environment:
      DATABASE_URL: postgresql://admin:MyHackathonPassword123@db:5432/hackathon
      API_KEY: AIzaSy_LeakedAgain

✅ Secure:

services:
  db:
    image: postgres:16
    env_file:
      - .env
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_USER: ${POSTGRES_USER}
  app:
    env_file:
      - .env
    environment:
      DATABASE_URL: ${DATABASE_URL}
      API_KEY: ${API_KEY}

Part 3: Automated Defense — Tools That Catch Secrets Before They Ship

Humans make mistakes. Tools don’t get tired at 3 AM during a hackathon. Set up these automated defenses.

Layer 1: Pre-Commit Hooks (Catches secrets before they enter Git)

This is your first and most important line of defense. Install Gitleaks as a pre-commit hook:

Step 1: Install the pre-commit framework

# macOS
brew install pre-commit

# pip
pip install pre-commit

Step 2: Create **.pre-commit-config.yaml in your repo root**

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1 # Check GitHub for latest version
    hooks:
      - id: gitleaks

Step 3: Install the hook

pre-commit install

Now every git commit will automatically scan for secrets and block the commit if any are found.

Hackathon shortcut: If you don’t want to set up pre-commit, you can run Gitleaks manually before pushing:

# Install
brew install gitleaks

# Scan your repo
gitleaks detect --source . --verbose

Layer 2: GitHub Push Protection (Catches secrets at the remote)

GitHub automatically scans every push to public repositories and blocks commits containing recognized secret patterns (API keys, Stripe keys, etc.). This is enabled by default on public repos.

For private repos: Go to Settings → Code security → Secret scanning and enable both Secret scanning and Push protection.

Layer 3: CI/CD Pipeline Scanning (Final safety net)

Add Gitleaks to your GitHub Actions workflow:

# .github/workflows/security.yml
name: Secret Scan
on: [push, pull_request]
jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Defense Layers Summary

Part 4: The AI Guardrail — System Prompt for Vibe Coding

If you rely on AI coding assistants (Antigravity, Claude, Claude, ChatGPT, Gemini, GitHub Copilot) to write your application code, you can block raw secrets at the source. Paste this into your AI assistant’s system rules or your initial chat prompt:

You are an expert, security-conscious Lead Developer. We are building a
rapid prototype / hackathon project, but infrastructure security is a
non-negotiable core feature.

STRICT GUARDRAILS for all code generation:

1. NEVER hardcode API keys, passwords, private tokens, connection strings,
   webhook URLs, or any environment secrets directly into the code.

2. When a credential is required, ALWAYS use the standard environment
   variable pattern for the language/framework:
   - Node.js: process.env.VARIABLE_NAME
   - Python: os.environ.get("VARIABLE_NAME")
   - Vite/React: import.meta.env.VITE_VARIABLE_NAME
   - Go: os.Getenv("VARIABLE_NAME")
   - Prisma: env("VARIABLE_NAME")

3. Every time you generate code that requires a secret, explicitly list the
   key-value pairs I need to add to my local .env file.

4. Provide a .env.example file with placeholder names (never real values).

5. If I accidentally paste code containing what appears to be a live API
   key, FLAG IT IMMEDIATELY and remind me to rotate the credential.

6. When generating Docker or docker-compose files, use env_file or
   variable substitution — never inline secrets.

7. When generating .gitignore, always include: .env, .env.local,
   .env.production, *.pem, *.key, serviceAccountKey.json, and
   any other credential files relevant to the project.

Part 5: Emergency Response — When You Leak a Secret

It’s 2 AM. You just realized you pushed a commit with your live keys 6 hours ago. Here’s the emergency protocol:

Step 1: ROTATE IMMEDIATELY (Do this FIRST)

Do not skip this step. Do not “clean up the code first.” Assume the secret has already been harvested.

Step 2: Check for Unauthorized Usage

Google Cloud: Check Cloud Audit Logs for unexpected API calls. Check Billing reports for unusual charges.
AWS: Check CloudTrail for unexpected API calls. Check the Billing dashboard for unusual charges.
Azure: Check Activity Log and Cost Management.
Stripe: Check the Events log for unauthorized transactions.

Step 3: Remove from Git History

Simply deleting the line and making a new commit is not enough. Use git filter-repo (the modern, Git-recommended replacement for the deprecated git filter-branch):

# Install
pip install git-filter-repo

# Clone a fresh mirror copy (required by git filter-repo)
git clone --mirror https://github.com/your-org/your-repo.git
cd your-repo.git

# Option A: Remove an entire file from history
git filter-repo --path .env --invert-paths

# Option B: Replace a specific secret string
# Create replacements.txt with format: literal:OLD_SECRET==> ***REDACTED***
echo 'literal:AKIAIOSFODNN7EXAMPLE==> ***REDACTED***' > /tmp/replacements.txt
git filter-repo --replace-text /tmp/replacements.txt

# Force push the cleaned history
git push origin --force --all
git push origin --force --tags

After force-pushing, every team member must re-clone the repository. If anyone pushes from their old local copy, the secret will be re-introduced into the history.

Part 6: Protect Your Wallet — Cloud Billing Safeguards

Leaked keys are the #1 cause of surprise cloud bills at hackathons. Even if you’re using free-tier credits, set these up immediately.

Set Budget Alerts on Day Zero

Hackathon Cost Hygiene

Use the smallest instance sizes (e2-micro on GCP, t3.micro on AWS) unless you specifically need more.
Set calendar reminders to delete resources after the hackathon.
Tag all resources with project=hackathon-name so you can identify orphaned resources.
Disable unused APIs in your cloud console.
Never use root/owner credentials — create a limited IAM user or service account with only the permissions you need.

Restrict Your API Keys

Even keys that are designed to be client-facing (like Firebase or Google Maps keys) should be restricted :

Configure these in the Google Cloud Console → APIs & Services → Credentials.

Part 7: The Bulletproof Submission Checklist

Before your team clicks “Submit,” take five minutes to walk through this loop. Print this out. Tape it to your monitor.

Pre-Submission Audit

.gitignore exists and contains: .env, .env.local, .env.production, *.pem, *.key, serviceAccountKey.json, config.json (if it has secrets)
.env.example is included in the repo with descriptive placeholder names (see template below)
No secrets in docker-compose.yml — uses env_file or ${VARIABLE} substitution
No secrets in CI/CD config — all secrets are in GitHub Secrets / environment variables
No test backdoors with hardcoded credentials remain in the code
Run the comprehensive grep scan (see below)
Run Gitleaks (gitleaks detect --source . --verbose)
API keys are restricted in cloud console (referrer, IP, API scope)
Budget alerts are set on all cloud accounts
README includes setup instructions that reference the .env.example

.env.example Template

Ship this in your repo root so judges and reviewers can set up your project:

# ==========================================
# PROJECT CONFIGURATION TEMPLATE
# ==========================================
# Copy this file to .env and fill in your values.
# DO NOT commit the .env file.
# ==========================================

# --- Server ---
PORT=8080
NODE_ENV=development

# --- Database ---
DATABASE_URL=

# --- AI / LLM ---
GEMINI_API_KEY=
OPENAI_API_KEY=
GROQ_API_KEY=

# --- Vector Database ---
PINECONE_API_KEY=
PINECONE_HOST=

# --- Cloud Storage ---
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=us-east-1

# --- Authentication ---
JWT_SECRET=
GOOGLE_OAUTH_CLIENT_ID=
GOOGLE_OAUTH_CLIENT_SECRET=

# --- Communication ---
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
DISCORD_WEBHOOK_URL=

# --- Payments ---
STRIPE_SECRET_KEY=
STRIPE_PUBLISHABLE_KEY=

# --- Firebase (client-side, restrict in Cloud Console) ---
VITE_FIREBASE_API_KEY=
VITE_FIREBASE_AUTH_DOMAIN=
VITE_FIREBASE_PROJECT_ID=

Leave values blank (not with fake-looking values like AIzaSyYourKeyHere that could be mistaken for real keys). Use descriptive variable names so it's obvious what each one is for.

Comprehensive Pre-Push Grep Scan

Run this in your terminal from the project root. It searches for common secret patterns across your codebase, ignoring common false-positive directories:

# Quick scan — looks for common secret patterns
git grep -inE \
  'sk_live|sk_test|AKIA[0-9A-Z]{16}|AIzaSy|ghp_|gho_|glpat-|xoxb-|xoxp-|hooks\.slack\.com|discord\.com/api/webhooks|mongodb\+srv://|postgresql://[^]*:[^]*@|-----BEGIN (RSA |EC )?PRIVATE KEY|pcsk_|gsk_' \
  -- ':!node_modules' ':!.git' ':!*.lock' ':!package-lock.json'

# Broader scan — catches environment variable assignments with values
git grep -inE \
  '(api[_-]?key|secret|password|token|credential|auth[_-]?token)\s*[:=]\s*["\x27][A-Za-z0-9_\-/.+]{8,}' \
  -- ':!node_modules' ':!.git' ':!*.lock' ':!*.md'

The original blog’s git grep -i "key|secret|password|token|sk_" is too broad and will produce hundreds of false positives (variable names, comments, documentation). The patterns above target actual secret values, not just keywords.

Part 8: Quick-Reference Cheat Sheet

Part 9: The Minimal .gitignore Every Hackathon Project Needs

# === Secrets & Config ===
.env
.env.*
!.env.example
*.pem
*.key
*.p12
*.pfx
serviceAccountKey.json
google-services.json
GoogleService-Info.plist
credentials.json
secrets.json
config.local.json

# === Dependencies ===
node_modules/
vendor/
__pycache__ /
*.pyc
.venv/
venv/

# === Build Outputs ===
dist/
build/
.next/
out/

# === IDE ===
.vscode/
.idea/
*.swp
*.swo
.DS_Store
Thumbs.db

# === Terraform ===
*.tfvars
.terraform/
terraform.tfstate*

Final Words

The five minutes you spend separating your logic from your secrets will save you from:

Surprise cloud bills that can reach thousands of dollars
Hackathon disqualification for security violations
The stress of rotating every credential at 3 AM
The embarrassment of explaining to your team why the Cloud bill is $12,000

The tools exist. The patterns are simple. The checklists are right here. Use them.

Keep building. Keep shipping. Keep it secure.

Mastering Gemini Computer Use : A Comprehensive Hands-on Guide

Romin Irani — Fri, 26 Jun 2026 10:34:30 +0000

Gemini Computer Use lets you build AI agents that control real screens by looking at screenshots and deciding what to click, type, or scroll, just like a human would.

You can read the announcement post below:

Introducing computer use in Gemini 3.5 Flash

This tutorial walks you through five progressive steps (from “Hello Screenshot” to Gemini Enterprise Agent Platform), then shows five real-world use cases. All code is included and runnable.

What is Computer Use?

If you’ve ever written a Selenium test or a Puppeteer script, you know the script and the friction that comes with it. You spend hours crafting CSS selectors, XPath expressions, and fragile wait conditions. Then one day, the website changes a class name, and everything breaks. This is the fragile nature of selector-based automation, where it depends on the implementation details of the UI rather than what’s actually visible on the screen.

And there’s a deeper problem. Not every application exposes an API. Legacy enterprise software, desktop apps, mobile interfaces , there’s an enormous surface area of software that can only be operated by a human looking at a screen and clicking around.

The Solution: AI That Sees

Gemini Computer Use takes a radically different approach. Instead of parsing HTML or querying the DOM, the model looks at a screenshot and decides what to do, exactly the way a human would. It doesn’t need selectors. It doesn’t need APIs. It just needs eyes.

The paradigm is beautifully simple: Observe → Think → Act.

Observe: Capture a screenshot of the current screen state
Think: Send it to Gemini 3.5 Flash, which analyzes the visual content and decides the next action
Act: Execute the action (click a button, type text, scroll down), then capture a new screenshot and loop back

This loop continues until the model decides the task is complete and responds with text instead of a function call.

How Computer Use Works: Brain, Eyes, and Hands

Every Computer Use agent has three parts:

The Brain is always the same — Gemini 3.5 Flash. But the Hands change depending on what you’re controlling:

┌─────────────────────────────────────────────────────────────────┐
│ 🧠 BRAIN (always the same) │
│ Gemini 3.5 Flash │
│ "Look at this screenshot, what should I do?" │
└──────────────────────────┬──────────────────────────────────────┘
                           │
              Model returns: click(x=396, y=185)
                           │
          ┌────────────────┼────────────────┐
          ▼ ▼ ▼
   🖐️ Browser 🖐️ Mobile 🖐️ Enterprise
   Playwright ADB CDP Sandbox
   page.mouse adb shell Remote browser
   .click(506,148) input tap in the cloud
                      506 148

Why this matters: The model doesn’t know or care what “hands” you’re using. It just sees screenshots and returns actions. You can swap Playwright for Selenium, ADB for a physical device, or a local browser for a cloud sandbox — the model’s output is identical. The only thing that changes is the environment parameter you declare (browser, mobile, or desktop), which tells the model what kind of screen it's looking at.

Why Gemini 3.5 Flash is Special

Computer Use isn’t a separate model or a bolted-on capability. In gemini-3.5-flash, it's a native tool, declared alongside other tools like function calling and code execution. This design decision has key implications and its worthwhile to understand them:

Multi-tool composition: The model can interleave browser actions with custom function calls in the same conversation. Click a button, then call save_product() to store data, then scroll down for more.
Three environments: One model supports ENVIRONMENT_BROWSER, ENVIRONMENT_MOBILE, and ENVIRONMENT_DESKTOP. You declare the environment and the model adapts its available actions.
Thinking mode: You can enable ThinkingConfig(include_thoughts=True) to see the model's reasoning before each action, invaluable for debugging.

Key Technical Concepts

Normalized Coordinates (0–999): The model doesn’t know your screen resolution. Instead, it outputs coordinates in a normalized 0–999 range. You convert them to pixels with:

pixel = int(normalized / 1000 * screen_dimension)

For a 1280×800 viewport, coordinate (500, 500) maps to pixel (640, 400) — the centre of the screen.

The intent Field: Each function call includes an intent string describing what the model is trying to achieve , not just the mechanical action. This is crucial if you try to debug the whole flow.

Safety Decisions: When the model encounters potentially sensitive actions (making a purchase, sending a message, deleting data), it includes a safety_decision object requesting explicit user confirmation.

What Changed from Legacy to Current

The previous gemini-2.5-computer-use-preview model was an early experiment with a separate API surface. The current gemini-3.5-flash approach integrates Computer Use as a standard tool. This means the same model, the same SDK, and the same generate_content() call, that you already know.

Two Paths: Gemini API vs Enterprise Platform

There are two ways to use Gemini Computer Use, and which one you choose depends on where you are in the development lifecycle.

Gemini API (ai.google.dev)

The fastest path from zero to working agent. Grab an API key, pip install the SDK, and you’re running. You build your own execution environment (Playwright for browsers, ADB for Android), which gives you maximum flexibility and zero cloud dependencies.

Enterprise Agent Platform (Vertex AI)

When you’re ready for production, Vertex AI adds IAM-based authentication, managed browser sandboxes (no local browser needed), VPC Service Controls, audit logging, and all the enterprise trimmings. The important part? The code is almost identical. You change one line.

The migration between paths is a single-line change in client construction:

Before — Gemini API (prototyping)

# Gemini API (prototyping)
client = genai.Client(api_key="YOUR_KEY")

After — Vertex AI (production)

# That's it — that's the migration
client = genai.Client(
    vertexai=True,
    project="my-project",
    location="us-central1",
)

Prerequisites & Setup

In this section, we will identify the software that we need. This completely depends on what use cases and scenarios that you are interested in, while using Gemini Computer Use.

The table given in the section What You Need identifies the requirement and which step/use case that you need it for. For e.g. if you are not interested in Android app scenarios or running this on Google Cloud, you can simply do with Python 3.10+ and Gemini API Key only. Each of the steps and use cases are mentioned clearly in the article. So as you go along, remember to have these requirements handy.

What You Need

Step-by-Step Installation

The examples are code heavy and hence I have made a code repository available for you. The tutorial too goes into each of the folders i.e. steps or use cases in the repository, and you can follow the steps to run the examples.

GitHub - rominirani/computer-use-tutorial: Mastering Gemini Computer Use: A Comprehensive Hands-On Guide - Build AI agents that control browsers, mobile devices, and desktops with Gemini 3.5 Flash

The Repository structure is shown below:

computer-use-tutorial/
├── README.md ← You are here
├── requirements.txt ← Python dependencies
├── .env.example ← Template for API key
├── 01-hello-screenshot/ ← Step 1: Visual understanding
│ └── hello_screenshot.py
├── 02-single-action/ ← Step 2: One screenshot → one click
│ └── single_action.py
├── 03-browser-agent/ ← Step 3: Full agentic browser loop
│ ├── browser_agent.py
│ └── playwright_env.py
├── 04-mobile-agent/ ← Step 4: Android + Interactions API
│ ├── mobile_agent.py
│ ├── adb_bridge.py
│ └── setup_emulator.sh
├── 05-enterprise-platform/ ← Step 5: Vertex AI + sandboxes
│ └── enterprise_agent.py
└── 06-use-cases/ ← 5 real-world use cases
    ├── usecase1_qa_testing/
    ├── usecase2_price_comparison/
    ├── usecase3_mobile_testing/
    ├── usecase4_web_research/
    └── usecase5_form_filling/

1. Clone the repository

git clone https://github.com/rominirani/computer-use-tutorial
cd computer-use-tutorial

2. Create a Python virtual environment

python3 -m venv .venv
source .venv/bin/activate # macOS / Linux
# On Windows: .venv\Scripts\activate

⚠️ Important : Always activate the virtual environment before running any tutorial script. If your shell prompt doesn’t show (.venv), run source .venv/bin/activate again.

3. Install Python dependencies

pip install -r requirements.txt

The requirements.txt is intentionally lean:

google-genai>=2.7.0
playwright==1.55.0
pydantic>=2.0
rich
termcolor
python-dotenv

What is Playwright doing here?

Playwright is the “ hands ” of the agent. Gemini Computer Use gives the model eyes (it can see screenshots) and a brain (it decides what to do), but it has no way to actually interact with a browser. That’s where Playwright comes in.

It is an open-source browser automation library from Microsoft. It lets Python code control a real Chromium browser i.e. open pages, click at pixel coordinates, type text, scroll, take screenshots, intercept popups, etc.

Why we need it?

The Gemini model returns structured instructions like:

click(x=396, y=185)
type(text="hello world")
scroll(direction="down")

But these are just data. The model can’t execute them. Something needs to translate click(x=396, y=185) into an actual mouse click inside a real browser. Playwright does that:

Model says click(x=396, y=185) → Playwright runs page.mouse.click(506, 148)
Model says type("hello") → Playwright runs page.keyboard.type("hello")
Model says take a screenshot → Playwright runs page.screenshot() → PNG bytes

Could you use something else?

Yes you could. Selenium, Puppeteer, or any browser automation tool would work. Playwright is chosen here because it’s fast, has a clean Python API, handles headless mode well, and has built-in screenshot capture. For mobile, we use ADB instead of Playwright (same role, different “hands”).

Playwright doesn’t use the Chrome/Chromium already on your machine. It ships its own browser binaries that are patched for automation, they expose internal APIs (like the Chrome DevTools Protocol) that Playwright uses to control the browser programmatically (click, type, screenshot, navigate, etc.).

playwright install chromium downloads this patched Chromium binary (~150 MB) into a Playwright-managed directory (e.g. ~/Library/Caches/ms-playwright/).

4. Install the Chromium browser binary

playwright install chromium

Verify it works:

python3 -c "from playwright.sync_api import sync_playwright; pw = sync_playwright().start(); b = pw.chromium.launch(); print('✅ Playwright Chromium works'); b.close(); pw.stop()"

5. Configure your Gemini API key

Please get a Gemini API Key from here.

cp .env.example .env
# Edit .env and replace 'your-api-key-here' with your actual key

Your .env file should look like:

GEMINI_API_KEY=AIzaSy...(your actual key)

6. Verify — run Step 01

cd 01-hello-screenshot
python hello_screenshot.py

If you see the model describe the Hacker News page, your setup is complete for Steps 1–3 and browser-based use cases. 🎉

In my case here, this is what I got as output:

✓ Gemini client initialised

============================================================
  Step 1 → Launch browser
  Opening https://news.ycombinator.com
============================================================

  → Page loaded: Hacker News
  → Viewport : 1280×800

============================================================
  Step 2 → Capture screenshot
  Taking a full-viewport PNG snapshot
============================================================

  → Screenshot captured: 206.7 KB
  → Saved to : /Users/romin/computer-use-tutorial/01-hello-screenshot/screenshot.png

============================================================
  Step 3 → Send to Gemini
  Asking the model to describe the screenshot
============================================================

============================================================
  Step 4 → Model response
  Gemini's description of the screenshot
============================================================

Based on the screenshot provided, here is a detailed description of the webpage:

### **Website Name and Identity**
* **Site Name:**  **Hacker News** (a social news website focusing on computer science and entrepreneurship, run by the investment fund Y Combinator).
* **Logo:** A small, bright orange square containing a stylized white letter **"Y"** sits in the top-left corner.

### **Color Scheme**
* **Primary Accent:** Bright safety orange (`#ff6600`), used exclusively for the top navigation bar.
* **Background:** The main content area has a very light, warm gray/off-white background, while the outer margins of the page are plain white.
* **Text:** Dark gray to black for the main headlines, and a lighter, muted gray for metadata (points, time, domains, and comment counts).

### **Layout and Navigation**
* **Structure:** The site features an extremely minimalist, text-heavy, "Web 1.0" style layout. The content is centered in a single vertical column with wide white margins on the left and right.
* **Header Bar:** A solid orange horizontal bar spans the top of the content column. 
    * On the left, next to the "Y" logo, is the bold text **"Hacker News"** followed by a pipe-separated menu of navigation links: `new | past | comments | ask | show | jobs | submit`.
    * On the far right of this bar is a single `login` link.
* **Main List:** Below the header is a sequentially numbered list of stories (numbered 1 through 22 are visible). 

### **Anatomy of a List Item**
Each item in the list follows a strict, consistent format:
1. **Number and Upvote Arrow:** A number (e.g., "1.") followed by a small, light-gray upward-pointing triangle (▲) used for voting.
2. **Headline:** The title of the article, styled as a clickable dark link.
3. **Source Domain:** Directly next to the headline, the hosting website's domain is listed in parentheses in light gray (e.g., `(om.co)` or `(github.com/plbrault)`).
4. **Metadata Line:** Positioned directly below the headline in smaller, lighter text. This includes:
    * The score (e.g., "843 points")
    * The submitting user's handle (e.g., "by minimaxir")
    * How long ago it was posted (e.g., "11 hours ago")
    * A "hide" link
    * The comment count, which links to the discussion page (e.g., "96 comments").

### **Visible Top Headlines**
The top stories visible on this front page cover tech news, programming, hardware, and history. Notable headlines include:
1. *Om Malik has died* (om.co)
2. *Why current LLM costs are not sustainable* (patadia.org)
3. *An entire Herculaneum scroll has been read for the first time* (scrollprize.org)
4. ....
10. ....

────────────────────────────────────────────────────────────
Cleaning up browser resources...
✓ Done — screenshot saved to screenshot.png

(Optional) Android Emulator Setup

Skip this if you only want the browser-based examples (Steps 1–3, Use Cases 1–2, 4–5).

Option A: Use the included setup script

cd 04-mobile-agent
chmod +x setup_emulator.sh
./setup_emulator.sh

This idempotent script installs Java, Android SDK, creates an AVD named ComputerUseTutorial, and prints the export lines for your shell.

If you are familiar with Android SDK, feel free to look at the setup_emulator.sh script and create an AVD named ComputerUseTutorial.

Option B: Existing Android SDK

# Common ANDROID_HOME locations:
export ANDROID_HOME=~/Library/Android/sdk # Android Studio default
export ANDROID_HOME=/opt/homebrew/share/android-commandlinetools # Homebrew (Apple Silicon)
# Add to PATH
export PATH="$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools:$PATH"
# Add to ~/.zshrc so it persists
echo 'export ANDROID_HOME=~/Library/Android/sdk' >> ~/.zshrc
echo 'export PATH="$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools:$PATH"' >> ~/.zshrc
source ~/.zshrc

Starting and verifying the emulator

# List and start
emulator -list-avds
emulator -avd <your-avd-name>
# Verify it's ready
adb devices # → emulator-5554 device
adb shell getprop sys.boot_completed # → 1

(Optional) Google Cloud Setup

Skip this if you don’t have a Google Cloud project or only want the Gemini API.

# Authenticate
gcloud auth login
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID
# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com

Add to your .env:

GCP_PROJECT_ID=your-gcp-project-id
GCP_LOCATION=us-central1

Required IAM role: roles/aiplatform.user

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="user:your-email@domain.com" \
    --role="roles/aiplatform.user"

Understanding the Code: Key Computer Use Patterns

Before diving into the step-by-step code, here are the patterns you’ll see in every script.

Pattern 1: Normalized Coordinates (0–999)

The model always outputs coordinates in a 0–999 grid, regardless of screen size. Your code must denormalize:

# Model returns: click(x=396, y=185) — these are NOT pixels!
pixel_x = int(396 / 1000 * viewport_width) # 396 → 506 on a 1280px screen
pixel_y = int(185 / 1000 * viewport_height) # 185 → 148 on an 800px screen

This is the most common source of bugs, forgetting to denormalize will cause clicks to land in the wrong place.

Pattern 2: The Agentic Loop

1. Take screenshot → send to model with task description
2. Model returns: function_call (e.g., click, type, scroll)
3. Execute the action in the browser/device
4. Take a NEW screenshot → send back as FunctionResponse
5. Goto 2 — until model returns plain text (= task complete)

The key insight: the model signals it’s done by returning text instead of function_calls.

Pattern 3: FunctionResponse Must Include a Screenshot

FunctionResponse(
    name="click",
    response={
        "result": "ok",
        "screenshot": types.Part.from_bytes(
            data=screenshot_png, mime_type="image/png"
        ),
    },
)

Without the screenshot, the model is blind and can’t plan its next move.

Pattern 4: Tool Declaration

tools=[
    types.Tool(
        computer_use=types.ComputerUse(
            environment=types.Environment.ENVIRONMENT_BROWSER,
            # or ENVIRONMENT_MOBILE / ENVIRONMENT_DESKTOP
        )
    )
]

This is NOT a regular function declaration — it activates the model’s built-in understanding of screenshots and UI interaction.

Pattern 5: Screenshot Pruning

Screenshots are ~100–300 KB each. In a 20-turn conversation, that’s 2–6 MB of image data in the context:

# Keep only the 3 most recent screenshots
for old_turn in history[:-3]:
    for part in old_turn.parts:
        if hasattr(part, 'inline_data'):
            part.inline_data = None # free memory, keep text

Step-by-Step Tutorial

This tutorial has several steps (numbered 1 to 5). Step 1 to 3 can be done simply via Python and Gemini API Key. Step 4 is about Android , while Step 5 is about Google Cloud.

Step 1 : Hello Screenshot 01-hello-screenshot/

Before we can build an agent that controls a screen, we need to make sure it can see one. In this step, you’ll launch a headless browser, navigate to Hacker News, capture a screenshot, and send it to Gemini 3.5 Flash to get a visual description. There’s no Computer Use here , just the two foundational building blocks (screenshots + the model) that every subsequent step builds on.

Key Concept: This step uses no Computer Use at all. It establishes the two foundational building blocks:

Capturing screenshots
Sending them to Gemini , that every subsequent step depends on.

Code Walkthrough

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        types.Content(
            role="user",
            parts=[
                types.Part(text="Describe what you see..."),
                types.Part(
                    inline_data=types.Blob(
                        mime_type="image/png",
                        data=screenshot_bytes,
                    )
                ),
            ],
        )
    ],
)

The SDK handles base64 encoding. You pass raw bytes and the MIME type.

Running It

cd 01-hello-screenshot
python hello_screenshot.py

Expected Output

✓ Gemini client initialised
Step 1 → Launch browser
  Opening https://news.ycombinator.com
  → Page loaded: Hacker News
  → Viewport : 1280×800
  Step 4 → Model response
  The screenshot shows Hacker News (news.ycombinator.com)...

Step 2 : Your First Computer Use Action 02-single-action/

Now we give the model its “ hands.” You’ll show Gemini a screenshot of Wikipedia’s language selection page and ask it to click on the English link. The model will return a function_call with normalized coordinates, and you'll translate those into real pixel positions and execute the click with Playwright. This is a single round-trip — one screenshot in, one action out — but it covers the most critical concept in Computer Use: coordinate normalization.

Key Concept: This is where Computer Use enters the picture. The critical new concept is coordinate normalization.

Code Walkthrough

# Declare the Computer Use tool
computer_use_tool = types.Tool(
    computer_use=types.ComputerUse(
        environment=types.Environment.ENVIRONMENT_BROWSER,
    )
)
# Send request
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=request_contents,
    config=types.GenerateContentConfig(tools=[computer_use_tool]),
)
# Parse and execute
for part in response.candidates[0].content.parts:
    if part.function_call:
        fc = part.function_call
pixel_x = int(fc.args["x"] / 1000 * SCREEN_WIDTH)
pixel_y = int(fc.args["y"] / 1000 * SCREEN_HEIGHT)
page.mouse.click(pixel_x, pixel_y)

Running It

cd 02-single-action
python single_action.py

Expected Output

✓ Gemini client initialised

================================================================
  Step 1 → Launch browser
  Navigating to https://www.wikipedia.org
================================================================

  → Page loaded : Wikipedia
  → Current URL : https://www.wikipedia.org/
  → Viewport : 1280×800

================================================================
  Step 2 → Capture screenshot
  Grabbing the Wikipedia portal page
================================================================

  → Screenshot size : 124.7 KB
  → Saved to : /Users/romin/computer-use-tutorial/02-single-action/01_before_click.png

================================================================
  Step 3 → Ask Gemini to click
  Sending screenshot + instruction with Computer Use tool
================================================================

  → Response received from Gemini

================================================================
  Step 4 → Parse response
  Extracting the function call from the model
================================================================

  Function call received:
    Name : click
    x : 396
    intent: Click on the English Wikipedia link to navigate to the English Wikipedia.
    y : 182

================================================================
  Step 5 → Execute click
  Converting coordinates and clicking
================================================================

  Coordinate conversion:
    Normalised : (396, 182) [0-999 space]
    Pixel : (506, 145) [1280×800 viewport]

  → Click executed at pixel (506, 145)
  → Page navigated to: https://www.wikipedia.org/

================================================================
  Step 6 → Verify result
  Taking a post-click screenshot
================================================================

  → Screenshot size : 315.8 KB
  → Saved to : /Users/romin/computer-use-tutorial/02-single-action/02_after_click.png
  → Current URL : https://en.wikipedia.org/wiki/Main_Page
  → Page title : Wikipedia, the free encyclopedia

  ✅ SUCCESS — Navigated to English Wikipedia!

────────────────────────────────────────────────────────────────
Cleaning up browser resources...
✓ Done — screenshots saved to 01_before_click.png & 02_after_click.png

Step 3 : Building a Full Browser Agent 03-browser-agent/

This is the big leap where we are going from a single action to a fully autonomous agent. You’ll build a complete browser agent that can accept any task (“find the top 3 stories on Hacker News”), take screenshots, send them to the model, execute the returned actions, capture new screenshots, and loop until the task is done. Along the way, you’ll tackle the real-world challenges: managing a growing conversation history, pruning old screenshots to stay within context limits, handling safety decisions, and recovering from transient API errors with exponential backoff.

Key Concept: This is the big step, going from a single action to a fully autonomous agent.

Critical Pattern: Screenshot Pruning

def _prune_old_screenshots(self) -> None:
    screenshots_seen = 0
    for content in reversed(self._history):
        if content.role != "user" or not content.parts:
            continue
        has_screenshot = any(
            p.function_response and p.function_response.parts
            for p in content.parts
        )
        if has_screenshot:
            screenshots_seen += 1
            if screenshots_seen > self.MAX_SCREENSHOTS_IN_HISTORY:
                for part in content.parts:
                    if part.function_response and part.function_response.parts:
                        part.function_response.parts = None

Critical Pattern: FunctionResponse Construction

FunctionResponse(
    name=fc.name,
    response={"url": current_url},
    parts=[
        types.FunctionResponsePart(
            inline_data=types.FunctionResponseBlob(
                mime_type="image/png",
                data=post_action_png,
            ),
        ),
    ],
)

Running It

cd 03-browser-agent
python browser_agent.py --task "Go to https://news.ycombinator.com and tell me the top 3 stories"

Expected Output

╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Gemini Computer Use — Browser Agent │
│ Model: gemini-3.5-flash | Viewport: 1280×800 | Headless: False │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
────────────────────────────────────────────────────────── Browser Agent Starting ──────────────────────────────────────────────────────────
Task: Go to https://news.ycombinator.com and tell me the top 3 stories

Initial screenshot captured.

─────────────────────────────────────────────────────────────── Iteration 1 ────────────────────────────────────────────────────────────────
╭───────────────────────────────────────────────────────────── Model Thinking ─────────────────────────────────────────────────────────────╮
│ Okay, here's my thought process on this task: │
│ │
│ **Accessing and Prioritizing Hacker News Articles** │
│ │
│ Right, so the goal is clear: identify the top three stories currently dominating Hacker News. My immediate instinct is to open the site. │
│ It's second nature at this point – navigate to `https://news.ycombinator.com`. Once I'm there, the real work begins. I'll need to sift │
│ through the current submissions, using my knowledge of the site's ranking algorithm and usual trends, to identify which articles are │
│ garnering the most attention. I'll be looking at score, comment count, and potentially the recency of the posts to figure out what's │
│ currently hot and relevant. The top three are what I'm looking for, and I can be flexible with the ranking methodology. │
│ │
│ │
│ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
  ▶ navigate(intent=Navigate to Hacker News, url=https://news.ycombinator.com)
  → Screenshot captured | URL: https://news.ycombinator.com/

─────────────────────────────────────────────────────────────── Iteration 2 ────────────────────────────────────────────────────────────────
╭───────────────────────────────────────────────────────────── Model Thinking ─────────────────────────────────────────────────────────────╮
│ Okay, here's my take on those Hacker News headlines, as I see them: │
│ │
│ **Hacker News Digest - A Quick Glance** │
│ │
│ Alright, let's process these top stories on Hacker News. First up, the Patadia article on LLM costs – always a crucial point for │
│ long-term viability, and something I've been tracking myself. The core of this research is likely to be a deep dive into the │
│ computational inefficiencies, scaling issues, and the sheer energy consumption that underpins current models. I'm especially keen to see │
│ what specific cost-saving strategies the author proposes, and whether they involve architectural improvements, hardware optimization, or │
│ more fundamental algorithmic innovations. That's definitely one to bookmark and dig into. │
│ │
│ Then, a somber note: Om Malik has passed. A prominent voice in the tech sphere is gone. Always a difficult thing to grapple with when a │
│ familiar and respected figure leaves the scene. My thoughts are with his friends and family. A pause for reflection is definitely │
│ warranted. │
│ │
│ Finally, the Herculaneum scroll! This is truly fascinating. Reading an entire scroll from Herculaneum is a significant breakthrough. I'm │
│ guessing the team has leveraged advanced imaging techniques like X-ray tomography and computational tools for deciphering fragmented │
│ texts. What surprises me is this is a first. I'll need to research what the issues have been in deciphering this, if the material has │
│ been too degraded for even cutting-edge processing, or if this new tech is truly groundbreaking. The content itself will undoubtedly │
│ offer invaluable insights into ancient history, philosophy, and everyday life. A promising development. │
│ │
│ │
│ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

────────────────────────────────────────────────────────────── Task Complete ───────────────────────────────────────────────────────────────

Agent Summary: The top 3 stories on Hacker News are:

1. **Why current LLM costs are not sustainable** (patadia.org)
2. **Om Malik has died** (om.co)
3. **An entire Herculaneum scroll has been read for the first time** (scrollprize.org)

─────────────────────────────────────────────────────────────── Final Result ───────────────────────────────────────────────────────────────

The top 3 stories on Hacker News are:

1. **Why current LLM costs are not sustainable** (patadia.org)
2. **Om Malik has died** (om.co)
3. **An entire Herculaneum scroll has been read for the first time** (scrollprize.org)

Architecture: browser_agent.py (AI loop) + playwright_env.py (browser abstraction).

Step 4 : Android Mobile Agent 04-mobile-agent/

We swap the browser for a phone. In this step, you’ll connect to an Android emulator via ADB, capture screenshots of the device screen, and let Gemini drive it with touch gestures : taps, swipes, and long-presses. This step also introduces the Interactions API, a stateful alternative to generateContent where the server manages conversation history for you. Instead of sending the full history every turn, you just chain calls with previous_interaction_id , thereby making the code simpler.

Interactions API vs generateContent

ADB Bridge Pattern

def click(self, y: int, x: int, **_) -> None:
    px, py = self._denormalize(x, y)
    self._execute(["shell", "input", "tap", str(px), str(py)])

Running It

# Start emulator first (see Android Setup above)
cd 04-mobile-agent
python mobile_agent.py "Open Settings and check the Android version"

Expected Output

╔══════════════════════════════════════════════════════════╗
║ Gemini Computer Use — Android Mobile Agent ║
║ Model: gemini-3.5-flash | API: Interactions ║
╚══════════════════════════════════════════════════════════╝
Turn 1/50
  🔧 Action: open_app({'package_name': 'com.android.settings'})
  ✓ Result: {'status': 'ok'}
  ... (4-6 turns: scrolls, clicks About Phone, reads version) ...
✅ Agent completed the task!
   Model response: The Android version is 16.

Step 5 : Enterprise Platform 05-enterprise-platform/

Everything you’ve built so far works with a free Gemini API key. But when you’re ready for production i.e. IAM authentication, VPC isolation, audit logging, and managed browser sandboxes, you can move to Vertex AI. The best part? The agent code is virtually identical. You change one line to switch from API-key auth to IAM, and optionally connect to a cloud-hosted sandbox browser instead of launching a local one. This step walks through both approaches.

The One-Line Migration

Your agent code — the agentic loop, the action dispatch, the screenshot pruning — is 100% identical between Gemini API and Vertex AI. The only change:

CDP Sandbox Connection

# Local browser (Steps 1-3):
browser = pw.chromium.launch(headless=True)
# Managed sandbox (Step 5):
browser = pw.chromium.connect_over_cdp(cdp_endpoint)

Running It

cd 05-enterprise-platform
# Approach 1: Self-managed browser (your local Playwright)
python enterprise_agent.py --approach self-managed --project YOUR_PROJECT_ID
# Approach 2: Managed sandbox (cloud-hosted browser)
python enterprise_agent.py --approach managed-sandbox --project YOUR_PROJECT_ID

💡 Tip : Replace YOUR_PROJECT_ID with your actual Google Cloud project ID. You can also set it in .env as GCP_PROJECT_ID=my-company-prod-123.

Part 5: Real-World Use Cases

Each use case in 06-use-cases/ is a complete, self-contained script demonstrating a practical application.

Use Case 1: QA Testing (TodoMVC)

Scenario : Run end-to-end QA tests on a React web app without writing fragile selectors. The agent sees the app and tests it the way a human QA tester would.

Architecture: generateContent API with a full agentic loop + custom report_qa_result function (multi-tool composition).

The Prompt

Navigate to https://todomvc.com/examples/react/dist/ and perform QA testing:
1. Add three todos: 'Buy groceries', 'Read a book', 'Write code'
2. Mark 'Read a book' as complete
3. Verify items are displayed correctly
4. Click the 'Completed' filter
5. Report what you see

Running It

cd 06-use-cases/usecase1_qa_testing
python qa_agent.py

Step-by-Step Walkthrough

Agent navigates to TodoMVC React app
Clicks “What needs to be done?” input and types “Buy groceries” + Enter
Repeats for “Read a book” and “Write code”
Clicks the circle next to “Read a book” to mark it complete
Verifies all three items are visible with correct state
Clicks the “Completed” filter
Confirms only “Read a book” appears with strikethrough
Returns a structured test report

Expected Results

╔══════════════════════════════════════════════════════════════╗
║ Use Case 1: Automated QA Testing Agent — TodoMVC ║
╚══════════════════════════════════════════════════════════════╝

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Step 1 → Validate environment
  Checking GEMINI_API_KEY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ API key found

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Step 2 → Launch browser
  Opening https://todomvc.com/examples/react/dist/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ Browser launched — viewport (1440, 900)
  ✓ Page loaded: https://todomvc.com/examples/react/dist/
  ✓ Initial screenshot: 87 KB

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Step 3 → Initialise QA agent
  Setting up Gemini Computer Use loop
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ Agent ready — initial screenshot attached to prompt

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Step 4 → Run QA test plan
  Agent is now autonomously executing tests…
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

────────────────────────────────────────────────────────────────
  🤖 Agent Turn 1
────────────────────────────────────────────────────────────────
Tools at indices [1] are not compatible with automatic function calling (AFC). AFC is disabled. If AFC is intended, please include python callables in the tool list, and do not include function declaration and MCP server in the tool list.
  💭 Reasoning: **QA Test Plan: TodoMVC React Application - Add Todo Items**

Okay, let's get down to brass tacks. I need to run a QA test plan on this TodoMVC React application. The first test is pretty straightforw…
  ▶ Action: click(x=603, y=180, intent=Click the todo input field to focus it.)
     📸 Screenshot captured (87 KB) — URL: https://todomvc.com/examples/react/dist/

────────────────────────────────────────────────────────────────
  🤖 Agent Turn 2
────────────────────────────────────────────────────────────────
Tools at indices [1] are not compatible with automatic function calling (AFC). AFC is disabled. If AFC is intended, please include python callables in the tool list, and do not include function declaration and MCP server in the tool list.
  💭 Reasoning: Here's my attempt at summarizing the thought process, tailored for an expert audience:

**Initiating Task Execution**

Okay, so the prompt is straightforward. It's an instruction set. It's not asking …
  ▶ Action: type(intent=Type 'Buy groceries' and press Enter., press_enter=True, text=Buy groceries)
     📸 Screenshot captured (94 KB) — URL: https://todomvc.com/examples/react/dist/

────────────────────────────────────────────────────────────────
  🤖 Agent Turn 3
────────────────────────────────────────────────────────────────
Tools at indices [1] are not compatible with automatic function calling (AFC). AFC is disabled. If AFC is intended, please include python callables in the tool list, and do not include function declaration and MCP server in the tool list.
  💭 Reasoning: Here's my attempt at summarizing the thought process, tailored for an expert audience:

**Initiating a Simple Instruction**

Okay, so the prompt is incredibly straightforward, almost rudimentary. It's…
  ▶ Action: type(text=Read a book, intent=Type 'Read a book' and press Enter., press_enter=True)
     📸 Screenshot captured (98 KB) — URL: https://todomvc.com/examples/react/dist/

────────────────────────────────────────────────────────────────
  🤖 Agent Turn 4
────────────────────────────────────────────────────────────────
Tools at indices [1] are not compatible with automatic function calling (AFC). AFC is disabled. If AFC is intended, please include python callables in the tool list, and do not include function declaration and MCP server in the tool list.
  💭 Reasoning: Here's my attempt at summarizing the thought process, tailored for an expert audience:

**Initiating the Inquiry into Gemini's Capabilities**

Okay, so the prompt directs me to explore the "Learn Gemi…
  ▶ Action: type(intent=Type 'Learn Gemini Computer Use' and press Enter., text=Learn Gemini Computer Use, press_enter=True)
     📸 Screenshot captured (103 KB) — URL: https://todomvc.com/examples/react/dist/

────────────────────────────────────────────────────────────────
  🤖 Agent Turn 5
────────────────────────────────────────────────────────────────
Tools at indices [1] are not compatible with automatic function calling (AFC). AFC is disabled. If AFC is intended, please include python callables in the tool list, and do not include function declaration and MCP server in the tool list.
  💭 Reasoning: Okay, here's my understanding, formatted as requested:

**Assessing Task Completion**

Right, let's just make absolutely sure we've got a handle on this. The task asks me to verify the presence of thr…
  ▶ Action: report_qa_result(test_name=Add Todo Items, details=Successfully added 'Buy groceries', 'Read a book', and 'Learn Gemini Computer Use' to the todo list., passed=True)

  📋 QA Result: Add Todo Items → [PASS ✅]
     Details : Successfully added 'Buy groceries', 'Read a book', and 'Learn Gemini Computer Use' to the todo list.

────────────────────────────────────────────────────────────────
  🤖 Agent Turn 6
────────────────────────────────────────────────────────────────
Tools at indices [1] are not compatible with automatic function calling (AFC). AFC is disabled. If AFC is intended, please include python callables in the tool list, and do not include function declaration and MCP server in the tool list.
  💭 Reasoning: **Marking an Item as Complete**

Okay, so the next test is to mark an item as complete. Specifically, I need to find the "Read a book" task and visually confirm that it's marked as done after I intera…
  ▶ Action: click(y=316, intent=Click the toggle checkbox next to 'Read a book'., x=429)
     📸 Screenshot captured (105 KB) — URL: https://todomvc.com/examples/react/dist/

────────────────────────────────────────────────────────────────
  🤖 Agent Turn 7
────────────────────────────────────────────────────────────────
Tools at indices [1] are not compatible with automatic function calling (AFC). AFC is disabled. If AFC is intended, please include python callables in the tool list, and do not include function declaration and MCP server in the tool list.
  💭 Reasoning: Okay, here's my interpretation of that thought process, assuming I'm an expert in this particular task:

**Test Result Reporting - Iteration Complete**

Alright, that's done. I see "Read a book" is cr…
  ▶ Action: report_qa_result(test_name=Mark Complete, passed=True, details=Successfully marked 'Read a book' as completed, showing a strikethrough style and checked state.)

  📋 QA Result: Mark Complete → [PASS ✅]
     Details : Successfully marked 'Read a book' as completed, showing a strikethrough style and checked state.

────────────────────────────────────────────────────────────────
  🤖 Agent Turn 8
────────────────────────────────────────────────────────────────
Tools at indices [1] are not compatible with automatic function calling (AFC). AFC is disabled. If AFC is intended, please include python callables in the tool list, and do not include function declaration and MCP server in the tool list.
  💭 Reasoning: **Executing the "Filter Completed" Test**

Okay, test three is up. We're verifying the "Completed" filter function. Let's start by identifying and clicking the "Completed" filter link at the bottom of…
  ▶ Action: click(intent=Click the 'Completed' filter link., y=438, x=637)
     📸 Screenshot captured (96 KB) — URL: https://todomvc.com/examples/react/dist/#/completed

────────────────────────────────────────────────────────────────
  🤖 Agent Turn 9
────────────────────────────────────────────────────────────────
Tools at indices [1] are not compatible with automatic function calling (AFC). AFC is disabled. If AFC is intended, please include python callables in the tool list, and do not include function declaration and MCP server in the tool list.
  💭 Reasoning: Okay, here's my take on those thoughts, framed as my own reasoning:

**Test Result Verification and Reporting**

Alright, let's just make absolutely sure we're on the right track here. First, I need t…
  ▶ Action: report_qa_result(details=Successfully filtered by 'Completed' and verified that only 'Read a book' is visible in the list., test_name=Filter Completed, passed=True)

  📋 QA Result: Filter Completed → [PASS ✅]
     Details : Successfully filtered by 'Completed' and verified that only 'Read a book' is visible in the list.

────────────────────────────────────────────────────────────────
  🤖 Agent Turn 10
────────────────────────────────────────────────────────────────
Tools at indices [1] are not compatible with automatic function calling (AFC). AFC is disabled. If AFC is intended, please include python callables in the tool list, and do not include function declaration and MCP server in the tool list.

  ✅ Agent finished.
  Final reasoning: Here's your summary:

**QA Session Complete**

Okay, that's it. All three tests have been successfully run and are now complete. Time to formally declare the QA session as finished. I've confirmed all the data, reviewed the results, and I'm satisfied that we can move forward. No outstanding issues or anomalies were discovered. Let's get the final report generated and distributed.

 The QA session is complete. All three tests passed successfully:
1. **Add Todo Items** : Successfully added "Buy gr…

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Step 5 → QA Report
  Printing final test results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

================================================
           QA TEST REPORT
================================================
  Test: Add Todo Items [PASS] ✅
  Test: Mark Complete [PASS] ✅
  Test: Filter Completed [PASS] ✅
================================================
  Overall: 3/3 PASSED
================================================

✓ Browser closed. QA session complete.

Key Takeaway: Computer Use can replace hundreds of lines of Selenium/Cypress test code with a single natural-language task description.

Use Case 2: Price Comparison

Scenario: Compare product prices across the web. The agent searches Google Shopping, extracts prices, and saves them through a custom function, demonstrating multi-tool composition.

Architecture: Computer Use (for browsing) + custom save_product() function in the same conversation.

The Prompt

You are a price comparison agent. Your job is to search for products and
extract pricing information.

## Instructions

1. You are on Amazon.com. In the search box, type "wireless noise
   cancelling headphones" and press Enter to search.

2. Wait for results to load. You should see product listings with names
   and prices.

3. Look at the search results. For each of the top 3-5 products you can
   see, call the `save_product` function with:
   - name: the product name (e.g. "Sony WH-1000XM5")
   - price: the displayed price (e.g. "$278.00")
   - source: "Amazon"

4. If you need to scroll down to see more products, do so.

5. Try to find at least 3 products with visible prices. Save each one
   using `save_product`.

6. After saving 3-5 products, state that the comparison is complete.

IMPORTANT: Call `save_product` once for each product you identify.
Do NOT try to save all products in one call.

Running It

cd 06-use-cases/usecase2_price_comparison
python price_agent.py

Expected Results


.... Agent Turn(s) ...
    🔍 PRICE COMPARISON RESULTS                                
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ Product ┃ Price ┃ Source ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ Soundcore by Anker Q20i Hybrid Active Noise │ INR 3,774.86 │ Amazon │
│ Cancelling Headphones, Wireless Over-Ear │ │ │
│ Bluetooth, 40H Long ANC Playtime, Hi-Res Audio, │ │ │
│ Big Bass, Customize via an App, Transparency Mode │ │ │
│ (Black) │ │ │
├────────────────────────────────────────────────────┼───────────────┼────────────────────┤
│ Sony WH-CH720N Noise Canceling Wireless Headphones │ INR 7,084.34 │ Amazon │
│ Bluetooth Over The Ear Headset with Microphone and │ │ │
│ Alexa Built-in, Black New │ │ │
├────────────────────────────────────────────────────┼───────────────┼────────────────────┤
│ Bose QuietComfort Headphones - Wireless Bluetooth │ INR 16,896.70 │ Amazon │
│ Headphones, Active Over Ear Noise Cancelling and │ │ │
│ Mic, USB-C Charging, Deep Bass, Up to 24 Hours of │ │ │
│ Playtime, Twilight Blue - Limited Edition... │ │ │
├────────────────────────────────────────────────────┼───────────────┼────────────────────┤
│ Bose QuietComfort Headphones - Wireless Bluetooth │ INR 16,896.70 │ Amazon │
│ Headphones, Active Over Ear Noise Cancelling and │ │ │
│ Mic, USB-C Charging, Deep Bass, Up to 24 Hours of │ │ │
│ Playtime, Black │ │ │
└────────────────────────────────────────────────────┴───────────────┴────────────────────┘

  📊 Total products found: 4

Key Takeaway: Multi-tool composition is the solid feature. The model seamlessly switches between “driving the browser” and “calling your business logic functions.”

Use Case 3: Mobile App Testing

Scenario : Verify that an Android app’s Settings screen works — toggle dark mode, check About Phone, verify system info.

Architecture : Uses the Interactions API with ENVIRONMENT_MOBILE.

Prompt

You are an automated QA agent testing an Android device.

Your current test plan:
1. Open the Android Settings app (package: com.android.settings).
2. Navigate to "Display" settings.
3. Check whether Dark theme / Dark mode is currently ON or OFF.
4. Toggle Dark mode (turn it ON if it is OFF, or OFF if it is ON).
5. Press Back to return to the main Settings screen.
6. Navigate to "About phone" (scroll down if needed).
7. Read the Android version string shown on that page.
8. Report a test summary with: dark mode before, dark mode after, Android version.

Rules:
* Use the tools provided. Scroll down before assuming an item is missing.
* When the task is complete, output a **Test Summary** with all findings.
* Do NOT use the on-screen keyboard — use the `type` tool instead.

Running It

cd 06-use-cases/usecase3_mobile_testing
python app_test_agent.py

⚠️ Prerequisite : You need a running Android emulator. See the Android Setup section above.

Key Takeaway: The Interactions API handles state management server-side, making mobile agents significantly simpler to build.

Use Case 4: Web Research & Report

Scenario: Research a topic across multiple websites and produce a structured Markdown report using dual custom functions (save_finding + generate_report).

Prompt

You are a web research assistant. Your job:

1. The browser is open to DuckDuckGo. Search for: "{search_query}"
2. Browse the first 2-3 search result pages.
3. On each page, extract **key findings** and call the ``save_finding`` tool
   for each distinct insight (with a descriptive title, the page URL, the
   key point, and a category like "hardware", "algorithm", "partnership",
   "investment", or "breakthrough").
4. After collecting findings from 2-3 pages, call ``generate_report`` to
   signal you are done.
5. Finally, output a brief natural-language summary.

Rules:
* You MUST call ``save_finding`` at least once per page visited.
* Call ``generate_report`` exactly once when finished.
* Navigate with clicks and scrolls — read the page content on screen.
* If a page fails to load, use the browser back button and try the next result.

Running It

cd 06-use-cases/usecase4_web_research
python research_agent.py
# Or with a custom topic:
python research_agent.py --search "AI safety regulations 2026"

Expected Results

A research_report.md file saved to disk with structured findings, source URLs, and a summary.

✓ Report saved to: /Users/romin/computer-use-tutorial/06-use-cases/usecase4_web_research/report_AI_safety_regulations_2026_2026-06-26_152011.md

                                                               Collected Findings (7)                                                               
╭─────┬──────────────────────────────────────────────────────────────┬─────────────┬───────────────────────────────────────────────────────────────╮
│ # │ Title │ Category │ Source │
├─────┼──────────────────────────────────────────────────────────────┼─────────────┼───────────────────────────────────────────────────────────────┤
│ 1 │ EU AI Act High-Risk AI System Compliance and Penalties │ algorithm │ https://is4.ai/blog/our-blog-1/ai-safety-legislation-2026-gl… │
├─────┼──────────────────────────────────────────────────────────────┼─────────────┼───────────────────────────────────────────────────────────────┤
│ 2 │ California SB 1047 Large-Scale AI Model Safety Protocols │ algorithm │ https://is4.ai/blog/our-blog-1/ai-safety-legislation-2026-gl… │
├─────┼──────────────────────────────────────────────────────────────┼─────────────┼───────────────────────────────────────────────────────────────┤
│ 3 │ China Generative AI Content and Alignment Regulations │ algorithm │ https://is4.ai/blog/our-blog-1/ai-safety-legislation-2026-gl… │
├─────┼──────────────────────────────────────────────────────────────┼─────────────┼───────────────────────────────────────────────────────────────┤
│ 4 │ NIST Launches Autonomous AI Agent Standards Initiative │ algorithm │ https://www.hungyichen.com/en/insights/ai-governance-regulat… │
├─────┼──────────────────────────────────────────────────────────────┼─────────────┼───────────────────────────────────────────────────────────────┤
│ 5 │ Singapore IMDA Model AI Governance Framework for Agentic AI │ algorithm │ https://www.hungyichen.com/en/insights/ai-governance-regulat… │
├─────┼──────────────────────────────────────────────────────────────┼─────────────┼───────────────────────────────────────────────────────────────┤
│ 6 │ US Federal AI Litigation Task Force Challenges State AI Laws │ algorithm │ https://www.gunder.com/en/news-insights/insights/2026-ai-law… │
├─────┼──────────────────────────────────────────────────────────────┼─────────────┼───────────────────────────────────────────────────────────────┤
│ 7 │ US Restricts BEAD Funding for States with Onerous AI Laws │ partnership │ https://www.gunder.com/en/news-insights/insights/2026-ai-law… │
╰─────┴──────────────────────────────────────────────────────────────┴─────────────┴───────────────────────────────────────────────────────────────╯

✓ Done — report at: /Users/romin/computer-use-tutorial/06-use-cases/usecase4_web_research/report_AI_safety_regulations_2026_2026-06-26_152011.md

Key Takeaway: Computer Use + custom functions turns Gemini into a research agent that can navigate the open web and produce structured, citable output.

Use Case 5: Form Filling

Scenario : Fill out a complex HTML form with text inputs, radio buttons, checkboxes, dropdowns, and text areas. A classic RPA task.

The Prompt

Fill out the local practice registration form with:
- Name: Jane Smith
- Email: jane.smith@example.com
- Gender: Female
- Mobile: 555-0123
- Subject: Computer Science
- Hobby: Reading
- Address: 123 AI Street, Tech City, CA 90210
- State: California, City: San Francisco

Then submit the form and verify the confirmation.

Running It

cd 06-use-cases/usecase5_form_filling
python form_agent.py

The form getting filled in real-time:

Expected Results

╭───────────────────────────────────────────────────────────────────────────────────── Agent Report ──────────────────────────────────────────────────────────────────────────────────────╮
│ Okay, here's my take on those thoughts, tailored for an expert's perspective: │
│ │
│ **Registration Confirmation and Report Preparation** │
│ │
│ Alright, the registration's gone through. Got the confirmation message – "Registration Submitted Successfully!" – so that's a good starting point. Now, let's nail down what needs to │
│ be in this final report. I need to clearly articulate what specific fields were populated correctly, essentially a field-by-field breakdown to demonstrate data integrity. Of course, │
│ the form submission success is key, and I’ll confirm that the confirmation message, the visual indicator of a successful transaction, was present. Time to outline this response. │
│ │
│ │
│ I have successfully completed the form-filling task! │
│ │
│ ### 1. Fields Successfully Filled: │
│ * **First Name** : Jane │
│ * **Last Name** : Smith │
│ * **Email** : jane.smith@example.com │
│ * **Gender** : Female │
│ * **Mobile** : 555-0123 │
│ * **Date of Birth** : 1995-06-15 │
│ * **Subject** : Computer Science │
│ * **Hobbies** : Reading │
│ * **Current Address** : 123 AI Street, Tech City, CA 90210 │
│ * **State** : California │
│ * **City** : San Francisco │
│ │
│ ### 2. Submission Status: │
│ * **Successfully Submitted** : Yes, the form was submitted successfully, and the green confirmation box with **"Registration Submitted Successfully!"** appeared on the screen, │
│ displaying all the correct values. │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✓ Browser closed
                                                                                   Form Filling Summary                                                                                    

  Metric Value                                                                                                                                                                      
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 
  Target URL file:///Users/romin/computer-use-tutorial/06-use-cases/usecase5_form_filling/practice_form.html                                                                            

  Total turns 39                                                                                                                                                                         

  Model gemini-3.5-flash                                                                                                                                                           

  API generateContent (browser)                                                                                                                                                  

  Data filled First Name: Jane, Last Name: Smith, Email: jane.smith@example.com, Gender: Female, Mobile: 555-0123, Subject: Computer Science, Hobbies: Reading, Address: 123 AI Street,  
                Tech City, CA 90210, State: California, City: San Francisco

✓ Form filling complete.

Key Takeaway: Computer Use handles diverse HTML controls (radio buttons, checkboxes, dropdowns) that would each require different selector strategies in traditional automation. The model just sees the form and fills it in.

Summary

Gemini Computer Use represents a fundamental shift in how we automate software i.e. from brittle, selector-based scripts to AI agents that see and interact with screens just like humans do. In this tutorial, you went from sending a single screenshot to building autonomous agents that control browsers, drive Android devices, and scale to enterprise with Vertex AI — all powered by the same model and the same Brain → Eyes → Hands architecture.

The five use cases showed that this isn't a toy demo: QA testing, price comparison, mobile automation, web research, and form filling are real workflows being automated today.

The code is open, the patterns are reusable, and with gemini-3.5-flash, you're one API call away from giving your next application the ability to operate any screen. Go for it.

[Boost]

Romin Irani — Fri, 12 Jun 2026 14:40:25 +0000

Aryan Irani for Google Developer Experts

Jun 12

Connecting GCP Budget Alerts to AppSheet: A Step-by-Step Guide

#googlecloud #appsheet #finops #cloudbilling

7 min read

Antigravity Managed Agents Tutorial: Ship Production AI Agents

Romin Irani — Tue, 09 Jun 2026 12:16:25 +0000

If you’ve tried building AI applications, you often face a familiar engineering wall.

It goes like this: You ask a Large Language Model to help you launch a website. It replies with beautiful code. But then what? The AI can’t actually open a text editor, save the file, or click “Run” to see if it works. You need to do all the heavy lifting.

You might say that you use one of the AI Agents that does a lot more including starting up the server, doing a few tests, etc. Of course they do but in case you had to do that, there are multiple things to consider:

Ensure that you do have a sandbox so the AI can run code safely without accidentally wiping your files.
Stitch together some logic of passing data back and forth across modules.
You need to configure tools, so that the AI can invoke those tools, talk to your data and/or even run a script.

There’s a lot more to think of and it all points towards more operational and management overheard to keep things running safely.

Here’s what this looks like in practice. Say you want an AI to write and test a Python script:

from google import genai
import subprocess

client = genai.Client()

# Step 1: Ask the model for code
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Write a Python script that checks password strength and saves a report."
)

# Step 2: YOU must manually extract the code block from the text response
code = extract_code_from_markdown(response.text) # You wrote this function

# Step 3: YOU must save the file and run it locally
with open("password_checker.py", "w") as f:
    f.write(code)

# ⚠️ Danger: Running untrusted AI-generated code on YOUR machine!
result = subprocess.run(["python3", "password_checker.py"], capture_output=True, text=True)
print(result.stdout)

You’re doing all the work. The extraction. The file I/O. The risky local execution. The error loop when it inevitably fails.

What if you could replace all of this with a single API call?

What Are Managed Agents?

Google’s Managed Agents framework, featuring the flagship Antigravity agent, looks to help you overcome the engineering wall, that we just mentioned.

Think of it as Agent-as-a-Service. Instead of just giving you a text-based chatbot, Google instantly hands your AI its own secure, fully managed cloud computer (a Linux workspace) with the keys to the live internet.

Generated by NotebookLM for this article.

The Three Levels of AI Systems

Let’s look at the following table that highlights the three levels of AI Systems:

The Core Agentic Loop

When you give an Antigravity Agent a task, it doesn’t just guess an answer. It operates inside a continuous, hardware-backed loop:

┌────────────────────────────────────────┐
│ 1. PLAN & REASON │
│ (Analyzes objective & breaks it down) │
└───────────────────┬────────────────────┘
                    │
                    ▼
┌────────────────────────────────────────┐
│ 2. ACT │
│ (Executes a tool: Bash, Python, Web) │
└───────────────────┬────────────────────┘
                    │
                    ▼
┌────────────────────────────────────────┐
│ 3. OBSERVE │
│ (Reads execution output, errors, data) │
└───────────────────┬────────────────────┘
                    │
                    └─── Loop back until task is complete

This isn’t a one-shot prompt/response. The agent iterates. It writes a script, runs it, reads a SyntaxError from the terminal, fixes the bug, re-runs, and keeps going until the task is done.

The Remote Sandbox

Every time you invoke an Antigravity Agent, Google boots up a dedicated workspace:

What you get is a real Linux computer in the cloud that your agent owns for the duration of its task.

Architecture Deep Dive: How It All Works

When working with Managed Agents, you interact with two separate planes via the Gemini API:

                  ┌─────────────────────────────────┐
                  │ YOUR APP │
                  └────────┬───────────────┬────────┘
                           │ │
      1. Define/Configure │ │ 2. Run Task
      (System rules, ID) │ │ (Send Prompt)
                           ▼ ▼
 ┌───────────────────────────────────┐ ┌───────────────────────────────────┐
 │ THE CONTROL PLANE │ │ THE RUNTIME PLANE │
 │ (Agents API) │ │ (Interactions API) │
 ├───────────────────────────────────┤ ├───────────────────────────────────┤
 │ Saves persistent identity, system │ │ Spawns the Ubuntu sandbox, logs │
 │ instructions, and data mounts. │ │ live traces, and processes loops. │
 └───────────────────────────────────┘ └───────────────────────────────────┘

The Control Plane (Agents API) is where you configure and register your agent. Think of it as creating an employee profile i.e. you define its name, system instructions, custom skills, and code repositories to clone. It gives you back a static Agent ID.

The Runtime Plane (Interactions API) is where actual work happens. You send a task to your Agent ID via an “Interaction.” This plane handles sandbox provisioning, tool execution, reasoning traces, and the agentic loop.

Security: The Egress Proxy

Allowing an autonomous agent to run unverified scripts is a security risk. Google isolates the environment using an Egress Proxy Layer :

 ┌─────────────────────────┐
 │ REMOTE UBUNTU SANDBOX │
 │ (No internal secrets) │
 └───────────┬─────────────┘
             │ Agent attempts outbound API call
             ▼
 ┌─────────────────────────┐
 │ EGRESS PROXY LAYER │ ◄── Checks Domain Allowlist
 ├─────────────────────────┤
 │ Intercepts connection, │
 │ injects secrets securely│
 └───────────┬─────────────┘
             │ Safe, Authenticated Request Sent
             ▼
    [External Target API]

Three key guarantees:

Zero Secrets Inside the Sandbox. You never save API keys or database passwords in the agent’s Linux workspace.
Domain Allowlists. You explicitly define which external domains the agent can contact.
Header Transformations. When the agent needs to call an external API, the Egress Proxy intercepts the request, confirms the domain is allowed, and injects the authentication token automatically. The agent gets the data, but never sees your private key.

Getting Started: Your First Agent in 5 Minutes

Let’s create our First Agent using the Managed Agents framework.

Prerequisites

Before writing any code, make sure your environment meets these requirements:

Python: 3.10+. 3.12 recommended (matches sandbox runtime)
google-genai SDK >=2.0.0. The latest at the time of writing is 2.8.0.
API Key —Free tier available at aistudio.google.com/apikey.
OS : Any (macOS, Linux, Windows, or WSL). Your code runs locally, the agent runs in Google’s cloud.

python3 -m venv managed-agents-env
source managed-agents-env/bin/activate # On Windows: managed-agents-env\Scripts\activate
# Install (or upgrade) the Google GenAI SDK
pip install -U google-genai
# Verify the version — must be 1.14.0 or later
python3 -c "import google.genai; print(google.genai. __version__ )"
# Set your API key (get one at https://aistudio.google.com/apikey)
export GEMINI_API_KEY="your-api-key-here"

No local setup needed? You can also try Managed Agents directly in Google AI Studio without writing any code. Look for the “Managed Agents” template section. Iit gives you an interactive playground to test agent interactions in your browser.

Running the Examples

Every code block in this tutorial is a complete, self-contained Python script. To run any example:

# 1. Save the code to a file (an example name used here is hello_agent.py
vim hello_agent.py # or use any editor

# 2. Run it
python3 hello_agent.py

How long does it take? Each interaction takes 30 seconds to 3 minutes depending on task complexity. The agent is doing real work — booting a sandbox, writing code, executing it, reading errors, and iterating. Simple tasks finish in under a minute; complex multi-turn chains may take 2–3 minutes per turn.

Your First Interaction: Hello Managed Agents

Remember that painful multi-step code from earlier? Here’s the Antigravity Managed Agents equivalent:

from google import genai

client = genai.Client()

# One API call. One autonomous agent. One remote Linux sandbox.
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script that generates 100 random exam scores between 0 and 100, "
          "calculates the mean, median, and standard deviation, prints a summary, "
          "and saves a grade distribution histogram as grade_report.png using matplotlib.",
    environment="remote" # This provisions a secure Linux sandbox hosted by Google
)

print(interaction.output_text)

Run it:

python3 hello_agent.py

Expected output

For the first interaction, it produced the following output (your numbers will vary since the data is random):

I have successfully written and executed a Python script that generates 100 random exam scores, computes their key statistics, and plots a grade distribution histogram.

### 1. Generated Python Script (`generate_report.py`)

Here is the Python script, which is saved in the environment as `generate_report.py`. It uses `numpy` for data generation, `statistics` conventions for calculation (such as sample standard deviation), and `matplotlib` to generate a high-quality visualization.

python
import numpy as np
import matplotlib.pyplot as plt
import statistics

def generate_and_analyze_grades():
# Set a random seed for reproducibility
np.random.seed(42)

# Generate 100 random exam scores between 0 and 100 (inclusive)
scores = np.random.randint(0, 101, size=100)

# Calculate statistics using Python's standard statistics module and NumPy
# (Using ddof=1 for sample standard deviation, which is standard for student grade samples)
mean_val = np.mean(scores)
median_val = np.median(scores)
std_val = np.std(scores, ddof=1)

# Print summary to console
print("=========================================")
print(" EXAM GRADE REPORT SUMMARY ")
print("=========================================")
print(f"Number of Students : {len(scores)}")
print(f"Minimum Score : {np.min(scores)}")
print(f"Maximum Score : {np.max(scores)}")
print(f"Mean Score : {mean_val:.2f}")
print(f"Median Score : {median_val:.2f}")
print(f"Standard Deviation : {std_val:.2f}")
print("=========================================")

# Create the histogram plot
plt.figure(figsize=(10, 6))

# Customize the grid and style
plt.grid(axis='y', linestyle='--', alpha=0.7, zorder=0)

# Draw the histogram with bins of size 10 (0-10, 10-20, ..., 90-100)
bins = range(0, 111, 10)
plt.hist(scores, bins=bins, color='#4A90E2', edgecolor='black', rwidth=0.85, zorder=3)

# Add labels and title
plt.title('Distribution of Exam Scores', fontsize=16, fontweight='bold', pad=15)
plt.xlabel('Exam Scores', fontsize=12, labelpad=10)
plt.ylabel('Number of Students', fontsize=12, labelpad=10)

# Mark Mean and Median with vertical lines
plt.axvline(mean_val, color='#D0021B', linestyle='dashed', linewidth=2, zorder=4, label=f'Mean: {mean_val:.2f}')
plt.axvline(median_val, color='#F5A623', linestyle='dotted', linewidth=2, zorder=4, label=f'Median: {median_val:.2f}')

# Set x-ticks to align with bins
plt.xticks(range(0, 101, 10))

# Add a legend
plt.legend(fontsize=11, loc='upper left')

# Add details text box on the plot
textstr = '\n'.join((
    f'Total Students: {len(scores)}',
    f'Mean: {mean_val:.2f}',
    f'Median: {median_val:.2f}',
    f'Std Dev: {std_val:.2f}'
))
props = dict(boxstyle='round', facecolor='wheat', alpha=0.5)
plt.gca().text(0.05, 0.75, textstr, transform=plt.gca().transAxes, fontsize=10,
        verticalalignment='top', bbox=props)

# Adjust layout and save the figure
plt.tight_layout()
output_filename = 'grade_report.png'
plt.savefig(output_filename, dpi=300)
print(f"\nHistogram successfully saved to '{output_filename}'")

if name == ' main':
generate_and_analyze_grades()


---

### 2. Output Statistics Summary

Upon running the script in the sandbox environment, it produced the following output:

text

     EXAM GRADE REPORT SUMMARY

=========================================
Number of Students : 100
Minimum Score : 1
Maximum Score : 100
Mean Score : 51.31
Median Score : 53.50

Standard Deviation : 29.70

Histogram successfully saved to 'grade_report.png'


---

### 3. Generated Histogram Details (`grade_report.png`)

The script successfully outputted `grade_report.png` in high-resolution format (300 DPI) containing:
- **Clean Grid & Styling** : Standard light-gray horizontal grids to easily identify column heights.
- **Grade Bins** : Defined score ranges of size 10 (e.g., 0–10, 10–20, ..., 90–100) using custom spacing to give the columns a professional look.
- **Key Metrics Highlighted** : 
  - A red dashed line representing the **Mean** (`51.31`).
  - A yellow dotted line representing the **Median** (`53.50`).
- **An Info Legend and Box** : In the top-left area summarizing all descriptive statistics for easy offline reference.

### How to Run it Yourself
If you want to run this script in another environment, ensure you have the required packages installed:

bash
pip install matplotlib numpy
python generate_report.py

plaintext

📝 Note: The agent’s response is a natural-language summary, not raw program output. It describes what it did i.e. the code it wrote, the packages it installed, and the results. The actual Python script and chart file exist inside the remote sandbox.

That’s it. 3–4 lines of meaningful code that we can actually understand.

Behind the scenes, the agent:

Booted up an Ubuntu Linux sandbox
Wrote a Python script that generates random data and computes statistics
Auto-installed matplotlib (it wasn't asked to — it just knew it was needed)
Executed the script, rendering a histogram to grade_report.png
Returned a summary with the statistics and a confirmation that the chart was saved

Let’s try something more ambitious — a task that requires multiple tools:

from google import genai
client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="""
    Research the top 5 most popular Python web frameworks in 2026.
    For each framework:
    1. Find the latest version number and release date
    2. Count the GitHub stars
    3. Write a comparison table in Markdown
    """,
    environment="remote"
)

print(interaction.output_text)

plaintext

The agent will use web browsing to search Google, code execution to structure the data, and file management to save the results , all autonomously, all within one API call.

Here is the output:

The landscape of Python web development in **2026** is marked by a fascinating split [1, 2]. On one side, classic **backend-first** and **API-focused** frameworks (Django, FastAPI, Flask) remain the dominant standards for enterprise applications and microservices [3, 5]. On the other side, **pure-Python UI and full-stack** frameworks (Streamlit, Reflex) have seen explosive growth—driven by the need to build interactive web apps, data dashboards, and AI/ML interfaces without writing JavaScript or TypeScript [1, 2].

Below is an in-depth research report on the **top 5 most popular Python web frameworks in 2026** , ranked by GitHub stars and overall developer adoption.

---

### Detailed Breakdown of the Top 5 Python Web Frameworks

#### 1. FastAPI (99,034 GitHub Stars)
* **Latest Version:** `0.136.3` (Released: **May 23, 2026** )
* **Architecture Type:** ASGI (Asynchronous Server Gateway Interface)
* **Primary Focus:** High-Performance APIs and Microservices [4]
* **Core Philosophy:** FastAPI is designed to build APIs quickly with standard Python type hints. It leverages **Pydantic v2** for extremely fast data validation and serialization, and **Starlette** for high-concurrency async handling [3, 4]. It natively auto-generates interactive Swagger UI and ReDoc documentation.
* **Ideal Use Case:** AI/ML model deployment, backend APIs for single-page applications (React/Vue/Svelte), and low-latency microservices [5].

#### 2. Django (87,811 GitHub Stars)
* **Latest Version:** `6.0.6` (Released: **June 3, 2026** )
* **Architecture Type:** WSGI & ASGI (Fully async-supported)
* **Primary Focus:**"Batteries-Included" Monolithic Web Applications [4]
* **Core Philosophy:** As an 18-year industry standard, Django remains the premier full-featured web framework [2]. It handles everything—database routing (via its powerful ORM), administration panels, user authentication, form validation, and robust security defaults (SQLi, CSRF, XSS protection) [1]. In 2026, Django 6.x is highly optimized with full native asynchronous views and type hints [4].
* **Ideal Use Case:** Large-scale enterprise applications, content management systems, e-commerce platforms, and fast SaaS MVP development where you need a complete, secure architecture out of the box [2, 5].

#### 3. Flask (71,638 GitHub Stars)
* **Latest Version:** `3.1.3` (Released: **February 19, 2026** )
* **Architecture Type:** WSGI
* **Primary Focus:** Lightweight, Flexible Microframework [4]
* **Core Philosophy:** Flask provides a minimalist core, leaving the choice of database ORM, form handling, and security components completely up to the developer [1, 2]. Paired with modern 2026 extensions (SQLAlchemy 2.x, Pydantic), it represents a simple, un-opinionated foundation that never gets in the developer's way [3].
* **Ideal Use Case:** Small utility applications, lightweight APIs, microservices, and custom projects where developers want total control over their system design [1, 5].

#### 4. Streamlit (44,895 GitHub Stars)
* **Latest Version:** `1.58.0` (Released: **May 28, 2026** )
* **Architecture Type:** UI-First Scripting Paradigm
* **Primary Focus:** Rapid Data and Machine Learning Applications [1]
* **Core Philosophy:** Streamlit turns standard Python scripts into interactive, beautiful web apps in a matter of minutes. It handles the entire frontend and backend flow by re-running the script from top to bottom whenever a user interacts with a widget.
* **Ideal Use Case:** Quick data dashboards, machine learning model prototypes, and internal analytical tools for teams without frontend resources [1, 2].

#### 5. Reflex (28,467 GitHub Stars)
* **Latest Version:** `0.9.4` (Released: **June 4, 2026** )
* **Architecture Type:** Full-Stack Async React-Compiled
* **Primary Focus:** Interactive, Pure-Python Full-Stack Apps [2]
* **Core Philosophy:** Formerly known as Pynecone, Reflex compiles Python code into a high-performance **React/Next.js frontend** and a **FastAPI backend** , using real-time WebSockets to synchronize states between them [1, 2]. It bypasses JavaScript entirely, offering 60+ pre-built Radix UI components with native Tailwind integration [1, 2].
* **Ideal Use Case:** Complex, interactive web applications, real-time streaming dashboards (e.g., AI chat applications, financial trackers), and user-facing SaaS applications built entirely in Python [2].

---

### Other Honorable Mentions in 2026
While they didn't make the top 5 by GitHub stars, these frameworks are heavily utilized:
* **Tornado** (22,182 stars, v6.5.7, Released June 8, 2026): A mature, asynchronous networking framework ideal for long-lived WebSocket connections [4].
* **Sanic** (18,629 stars, v25.12.1, Released May 31, 2026): An ASGI web framework built for extreme speed and Flask-like simplicity, running on its own high-performance web server.
* **Litestar** (8,269 stars, v2.23.0, Released May 29, 2026): A highly structured, strict, and enterprise-grade ASGI alternative to FastAPI [3, 4].

---

### 2026 Python Web Frameworks Comparison Table

| Framework | GitHub Stars | Latest Version | Release Date | Architecture | Best For | Key Strength | Learning Curve |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **FastAPI** | ~99,034 | `0.136.3` | May 23, 2026 | ASGI (Async) | High-performance API development & AI model deployments [4, 5] | Autogenerated Swagger docs, native Pydantic v2 validation [4] | **Easy / Moderate** |
| **Django** | ~87,811 | `6.0.6` | Jun 03, 2026 | WSGI / ASGI | Enterprise apps, content-heavy websites, secure SQL backends [1, 2] | "Batteries-included" (built-in admin, ORM, security, auth) [1, 2] | **Moderate / Hard** |
| **Flask** | ~71,638 | `3.1.3` | Feb 19, 2026 | WSGI (Sync-first) | Microservices, custom MVPs, lightweight apps [1, 5] | Unrivaled design flexibility, minimal core overhead [1] | **Very Easy** |
| **Streamlit** | ~44,895 | `1.58.0` | May 28, 2026 | Scripted Reactive | Data visualization dashboards & ML interactive tools [1] | Zero frontend experience needed; fast prototyping [1] | **Very Easy** |
| **Reflex** | ~28,467 | `0.9.4` | Jun 04, 2026 | Async React-compiled | Interactive, real-time SaaS & full-stack apps in pure Python [2] | True multi-page routing, state management without JavaScript [2] | **Moderate** |

---

### Guidance: Which Framework Should You Choose in 2026?

1. **Choose FastAPI** if you are building modern REST/GraphQL APIs, backend microservices, or deploying AI/ML models with high concurrency and automatic documentation [3, 5].
2. **Choose Django** if you are building database-driven business platforms or SaaS architectures where user authentication, administrative interfaces, and built-in security are paramount [1, 2].
3. **Choose Flask** if you need to build simple backend services or you want to hand-select every tool in your stack (e.g., combining custom database layers with external identity providers) [1].
4. **Choose Streamlit** if your core team consists of data scientists or business analysts who need to quickly present internal analytics, charts, and interactive widgets without building a complex web architecture [1, 2].
5. **Choose Reflex** if you want to build a fully interactive, production-ready full-stack application (with complex states, WebSocket interactions, and beautiful custom styles) but do not want to divide your team between Python and JavaScript [2].

---

### Sources & References
* [1] [Best Python Web Frameworks 2026 Compared - Reflex](https://reflex.dev/blog/top-python-web-frameworks/)
* [2] [Django vs Flask vs Reflex (April 2026) - Reflex](https://reflex.dev/blog/django-vs-flask-vs-reflex-comparison/)
* [3] [12 Modern Python Frameworks to Try in 2026 - Medium](https://medium.com/the-pythonworld/12-modern-python-frameworks-to-try-in-2026-e7089305bb19)
* [4] [5 top Python web frameworks of 2026 - Educative.io](https://www.educative.io/blog/top-python-web-frameworks)
* [5] [The Python Backend Framework Decision Guide for 2026 - Rollbar](https://rollbar.com/blog/python-backend-frameworks/)

plaintext

Multi-Turn Conversations: Persistent Sandbox State

What if you want the agent to build on its previous work? By default, each interactions.create() call spins up a brand-new, empty sandbox. To continue in the same environment, you pass two IDs back:

from google import genai
client = genai.Client()

# Turn 1: Research and create a report
interaction_1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the current state of carbon capture technology in 2026. "
          "Write a comprehensive 500-word report and save it as report.md",
    environment="remote"
)
print(f"Environment ID: {interaction_1.environment_id}")
print(f"Interaction ID: {interaction_1.id}")
print(interaction_1.output_text)

# Turn 2: Build on the previous work - same sandbox, same files
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction_1.environment_id, # ← Re-attaches to same Ubuntu sandbox
    previous_interaction_id=interaction_1.id, # ← Preserves conversation memory
    input="Convert that report.md file into a clean index.html webpage "
          "with modern inline CSS styling and responsive design."
          " Please output the contents of the index.html file"
)
print(interaction_2.output_text)

plaintext

The first interaction produced the report.md file.

Environment ID: 5eb9b4b8-c02f-4a8f-b7a0-c90a796c01a6
Interaction ID: v1_ChdidXNuYXJLQkF1eWlqdU1QODRmUjJRZxIXYnVzbmFyS0JBdXlpanVNUDg0ZlIyUWc
I have researched the state of carbon capture, utilization, and storage (CCUS)
technology in 2026 and compiled a comprehensive 494-word report. 
The report has been successfully saved to your environment as **`report.md`**.

Below is the full text of the report, 
highlighting how the CCUS sector has transitioned from pilot-stage 
demonstrations to industrial infrastructure in 2026.

***

# The State of Carbon Capture Technology in 2026: From Pilot to Infrastructure

## Executive Summary
....

## Point-Source Capture: The Current Backbone
...

## Scaling Direct Air Capture (DAC)
... 

## Infrastructure, Transport, and Policy
...

## Key Challenges
...

***

### Sources Cited

* **[1] S&P Global:** [2026 CCUS: Navigating the tides of the great realignment](https://www.spglobal.com/energy/en/news-research/blog/energy-transition/041426-2026-ccus-navigating-the-tides-of-the-great-realignment) (April 2026)
* **[2] Carbon Herald:** [What's Next For Carbon Capture, Utilization & Storage (CCUS) In 2026](https://carbonherald.com/whats-next-for-carbon-capture-utilization-storage-ccus-in-2026/) (January 2026)
* **[3] Nature Tech Memos:** [Top 10 Carbon Capture Startups for Corporate Partnerships in 2026](https://www.naturetechmemos.com/p/top-10-carbon-capture-startups-for-corporate-partnerships-in-2026) (April 2026)
.....

plaintext

The second interaction continued with the previous environment and interaction, and asked it to produce an HTML version of it i.e. index.html. The instruction specifically asked for the HTML contents to be produced.

I have successfully converted your `report.md` file into a clean, modern, and highly responsive **`index.html`** webpage! 

### What was done:
1. **Designed a cohesive palette:** Implemented a modern climate-tech inspired aesthetic using Slate (`#1e293b`) and a range of deep and light teals (`#0f766e`, `#14b8a6`, `#115e59`).
2. **Added an Interactive Stat Dashboard:** Created a high-level statistical summary card grid displaying key 2026 data at a glance (e.g., global Mtpa capacity, Stratos targets, US Section 45Q tax credits).
3. **Structured visual highlights:** Embedded two distinct grid comparison cards for the **Climeworks Mammoth** and **1PointFive Stratos** facilities, as well as a custom callout block highlighting the trans-European **Northern Lights** shipping route.
4. **Professionalized the typography & chemistry:** Used system-ui fonts for excellent loading speeds and correctly formatted all chemical formulas to standard subscripts (e.g., **CO<sub>2</sub>** ).
5. **Citations & Interactivity:** Mapped the original references into clickable, superscript citation numbers (e.g., `[1]`) that link smoothly down to a beautifully bulleted "Sources Cited" section with custom index bullet styling.

The full HTML contents of the newly created `index.html` are shown below:

html
<!DOCTYPE html>

The State of Carbon Capture Technology in 2026
 :root { --primary: #0f766e; --primary-light: #14b8a6; --primary-dark: #115e59; --bg: #f8fafc; --card-bg: #ffffff; --text-main: #1e293b; --text-muted: #475569; --accent: #0284c7; --border: #e2e8f0; --shadow: 0 4px 6px -1px rgba(15, 118, 110, 0.05), 0 2px 4px -2px rgba(15, 118, 110, 0.05); --shadow-md: 0 10px 15px -3px rgba(15, 118, 110, 0.1), 0 4px 6px -4px rgba(15, 118, 110, 0.1); } * { box-sizing: border-box; } body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; background-color: var(--bg); color: var(--text-main); line-height: 1.8; margin: 0; padding: 0; -webkit-font-smoothing: antialiased; } header { background: linear-gradient(135deg, #0d5c56 0%, #0f766e 50%, #115e59 100%); color: white; padding: 5rem 2rem; text-align: center; position: relative; } header::after { content: ''; position: absolute; bottom: 0; left: 0; right: 0; height: 6px; background: linear-gradient(90deg, var(--primary-light), var(--accent)); } .header-content { max-width: 800px; margin: 0 auto; } header h1 { font-size: 2.75rem; font-weight: 800; margin: 0 0 1rem 0; letter-spacing: -0.025em; line-height: 1.2; } header p { font-size: 1.25rem; color: #ccfbf1; margin: 0 0 1.5rem 0; font-weight: 300; } .meta { font-size: 0.875rem; color: #99f6e4; text-transform: uppercase; letter-spacing: 0.125em; font-weight: 600; } main { max-width: 900px; margin: -3rem auto 4rem auto; padding: 0 1.5rem; position: relative; z-index: 10; } .stats-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 1.5rem; margin-bottom: 3rem; } .stat-card { background: var(--card-bg); padding: 1.75rem 1.5rem; border-radius: 14px; box-shadow: var(--shadow); border: 1px solid var(--border); text-align: center; transition: transform 0.25s ease, box-shadow 0.25s ease; } .stat-card:hover { transform: translateY(-5px); box-shadow: var(--shadow-md); } .stat-num { font-size: 2.25rem; font-weight: 800; color: var(--primary); margin-bottom: 0.5rem; line-height: 1; } .stat-label { font-size: 0.875rem; color: var(--text-muted); font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; } .content-wrapper { background: var(--card-bg); padding: 4rem 3.5rem; border-radius: 20px; box-shadow: var(--shadow-md); border: 1px solid var(--border); } section { margin-bottom: 3.5rem; } section:last-of-type { margin-bottom: 0; } h2 { color: var(--primary-dark); font-size: 1.85rem; font-weight: 700; margin-top: 0; margin-bottom: 1.5rem; border-bottom: 2px solid #f1f5f9; padding-bottom: 0.75rem; } p { margin-top: 0; margin-bottom: 1.5rem; font-size: 1.1rem; color: #334155; text-align: justify; } .highlight-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; margin: 2rem 0; } @media (max-width: 768px) { header h1 { font-size: 2.25rem; } .content-wrapper { padding: 2.5rem 1.5rem; } .highlight-grid { grid-template-columns: 1fr; } } .highlight-box { background: #f0fdfa; border: 1px solid #ccfbf1; padding: 1.5rem; border-radius: 12px; border-left: 5px solid var(--primary); } .highlight-box h4 { margin: 0 0 0.75rem 0; color: var(--primary-dark); font-size: 1.15rem; font-weight: 700; } .highlight-box p { margin: 0; font-size: 0.95rem; color: #0f766e; text-align: left; line-height: 1.6; } .callout { background: #f8fafc; border: 1px solid var(--border); border-left: 5px solid var(--accent); padding: 1.5rem; border-radius: 4px 12px 12px 4px; margin: 2rem 0; } .callout-title { font-weight: 700; color: #0369a1; margin-bottom: 0.5rem; font-size: 1.1rem; } .callout p { margin: 0; font-size: 1rem; color: #475569; text-align: left; } .citation-link { color: var(--primary); text-decoration: none; font-weight: 700; font-size: 0.85rem; padding: 0 2px; vertical-align: super; } .citation-link:hover { color: var(--accent); text-decoration: underline; } .sources-section { background: #f8fafc; border: 1px solid var(--border); margin-top: 4rem; padding: 2.5rem; border-radius: 14px; } .sources-section h3 { margin-top: 0; color: var(--primary-dark); font-size: 1.35rem; margin-bottom: 1.5rem; font-weight: 700; } .sources-list { list-style-type: none; padding: 0; margin: 0; } .sources-list li { margin-bottom: 1rem; font-size: 0.95rem; padding-left: 2rem; position: relative; line-height: 1.6; color: #475569; } .sources-list li::before { content: attr(data-index); color: var(--primary); position: absolute; left: 0; font-weight: 700; background: #ccfbf1; width: 24px; height: 24px; border-radius: 50%; display: flex; align-items: center; justify-content: center; font-size: 0.75rem; top: 2px; } .sources-list a { color: var(--primary-dark); text-decoration: none; font-weight: 600; transition: color 0.2s ease; } .sources-list a:hover { color: var(--accent); text-decoration: underline; } footer { text-align: center; color: var(--text-muted); font-size: 0.875rem; margin-top: 4rem; padding-top: 2rem; border-top: 1px solid var(--border); }

<header>
    <div class="header-content">
        <span class="meta">Special Intelligence Report</span>
        <h1>The State of Carbon Capture Technology in 2026</h1>
        <p>From Pilot to Infrastructure</p>
    </div>
</header>

<main>
    <!-- Key Metrics Dashboard -->
    <div class="stats-grid">
        <div class="stat-card">
            <div class="stat-num">~73 Mtpa</div>
            <div class="stat-label">Global Operational Capacity</div>
        </div>
        <div class="stat-card">
            <div class="stat-num">500k Tons</div>
            <div class="stat-label">Stratos DAC Annual Target</div>
        </div>
        <div class="stat-card">
            <div class="stat-num">Up to $180</div>
            <div class="stat-label">US 45Q Subsidy per Ton</div>
        </div>
        <div class="stat-card">
            <div class="stat-num">36,000 T</div>
            <div class="stat-label">Mammoth Iceland Capacity</div>
        </div>
    </div>

    <div class="content-wrapper">
        <!-- Executive Summary -->
        <section id="executive-summary">
            <h2>Executive Summary</h2>
            <p>
                In 2026, the Carbon Capture, Utilization, and Storage (CCUS) industry is undergoing an "industrial hardening" phase, transitioning decisively from demonstration-stage pilots to commercial-scale infrastructure<sup><a href="#ref-1" class="citation-link">[1]</a></sup>. Global operational capture capacity has reached approximately 73 million metric tons per annum (Mtpa) as of mid-2026, up from 50 Mtpa in early 2025<sup><a href="#ref-1" class="citation-link">[1]</a></sup><sup><a href="#ref-2" class="citation-link">[2]</a></sup>. This momentum is propelled by robust climate policies, corporate carbon-removal commitments, and the commissioning of megaton-scale facilities.
            </p>
        </section>

        <!-- Point-Source Capture -->
        <section id="point-source">
            <h2>Point-Source Capture: The Current Backbone</h2>
            <p>
                Point-source carbon capture remains the commercial backbone of CCUS<sup><a href="#ref-2" class="citation-link">[2]</a></sup>. Technologies deployed at industrial and energy facilities—such as cement, steel, chemicals, and refining—now represent the vast majority of active capture capacity. Post-combustion chemical absorption using amine-based solvents is the most widely deployed technology<sup><a href="#ref-2" class="citation-link">[2]</a></sup>. Companies like Carbon Upcycling Technologies are successfully integrating capture systems with utilization, converting captured carbon dioxide (CO<sub>2</sub>) into high-quality construction materials, turning emissions from cement manufacturers into a low-carbon concrete feedstock<sup><a href="#ref-3" class="citation-link">[3]</a></sup>.
            </p>
        </section>

        <!-- Scaling Direct Air Capture -->
        <section id="dac">
            <h2>Scaling Direct Air Capture (DAC)</h2>
            <p>
                Direct Air Capture is experiencing a dramatic scale-up<sup><a href="#ref-4" class="citation-link">[4]</a></sup>. Climeworks' "Mammoth" facility in Iceland, operational since May 2024, captures up to 36,000 tons of CO<sub>2</sub> annually, storing it permanently underground via Carbfix mineralization<sup><a href="#ref-4" class="citation-link">[4]</a></sup><sup><a href="#ref-5" class="citation-link">[5]</a></sup>. Meanwhile, 1PointFive's (a subsidiary of Occidental Petroleum) "Stratos" facility in Ector County, Texas, is entering active operation in 2026<sup><a href="#ref-4" class="citation-link">[4]</a></sup>. Designed to capture up to 500,000 tons of atmospheric CO<sub>2</sub> annually using liquid solvent technology licensed from Carbon Engineering, Stratos is currently the world’s largest DAC plant<sup><a href="#ref-4" class="citation-link">[4]</a></sup><sup><a href="#ref-6" class="citation-link">[6]</a></sup>. 
            </p>

            <div class="highlight-grid">
                <div class="highlight-box">
                    <h4>Climeworks: Mammoth (Iceland)</h4>
                    <p>Nameplate capacity of 36,000 tons/year. Relies on solid-sorbent collectors powered by clean geothermal energy with deep Carbfix basaltic storage.</p>
                </div>
                <div class="highlight-box">
                    <h4>1PointFive: Stratos (Texas)</h4>
                    <p>World's largest facility with 500,000 tons/year target. Employs liquid-solvent infrastructure designed for rapid regional scalability.</p>
                </div>
            </div>

            <p>
                Major technology firms (including Microsoft, Google, Meta, and Amazon) have signed multi-year offtake agreements for high-quality, durable carbon credits, paying between $200 and $300 per ton, though current baseline DAC capture costs remain high, between $400 and $1,000 per ton<sup><a href="#ref-3" class="citation-link">[3]</a></sup><sup><a href="#ref-7" class="citation-link">[7]</a></sup>.
            </p>
        </section>

        <!-- Infrastructure, Transport, and Policy -->
        <section id="infrastructure">
            <h2>Infrastructure, Transport, and Policy</h2>
            <p>
                The commercial viability of carbon capture relies heavily on dedicated transportation and storage networks<sup><a href="#ref-2" class="citation-link">[2]</a></sup>. In Europe, 2026 marks the active operation of Norway’s "Northern Lights" project, the world's first open-source CO<sub>2</sub> transport and storage network<sup><a href="#ref-8" class="citation-link">[8]</a></sup>. For example, Yara's flagship Sluiskil ammonia plant in the Netherlands is liquefying up to 800,000 tons of CO<sub>2</sub> annually to be shipped by Northern Lights for permanent undersea storage<sup><a href="#ref-8" class="citation-link">[8]</a></sup>. Concurrently, Denmark’s "Greensand" offshore storage initiative is beginning operations<sup><a href="#ref-2" class="citation-link">[2]</a></sup>. 
            </p>

            <div class="callout">
                <div class="callout-title">The Trans-European Shipping Pathway</div>
                <p>Northern Lights bridges emission-heavy inland industrial sites like Yara Sluiskil in the Netherlands directly with permanent injection storage wells beneath the North Sea seabed.</p>
            </div>

            <p>
                On the policy front, the sector is heavily anchored by government subsidies. In the United States, the Inflation Reduction Act’s (IRA) modified Section 45Q tax credit provides up to $180 per metric ton for DAC and $85 per metric ton for point-source capture<sup><a href="#ref-9" class="citation-link">[9]</a></sup>. In the European Union, the Net Zero Industry Act has accelerated cross-border transport approvals, providing regulatory certainty.
            </p>
        </section>

        <!-- Key Challenges -->
        <section id="challenges">
            <h2>Key Challenges</h2>
            <p>
                Despite rapid progress, critical bottlenecks persist. Chief among these is the high energy intensity of DAC, which requires 1.5 to 2.5 megawatt-hours (MWh) of zero-carbon energy per ton of captured CO<sub>2</sub><sup><a href="#ref-7" class="citation-link">[7]</a></sup>. Permitting delays for geologic injection wells—specifically the EPA’s rigorous Class VI permits in the United States—also restrict how fast captured carbon can be sequestered<sup><a href="#ref-4" class="citation-link">[4]</a></sup>. Overcoming these economic and infrastructure hurdles remains essential to achieving megaton targets by 2030.
            </p>
        </section>

        <!-- Sources Cited -->
        <div class="sources-section">
            <h3>Sources Cited</h3>
            <ul class="sources-list">
                <li id="ref-1" data-index="1"><strong>S&P Global:</strong> <a href="https://www.spglobal.com/energy/en/news-research/blog/energy-transition/041426-2026-ccus-navigating-the-tides-of-the-great-realignment" target="_blank">2026 CCUS: Navigating the tides of the great realignment</a> (April 2026)</li>
                <li id="ref-2" data-index="2"><strong>Carbon Herald:</strong> <a href="https://carbonherald.com/whats-next-for-carbon-capture-utilization-storage-ccus-in-2026/" target="_blank">What's Next For Carbon Capture, Utilization & Storage (CCUS) In 2026</a> (January 2026)</li>
                <li id="ref-3" data-index="3"><strong>Nature Tech Memos:</strong> <a href="https://www.naturetechmemos.com/p/top-10-carbon-capture-startups-for-corporate-partnerships-in-2026" target="_blank">Top 10 Carbon Capture Startups for Corporate Partnerships in 2026</a> (April 2026)</li>
                <li id="ref-4" data-index="4"><strong>Senken:</strong> <a href="https://www.senken.io/blog/top-direct-air-capture-carbon-removal-projects-buyers-guide" target="_blank">The Top 3 Direct Air Capture Carbon Removal Projects</a> (February 2026)</li>
                <li id="ref-5" data-index="5"><strong>Climeworks:</strong> <a href="https://climeworks.com/plant-mammoth" target="_blank">Mammoth: our newest direct air capture and storage facility</a> (May 2024)</li>
                <li id="ref-6" data-index="6"><strong>Carbon Credits:</strong> <a href="https://carboncredits.com/top-3-carbon-capture-leaders-to-drive-the-net-zero-race-in-2026/" target="_blank">Top 3 Carbon Capture Leaders to Drive the Net-Zero Race in 2026</a> (January 2026)</li>
                <li id="ref-7" data-index="7"><strong>Energy Solutions Intelligence:</strong> <a href="https://energy-solutions.co/articles/sub/carbon-capture-direct-air-dac-cost-analysis" target="_blank">Direct Air Capture in 2026: Cost, Scale, and Path to $200/tCO2</a> (January 2026)</li>
                <li id="ref-8" data-index="8"><strong>World Economic Forum:</strong> <a href="https://www.weforum.org/stories/2026/01/scale-carbon-capture-storage-climate-action/" target="_blank">How to scale carbon capture and storage for climate action</a> (January 2026)</li>
                <li id="ref-9" data-index="9"><strong>International Energy Agency (IEA):</strong> <a href="https://www.iea.org/policies/16255-inflation-reduction-act-2022-sec-13104-extension-and-modification-of-credit-for-carbon-oxide-sequestration" target="_blank">Inflation Reduction Act 2022: Sec. 13104 Extension and Modification of Credit for Carbon Oxide Sequestration</a> (February 2026)</li>
            </ul>
        </div>

        <footer>
            <p style="text-align: center; color: var(--text-muted); font-size: 0.875rem; margin: 0;">&copy; 2026 Carbon Capture Intelligence. Compiled June 2026.</p>
        </footer>
    </div>
</main>

plaintext

The rendered form of the report is shown here:

Understanding the Two IDs

It is important to understand the Two IDs and here is a table that breaks it down:

Tip: You can pass environment_id without previous_interaction_id to reuse the files and installed packages, but start a fresh conversation. This is useful when you want to "fork" the workspace with a new task.

Downloading files

The previous section demonstrated how we can use the instruction itself to specify it to output the file content that it generated. That is one way but maybe not the way that you may want. You would probably want to download the file directly from the sandbox. Let’s do that.

Shown below is the entire code listing that we saw in the previous multi-turn interaction to create markdown report and then a HTML version of it. Just that we are going to add some code at the end to download the entire environment snapshot as a tar file and then extract it in a local folder. This is currently what the Managed Agents Environment supports. Read the documentation here.

import os
import requests
import tarfile
from google import genai
client = genai.Client()

# Turn 1: Research and create a report
interaction_1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the current state of carbon capture technology in 2026. "
          "Write a comprehensive 500-word report and save it as report.md",
    environment="remote"
)
print(f"Environment ID: {interaction_1.environment_id}")
print(f"Interaction ID: {interaction_1.id}")
print(interaction_1.output_text)

# Turn 2: Build on the previous work - same sandbox, same files
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction_1.environment_id, # ← Re-attaches to same Ubuntu sandbox
    previous_interaction_id=interaction_1.id, # ← Preserves conversation memory
    input="Convert that report.md file into a clean index.html webpage "
          "with modern inline CSS styling and responsive design."
          " Please output the contents of the index.html file"
)
print(interaction_2.output_text)

env_id = interaction_2.environment_id
api_key = os.environ.get("GEMINI_API_KEY")

response = requests.get(
    f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download",
    params={"alt": "media"},
    headers={"x-goog-api-key": api_key},
    allow_redirects=True,
)

with open("snapshot_env.tar", "wb") as f:
    f.write(response.content)

os.makedirs("extracted_env_snapshot", exist_ok=True)
with tarfile.open("snapshot_env.tar") as tar:
    tar.extractall(path="extracted_env_snapshot")

plaintext

Currently, as of writing this article, there is no SDK and it is a direct REST call to get the environment snapshot.

Here is the output on my local machine after I run the above program:

Customizing Agents: Skills, Personas, and Configuration

Instead of cramming everything into a single prompt string, Antigravity uses a filesystem-native configuration system. When the sandbox boots up, it automatically looks for a hidden .agents/ directory:

📁 Your-Project-Directory/
└── 📁 .agents/
    ├── 📄 AGENTS.md ← Global system instructions (persona, rules, standards)
    └── 📁 skills/
        └── 📁 data-cleaner/
            └── 📄 SKILL.md ← Specific skill with step-by-step instructions

plaintext

AGENTS.md — The Agent’s Persona

This file contains the foundational rules, behavioral guardrails, and project-specific context for your agent. Think of it as a README that the agent reads before starting any task.

SKILL.md — Modular Expertise

Skills package domain-specific expertise into reusable, modular units. They use YAML frontmatter for metadata and Markdown for instructions:

---
name: data-cleaner
description: Use when the user needs to clean, normalize, or validate tabular data files.
---
# Data Cleaner
## When to Use
- User provides CSV, Excel, or JSON files that need cleaning
- Data has missing values, inconsistent formatting, or duplicate rows
## Steps
1. Load the data file using pandas
2. Profile the data: count nulls, duplicates, and type mismatches
3. Apply cleaning rules (fill nulls, normalize strings, deduplicate)
4. Save the cleaned output and generate a summary report

plaintext

The key insight is progressive disclosure : the agent only loads the full content of a SKILL.md when it determines the skill is relevant to the current task. At startup, it reads only the name and description from the frontmatter, keeping the context window clean.

Tip: If a skill isn’t triggering when you expect it to, the issue is almost always the description in the YAML frontmatter. Make it more specific about when the skill should activate.

Persistent Agent Creation

For production use, you can register a persistent agent configuration so you don’t repeat yourself. In other words, you can create a Named Agent with the Agents API.

Let’s see how to create a persistent agent using the same CSV Cleaner logic skill that we introduced in the previous section.

from google import genai

client = genai.Client()

# Register a reusable, named agent with the data-cleaner skill baked in
agent = client.agents.create(
    id="my-csv-cleaner",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a data quality engineer. Always use pandas for data manipulation. "
                       "Always generate a before/after summary showing what changed.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": (
                    "# Data Quality Agent\n\n"
                    "## Standards\n"
                    "- Never drop rows silently — log every removal with a reason\n"
                    "- Normalize all string columns to lowercase, stripped of whitespace\n"
                    "- Output cleaned files in UTF-8 CSV format\n"
                    "- Always print a summary table at the end\n"
                )
            },
            {
                "type": "inline",
                "target": ".agents/skills/data-cleaner/SKILL.md",
                "content": (
                    "---\n"
                    "name: data-cleaner\n"
                    "description: Use when the user needs to clean, normalize, or validate tabular data files.\n"
                    "---\n"
                    "# Data Cleaner\n\n"
                    "## When to Use\n"
                    "- User provides CSV, Excel, or JSON files that need cleaning\n"
                    "- Data has missing values, inconsistent formatting, or duplicate rows\n\n"
                    "## Steps\n"
                    "1. Load the data file using pandas\n"
                    "2. Profile the data: count nulls, duplicates, and type mismatches\n"
                    "3. Apply cleaning rules (fill nulls, normalize strings, deduplicate)\n"
                    "4. Save the cleaned output and generate a summary report\n"
                )
            }
        ]
    }
)

print(f"Agent created with ID: {agent.id}")

python

Create a file named create_csv_cleaner_agent.py with the above code and run it. This will create a persistent agent that you can refer to via its registered agent ID i.e. my-csv-cleaner.

Let’s put the agent to use. First up, create a file with a few messed up customer records in a CSV file named messy_customers.csv.

name,email,phone,country
John Smith,john@example.com,+14155551234,US
jane doe, JANE@EXAMPLE.COM ,4155559999,
John Smith,john@example.com,+14155551234,US
Bob Wilson,bob@@invalid,+442071234567,
María García,maria@test.com,+34612345678,Spain
  alice brown ,alice@example.com,,US
Charlie Lee,charlie@test.com,+61412345678,AU
jane doe,jane@example.com,+14155559999,

python

Now you can invoke this agent by ID anywhere in your app. Create a file named run_csv_cleaner_agent.py with the content given below.

from google import genai

client = genai.Client()

# Read your local CSV file
with open("messy_customers.csv", "r") as f:
    csv_content = f.read()

# Inject the file into the sandbox and tell the agent to clean it
interaction = client.interactions.create(
    agent="my-csv-cleaner",
    input="Clean the file at data/customers.csv. "
          "Remove duplicate rows by email (case-insensitive), "
          "standardize phone numbers to E.164 format, "
          "fill missing 'country' fields by looking up the phone country code, "
          "and flag any rows where the email format is invalid. "
          "Generate a before/after summary showing what changed.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": "data/customers.csv", # ← Path inside the sandbox
                "content": csv_content # ← Your local file contents
            }
        ]
    }
)

print(interaction.output_text)

python

What’s happening in the above code: The sources array pre-loads files into the sandbox before the agent starts working. The agent sees data/customers.csv as a real file in its Linux filesystem — it doesn't know or care that you injected it from your local machine. This works for any file type: CSV, JSON, XML, Python scripts, config files, etc.

Notice how the prompt doesn’t mention pandas, UTF-8, or logging rules — all of that is already encoded in the AGENTS.md and SKILL.md that the named agent carries with it. The data-cleaner skill activates automatically because the task description matches the skill's description field.

A sample run of the above file is shown below:

I have successfully cleaned the customer dataset at `data/customers.csv` using Python and `pandas`. 

Below is a detailed report and before/after summary of the transformations applied.

---

### Summary of Transformations

1. **whitespace Trimming:** Stripped all leading and trailing whitespace from both column names and text values (e.g., ` alice brown ` became `alice brown`).
2. **Email Normalization & Validation:** 
   - Converted all email addresses to lowercase and trimmed whitespace.
   - Added a new column `email_invalid` (boolean) to flag emails with an invalid format.
   - Identified `bob@@invalid` as an invalid format (due to a duplicate `@` symbol and lack of a top-level domain).
3. **Phone Number Standardization:**
   - Standardized all valid phone numbers to the international **E.164** format using the `phonenumbers` library.
   - Converted `4155559999` (with a default US region fallback) to `+14155559999`.
   - Ignored the missing phone number for `alice brown` while leaving it empty.
4. **Country Code Lookup:**
   - Looked up and populated missing `country` values based on the telephone country code prefix.
   - Filled `jane doe`'s country as `US` (derived from prefix `+1`).
   - Filled `Bob Wilson`'s country as `GB` (derived from prefix `+44`).
   - Kept existing valid country entries (e.g., `Spain`, `US`, `AU`) intact.
5. **Deduplication:**
   - Removed duplicate rows by performing a case-insensitive match on the cleaned `email` column, keeping the first occurrence.
   - Safely removed the duplicate row for `john@example.com` (Row 3).
   - Safely removed the duplicate row for `jane@example.com` (Row 8).

---

### Before/After Summary

#### 1. Data Quality Metrics

| Metric | Before Clean | After Clean | Change Description |
| :--- | :---: | :---: | :--- |
| **Total Rows** | 8 | 6 | 2 duplicate rows were removed. |
| **Duplicates Removed** | 0 | 2 | Dropped rows 3 (`john@example.com`) and 8 (`jane@example.com`). |
| **Invalid Emails Flagged** | 0 | 1 | Flagged `bob@@invalid` as invalid (`email_invalid = True`). |
| **Standardized Phone Numbers** | 1 | 5 | All numbers formatted to E.164 (e.g., `4155559999` -> `+14155559999`). |
| **Filled Country Fields** | 5 | 6 | Filled 2 missing country values (`US` and `GB`) via phone prefix lookups. |

#### 2. Row-by-Row Comparison

Below is the row-by-row evolution from the raw file to the cleaned output:

| Row # | Name (Before) | Name (After) | Email (Before) | Email (After) | Phone (Before) | Phone (After) | Country (Before) | Country (After) | Email Invalid Flag | Action Taken / Status |
| :---: | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :---: | :--- |
| **1** | `John Smith` | `John Smith` | `john@example.com` | `john@example.com` | `+14155551234` | `+14155551234` | `US` | `US` | `False` | Retained as first unique instance. |
| **2** | `jane doe` | `jane doe` | ` JANE@EXAMPLE.COM ` | `jane@example.com` | `4155559999` | `+14155559999` | *Missing* | `US` | `False` | Email normalized; Phone formatted to E.164; Country populated from `+1` prefix. |
| **3** | `John Smith` | — | `john@example.com` | — | `+14155551234` | — | `US` | — | — | **Removed** (Duplicate email). |
| **4** | `Bob Wilson` | `Bob Wilson` | `bob@@invalid` | `bob@@invalid` | `+442071234567` | `+442071234567` | *Missing* | `GB` | `True` | Country populated from `+44` prefix; Email flagged as invalid. |
| **5** | `María García` | `María García` | `maria@test.com` | `maria@test.com` | `+34612345678` | `+34612345678` | `Spain` | `Spain` | `False` | Retained; Email valid; Preserved existing country. |
| **6** | ` alice brown ` | `alice brown` | `alice@example.com` | `alice@example.com` | *Missing* | *Missing* | `US` | `US` | `False` | Name whitespace stripped; Phone left empty; Preserved existing country. |
| **7** | `Charlie Lee` | `Charlie Lee` | `charlie@test.com` | `charlie@test.com` | `+61412345678` | `+61412345678` | `AU` | `AU` | `False` | Retained; Email valid. |
| **8** | `jane doe` | — | `jane@example.com` | — | `+14155559999` | — | *Missing* | — | — | **Removed** (Duplicate email). |

---

### Cleaned Dataset Output

The cleaned data has been written back to `data/customers.csv` and contains the following records:

csv
name,email,phone,country,email_invalid
John Smith,john@example.com,+14155551234,US,False
jane doe,jane@example.com,+14155559999,US,False
Bob Wilson,bob@@invalid,+442071234567,GB,True
María García,maria@test.com,+34612345678,Spain,False
alice brown,alice@example.com,,US,False
Charlie Lee,charlie@test.com,+61412345678,AU,False

plaintext

Building Real-World Agents: A few Use Cases

Now that you understand the foundations, let’s build a few agents. Each one introduces new capabilities and patterns.

Use Case 1: Automated Code Refactoring & Test Fixing

The Problem: You have a Python project with outdated code and failing tests. A standard LLM gives you code snippets, but you still have to manually copy, paste, run tests, debug, and iterate.

The Antigravity Solution: The agent clones your code, runs the test suite, reads terminal errors, patches the code, and re-runs tests — looping until everything passes.

We are providing a repository here with buggy code. Take a look:

GitHub - rominirani/uc1-legacy-app: Managed Agents Sample App Repository with Bugs

Known Bugs to fix for the Agent

As per the repository and you can take a look at it too, there are 3 root-cause bugs across the codebase (causing 6 test failures):

utils.py — calculate_total() does arithmetic on a string tax_rate without converting to float.
utils.py — normalize_name() crashes on None input (no null check).
models.py — Invoice.summary() references self.total (method object) instead of self.total() (method call).

The Code

Let’s write our Agent that can fix this for us. Check out the instruction in detail below:

from google import genai
client = genai.Client()

system_instructions = """
You are an expert QA and Refactoring Engineer. Your workflow is:
1. Clone the target repository into the workspace
2. Install all dependencies from requirements.txt
3. Run the full pytest suite and capture all output
4. For each failing test:
   a. Read the error traceback carefully
   b. Open the source file causing the failure
   c. Diagnose the root cause
   d. Apply the minimal fix
5. Re-run pytest after each fix to confirm resolution
6. Continue until ALL tests pass (0 failures)
7. Generate a summary of every change you made
IMPORTANT: Make the minimal possible change to fix each test.
Do not refactor working code unnecessarily.
"""
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    system_instruction=system_instructions,
    input="""
    Clone this repository: https://github.com/rominirani/uc1-legacy-app
    Run the pytest suite to check for environment or code failures.
    Isolate the bugs causing test failures and fix them one by one.
    Keep running the tests until you achieve a 100% pass rate.
    When done, provide:
    1. A list of all files modified with a diff summary
    2. The final pytest output showing all tests passing
    3. Any dependency changes you had to make
    """,
    environment="remote"
)
print(interaction.output_text)

plaintext

Run it: Save the above as uc1_refactor.py and run:

python3 uc1_refactor.py

shell

Expected output:

I have successfully diagnosed and resolved all the issues causing test failures in the `uc1-legacy-app` repository. Below is a detailed summary of the findings, modifications, and the final test execution output.

---

### 1. Modified Files & Diff Summary

#### File: `src/models.py`
- **Issue** : In the `Invoice.summary()` method, the `self.total` method itself was passed to `format_currency()` as an object, instead of being invoked (`self.total()`). This led to a `TypeError` during format evaluation.
- **Fix** : Changed `self.total` to `self.total()`.
- **Diff Summary** :

diff
@@ -23,7 +23,7 @@ class Invoice:
"""Return a one-line summary of the invoice."""
from src.utils import format_currency, normalize_name
name = normalize_name(self.customer_name)

return f"Invoice {self.invoice_id}: {name} - {format_currency(self.total)}"
return f"Invoice {self.invoice_id}: {name} - {format_currency(self.total())}"


#### File: `src/utils.py`
- **Issues** :
1. **`calculate_total()`**: When `tax_rate` is received as a string, Python fails to perform multiplication of float/string (`TypeError: can't multiply sequence by non-int of type 'float'`).
2. **`normalize_name()`**: When passed a `None` value (common in CSV imports), the code raised `AttributeError: 'NoneType' object has no attribute 'strip'`.
- **Fixes** :
1. Explicitly cast `subtotal` and `tax_rate` to `float` prior to calculating the tax.
2. Add a safeguard to return an empty string (`""`) when `name` is `None`.
- **Diff Summary** :

diff
@@ -11,8 +11,10 @@ def calculate_total(subtotal, tax_rate):
Returns:
The total as a float rounded to 2 decimal places.
"""

tax = subtotal * tax_rate / 100
return round(subtotal + tax, 2)
subtotal_val = float(subtotal)
tax_rate_val = float(tax_rate)
tax = subtotal_val * tax_rate_val / 100
return round(subtotal_val + tax, 2)

def format_currency(amount):
@@ -36,6 +38,8 @@ def normalize_name(name):
Returns:
Cleaned, title-cased name.
"""

if name is None:
return "" return name.strip().title()


---

### 2. Dependency Changes
No additional packages or dependency changes were made. All required libraries from `requirements.txt` (consisting of `pytest>=7.0.0`) were successfully installed and utilized without modification.

---

### 3. Final Pytest Output
Running the full suite confirms that all 10 tests now pass:

plaintext
============================= test session starts ==============================
platform linux -- Python 3.12.3, pytest-9.0.3, pluggy-1.6.0
rootdir: /uc1-legacy-app
plugins: anyio-4.13.0
collected 10 items

tests/test_models.py .... [40%]
tests/test_utils.py ...... [100%]

============================== 10 passed in 0.02s ==============================

plaintext

What Happens Behind the Scenes

The agent autonomously:

Runs git clone in the sandbox terminal
Runs pip install -r requirements.txt (installing into the sandbox's Python)
Runs pytest -v and reads the full output, including tracebacks
Opens the failing source files, identifies buggy logic
Writes patches, saves files, re-runs pytest
Loops until the output shows 0 failures

Key Concept Introduced: The Plan → Act → Observe loop in action. The agent doesn’t just generate code — it executes, reads real terminal output, and self-corrects.

Use Case 2: Live Competitive Intelligence Engine

The Problem: You need a deep competitive analysis of rival products. Manual web scraping is tedious, and static scrapers break constantly.

The Antigravity Solution: The agent uses its web browsing tools to search Google, crawls competitor websites, dynamically adapts to different page structures, writes a custom pandas script to structure the data, and exports a polished spreadsheet.

The Code

from google import genai
client = genai.Client()

system_instructions = """
You are a precise Business Intelligence Analyst. Your workflow:
1. Use web search to find current, real-time information
2. Navigate to official product/pricing pages for each competitor
3. Extract: pricing tiers, key features, target audience, notable limitations
4. Structure ALL findings into a pandas DataFrame
5. Export to both CSV and a formatted Markdown comparison table
6. Include the date/time of research and source URLs for every data point
Rules:
- Only report data you can verify from official sources
- If pricing isn't publicly available, note "Contact Sales" - don't guess
- Use USD for all pricing normalization
"""
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    system_instruction=system_instructions,
    input="""
    Research the pricing models and core feature matrices of the top 3 alternative
    platforms to Vercel for frontend deployment:
    1. Netlify
    2. Cloudflare Pages
    3. Cloud Run
    For each, extract:
    - Free tier limits (bandwidth, builds, sites)
    - Pro/paid tier pricing and what it unlocks
    - Key differentiating features
    - Notable limitations or complaints from developer communities
    Create:
    1. A competitive_matrix.csv spreadsheet with all data
    2. A competitive_analysis.md report with a formatted comparison table
       and a "Recommendation" section at the bottom
    """,
    environment="remote"
)
print(interaction.output_text)

python

This produces the following output (a lovely report).

As a Business Intelligence Analyst, I have conducted a precise competitive analysis of the top three frontend deployment alternatives to Vercel: **Netlify** , **Cloudflare Pages** , and **Google Cloud Run**.

All findings have been structured using `pandas` and exported to `/` (the current working directory) as:
1. `competitive_matrix.csv` — The raw, structured dataset.
2. `competitive_analysis.md` — A comprehensive, reader-ready report including a detailed markdown comparison matrix, architectural breakdowns, limitation analyses, and a tailored recommendation framework.

All data has been verified against official vendor pricing, product, and developer documentation as of **June 9, 2026**. All currency values are normalized in **USD**.

---

### Core Finding Highlights

#### 1. Netlify
* **The Architectural Shift (April 2026):** Netlify made a massive strategic update to its Pro plans, moving from a seat-based model ($19/member/month) to a **flat $20/month per organization** [10]. This includes unlimited team members (Owners, Developers, Reviewers, and Git Contributors) [10], which is highly disruptive compared to Vercel's strict per-seat billing.
* **The Credits Trap:** Usage is now managed entirely via a unified credit-based model (300 credits/mo free, 3,000 on Pro) [2, 10]. However, credits are consumed fast: bandwidth costs 20 credits per GB [2, 10] (meaning Free tier is only **~15 GB max** and Pro is only **~150 GB max** if solely used for traffic). If Free tier credits run out, **all site traffic pauses immediately** (no auto-recharge is supported on Free) [2, 11]. 
* **Capabilities:** Highly integrated features like Netlify Database (managed Postgres via Neon) [4], Blob storage, Forms, and Auth [10]. Serverless timeout is 10s on Free/Personal [2] and 26s on Pro [2].

#### 2. Cloudflare Pages
* **Unmetered Freedom:** Genuinely **unlimited and unmetered static bandwidth and requests** across all tiers (including the $0 Free tier) [24, 25, 27].
* **The Pro Tier ($20/mo billed annually / $25/mo monthly):** Tied directly to Cloudflare's Workers Paid plan [25, 27]. It increases build limits from 500/mo to 5,000/mo, concurrent builds from 1 to 5, and the file-count ceiling per project from 20,000 to 100,000 assets [31] (unlocked via the `PAGES_WRANGLER_MAJOR_VERSION=4` env variable) [31].
* **Edge Isolates Constraints:** While running serverless code on Cloudflare's global network of 310+ cities is blazingly fast with zero cold starts [24, 33], it uses a **strict V8 edge runtime** [24]. Standard Node.js library modules (`fs`, `path`, native `crypto`) do not run natively [24], forcing developers to compile meta-frameworks like Next.js via edge adapters (e.g., `@cloudflare/next-on-pages` or OpenNext) [24] which restricts certain features like Incremental Static Regeneration (ISR).

#### 3. Google Cloud Run
* **Pure Container Portability:** Cloud Run runs any application, language, or compiled binary (Node.js, Python, Go, Rust) packaged in a standard Docker container [37, 39]. It runs full Node.js natively [39], ensuring 100% Next.js feature parity (ISR, Server Actions, dynamic image optimization) with zero edge-runtime workarounds [39].
* **No Monthly Base Fee:** Operates on a pure pay-as-you-go serverless model (billed in granular vCPU-seconds and GiB-seconds) [41], backed by a generous Always Free tier (2 million requests/mo, 180,000 vCPU-seconds, 360,000 GiB-seconds, and 120 daily Cloud Build minutes free) [37, 38, 41]. 
* **The Infrastructure Overhead:** Not a standard "push-to-deploy" platform. Developers must write Dockerfiles, configure Artifact Registry, and manage IAM and networking [37, 39]. It is regionally hosted; to get a global CDN with SSL mapping, you must set up Cloud CDN and a Global HTTP Load Balancer [37] (~$20-$30/mo base fee) and navigate container cold starts (2 to 10+ seconds) [37] and expensive internet egress rates ($0.085 - $0.12 per GB) [37].

---

### Structure of Generated Files

#### 1. `competitive_matrix.csv`
A raw, tabular CSV structured for business intelligence pipelines, featuring the following schema:
- `Platform Name`
- `Free Tier Pricing (USD)`
- `Free Tier Bandwidth Limit`
- `Free Tier Build Limit`
- `Free Tier Sites/Projects Limit`
- `Free Tier Key Specs & Features`
- `Paid/Pro Tier Price (USD)`
- `Paid/Pro Tier Features Unlocked`
- `Key Differentiating Features`
- `Notable Limitations & Developer Complaints`
- `Date of Research`
- `Source URLs`

#### 2. `competitive_analysis.md`
A professionally formatted report including:
* **Executive Summary:** Contextualizing why frontend teams are exploring alternatives to Vercel in 2026.
* **Structured Comparison Table:** Transposed for high-density reading and side-by-side comparison.
* **Deep-Dive Section:** Dedicated analyses of the Free limits, paid features, unique differentiators, and community complaints for Netlify, Cloudflare Pages, and Google Cloud Run.
* **Architectural Recommendation Flowchart & Matrix:** Tailored decision pathways based on project profile:
  * *Static / JAMstack / Zero-Budget* $\rightarrow$ **Cloudflare Pages**
  * *Collaborative Teams / Rapid Prototyping / Seat-Free DX* $\rightarrow$ **Netlify**
  * *Complex Server-Side Rendering / Backend Pipelines / Custom Docker* $\rightarrow$ **Google Cloud Run**

---

### Source Verification & Citations

1. **Netlify:**
   - [Official Pricing & Plans](https://www.netlify.com/pricing/)
   - [Introducing Seat-Free Collaborative Billing (April 14, 2026)](https://www.netlify.com/blog/pricing-netlify-for-3-billion-builders/)
   - [Credit-Based Pricing Documentation](https://docs.netlify.com/manage/accounts-and-billing/billing/billing-for-credit-based-plans/credit-based-pricing-plans/)
   - [Netlify Free Tier Credit Analysis (Temps)](https://temps.sh/compare/vs-netlify)

2. **Cloudflare Pages:**
   - [Workers & Pages Pricing Matrix](https://www.cloudflare.com/plans/developer-platform/)
   - [Official Pages Limits Documentation](https://developers.cloudflare.com/pages/platform/limits/)
   - [Cloudflare Pages Platform Features](https://pages.cloudflare.com/)
   - [Cloudflare Pages Edge Limitations (Temps)](https://temps.sh/compare/vs-cloudflare-pages)

3. **Google Cloud Run:**
   - [Official Cloud Run Pricing Breakdown](https://cloud.google.com/run/pricing)
   - [Google Cloud Free Tier Inclusions](https://cloud.google.com/free)
   - [Cloud Run Quotas & Limits](https://docs.cloud.google.com/run/quotas)
   - [Cloud Run Cost Optimization & Egress Guide (Cloudchipr)](https://cloudchipr.com/blog/cloud-run-pricing)

The generated files are saved directly in your working directory and are immediately available for download or integration into your reporting pipelines. Let me know if you would like me to modify the analysis parameters or explore a specific platform further!

plaintext

Building on the Analysis (Multi-Turn)

You can do a follow up too, by using the previous environment and interaction to take the competitive_matrix.csv generated and creating some visualization out of it. While the code below retrieves only the text output, you can use the technique shown below to download the environment sandbox and extract out the files generated.

# Follow-up: generate a visual chart from the data we just collected
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="""
    Using the competitive_matrix.csv you just created:
    1. Create a grouped bar chart comparing the free tier limits across all 3 platforms
    2. Create a pricing comparison chart for the paid tiers
    3. Save both charts as PNG files with clear labels and a professional color scheme
    4. Add the charts as embedded images in the competitive_analysis.md report
    """
)
print(interaction_2.output_text)

python

Key Concepts Introduced: Web browsing + code execution in the same task. The agent searches the live internet, then writes Python code to structure and visualize the data — all in one flow.

More Use Cases

I plan to keep adding to this document with more use cases, as this solution matures with more features. Stay tuned for updates.

Best Practices

Here are the architectural patterns that will serve you well in production:

Build to Delete

Model performance improves rapidly. Design your agents with the expectation that they’ll be rebuilt with newer models soon. Keep configurations modular — AGENTS.md + SKILL.md files are easy to swap. Don't over-engineer the orchestration layer.

Treat Agents as Microservices

Don’t build one massive agent with a 2,000-word system prompt. Decompose complex problems into specialized sub-agents:

Errors as Inputs, Not Crashes

In robust agentic architectures, errors are data and are inputs for the agent to self-reflect and correct. The agent reads a TypeError, reasons about the cause, and fixes it. Don't wrap everything in try/except blocks that swallow errors. Let the agent see them.

Evals Over Unit Tests

Agent behavior is non-deterministic. Testing focuses on evaluation metrics rather than exact output matching:


# ❌ Don't: Assert exact output
assert agent_output == "The answer is 42"

# ✅ Do: Evaluate behavioral success rate
results = [run_agent(task) for _ in range(20)]
success_rate = sum(1 for r in results if r.meets_criteria) / len(results)
assert success_rate >= 0.85 # Agent succeeds at least 85% of the time

Token Cost Awareness

Because Antigravity operates an autonomous reasoning loop, a single prompt can trigger many internal operations. Expect something around this ball park:

Implement strict timeouts and monitor trace lengths during development. Use system_instruction to tell the agent to be concise when you don't need verbose reasoning.

Error Handling Patterns

Resources

Official Documentation: ai.google.dev/gemini-api/docs/custom-agents
Gemini Managed Agents: Developer Guide : https://www.philschmid.de/gemini-managed-agents-developer-guide
Video: Managed Agents Deep Dive: youtube.com/watch?v=Psa8mLikdag
Video: Getting Started Tutorial: youtube.com/watch?v=0YXe7u-i1qU
Google AI Studio: aistudio.google.com

Ideas for Your Next Agent

CI/CD Pipeline Agent — monitors your GitHub repo, runs tests on every push, opens fix PRs for failures
Documentation Generator — reads your codebase and generates comprehensive API docs
Data Pipeline Orchestrator — connects to your warehouse, runs transformations, validates output
Customer Support Triage Agent — reads tickets, categorizes severity, drafts responses, escalates critical issues
Research Assistant — takes a topic, searches papers and articles, writes a literature review with citations

Final Thought

Managed Agents represent a fundamental shift in how we build with AI. You’re no longer building the infrastructure around the AI, you’re simply giving the AI a goal and a sandbox, and letting it work. The sandbox is the abstraction. The agentic loop is the engine. And the Interactions API is your single point of contact with all of it.

Most importantly, start small and set limits on what the agent can do autonomously. Then scale up.

Happy building.

Google Cloud Platform Technology Nuggets — May 16–31, 2026

Romin Irani — Wed, 03 Jun 2026 06:19:11 +0000

Welcome to the May 16–31, 2026 edition of Google Cloud Platform Technology Nuggets. The nuggets are also available on YouTube.

Infographic for the post generated by NotebookLM

AI and Machine Learning

If you are looking to stay updated on the latest Google Cloud AI tools, you should bookmark this link that covers updates made across the months.

There has been a spate of announcements at Google Cloud Next 2026 in April and Google I/O held in May introduced several other releases too, that included:

Gemini 3.5 Flash models
Gemini Omni (any output from any input, starting with video)
Google Antigravity in its new version
Managed Agents on Agent Platform

Check out the post that highlights these announcements in detail.

Google Cloud has introduced the general availability of Nano Banana 2 (Gemini 3.1 Flash Image) and Nano Banana Pro (Gemini 3 Pro Image) on the Gemini Enterprise Agent Platform and the Gemini API. These enterprise-grade models allow developers to integrate image generation and editing capabilities directly into their applications and workflows.

Long-running agent workflows is where the industry is moving. But how to manage and operate them reliably and efficiently. Google believes you can use Agent Executor, an open-source runtime standard designed for executing, resuming, and deploying distributed AI agents. The key technical capabilities of this standard include:

Durable execution to automatically resume progress via event logs and snapshotting after human-in-the-loop steps or outages
Secure isolation through sandboxes to safely execute code and manage multi-tenant workloads
Session consistency using a single-writer architecture to prevent state corruption
Connection recovery to allow disconnected clients to reconnect and backfill missed responses
Trajectory branching to let agents test alternative decision paths using checkpoints.

Check out the blog post for more details.

Looking to deploy and optimize large language models on mobile devices, take a look at new benchmarking and debugging capabilities within the Google AI Edge Portal. The platform allows developers to run automated testing across a fleet of over 120 Android device types to evaluate performance across CPU and GPU backends using the LiteRT-LM format. Check out the blog post.

Data Analytics

Data Agent Kit is an open-source collection of data engineering and data science skills, Model Context Protocol (MCP) tools, and plugins designed to connect development environments like VS Code and various CLIs with enterprise data. The kit provides pre-codified skills for tasks like query optimization, data validation, and troubleshooting, alongside MCP tools that create secure connections to platforms like BigQuery, AlloyDB, and Google Cloud Storage without requiring manual pipeline code. Check it out.

Remote Model Context Protocol (MCP) Server for AlloyDB is now in General Availability. The Remote MCP Server for AlloyDB runs on fully-managed Google Cloud infrastructure and exposes an HTTP endpoint that connects your AI applications to your data. It is integrated with the Agent Registry, supports fine-grained authorization, allows agents to not just run queries but also manage instances and more. Check out the blog post that highlights the features and a demo of how an agent has been integrate to work with AlloyDB.

Connected Sheets, which provides a direct connection between Google Sheets and BigQuery, has been there for a while. Instead of exporting data as CSVs, which causes version control and security risks, this feature allows users to perform ad-hoc analysis, modeling, and reporting on live data without writing SQL. Check out a blog post, which gives you a quick overview of Connected Sheets, walk through real-world use cases, and show you how to perform enterprise-grade data analysis using BigQuery directly in Google Sheets.

Databases

AlloyDB has got a significant upgrade to its High Availability (HA) architecture: Hot Standby. With the new architecture, the standby node continuously streams and applies write-ahead logs (WAL) from the primary node. This change allows the system to detect failures and promote the standby node within 30 seconds, dropping the average failover time to approximately 15 seconds. Furthermore, because the standby node constantly replays logs, its memory caches stay warm, allowing the database to maintain its transaction-per-second rate immediately after a failover without any performance brownouts. This feature is automatically rolled out to new instances on PostgreSQL 18 at no additional cost, with earlier versions receiving support in the following months. For more details, check out the blog post.

Developers & Practitioners

You are a developer working on building out Agents on Google technologies. How do you know which one to pick to develop these agents, since there are quite a few ranging from no-code to heavily code-driven frameworks. The article is an excellent way to step back and look at the existing landscape today to develop agents on Google Cloud, with options ranging from low code (Agent Studio) to ADK 2.0. Included in the spectrum is the recently announced Managed Agents API, which allows you to define agentic behavior and let Google Cloud handle the heavy lifting, acting as an agent-as-a-service with nothing to manage.

It is given that we need to secure our credentials, especially API Keys that may have been configured to have access to several Google Cloud services and could be a problem, if misused. But what are the recommended best practices to manage and secure your API Keys. This post goes into the detail while highlighting services like Secret Manager to manage/rotate keys, regular audits and more.

Reducing friction for developers trying out developer tools from Google and eventually deploying them on Google, has traditionally faced the common struggle of folks signing up for billing first. With a newly announced deeper integration between Google AI Studio and Google Cloud, you can now vibe code with Google AI Studio with a possible persistent layer backed by Firestore and deploy two applications on Google Cloud Run, without the need of a credit card. Check this out.

Gemini Live Agent Challenge has announced the winners and key highlights from the contest that asked developers to integrate real-time multimodal capabilities using the Gemini Live API, the Agent Development Kit (ADK), and Google Cloud infrastructure. The global challenge resulted in projects across three main categories:

Live Agent (Voice)
Creative Storyteller (Audio / Visual)
UI Navigator (Gesture-driven interactions)

Notable winners included ORION, a voice-directed surgical co-pilot for robotic surgery; drone-copilot, which replaces manual joysticks with natural language voice commands for navigation and autonomous visual inspections; and Moonwalk, a hands-free desktop assistant that automates workflows by controlling the keyboard and mouse through voice.

AI agent conversations usually go back and forth with a series of questions and usually the interactions end up with just text data and interpreting the intent and extracting data can be not just challenging but more efficient in terms of number of interactions. What if a set of questions that the Agent wants to ask of the user, is converted into a simple UI with the right kind of input controls to select the data from. For e.g. a dropdown, a few checkboxes, etc. Enter A2UI (Agent to UI) Protocol, an open protocol for agent-driven user interfaces and a great example of how this protocol can be embedded into the front-door Gemini Enterprise application is demonstrated in this blog post.

Customers

One of the interesting blog posts that I look forward to each month is one in which we can learn what customers have been building with Google Cloud. For the month of May, there were interesting things that they built. Some of which include:

Glance automated its short-form video extraction pipeline by combining Google Cloud Speech-to-Text v2, Gemini 2.5 Flash, the Google Vision API, Samurai object tracking, OpenCV, and MoviePy.
Urban Outfitters migrated its 11TB Oracle database to AlloyDB for PostgreSQL to power its IBM Sterling OMS, deploying two read replicas to lower data latency for reporting and analytics.
Movix engineered an agentic AI solution for dental lab quality control using the Gemini Enterprise Agent Platform alongside Cloud Run with L4 GPUs and Compute Engine VMs.

Check out the post for more of what cool things that customers built.

Containers and Kubernetes

Google Kubernetes Engine (GKE) Agent Sandbox helps you manage isolated, stateful, and single-replica workloads on GKE. It is optimized for use cases like AI agent runtimes, where untrusted, LLM-generated code must be executed in a secure and performant environment. The GKE Agent Sandbox is now generally available and there is a new introduction too, Agent Substrate. This open source project introduces a minimal control plane that moves agents on and off ready compute capacity in real-time while integrating data locality directly into its scheduler to minimize overhead. . Check out the blog post.

Security and Identity

If you are looking to protect your systems from high-speed, automated cybersecurity threats, Google Cloud has introduced Google AI Threat Defense, an autonomous platform built on a four-step framework: Prepare, Scan and Prioritize, Remediate, and Monitor. The system reduces attack surface exposure through Wiz, which maps your live environment and uses an AI penetration testing agent to validate exploitable pathways. When vulnerabilities are discovered, the platform incorporates Mandiant expertise for response planning while CodeMender automatically generates fixes, analyzes library dependencies, and creates verification tests directly inside the developer’s integrated development environment or command-line interface. Check out the blog post for more details.

The second Cloud CISO Perspectives for May 2026 is out. If you are looking to build an AI-ready security program for the public sector, this article outlines a structured, 12-month roadmap designed to manage complex systems and reduce operational toil. The plan is organized across five core workload domains: executive alignment, process optimization, talent augmentation, posture elevation, and advanced governance.

Infrastructure and Networking

There have been several architectural updates to Google’s global and data center networks designed to handle the specific traffic patterns and scale required for AI training and inference workloads. The new Virgo Network serves as a flat, two-layer scale-out data center fabric that connects up to 134,000 eighth-generation TPU chips, delivering increased bandwidth, lower latency, and autonomous reliability features like automated hang and straggler detection to isolate faulty instances. Read more here.

Given the kind of infrastructure that Google runs, it should be interesting to learn about how they ensure that any optimizations that they introduce to their infrastrcture takes place safely. In fact they run a fleet-wide, machine-level A/B experimentation framework. Instead of testing at the application level, Google enables changes on individual machines across a balanced 1% subset of the fleet to capture system-wide effects for core components like libraries, compilers, kernels, and cluster management systems. Check out the details here.

DevOps and SRE

SRE AI is an initiative that integrates agentic AI into Site Reliability Engineering. This includes deploying autonomous AI agents across the entire software development lifecycle. These agents assist in reliability design by creating and updating playbooks, use models like TimesFM for anomaly detection and alert enrichment, and orchestrate incident management by summarizing communications and drafting postmortems. For more details, check out the blog post.

Application Development

Google Cloud has introduced App-centric maintenance visibility within Unified Maintenance to shift planned maintenance tracking from an infrastructure-focused view to a business-oriented view. By integrating directly with App Hub, Unified Maintenance automatically aggregates the maintenance schedules of registered resources (GKE clusters, GCE VMs, or AlloyDB instances) into a single dashboard centered around the application as the primary unit of management. To use this feature, teams need to enable the Maintenance API and configure application boundaries in the Google Cloud Console. For more details, check out the blog post.

Continuing on Application Development, we now have a public preview of AppLifecycle Manager Feature Flags (ALM FF). This service decouples feature releases from code deployments, allowing teams to ship code with new features disabled by default and use a toggle as an instant kill switch if issues arise. Built on the open-source OpenFeature standard and the flagd evaluation engine, ALM FF uses Common Expression Language (CEL) to enable targeted rollouts, such as percentage-based traffic ramping or precise allowlisting for specific internal teams and testers. Check out the blog post.

Learn about Google Cloud

If you have been working with traditional transactional databases and are looking to transition enterprise data from static reports to autonomous systems, Google Cloud outlines a structural evolution across five technical scenarios to manage security, costs, and accuracy. These five scenarios are:

Scenario 1: The Static API Contract, which uses pre-written, parameterized SQL queries for deterministic performance.
Scenario 2: Custom Agent with SQL Generation, where an LLM translates natural language into queries using schema metadata.
Scenario 3: Conversational Analytics, which uses a platform-native engine grounded in verified query libraries to enforce business logic.
Scenario 4: Managed MCP Tools introduces the open-source Model Context Protocol (MCP) to decouple the reasoning layer from tool execution via a managed BigQuery server. This helps to scale across different systems.
Scenario 5: Custom Hosted MCP Servers gives engineers full control to build specialized, multi-source tools on infrastructure like Cloud Run, allowing for programmatic governance and custom data abstraction.

Check out the blog post that provides detailed guidance, queries and more.

Write for Google Cloud Medium publication

If you would like to share your Google Cloud expertise with your fellow practitioners, consider becoming an author for Google Cloud Medium publication. Reach out to me via comments and/or fill out thisform and I’ll be happy to add you as a writer.

Stay in Touch

Have questions, comments, or other feedback on this newsletter? Please send Feedback.

If any of your peers are interested in receiving this newsletter, send them theSubscribe link.

Antigravity CLI Tutorial Series: Part 2 : Conversations, Conversations and Conversations

Romin Irani — Sun, 24 May 2026 13:15:36 +0000

Welcome to Antigravity CLI Tutorial.

The Series:

Part 1 : Getting Started

Part 2 : Conversations, Conversations, Conversations (this blog)

Codelab : If you prefer to do a hands-on, step-by-step instructional codelab, go directly to the “Getting Started with Antigravity CLI Codelab”.

In this part of the series, we are going to understanding the mechanics of Conversations in Antigravity CLI.

You might already have your own definition of what a conversation means? And you would be right in your approximate definition of it. It is definitely a sequence or a thread of messages exchanged between you (user) and the agent.

But you would have multiple questions pop up like:

Are these conversations stored somewhere?
How do we manage multiple threads of conversation? Each thread having its own sequence of unique user and agent interactions.
Can we switch from one conversation to another?

And definitely a lot more questions along similar lines. What follows is my understanding of what Conversations are in Antigravity CLI and an attempt to get the answers to the above questions.

I call these as my experiments since the documentation is sparse at the time of writing and the source code is not open for me to take a peek into. So please correct me if I have hallucinated unintentionally. :-)

What is a Conversation?

First up, let usattempt to define what a conversation means and what better than to ask Antigravity CLI itself. It came up quite well:

In the context of Antigravity CLI, a conversation is an isolated work session or execution thread identified by a unique Conversation ID (e.g., 3b4a1d20–3968–4ed2–90b3–00eea3060b02 ).

Here is what defines a conversation:

State and History: Every conversation preserves a history of interactions (user requests, agent responses, tool calls, and system messages) serialized as JSON Lines (JSONL) transcripts under

/brain//.system_generated/logs/ .
Dedicated Artifacts: Each conversation has its own storage directory

( /brain// ) where structured markdown documents like the implementation_plan.md , task.md , and walkthrough.md are saved and updated.
Scratch Space: Conversations have a dedicated scratchpad directory ( /brain//scratch/ ) for temporary test scripts, helper files, or data files that persist across steps.
Agent Tree: When a main agent invokes a subagent, a new child conversation is spawned with its own ID, allowing agents to work in parallel on specialized sub-tasks while maintaining isolated context.

What is an appDataDir?

Good question. On my mac, it is in my $HOME/.gemini/antigravity-cli folder or ~/.gemini/antigravity-cli folder. So inside of this directory, you will find the following:

Inside this directory, you will find the following folder and sub-folders under it (not all subfolders are described):

brain/ : Contains subdirectories for each conversation (using their Conversation ID) containing:

— .system_generated/logs/ : Chat transcripts ( transcript.jsonl , transcript_full.jsonl ).

— Artifacts: Markdown files like implementation_plan.md , task.md , and walkthrough.md .

Conversation Management commands

There are several in-built commands in Antigravity CLI that we can use for conversation management. They are:

• /clear : Clears the screen and starts a fresh conversation thread.

• /resume (or /switch ): Displays a menu showing your previous conversations, allowing you to choose one to resume.

• /rewind (or /undo ): Rolls back the active conversation history to a previous step (useful if a command failed or you want to try a different direction).

• /fork : Branches the current conversation into a new workspace from a specific step, preserving history up to that point.

/rename : Renames the active conversation with a custom, readable title.

Let’s see it work

Let’s ensure that we are starting a fresh conversation thread. To do that, you can use /clear command. This can be used anytime to create a new conversation. This does not lose any of the previous conversation and we can always switch back to previous conversation threads. We will see all of that in a while.

But for now, just ensure that you have used the /clear command and are ready in Antigravity CLI.

Give the following prompt:

What is Google Cloud Run?

Antigravity CLI gets down to work and produces the following output:

● WebSearch(Google Cloud Run overview features) (ctrl+o to expand)

  Google Cloud Run is a fully managed, serverless platform by Google Cloud that allows you to run containerized applications and services without having to manage the underlying server infrastructure. It combines the flexibility of        
  containers with the simplicity of serverless computing.                                                                                                                                                                                      

  ### Key Features                                                                                                                                                                                                                             

  • Fully Managed & Serverless: Google automatically handles infrastructure management, including server provisioning, operating system maintenance, and scaling.                                                                              
  • Automatic Scaling: Cloud Run scales automatically based on incoming request traffic. It can scale up to thousands of instances to handle high demand, and scale down to zero when there is no traffic, meaning you only pay when your      
  application is actively handling requests.                                                                                                                                                                                                   
  • Any Language or Library: Since it runs Docker/OCI-compliant containers, you can write your application in any programming language (e.g., Python, Node.js, Go, Java, Rust) and use any system library or custom dependency.                
  • Deploy from Source or Container: You can deploy an existing container image from Google Artifact Registry or deploy directly from your source code repository. If deploying from source, Cloud Run uses Google Cloud Buildpacks to         
  automatically package your code into a container.                                                                                                                                                                                            
  • Two Execution Modes:                                                                                                                                                                                                                       
      • Cloud Run Services: For web apps, APIs, microservices, or event-driven applications that respond to incoming web/HTTP requests or gRPC calls.                                                                                          
      • Cloud Run Jobs: For short-lived, run-to-completion tasks (like database migrations, nightly backups, or batch data processing) that do not serve web traffic.                                                                          
  • Hardware and AI Acceleration: It supports deploying workloads on GPUs (such as NVIDIA L4) and using larger machine configurations, making it a viable serverless platform for hosting Large Language Models (LLMs) and running AI inference
  workloads.                                                                                                                                                                                                                                   
  • Integrations: It integrates natively with other Google Cloud services (such as Pub/Sub, Cloud Storage, and Eventarc for event-driven workflows) and supports VPC connectivity to securely access private databases or other internal       
  resources.

But what has it done behind the scenes to persist this conversation thread.

Step 1

The Antigravity CLI instantly performs the following directory setup (I am assuming the following conversation id → 11111111–2222–3333–4444–555555555555):

Creates the Conversation Root Folder:

~/.gemini/antigravity-cli/brain/11111111–2222–3333–4444–555555555555/

Creates the System Logs Folder:

~/.gemini/antigravity-cli/brain/11111111–2222–3333–4444–555555555555/.system_generated/logs/

Creates the Scratchpad Directory:

~/.gemini/antigravity-cli/brain/11111111–2222–3333–4444–555555555555/scratch/ (This folder remains empty until the agent needs to write temporary test scripts or run one-off diagnostics).

Step 2: Logging the Initial Prompt (Internal System Logs)

The CLI creates two JSON Lines files under the .system_generated/logs/ folder:

• transcript.jsonl (assuming that this is a token-efficient log containing truncated text for large outputs)

• transcript_full.jsonl (assuming that this is a full, untruncated log containing exact tool results and text)

If you visit the transcript.jsonl file, you will notice that a JSON record representing your first input step is appended (few fields only since there is a lot of metadata too):

{
 "step_index":0,
 "source":"USER_EXPLICIT",
 "type":"USER_INPUT",
 "status":"DONE",
 "content":"What is Google Cloud Run?"
}

You will also see multiple steps being recorded next in terms of how Antigravity CLI is planning out its execution. I will only reproduce the steps / types, etc and it will be good enough for you to understand. I encourage you to inspect the files on your machine to see all the wonderful details.

{"step_index":1,"source":"SYSTEM","type":"CONVERSATION_HISTORY"...}
{"step_index":2,"source":"MODEL","type":"PLANNER_RESPONSE","status":"DONE","created_at":"2026-05-24T12:14:37Z","tool_calls":[{"name":"search_web","args":{"query":"\"Google Cloud Run overview features\"","toolAction":"\"Searching the web\"","toolSummary":"\"Web search\""}}]}
{"step_index":3,"source":"MODEL","type":"SEARCH_WEB","status":"DONE","created_at":"2026-05-24T12:14:38Z","content":"Created At: 2026-05-24T12:14:38Z\nCompleted At: 2026-05-24T12:14:43Z\nThe search for \"Google Cloud Run overview features\" returned the following summary:\nGoogle Cloud Run is a fully managed, serverless platform that allows you to run containerized applications and services without managing the underlying infrastructure[1][2][3]. It is designed to combine the flexibility of containers with the simplicity of a serverless environment[4].\n\n### Core Features\n\n* **Fully Managed & Serverless:** Google handles all infrastructure management, including provisioning, scaling, and maintenance[1][2]. You simply provide your code or container[3][4].\n* **Automatic Scaling:** Cloud Run s.....}
...
{"step_index":5,"source":"MODEL","type":"PLANNER_RESPONSE","status":"DONE","created_at":"2026-05-24T12:14:46Z","content":" **Google Cloud Run** is a fully managed, serverless platform by Google Cloud ...}

In this way, your current conversation as you go back and forth is persisted.

See what happens if you give a follow up message that says:

What kind of applications can I deploy on Google Cloud Run?

Once you get the response in Antigravity CLI terminal, go back to the conversation id folder and you will see additional steps in the transcript.jsonl file:

{"step_index":6,"source":"USER_EXPLICIT","type":"USER_INPUT","status":"DONE","created_at":"2026-05-24T12:27:18Z","content":"<USER_REQUEST>\nWhat kind of applications can I deploy on Google Cloud Run?\n</USER_REQUEST>\n<ADDITIONAL_METADATA>\nThe current local time is: 2026-05-24T17:57:18+05:30.\n</ADDITIONAL_METADATA>"}
{"step_index":7,"source":"MODEL","type":"PLANNER_RESPONSE","status":"DONE","created_at":"2026-05-24T12:27:18Z","content":"You can deploy a wide variety of applications on...}

Step 3: Agent Analysis and Planning (If coding changes are needed)

Now, let’s say we go a step further and ask it to actually generate/code a sample application for us that can be deployed on Cloud Run:

Create a single page HTML / JavaScript application to deploy on Cloud Run that takes my name and returns me a greeting.
Let's plan it out first.

Here I am specifically asking it to plan it out first. It comes back saying:

 I have created the implementation plan for the Google Cloud Run greeting application.                                                                                                                                                        

  Please review the proposed design and files in the implementation_plan.md artifact. Once you approve, let me know and we will proceed to verify it.

This behind the scenes creates:

~/.gemini/antigravity-cli/brain/11111111–2222–3333–4444–555555555555/implementation_plan.md

Depending on how you proceed, additional markdown files (walkthrough, task list, etc) will be created in the same folder.

As an experiment, go ahead with approving the implementation plan. This will make Antigravity CLI generate the code, test out the server, etc. This will result in additional folders being created but all within the brain/CONVERSATION_ID folder.

If you navigate to your app data folder during/after a coding conversation, here is exactly what you would start seeing something like this:

~/.gemini/antigravity-cli/
└── brain/
└── 11111111–2222–3333–4444–555555555555/ ← Root of the conversation
├── .system_generated/
│ └── logs/
│ ├── transcript.jsonl ← Truncated log
│ └── transcript_full.jsonl ← Untruncated full log
├── implementation_plan.md ← Technical design spec
├── task.md ← Interactive checklist
└── walkthrough.md ← Work summary & verification

A few other things worth mentioning are:

You will find a history.jsonl within the ~/.gemini/antigravity-cli folder that seems to be a index of all conversations.
A conversations folder that holds the conversations in a protocol buffer format. We can leave it as is for now.

Let’s Rewind

What if we want to go back at a point in time in the conversation. Remember we started with asking about Google Cloud Run, then we asked it to generate code for the application and so on. As a result of which, several code files, artifacts etc have been generated.

If I go into shell mode and see the current files in the folder, you can see from the output below, the files that are currently present. So far so good.

● ! ls
  ⎿ Dockerfile
     node_modules
     package-lock.json
     package.json
     public
     README.md
     server.js

Now, give the /rewind command and you should see a list of all interactions that you have had. In my case, you see the current conversation thread with the list of interactions. I can use the keyboard to go up at the specific point in time before the files were generated (8 files changed, etc).

──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Rewind Conversation

  What is Google Cloud Run?

> What kind of applications can I deploy on Google Cloud Run?

  Create a single page HTML / JavaScript application to deploy on Cloud Run tha...
    8 files changed +583 -1

  Could you first plan it out?
    1 artifact generated

  what is the history.jsonl file that you are managing for the conversations

  what is a .pb file and how are you using it for conversations

  (current)

Keyboard: ↑/↓ Navigate enter Select esc Cancel

Once I select to rewind it to a step before all the files were generated and execute that step, it will remove the files generated as is evident from the outputs that I now see.

● ! ls
  ⎿ node_modules
     package-lock.json
     public

The implementation_plan.md and other artifact files also go away from the brain/CONVERSATION_ID folder that we earlier saw. You can try out these scenarios on your machine.

Saving a Conversation with a different name

At any point in time, you can save the conversation with a name that is easier or makes sense to you in terms of the entire thread. Just use the /rename command.

In Antigravity CLI, I simply give the rename Google Cloud Run basics to rename this conversation. It comes back with the following message:

> /rename
  ⎿ Conversation renamed to: Google Cloud Run basics

Switching between Conversations

You can use the /resume or /switch command to switch to another conversation. For example, I see the following:

   CLI Antigravity (tab to cycle)

  Conversations
  Type to search...
> [CURRENT] Google Cloud Run basics 10 steps 8m ago
  Understanding Antigravity CLI Conversations 24 steps 52m ago
  hello 4 steps 1h ago

Keyboard: ↑/↓ Navigate ←/→ Page enter Select f2 Rename ctrl+delete Delete tab Switch Tab esc Go back / Clear search

You can see that our current context is now with our preferred name Google Cloud Run basics and the other ones that you see in the list are the ones that I had here. But you might see another list.

Select any one of these to switch to that conversation and carry on that conversation from there or maybe even rewind, etc.

Switching to an Antigravity conversation

If you have been paying attention to the output shown in the /switch command, you might see an Antigravity and CLI option. This might happen only if you have also installed the non-CLI option i.e. Antigravity on your machine. In my case I have and have interacted a bit with it.

But what is pleasantly surprising is that it is now showing me conversations that have been saved via Antigravity and allowing me to import them. Whew! Let’s try this out:

   CLI Antigravity (tab to cycle)

  Conversations
  Type to search...
> Extracting Invoice Information [Import this conversation? (y/n)] 20 steps 2h ago
  Generate a events website but let's discuss the requirements first. 67 steps 1d ago

Keyboard: ↑/↓ Navigate enter Select tab Switch Tab esc Go back / Clear search

So I select one of the conversations (Extracting Invoice Information) and then press on Enter. It asks me that it needs to import this conversation. This brought up the previous conversation and I was able to carry on with a new message in the thread. Wonderful. Probably this needs a lot more testing.

  <PREVIOUS _ CONVERSATION _ THREAD >

────────────────────────────────────────────────────────────
> What are the files sizes for each of the invoices

● ListDir(/Users/romin/agy-cli-projects/invoice-processing) (ctrl+o to expand)

  Here are the file sizes for each of the invoice image files in your directory:                                                                                                                                                               

  • inv1.png: 273,828 bytes (approx. 273.8 KB)                                                                                                                                                                                           
  • inv2.png: 369,086 bytes (approx. 369.1 KB)                                                                                                                                                                                           
  • inv3.png: 446,932 bytes (approx. 446.9 KB)                                                                                                                                                                                           
  • inv4.png: 343,328 bytes (approx. 343.3 KB)                                                                                                                                                                                           

  (Note: The CHUBB.pdf insurance document size is 42,965 bytes / approx. 43 KB).

One more thing

If you quit your Antigravity CLI at this point, you will notice that there is a message at the end that looks something like this:

Resume: agy --conversation=d1d8a55b-cc27-4dd4-bc62-2f73015960d2 (or -c)

That’s right. Antigravity CLI comes with a command line option to resume a specific conversation via the --conversation or -c parameter. This value has to be the unique conversation id that you see. I think this is useful but might be a bit unwieldy to remember or use.

In any case, the key message is that you now what is going on with this unique conversation id , where the stuff is persisted on your local machine and can discover more. In any case, you can always launch Antigravity CLI and use the /switch command to go to a specific conversation thread. Just remember to use /rename to name them in a way that you understand.

Conclusion

While a conversation in Antigravity CLI is something that is managed behind the scenes for you, it is helpful to understand how the tool is working. Hopefully these examples give you a good idea of what is happening under the hood. I will keep adding more examples to this as I understand this better. See you in latter parts of the series.

Antigravity CLI Tutorial Series

Romin Irani — Fri, 22 May 2026 15:08:49 +0000

Getting Started with Antigravity CLI : Tutorial Series

Welcome to the Antigravity CLI Tutorial Series. Antigravity CLI is the terminal-first interface to work with Antigravity Agents. It can be used for all kinds of tasks ranging from coding to automating repeated tasks.

Welcome to Antigravity CLI Tutorial.

The Series:

Part 1 : Getting Started(this blog)

Part 2 : Conversations, Conversations, Conversations

Codelab : If you prefer to do a hands-on, step-by-step instructional codelab, go directly to the “Getting Started with Antigravity CLI Codelab”.

Antigravity CLI is part of the Antigravity 2 release. As the documentation states, “It brings the same core agentic capabilities as Antigravity 2.0 — including multi-step reasoning, multi-file editing, tool calling, and conversation history — directly to your terminal.”

Reference: https://antigravity.google/product/antigravity-cli

Here are a few highlights at the time of the initial announcement, in terms of what Antigravity CLI brings to the table:

Faster Execution: The new CLI is built in Go, making it noticeably snappier and more responsive than its predecessor.
Asynchronous Workflows: This is a huge productivity boost. Users can now run large-scale tasks (like codebase refactors or deep research) in the background. The CLI will orchestrate the agents without locking up the active terminal session.
Unified Architecture: The CLI shares the same backend agent harness as the new desktop app, Antigravity 2.0. This means any future improvements to the core agents will instantly apply to the terminal experience.

If you are looking for Gemini CLI, this is not the same as Antigravity CLI. Gemini CLI is the open-source version terminal interface that lets you use the power of the Gemini model for your tasks via natural language. It has its own ecosystem of Extensions and I have written a tutorial series on that earlier.

Blog Updates

04-Jun-2026 : Added section on understanding what changes have happened to Antigravity CLI via the agy changelog command. Added a new section on models subcommand introduced in 1.0.5 to get the current list of models supported and how to pass the model to the Antigravity CLI via the --model command-line parameter.

24-May-2026 : Added section on AGY CLI command-line parameters. Updated installation section with agy update command.

23-May-2026 : Updated the installation instructions. Added new sections on /btw command and /context command to visualize context.

Installation

The installation is straightforward and binaries are available across major Operating System. I have taken the commands to run in the terminal directly from the installation document:

macOS | Linux

curl -fsSL https://antigravity.google/cli/install.sh | bash

Windows PowerShell

irm https://antigravity.google/cli/install.ps1 | iex

Windows CMD

curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd

This should ideally setup and install the Antigravity CLI (agy) in your system and in the Path.

For e.g. on my MacOS , the installer copied and setup the following executable here: /Users/romin/.local/bin/agyand there was an entry made in the profile to add that folder to the path.


# Added by Antigravity CLI installer
export PATH="/Users/romin/.local/bin:$PATH"

In some cases, if the installer is not able to add the binary ( agy to the PATH), it will say so. For e.g. on another machine, I saw the following output, where it will clearly tell you what to do, to add it to the PATH.

% curl -fsSL https://antigravity.google/cli/install.sh | bash
⠋ Detecting system environment...
✓ Platform detected: darwin_arm64
⠋ Querying release repository...
✓ Latest available version: 1.0.1
⠋ Downloading release package...
✓ Download complete and checksum verified.
⠋ Extracting binary from archive...
⠋ Configuring shell environment...
I0523 11:44:14.012088 76528 installer.go:27] Running Antigravity CLI setup...
Warning: /Users/neilirani/.local/bin is not present in your active PATH.
To use the 'agy' CLI globally, please manually add it to your shell profile:
  echo 'export PATH="/Users/neilirani/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
✅ Antigravity CLI binary placed successfully at /Users/neilirani/.local/bin/agy
Note: The binary is installed, but it is not in your active PATH. Please follow the instructions above to add it, then restart your terminal session.

I suggest that we start with a specific folder agy-cli-projects and work through that for the rest of the tutorial.

Create a folder named agy-cli-projects and navigate into that. I have created it in my home folder but you can do that based on your preference.

Just check out the version of Antigravity CLI via the following command:

$ agy --version
1.0.2

Updating Antigravity CLI

You can update Antigravity CLI at any time via the agy update command. This checks for newer versions and then downloads and updates your current local installation.

Changelog

It is a good idea to check the changelog to get a sense of the updates that have happened across different versions of Antigravity CLI. Use the agy changelog command for that. A sample (partial) run for the latest update at the time of writing is shown below:

$ agy changelog
1.0.5:
· Added `--model` to set model when launching CLI. Also a new `models` subcommand to list available models.
· Added `/permissions` command which allows to add/edit/remove permissions rules for each of the three configs above directly inside the CLI.
· Allowed opening the Artifact Review panel (shortcut `ctrl+r`) while answering pending questions or tool permission confirmations, preserving your current progress when toggling back.
· Fixed a bug that metadata was written in the current directory as opposed to `~/.gemini/antigravity-cli/cache` when running using `-p`.
· Improved statusline layout by merging active tip and artifact status on a single line and truncating with ellipsis on narrow terminals to prevent collisions.
· Improved customization support by allowing directories in the customization manager to be passed as workspace directories, enabling correct trajectory metadata population and `/add-dir` support.
· Added support for `url` in `mcp_config.json` to configure MCP servers directly via a URL.
· Improved `/resume` performance: optimized lazy loading of conversation details, filtered out empty conversations, and added support for scanning SQLite database files (`.db` and `.db-wal`).
· Improved autocomplete: tab completion for slash commands now resolves to the matched alias instead of the primary command name (e.g., `/se` autocompletes to `/settings` instead of `/config`).
· Integrated the permissioning system with the rest of Antigravity. CLI permissions now merges project level permissions, permissions from user settings shared with Antigravity, and permissions from the CLI `settings.json`.

1.0.4:
· Added SQLite (.db) conversation support and will be CLI’s conversation format. Fixed a bug when importing SQLite conversation from Antigravity 2.0 to CLI.
· Added LaTeX math rendering, enabling the CLI to display beautiful mathematical formulas directly in the terminal viewport. Set `AGY_CLI_DISABLE_LATEX` environment variable to turn off LaTeX rendering globally if desired.
· Decoupled project discovery from local `.antigravitycli` workspace directories. The CLI now stores workspace-to-project mappings in a centralized `~/.gemini/antigravity-cli/cache/projects.json` file, eliminating repository clutter and speeding up project discovery to a single-map lookup.
· Resolved sporadic and permanent UI hangs caused by a stateful callback streamer race condition during network drops or extremely fast agent steps.
· Collapses all newlines and consecutive whitespaces in conversation previews and titles before rendering list items, preventing visual UI layout breaks in the picker rows.
· Styled the separator space between the line number column and diff content to match the text blocks, ensuring background highlights stretch seamlessly across the viewport width in tool outputs and `/diff` details.
· Resolved inconsistent behavior where selecting skill-derived slash commands from autocompletion suggestions cleared the input without executing. Autocompleted skill commands are now correctly submitted to the backend.
...

1.0.3: ...

1.0.2: ...

Logging into Antigravity CLI

When we launch Antigravity CLI for the first time, it will ask you to login. Launch agy and it should show something similar to this:


     ▄▀▀▄
    ▀▀▀▀▀▀
   ▀▀▀▀▀▀▀▀
  ▄▀▀ ▀▀▄
 ▄▀▀ ▀▀▄

 Welcome to the Antigravity CLI. You are currently not signed in.

 Select login method:
 > 1. Google OAuth
   2. Use a Google Cloud project

 [Use arrow keys to navigate, Enter to select]

Use your personal account for now. Choose 1. Google OAuth and press Enter. This will launch a browser and you can login with your Google Account. On successful authentication and authorization, you are asked to copy a code. Please come back into the Antigravity CLI terminal and paste the code.

Once the login is successful, a few things happen:

First up, it asks you about the color theme that you wish to choose for Antigravity CLI, as shown below. Pick the one that you like.

Next up, you need to accept a few terms of service:

Finally, the most important thing is to give your permission that you trust the folder, as shown below:

Accessing workspace:

/Users/romin/agy-cli-projects

Do you trust the contents of this project?

Antigravity CLI requires permission to read, edit, and execute files here.

> Yes, I trust this folder
  No, exit

  ↑/↓ Navigate · enter Confirm
                                                                                                                                   Gemini 3.5 Flash (High)

You will see this typically in any new folder that you launch the Antigravity CLI on. We will come to more on this later in the series but for now, go ahead and say Yes, I trust this folder.

You are all set now and its waiting for your prompt:


      ▄▀▀▄ Antigravity CLI 1.0.1
     ▀▀▀▀▀▀ <YOUR_ACCOUNT_EMAIL>
    ▀▀▀▀▀▀▀▀ Gemini 3.5 Flash (High)
   ▄▀▀ ▀▀▄ ~/agy-cli-projects
  ▄▀▀ ▀▀▄

───────────────────────────────────────────────────────────
>
───────────────────────────────────────────────────────────
? for shortcuts Gemini 3.5 Flash (Medium)

Antigravity CLI — A few housekeeping commands

Notice that it is using Gemini 3.5 Flash as shown in the bottom right. The first thing ideally is to understand that most of the customization and settings that you need to do are available via the /config or /settingscommand.

Configuration / Settings

Go ahead and invoke the /config command. This will bring up various areas of Antigravity that you can customize based on your preferences. This includes the Color Scheme, Tool permission, telemetry settings and more.

For example, the Color Scheme brings up the following options, from which I can choose my preferred color scheme:

settings.json

The configuration settings need to be stored somewhere right? All of them get stored in ~/.gemini/antigravity-cli/settings.json file. A sample is shown below:

{
       "colorScheme": "dark",
       "model": "Gemini 3.5 Flash (High)",
       "statusLine": {
         "type": "",
         "command": "",
         "enabled": true
       },
       "trustedWorkspaces": [
         "/Users/romin/antigravity-cli-projects",
         "/Users/romin/agy-cli-projects"
       ]
     }

You can notice the colorScheme that I have selected, the model and also various folders from where I have started Antigravity CLI and said yes to trusting the folders.

Note: You can modify the settings.json directly too and restart Antigravity CLI as a best practice to see the changes. But be sure of the settings, else it will display an error at startup. I suggest that given that the documentation is sparse at the moment, use the /settings or /config command in the Antigravity CLI to work with this file.

Tool Permission

An important setting to understand is the Tool Permission and I show the options below. You can get to this via the /config command.

Tool Permission
  > request-review (current)
    proceed-in-sandbox
    always-proceed
    strict

By default, it is set to request-review. Let’s understand this in more detail:

In Antigravity, Tool Permission settings control the balance between security (guarding your host system against unintended changes) and velocity (how autonomously the agent can work without pausing for your input).

request-review (Current Default)

In this mode, the agent is treated as a collaborative partner that checks in before performing any action that could affect your system or project files outside of pre-approved bounds.

How it works: Whenever the agent attempts to run a terminal command, perform a file operation (like writing/deleting), or call an external service where permission hasn’t been pre-approved, the execution pauses. The user is prompted to approve or reject the specific action.

Example:

The agent needs to install a package using npm install lodash.Instead of running the command immediately, the CLI pauses and shows a prompt as shown below, and you have choice to decide whether to allow it to proceed or so on. It is recommended that you can keep this default setting, so that you get familiar with how your commands are being run.

Requesting permission for: npm install lodash

Do you want to proceed?
> 1. Yes
  2. Yes, and always allow in this conversation for commands that start with 'npm install'
  3. Yes, and always allow for commands that start with 'npm install' (Persist to settings.json)
  4. No

proceed-in-sandbox

This mode allows the agent to execute terminal commands automatically, but within a secure, isolated container. The agent can run commands without prompting you, but those commands are executed in a virtualized sandbox (e.g., a lightweight container). They cannot modify your actual host machine’s filesystem or access your local network.

always-proceed

This is the fully autonomous mode, giving the agent maximum speed and capability. The agent is granted full permission to run commands and write files directly on your host machine. It will never prompt you for confirmation.

Example:

You leave a long-running task running overnight using the /goal command (e.g., “Refactor our styling system to use vanilla CSS and ensure all components build without error”). In this scenario, The agent writes dozens of files, runs npm run build , resolves compiler errors, installs helper packages, and runs git commands entirely on its own. The work completes without ever pausing to wait for your approval. (Use with caution: only use this in trusted, version-controlled repositories).

strict

This is a zero-trust, high-security mode. The agent’s capabilities are restricted to executing read tools. All non-read tools will require the user to be prompted for action.

Set a model

You can use the /model command to select a model that will be used. At the time of writing, this is the list of models shown when you use the /model command:

Switch Model

> Gemini 3.5 Flash (High) (current)
  Gemini 3.5 Flash (Medium)
  Gemini 3.1 Pro (High)
  Gemini 3.1 Pro (Low)
  Claude Sonnet 4.6 (Thinking)
  Claude Opus 4.6 (Thinking)
  GPT-OSS 120B (Medium)

Keyboard: ↑/↓ Navigate enter Select esc Go Back

You can choose any of the models as needed, based on your preference.

You do have an option of setting the model while starting a agy session. You can do that via the agy --model "model_name" command line options. This will then use a specify model for that session. This is very useful if you wish to start the agy session in an autonomous mode i.e. via the --prompt option. Take a look at the command-line options discussed later in this blog.

Antigravity CLI Reference (List of Commands and Shortcuts)

What are the commands and keyboard shorcuts Antigravity CLI. The command as expected /help is your friend. Alternately, you can just type a ? to get this list.

Try it out to see the range of commands available and learn a few shortcuts to navigate the terminal easily.

Here are all 34 commands available in 1.0.1 at the time of writing. Try out a few if you’d like. We will cover several of them as we go along in the series.

Changelog

Antigravity CLI is likely to undergo rapid changes. We saw that with Gemini CLI earlier, where there were almost daily updates. While we cannot predict the velocity of the releases, its good to know what is changing across the releases via the /changelog command. We are already seeing a good list of changes between the current version 1.0.1 vs 1.0.0 as shown below:

Exit Antigravity CLI

This can be done via the /quit command. If you are having difficulty to get to the prompt input, use esc esc to come out where you are.

Whenever you exit, you will see the command that is needed to continue the conversation. As an example, this is what I received. If you do that, you can resume the conversation and will have an entire list of prompts that you gave. Just use Arrows Keys (up and down) in the prompt to see the history.

Resume: agy --conversation=bbb2048c-7de6-4dd5-ba7e-8b0c27d46b95 (or -c)

Shell mode

This is similar to Gemini CLI and you can enter into a Shell mode, such that you can give shell commands without the need to exit Antigravity CLI and come back again to it.

Simply use the ! to go into Shell mode. You will notice that the prompt prefix will change from > to ! as shown below:

You can give commands like ls, pwd and other utilities that you might have too.

Our first coding task

I am going to create a folder inside of agy-cli-projects and start my Antigravity CLI inside of that. I have named the folder bq-release-notes since I am going to create a BigQuery Release Notes Reader application.

Let’s give Antigravity CLI our first task and ask it to build a web application that displays the content of a current RSS feed. Let’s say that I am very much interested in BigQuery Release notes. There is a RSS Feed for it.

I would like a web application in my prefered stack to be build to access this feed and show me the information.

I begin with the following prompt:

Please build a web application for me using Python Flask and plain vanilla HTML, JavaScript and CSS that fetches the BigQuery Release notes from (https://docs.cloud.google.com/feeds/bigquery-release-notes.xml) and shows them to me. A simple refresh button with a spinner is good enough, anytime I’d like to refresh the details. I would also like the ability to take any specific update, select it and then Tweet about it.

This results in the following response from Antigravity CLI:

  I will start by exploring the workspace to see if there is an existing structure or if this is a brand new project.                                                                    

● ListDir(/Users/romin/agy-cli-projects/bq-release-notes) (ctrl+o to expand)

  I will read the BigQuery release notes XML feed to understand its structure (Atom/RSS elements, entry/item elements, namespaces, dates, titles, content) so that we can parse it       
  correctly in the Python Flask backend.                                                                                                                                                 

● ReadURL(https://docs.cloud.google.com/feeds/bigquery-release-notes.xml) (ctrl+o to expand)

  I will view the fetched feed content saved locally to understand its format and structure.                                                                                             

● Read(/Users/romin/.gemini/antigravity-cli/brain/116191af-e6ea-4ba5-aa23-62f995bd068a/.system_generated/steps/6/content.md) (ctrl+o to expand)

▸ Thought for 2s, 2.3k tokens
  Analyzing XML Feed Structure
  I will write the implementation plan detailing the architecture, design aesthetic, components, and verification steps for the BigQuery Release Notes Web Application. This plan will be
  written to the artifacts directory.                                                                                                                                                    

● Create(/Users/romin/.gemini/antigravity-cli/brain/116191af-e6ea-4ba5-aa23-62f995bd068a/implementation_plan.md) (ctrl+o to expand)

  I have created the implementation_plan.md to outline the design and architecture of the BigQuery Release Notes Web Application.

  Please review the plan, especially the approach for the Twitter Composer & Preview Card, and let me know if you approve or if there are any adjustments you'd like to make!            

                                                                                                                                                            1 artifact · /artifact to review

Remember that behind the scenes, you get the same Antigravity harness and if you are familiar with Antigravity, you can see that it has created an artifact (file) for us to view. Artifacts are how the Antigravity CLI keeps us in the loop with an implementation plan, list of tasks that it is working on, verifiable outputs and more.

In this case, if you notice, it says and I quote “I will write the implementation plan detailing the architecture, design aesthetic, components, and verification steps for the BigQuery Release Notes Web Application. This plan will be written to the artifacts directory.”

Once it does that, it says “ I have created the implementation_plan.md to outline the design and architecture of the BigQuery Release Notes Web Application. Please review the plan, especially the approach for the Twitter Composer & Preview Card, and let me know if you approve or if there are any adjustments you’d like to make!”

You can see that it also mentions in the bottom right, that there is 1 Artifact to review and in this case, it is the implementation_plan.md.

Now remember, this is all in the terminal, so we will have to use that and see how it goes. It’s pretty neat if you ask me.

Give the command /artifact. This will display the following:

This clearly shows that there is a file implementation_plan.md created and I can use the arrow keys to open, approve, reject and so on. This should be familiar to those who have used earlier or even the recent version of Antigravity (the non-CLI app).

On opening it, I can see the entire artifact i.e. Implementation plan.

Just Escape and come back to the prompt, here you can approve it , if you’d like:

Alternately, you can reject or even converse with some changes or modifications that you like. For e.g. we will go full vibe mode and say approve.

This kicks off the next set of steps, where it will start the implementation i.e. creating files, running a few commans, etc. You will be prompted to approve and give permission to execute, as required.

In my case, I gave it the approval to create the Python virtual environment, install the dependencies via requirements.txt and so on.

In the background, it has also created a task.md file as part of the tasks that it has to do based on the implementation plan and it ticks off the individual tasks, as it completes them. You will just have to pay attention to the thought process and the tasks as it completes them. It makes for a fascinating experience.

Finally I get the message that I wanted to see:

I have successfully completed the implementation of the BigQuery Release Pulse web application!

The application dev server is up and running locally at http://127.0.0.1:5000.

Please refer to the walkthrough.md for details on the architectural implementation, the features we delivered, and verified test scenarios.

I also see that there are several artifacts as expected (Implementation Plan, Task List and a Walkthrough document)

Action required (3 left)
› task.md open 
  walkthrough.md
  □ new implementation_plan.md

  Media · 1 items (enter to expand)

If I look at the Task artifact, I get the following:

 task.md 
> 1 Tasks                                                                                                                                     
    2                                                                                                                                                
    3 [✓] Setup dependencies and environment                                                                                                     
    4 [✓] Implement backend Flask application ( app.py )                                                                                         
    5 [✓] Implement frontend HTML structure ( templates/index.html )                                                                             
    6 [✓] Implement frontend CSS styling ( static/css/style.css )                                                                                
    7 [✓] Implement frontend JS logic ( static/js/app.js )                                                                                       
    8 [✓] Verify local execution and manual test scenarios                                                                                       
    9 [✓] Create walkthrough documentation ( walkthrough.md )

Good work.

I check the application in my browser and here it is. It looks great with a lot of features already thought out:

Here’s my Tweet feature too:

I can go on now with new features, some changes, etc. But we can stop for now. The idea was to demonstrate and check out what it can do with simple requirements.

Our first non-coding Task

Go to https://github.com/rominirani/gemini-cli-codelab-projects and check out the folder invoice-processing folder that has several invoices in the form of images.

Let’s create a new folder inside of agy-cli-projects named invoice-processing. Download the four files into that folder and launch Antigravity CLI from there. You can take a peek into any of the invoices. One of the files is shown below (its an image):

You can use the Shell mode ( ! ) and then use the ls command to verify if you see the four invoice files there.

● ! ls
  ⎿ inv1.png
     inv2.png
     inv3.png
     inv4.png

Now give the following prompt:

Use @inv1.png and extract the following invoice information in the form of a table: Invoice No, Invoice Date, Invoice Sent By, Due Date, Due Amount.

Notice that you can use @ and you will see a list of files that will come up and you can choose from them. In short, I am asking Antigravity CLI to analyze this image file and extract relevant information of the invoice that I am interested in.

I get the following output:

  Analyzing Invoice Contents
  Here is the extracted invoice information from inv1.png:                                                                                      

   Invoice No │ Invoice Date │ Invoice Sent By │ Due Date │ Due Amount
  ─────────────────────────────┼─────────────────────────────┼─────────────────────────────┼─────────────────────────────┼────────────────────────────
    01234 │ 11.02.2030 │ Adeline Palmerston │ 11.03.2030 │ $440

I can even ask it to simply go through the folder and extract information from all the invoices present in the folder. Here is the prompt:

The current folder contains a list of invoice files in Image format. Go through all the files in this folder and extract the following invoice information in the form of a table: Invoice No, Invoice Date, Invoice Sent By, Due Date, Due Amount.

Here is the output:

Here is the extracted invoice information from all four files in the folder:                                                                        

   File │ Invoice No │ Invoice Date │ Invoice Sent By │ Due Date │ Due Amount
  ─────────────────────┼──────────────────────┼────────────────────┼────────────────────────────────────────┼────────────────────┼────────────────────
   inv1.png │ 01234 │ 11.02.2030 │ Adeline Palmerston │ 11.03.2030 │ $440.00
   inv2.png │ US-001 │ 11/02/2019 │ East Repair Inc. │ 26/02/2019 │ $154.06
   inv3.png │ 123456789 (P.O. #) │ November 23, 2023 │ A Company With A Clever Name (docubee) │ November 30, 2023 │ $42.30
   inv4.png │ [123456] │ 12/9/2019 │ Company Name │ 1/8/2020 │ $971.56

I could even go a bit different and ask it to highlight all invoices that are having payment date that has passed.

list all files with .png extension in this folder. Extract the invoice information from it by reading them locally and display it in a table format containing the following column headers: : Invoice No, Invoice Date, Invoice Sent By, Due Date, Due Amount. Add a column at the end of the table that shows a red cross emoji in case the due date is in the past.

Here’s the output:

I suggest that you go ahead and try out all kinds of tasks that are non-coding related. Analyzing some files, organizing them and so on.

Schedule an instruction

You can use the /schedule command to automate recurring tasks or set one-time reminders.

Let’s see how things work, when we just give the /schedule command. I get the following helpful reply:

/schedule

  Would you like to set up a recurring cron schedule or a one-time timer?                                                                             

  Please specify:                                                                                                                                     

  1. The timing: E.g., a duration in seconds (up to 900) or a cron expression (e.g., */5 * * * * ).                                                  
  2. The prompt: What task or reminder you want to run when it fires.

I go ahead and ask it to do a one-minute timer and then remind me that there is a meeting:

> A one-time timer

  For how many seconds (up to 900 seconds/15 minutes) should the timer run, and what reminder message (prompt) should be triggered when it fires?     

────────────────────────────────────────────────────────────
> In 1 minute, remind me that there is a meeting

○ Schedule() (ctrl+o to expand)

  I have set a 1-minute timer for you. I will notify you as soon as it fires.

Now, you can get back to your work with Antigravity CLI. Once the timer is up, it should fire and let you know. And yes , in a minute, I got this message:

 ⏰ Reminder: There is a meeting starting now!

Here are some examples:

A Pomodoro Timer that you can set and then get back to work. It will then remind you that time is up. /schedule duration=”600" prompt=”Remind me that the current task time is over”
In 3 minutes, run the following to check if migrations are successfully applied: /schedule duration=”180" prompt=”Run ‘npm run db:status’ to verify if all migrations were successfully applied.”
Here is one to check the logs in some time and see if there are any new errors: /schedule duration=”600" prompt=”Inspect the logs folder and check if there are any new error entries or uncaught exceptions.”

You can also do a recurring (Cron expression) schedule to do a task. For e.g. do something at 9:00 AM every monday, or every 12 hours, etc. Here are some examples (I recommend that you substitute it with your commands, utilities and specific instructions):

Standup Prep (Every weekday morning at 9:00 AM)

/schedule cron="0 9 * * 1–5" prompt="Generate a bulleted summary of all git commits and file modifications made in the workspace in the last 24 hours."

End-of-Day Code Quality Check (Every weekday at 5:00 PM)

/schedule cron="0 17 * * 1–5" prompt="Run 'npm test' and 'npm run lint' and report any test failures or code quality warnings."

Local Server Health Check (Every 10 minutes)

/schedule cron="*/10 * * * *" prompt="Check if the server running on http://localhost:3000 is still up and returning a 200 OK response."

Hourly Folder Scan (Every hour)

/schedule cron="0 * * * *" prompt="Scan the input directory for any new raw files, process them (put your rules here), and move them to the 'archive' folder."

Weekly Dependency Update Audit (Every Friday at 4:00 PM)

/schedule cron="0 16 * * 5" prompt="Run a security audit on project dependencies (e.g., 'npm audit' or 'pip-audit') and report any critical vulnerabilities."

As an example, I setup a one-time 10 minute timer and then another recurring timer than runs every 10 mins.

Once scheduled, I can interact in natural language with Antigravity CLI to find what tasks are running in the background. Just give a prompt like list my active tasks

> list my active tasks

● ManageTask(You have 2 background task(s) currently running:) (ctrl+o to expand)

  Here are your currently active background tasks:                                                                                                    

  1. task-35                                                                                                                                         
      • Type: One-time Timer (600 seconds)                                                                                                            
      • Prompt: "Remind the user that the current task time is over."                                                                                 
      • Start Time: 2026-05-22T20:26:11 (Local time)                                                                                                  
  2. task-43                                                                                                                                         
      • Type: Recurring Cron ( */10 * * * * — every 10 minutes)                                                                                      
      • Prompt: "Check if the server running on http://localhost:3000 is still up and returning a 200 OK response."                                   
      • Start Time: 2026-05-22T20:33:29 (Local time)

You can now interact with it to even remove a task and so on.

We have a lot more to cover

We have just scratched the surface at this point with Antigravity CLI. There are several commands to still try out, in addition to key things like configuring plugins, MCP Servers, skills, background tasks, parallel tasks, context management and more. Later parts of the tutorial will cover them.

Examine the Context

You can visualize your context at any point in time via the /context command. A sample is shown below:

By the Way (btw)

This is actually a command and a pretty useful one too. If you main agent is busy with some long running task, you can use the /btw command to ask it a side question. This does not interrupt the currently running task.

The best way to try this would be by giving the Antigravity CLI a long running task like generating some application and then while it is busy, just give /btw and see it in action.

For example, the Agent is in the midst of refactoring the code and you would like to know about a specific git command. Give this instruction:

/btw What is the git command to list branches sorted by last commit date?

or something like this:

/btw what does exit status code 137 typically indicate?

Here are few more things to know about /btw :

• Parallel & Non-Interruptive: If the agent is currently busy running a long build script or refactoring several files in the workspace, typing /btw does not pause, abort, or delay that process. The main agent task continues running in the background.

• Ephemeral UI: The output is rendered in a temporary overlay panel (similar to a modal) directly in the terminal interface. When you close the panel (by pressing Enter or Esc ), the response vanishes.

• No Side-Effects (Read-Only context): To ensure speed and safety, /btw operates in a read-only mode. It has full read access to the files and conversation state, but it cannot execute tools (e.g., writing files, running bash commands, or scheduling tasks).

• Token Efficiency: The prompt and response of a /btw query are not appended to the primary conversation history. This prevents casual questions from inflating the conversation context window (context bloat).

Understanding Command-line parameters of Antigravity CLI

When we launched Antigravity CLI, we simply used agy to launch it. It uses several defaults in terms of what it needs to do and then shows you the terminal in which you can proceed to give commands.

In this section, we shall look at a few command line options, that are available to use, while launching Antigravity CLI at the command line.

If you can’t wait, you can get the current list of command line parameters/options available to you by using the agy --help , agy help, or agy -h command. This shows the following list at the time of writing:

$ agy --help
Usage of agy:
  --add-dir Add a directory to the workspace (repeatable) (default [])
  -c Short alias for --continue
  --continue Continue the most recent conversation
  --conversation Resume a previous conversation by ID
  --dangerously-skip-permissions Auto-approve all tool permission requests without prompting
  -i Short alias for --prompt-interactive
  --log-file Override CLI log file path
  --model Model for the current CLI session
  -p Short alias for --print
  --print Run a single prompt non-interactively and print the response
  --print-timeout Timeout for print mode wait (default 5m0s)
  --prompt Alias for --print
  --prompt-interactive Run an initial prompt interactively and continue the session
  --sandbox Run in a sandbox with terminal restrictions enabled

Available subcommands:
  changelog Show changelog and release notes
  help Show help for subcommands
  install Configure environment paths and shell settings
  models List available models
  plugin Manage plugins (install, uninstall, list, enable, disable)
  plugins Alias for plugin
  update Update CLI

So far we have launched Antigravity CLI and have been using it in interactive mode. If you’d like Antigravity CLI to just take your prompt, execute it and give back the result., then go for the non-interactive mode. This is done via the --prompt parameter or via -p or --print parameter.

This can be very useful in scenarios where you want to integrate Antigravity CLI in automated pipelines or schedule something at a specific time, without the need for any human interface.

agy -p "What is the command line syntax for doing a GET call to myhost.com via curl"

This might be a good way to get some quick answers but do keep in mind that there is be no scope to continue the conversation with follow up questions.

If you like to live dangerously (I do not), then you can look for a very aptly named parameter called --dangerously-skip-permissions.

Launch Antigravity CLI via the following command:

agy --dangerously-skip-permissions

Then give the following prompt. Check that it did not ask me for any write file permissions.

> get the latest news and write it in a file called news.txt. Then create another file that contains the summary of that file.

● ListDir(/Users/romin/agy-cli-projects) 
● WebSearch(latest world news May 24 2026 news headlines) (ctrl+o to expand)

▸ Thought for 2s, 95 tokens
  Processing News Information

● Create(/Users/romin/agy-cli-projects/news.txt) 
● Create(/Users/romin/agy-cli-projects/summary.txt) (ctrl+o to expand)

  I have fetched the latest world news headlines and created the requested files in your workspace:                                                                   

  1. news.txt: Contains the detailed news headlines for today (May 24, 2026), including topics on geopolitics (U.S.-Iran negotiations, Ukraine conflict), U.S.  
  security incidents, the Ebola outbreak in Central Africa, and the passing of NASCAR champion Kyle Busch.                                                            
  2. summary.txt: Contains a concise, structured summary of the major categories covered in the news file.                                                         

● ! ls
     news.txt
     summary.txt

This mode can be useful in scenarios where things are local and in your control but still be prepared for surprises and hence use it with care.

Specifying a model to use for the session

You can use the --model parameter to tell Antigravity CLI to use a specific model during its session only. This is very useful for the autonomous mode that we discussed, where you would like to launch several agy sessions and use specific models for specific tasks.

But first, you need to know which models are available for Antigravity CLI. You can do that via the models subcommand as shown below:

$ agy models
Gemini 3.5 Flash (Medium)
Gemini 3.5 Flash (High)
Gemini 3.5 Flash (Low)
Gemini 3.1 Pro (Low)
Gemini 3.1 Pro (High)
Claude Sonnet 4.6 (Thinking)
Claude Opus 4.6 (Thinking)

You can use any of these model names to specify the model to be used for the session. You can do that via the --model command shown below:

$ agy --model "Claude Opus 4.6 (Thinking)"

Once Antigravity CLI launches, you can check either via the /model command about the specific model that you asked it to use or look at the bottom right that shows the model used for the session. An example is shown below:

More command-line options

We will cover c , continue , conversation parameters in a separate part in this series, but will keep adding more information on command line parameters here, as Antigravity CLI takes shape. If you’d like to learn more about Conversations, check out Part 2.

Transitioning from Gemini CLI to Antigravity CLI

If you have been using Gemini CLI, here are a few things that you need to understand.

First up, you are not going to lose any of favourite workflows. Antigravity CLI to a large extent retains most of the features that you have been used to from Gemini CLI. Since it is early days yet, it is expected that the product team will use this time to probably get more parity based on user feedback. When it comes to Antigravity CLI, note that at the start of the article, we highlighted its key points about parallel execution, shared backend harness of Antigravity 2.0 and faster execution times.

If you have been using a personal account with Gemini CLI, here are a few dates and events to keep in mind:

June 18, 2026: This is the hard cutoff for individual and free-tier users. On this date, the Gemini CLI and Gemini Code Assist IDE extensions will stop serving requests.

Please read the following blogs for more details on what will work or not, post June 18 2026 , especially if you are using a personal account.

An important update: Transitioning Gemini CLI to Antigravity CLI

It is also important to understand a few changes from Gemini CLI, especially when it comes to configuration files that you were used to editing while tweaking and setting things up. This is critical since you might be having Extentions, MCP Servers, Skills and Context files that you were using with Gemini CLI.

Check out this section of the document on Migrating , that helps you understand what Antigravity CLI can directly import and use and a few key differences.

Google Antigravity

Conclusion

Thanks for reading this tutorial. This is just an initial introduction to help maximum number of users get started with Antigravity CLI. I will cover more parts in detail, as we move along.

Google Cloud Platform Technology Nuggets — May 1–15, 2026

Romin Irani — Fri, 15 May 2026 04:50:41 +0000

Welcome to the May 1–15, 2026 edition of Google Cloud Platform Technology Nuggets. The nuggets are also available on YouTube.

Infographic for this post, generated by NotebookLM

AI and Machine Learning

Gemini 3.1 Flash-Lite is now generally available on the Gemini Enterprise Agent Platform. It is a model specifically optimized for ultra-low latency and high-volume production deployments. This addition to the Gemini 3 series focuses on providing precision for agentic tasks such as tool calling, orchestration, and automated pipeline execution while minimizing operational costs. Check out the blog post.

In a mid-cycle update of the Gartner® Magic Quadrant™ for AI Application Development Platforms, Google has been given the #1 ranking across the three use cases assessed in the associated Critical Capabilities report. Download a complimentary copy of the 2026 Gartner Magic Quadrant update here.

Data Analytics

While AI-powered SQL functions are a solid addition to the databases, cost and latency of these functions is a critical factor. An interesting approach called proxy models is now available, which are lightweight classifiers like logistic regression that replace the majority of expensive LLM calls during query execution. These models work by leveraging existing Gemini embeddings of data to identify semantic patterns, allowing the system to perform tasks like binary classification (AI.IF) or multiclass classification (AI.CLASSIFY) on the CPU rather than specialized hardware. The process involves an automated workflow where the engine samples a small portion of data, labels it using an LLM, trains a specialized proxy model on-the-fly, and evaluates its accuracy before deciding whether to use the proxy or the full LLM. This optimization is currently available in BigQuery and AlloyDB. Check out the blog post.

Databases

The Database Center has been infused with several AI-driven updates to assist with the management of large-scale database fleets. The platform now features Gemini-powered intelligence for fleet-wide performance analysis, a natural language chat interface for troubleshooting across services like Cloud SQL and Spanner, and a testing agent to validate the impact of recommendations on latency and throughput before they are applied. Technical enhancements include public APIs integrated with the Model Context Protocol (MCP) for developer tool integration, centralized slow query analysis, and the inclusion of BigQuery inventory and data affiliation to map dependencies between transactional and analytical systems. Check out the blog post.

Bigtable has introduced Bigtable in-memory tier, a new feature within the Enterprise Plus edition designed to provide sub-millisecond read latency by using a hybrid storage architecture. This tier utilizes Remote Direct Memory Access (RDMA) to transfer data directly from memory without involving the system’s CPU or operating system, which helps avoid performance bottlenecks during traffic spikes. It offers approximately 10x higher point read throughput per dollar compared to standard configurations and provides hotspot resistance by supporting up to 120,000 queries per second on a single row. Check out the blog post.

PostgreSQL 18 is now available in in AlloyDB alongside a new Extended Support offering for older versions. This update includes B-tree skip scans for faster data retrieval, parallel GIN index usage for JSON and full-text searches, and native UUIDv7 support for better indexing efficiency in distributed applications. The platform now allows for virtual generated columns to compute data on-the-fly without using additional disk space. For older versions ranging from PostgreSQL 14 to 17, Extended Support provides three additional years of critical security patches and bug fixes beyond the community end-of-life dates. Users can perform in-place major version upgrades to transition to these newer releases. Check out the blog post.

As always, if you are looking to bookmark a single link that covers whats new in Google Data Cloud, check this out.

Developers & Practitioners

The Gemini Enterprise Agent Platform is squarely focused on running, scaling, governing and optimizing agents in production. To do that, requires some key guidance from Google Cloud and that is now available in the form of 5 guides that help transition AI agents from prototypes to production:

Long-Running Agents: Utilize Agent Runtime for maintaining state up to seven days, enabling checkpoint-and-resume and human-in-the-loop approval workflows.
Agent Governance Stack: Implement a five-layer security framework using Agent Identity for isolation, Agent Registry for tool control, and Agent Gateway for policy enforcement.
Multi-Agent Orchestration: Use the Agent Development Kit (ADK) to build graph-based workflows and coordinator-specialist patterns for complex task management.
A2A and MCP Interoperability: Connect agents across organizations and data systems using Agent-to-Agent (A2A) and Model Context Protocol (MCP) standards.
Atomic Agent Blueprints: Access pre-configured architectures in the Agent Garden to accelerate development and avoid manual design errors.

Check out the blog post for more details.

While most of the AI developer tools focus on coding, one of the challenges that remains is that of the outer loop and bridging the gap between local development and production deployment. The Gemini CLI Extension for CI/CD is a tool that is designed to do exactly that. Using the Model Context Protocol (MCP), the extension integrates with Gemini CLI, Claude Code, and Antigravity to automate both “inner loop” tasks, like rapid deployment to Cloud Run via buildpacks, and “outer loop” requirements, such as generating cloudbuild.yaml files and provisioning infrastructure. Key technical features include a pre-deployment security scan to prevent secret leakage, an automated application analysis for containerization, and the ability to provision Artifact Registry repositories and Cloud Build triggers through natural language prompts. For more details, check out the blog post.

Containers and Kubernetes

Google Cloud has introduced an architectural update to Google Kubernetes Engine (GKE) that reduces node startup times by up to 4x to address cold-start latency. This improvement is achieved by reworking node provisioning logic through a combination of intelligent compute buffers, fast-starting virtual machines, and a control plane that allows for instant VM resizing without reboots. These technical changes aim to reduce the need for over-provisioning and improve the scaling of AI inference and batch processing workloads. The feature is currently available for GKE Autopilot and specific NVIDIA GPU hardware, including L4, A100, RTXPRO6000, and H100 nodes, as well as general-purpose compute. For more details, check out the blog post.

Security and Identity

Gartner has named Google a Leader in the 2026 Magic Quadrant for Cyberthreat Intelligence Technologies. You can download the full 2026 Gartner® Magic Quadrant™ for Cyberthreat Intelligence Technologies here.

The second Cloud CISO Perspectives for April 2026 is out. This issue discusses a strategy centered on multicloud and multi-AI environments to address modern security needs. Key technical highlights include the use of Gemini-powered security agents that have reduced alert triage times from 30 minutes to 60 seconds and a new dark web intelligence capability with 98% accuracy. The issue also discusses features in the new Gemini Enterprise Agent Platform, that has an Agent Gateway for identity management, Model Armor for prompt sanitization, and automated Agent Identity verification.

With the Wiz acquisition now complete and highlighted at Google Cloud Next 2026, most practitioners are looking forward to understand how it all comes together under a common platform. In the first Cloud CISO Perspectives for May 2026, the post highlights how the collaboration affects multicloud security and it discusses a strategy centered on developer enablement and automated defense. The collaboration combines Wiz’s cloud telemetry with Google Cloud AI logic to move toward near real-time vulnerability resolution and self-healing infrastructure.

If you are looking to understand the evolving security risks for AI coding agents, this article explains how the attack surface has expanded beyond source code to include the files these agents trust. Threat actors are now targeting repository-level artifacts like tasks.json, settings.json, and Skill.md files to execute code, exfiltrate API keys, or redirect traffic to malicious endpoints by manipulating the agent’s semantic intent. Because these files often use natural language or valid configurations, they bypass traditional signature-based scanners. To counter this, Google Cloud highlights the use of VirusTotal Code Insight to perform semantic analysis, allowing defenders to identify high-risk instructions and hidden supply-chain threats within developer environments.

Infrastructure

Google Cloud has introduced a cluster-level reliability framework for Tensor Processing Units (TPUs) designed to support the training of trillion-parameter AI models.

Storage

If you are looking to address storage bottlenecks in AI and machine learning workflows, you now have Cloud Storage Rapid, a suite of high-performance object storage capabilities designed for data-heavy workloads. This family includes Rapid Bucket, a zonal storage option that provides sub-millisecond latency and up to 15 TB/s throughput to keep accelerators like GPUs and TPUs saturated, and Rapid Cache, which increases read bandwidth for existing buckets without requiring code changes. Check out the blog post.

Write for Google Cloud Medium publication

Stay in Touch

Have questions, comments, or other feedback on this newsletter? Please send Feedback.

If any of your peers are interested in receiving this newsletter, send them theSubscribe link.

[Boost]

Romin Irani — Mon, 30 Mar 2026 11:23:30 +0000

Aryan Irani for Google Developer Experts

Mar 28

Reflections on my Trainings: Gemini for Google Workspace

#gemini #googleworkspace #livetraining #googleappsscript

6 min read