Certification Study Notes

Antigravity & Agents CLI

Google's agent-first developer harness (App, agy CLI, IDE and SDK) and the open-source Agents CLI: artifacts and planning, rules and skills, MCP, hooks and plugins, discovery precedence, subagents, permissions and the terminal sandbox, secure dev environments on Cloud Workstations and GKE, and the build → evaluate → deploy → publish lifecycle for ADK agents.

Author: Michaël Bettan

Track: Google Cloud / Professional Agentic Architect

Test Yourself: Antigravity & Agents CLI Practice Quiz →

About these notes

Independent study notes, grounded in the public Antigravity docs (antigravity.google/docs), the Google Cloud docs (Agent Platform, Cloud Workstations, GKE) and the Agents CLI docs (adk.dev, google.github.io/agents-cli). Antigravity and Agents CLI ship fast: flags, defaults and preview features change. Items marked (verify) could not be fully confirmed in official docs at writing time.

Overview & Mental Model

Google Antigravity

Google Antigravity is Google's agent-first development platform. You hand an agent a task, review the artifacts it produces (plans, diffs, walkthroughs, browser recordings), and approve key milestones. You no longer have to watch every keystroke.

Agents CLI

Agents CLI (agents-cli, package google-agents-cli) is a separate, open-source tool. It gives any coding agent (Antigravity, Claude Code, Codex, Gemini CLI) a machine-readable way to scaffold, evaluate, deploy and publish ADK agents on Google Cloud.

Layer	Tool	Role
Developer harness	Antigravity (App, CLI `agy`, IDE, SDK)	The coding agent you work with
Agent-building expertise	Agents CLI skills + `agents-cli` commands	Teach the coding agent ADK, evals and deployment
Agent framework	ADK (open source)	The code of the agent you ship
Production runtime	Agent Runtime, Cloud Run, GKE → Gemini Enterprise	Where the shipped agent runs and is distributed
Secure dev environment	Cloud Workstations, Agent Sandbox on GKE, Antigravity terminal sandbox	Where agent-run code is isolated

Rule 0: harness ≠ runtime

Antigravity is the developer's harness, not the production runtime of the agent you build. The agent you ship runs on Agent Runtime, Cloud Run or GKE.

Surfaces: App, CLI, IDE & SDK

Surface	What it is	Best for
Antigravity App (Antigravity 2.0)	Standalone desktop app that grew out of the original Agent Manager. Projects, conversations, Automations (scheduled runs), side panel with Subagents, Artifacts, Files changed and Terminals	Running and monitoring several agents across projects
Antigravity CLI (`agy`)	Terminal UI. Settings in `~/.gemini/antigravity-cli/settings.json`. Use `agy --help` for flags and `/help` for slash commands	Terminal-first and remote/headless work
Antigravity IDE	Standalone AI-first IDE built on VS Code, plus editor extensions	In-editor work: Tab autocomplete/supercomplete, inline command (Cmd/Ctrl+I), agent side panel
Antigravity SDK	Python package `google-antigravity` (`Agent`, `LocalAgentConfig`, `CapabilitiesConfig`)	Embedding agents in scripts, pipelines and tests

Facts to remember

Sign-in is shared: signing in on one local surface signs you in on the others.
The SDK agent is read-only by default. Pass capabilities=CapabilitiesConfig() to enable write tools.
Remote Control lets you drive App and CLI sessions from a browser. In the CLI, use /remote-control, --remote-control or agy remote-control start.
Gemini CLI migration: on first launch, agy detects old Gemini CLI configs. agy plugin import gemini converts Gemini CLI extensions into Antigravity plugins.

Agent-First Workflow: Plans, Artifacts & Verification

Planning mode

The agent researches the codebase, groups its work and produces an implementation plan artifact before it edits anything. Use it for multi-file changes, new features, migrations and security-sensitive work.

Fast mode

The agent acts right away. Use it for renames, one-off commands and small local fixes.

Analysis & discovery

/plan starts by exploring the codebase and the task.

Clarifying interview

Runs only if the requirements are unclear.

Implementation plan

Step-by-step tasks, verification gates and risks.

Review → execute

You review and approve, then the agent executes.

/grill-me interviews you one question at a time before work starts. Combine them with /plan /grill-me <task>.

Artifacts are structured deliverables: implementation plans, code diffs, diagrams, images and browser recordings. A walkthrough artifact is produced at the end. It summarizes the changes and often includes screenshots or recordings of browser tasks.

Steering: comment inline on a plan (like a doc). Then click Proceed, or click Review to send your comments as feedback.

Surface	Artifact review policy options	Default / guidance
App	Request review · Always proceed	Request review is recommended
CLI (`artifactReviewPolicy`)	`asks-for-review` · `agent-decides` · `always-proceed`	`asks-for-review` is the default. `agent-decides` currently behaves the same way

Exam trap: plans vs. file edits

The artifact review policy covers plans. File edits are controlled separately, by the agent mode (see section 07).

Multi-file refactoring & runtime optimization

Use Planning mode (/plan) to inventory call sites across the repository, establish a baseline (existing test suite or latency/memory benchmark), apply incremental diffs, and run verification gates after each step before producing the final walkthrough artifact. The full playbook follows below.

Automated vulnerability patching

Pair security scanner findings (SAST or dependency audit) with a security implementation plan and a Proof-of-Concept (PoC) reproduction test in an isolated sandbox (the Antigravity terminal sandbox: Seatbelt profiles on macOS, kernel namespaces on Linux). The agent confirms the PoC reproduces the flaw before the fix, patches the root cause (e.g., parameterized queries, output encoding, path canonicalization, upgraded dependency), verifies that the PoC and regression tests pass, and records a security audit report artifact. Use PreToolUse / PostToolUse hooks to run linters or security scanners automatically on every edit.

Refactoring and runtime optimization playbook

Refactoring and runtime optimization are judged by different proofs than a security patch, so they need their own gates.

Aspect	Multi-file refactoring	Runtime optimization	Vulnerability patching (CodeMender-style)
Goal	Change structure, keep external behavior identical	Cut latency, cost or resource use against a measured baseline	Remove one verified flaw at its root cause
Scope	Wide: many modules and call sites	Hot paths found in traces or profiles	Narrow: the code path behind one finding
Proof of success	Unchanged test results plus a clean interface diff	Better benchmark or trace numbers and no eval regression	The exploit or PoC stops reproducing and regression tests pass
Typical tooling	Rules, skills, `research` subagents, `branch` worktrees, hooks	Cloud Trace, benchmarks, `agents-cli eval compare`, revision traffic split	CodeMender (`cm fix` on Agent Platform, Preview) or the security plan flow above

Key point

CodeMender and the PoC flow above start from a finding and end with a small, reviewed diff. A refactor starts from a target design and can touch hundreds of files, so the safety net is the test suite and isolation, not an exploit reproducer.

Stage	Refactoring	Runtime optimization	Gate before the next stage
Contract and baseline	Write target structure and forbidden patterns as `.agents/rules/` files; package repeatable codemod steps as a skill	Record latency percentiles, token counts and Cloud Trace waterfalls before any edit	Characterization tests pass on the old code; baseline numbers are saved
Decompose	`research` subagents map imports, call graphs and public interfaces, then the plan splits the work into independent slices	The agent reads traces and ranks suspects (serial tool calls, repeated queries, uncached prompt prefixes)	You approve the implementation plan artifact
Isolated execution	One writer subagent per slice in `branch` mode (its own Git worktree), commands in the terminal sandbox	Apply one change at a time: parallel fan-out, caching, or a smaller model on simple steps	No writer shares a working tree; sandbox stays on
Automated checks	`PostToolUse` hooks format and lint each edit; a `Stop` hook refuses to finish while tests fail	Rerun the benchmark and the eval dataset after every change	Tests green, eval scores at or above baseline
Review and rollout	A fresh-context reviewer subagent checks the diff against the rules; merge through CI	Canary the new revision on a small traffic share, compare traces and quality, then promote	CI passes; canary metrics hold before 100%

Walkthrough: rename a module boundary across a monorepo

Pin the contract: add an always_on rule that names the new package path and bans imports of the old one; run the full suite and save the result as the baseline.
Map the blast radius: in /plan, have the agent delegate discovery to research subagents that list every importer and public symbol; the plan groups them into slices with no shared files.
Fan out safely: the main agent launches one subagent per slice, each in its own branch workspace so writers never share a working tree.
Let hooks enforce quality: the formatter runs after each edit and the Stop hook re-enters the loop with the failing test output until the slice is green.
Review and merge: a custom reviewer subagent whose tools list has only read tools audits each worktree diff; the walkthrough artifact summarizes the result before you merge.

Walkthrough: cut response latency of a deployed ADK agent

Measure first: open the agent's Cloud Trace spans and separate model time from tool and I/O time; save agents-cli eval run results as the quality baseline.
Fix orchestration: independent lookups that run one after another become a ParallelAgent fan-out.
Fix tokens: enable ADK context caching (ContextCacheConfig) for long, stable instructions on Gemini, or rely on prompt caching for Claude models; move simple classification steps to a smaller model.
Prove both speed and quality: rerun the benchmark, then agents-cli eval compare on the old and new result files.
Canary: on Agent Runtime, switch to a manual traffic split that keeps the current revision at 100% before you deploy, then move a small share to the new revision (revisions and traffic splitting are in Preview). The default is always-latest routing, which sends all traffic to a new revision as soon as it exists.

Hook setup used above (.agents/hooks.json; top-level keys are hook names, and Stop handlers sit directly under the event with no matcher):

JSON: .agents/hooks.json

{
  "format-on-edit": {
    "PostToolUse": [
      { "matcher": "write_to_file|replace_file_content|multi_replace_file_content",
        "hooks": [{ "type": "command", "command": "./scripts/format_changed.sh", "timeout": 20 }] }
    ]
  },
  "tests-before-stop": {
    "Stop": [
      { "type": "command", "command": "./scripts/stop_unless_green.sh", "timeout": 120 }
    ]
  }
}

Why the `Stop` hook carries the test gate

A PostToolUse hook returns an empty object, so it cannot steer the agent. A Stop hook can print {"decision": "continue", "reason": "..."} and the reason is injected into the conversation, which sends the agent back to fix the failure.
Cost: hooks run synchronously and block the loop (default timeout 30 seconds), so keep the PostToolUse script to changed files and run only the affected tests in the Stop script.

Anti-patterns

Refactor and feature in one change: behavior changes hide inside structural moves; ship the pure refactor first, gated by unchanged test results.
Optimizing by feel: tuning prompts or swapping models without a saved baseline and an eval comparison trades latency for silent quality loss.
Shared working tree: parallel writer subagents in inherit mode overwrite each other; use branch and non-overlapping slices.
Self-grading: asking the authoring agent to review its own diff reuses the same blind spots; use a separate reviewer subagent with a clean context.
Sandbox off for builds: benchmarks and build scripts written by the agent run with full host privileges outside the sandbox.
Deploy equals rollout: with always-latest routing, every Agent Runtime deploy is a 100% rollout; pin traffic with a manual split before deploying.

Rules, Skills & Workflows

Rules are persistent constraints and invariants, such as "always use zod" or "never import internal/".

File	Frontmatter	Activation
`AGENTS.md` / `GEMINI.md` (any directory)	None	Always on for that directory and below
`.agents/rules/*.md`	Required: `trigger`	`always_on` · `model_decision` (needs `description`) · `glob` (needs `globs`) · `manual`
Global: `~/.gemini/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.gemini/config/rules/*.md`	Modular rules need frontmatter	All projects on the machine

Rule mechanics

Rules add up. When they conflict, the more specific directory rule wins. Each rule file is injected only once.
A missing or invalid trigger (for example camelCase alwaysOn) means the rule is silently discarded.
.agents/rules/ is scanned one level deep. Files in nested folders are ignored unless you register them in .agents/rules.json.
Budgets: each rule file is capped at 24 KB. Always-on and global rules share a 20,000-token budget. Rules over budget are reduced to a file-path pointer.

Skills: on-demand procedures and runbooks

Layout: skills/<name>/SKILL.md with name and description in the frontmatter. Optional folders: scripts/, references/, examples/, resources/.
Progressive disclosure: only the name and description go into the context. The full body loads when the task matches. The description decides whether the skill ever activates.
Keep SKILL.md short. Move bulky docs into references/. Wrap long command sequences in scripts/. Include steps to validate the work.
Rule or skill? A rule is a constraint. A skill is a workflow ("how to run DB migrations").

Workflows (legacy, IDE)

Markdown prompt sequences you run as /workflow-name. The docs say current workflows stop working on October 19, 2026. Migrate them to skills with /migrate-workflows.

MCP, Hooks & Plugins

MCP servers: `mcp_config.json` (`mcpServers` map)

Locations: global ~/.gemini/config/mcp_config.json, workspace .agents/mcp_config.json, plugin plugins/<name>/mcp_config.json.
stdio (local): command, args, env. Streamable HTTP (remote): url (serverUrl is also accepted).
The legacy HTTP+SSE transport is not supported. For an SSE-only server, run a stdio bridge such as mcp-remote.
Discovered tools are added to the agent's toolset. Plugin tools get a namespace prefix when needed to avoid name clashes.

Hooks: hooks.json (named hooks → event handlers)

Event	Fires	Typical use
`SessionStart`	Once per new session	Inject startup context
`PreToolUse` (needs `matcher`)	Before a tool runs	Gate, block, audit, or rewrite arguments
`PostToolUse` (needs `matcher`)	After a tool runs	Lint, format, analyze
`PreInvocation`	Before each model call	Inject reminders
`PostInvocation`	Immediately after each model invocation completes	Inject follow-up steps; force the loop to continue or terminate
`Stop`	When the loop ends	Block stopping until the goal is met

Hook outputs & limits

PreToolUse returns decision: allow · deny · ask · force_ask (ignores cached approvals). It can also return overwrite (a shallow merge into the tool arguments).
Stop can return decision: "continue" to re-enter the loop.
Only type: "command" is supported. Hooks run synchronously and block the loop, so keep them fast. Set "enabled": false to turn a hook off.

Plugins: namespaced bundles

plugins/<name>/plugin.json, plus optional skills/, rules/ (a consolidated AGENTS.md is recommended), hooks.json at the plugin root, mcp_config.json and agents/.
Discovered plugins are on by default. Your on/off choice is stored in config.json, never inside the plugin.
Install: agy plugin install <name>@antigravity-plugins-official, a GitHub URL or a local directory. Or use /plugin in the TUI.

Discovery & Precedence

Workspace

.agents/ (also .agent/, _agents/, _agent/). The agent walks from the CWD up to the repo root. Commit this folder to share with the team.

Directory rules

AGENTS.md, GEMINI.md and .agents/rules/*.md, found by walking up from each file the agent reads or edits.

Global

~/.gemini/config/ (applies only on this machine).

Priority (highest → lowest). When two customizations have the same name, the higher one wins.

#	Source
1	Workspace project (walking up from the CWD)
2	Declared configs: workspace `skills.json` / `plugins.json`
3	Global discovery: `~/.gemini/config/`
4	Built-in customizations (mounted by name)
5	Global declared configs

skills.json / plugins.json: entries (paths scanned one level deep, with include_only / exclude) and inherits (other config files). Paths can be absolute, ~/-relative, or relative to the workspace/repo root.

Team pattern

Commit shared skills to tools/agents/skills/. Then commit .agents/skills.json with {"entries":[{"path":"tools/agents/skills"}]}. Anyone who clones the repo gets the skills automatically.

Subagents, Browser Agent & Parallel Work

How subagents work

The main agent calls invoke_subagent with a role and a prompt. Each subagent starts with a clean context window and does not see the parent's history. Subagents run in parallel, in the background.
Workspace modes: inherit (same folder), branch (an isolated Git worktree), share (shared repo storage).
Built-in subagents: research (codebase exploration), browser (only through /browser), self (a clone of the caller).
Custom subagents: .agents/agents/<name>.md (workspace), ~/.gemini/config/agents/ (global) or plugins/<name>/agents/. YAML frontmatter: name, description, tools, model (inherit/flash/pro), commandExecutionPolicy (default sandbox), mcpServers, skills, mainAgent, subagent. Known issue: a misspelled tool name in tools can make the subagent hang.
Lifecycle: Running → Idle (sent its result; wakes up with full context when it gets a message) → Killed (permanent; temporary worktrees are cleaned up).

CLI & SDK

CLI: the /agents panel (Agent Manager) shows ID, role, state and current step. Alt+J jumps to the next pending approval. Ctrl+K approves in place.
SDK: dynamic self-cloning (CapabilitiesConfig(enable_subagents=True)) or static SubagentConfig. A custom tool given to a subagent must also be in the parent's tools.

Browser subagent & Automations

/browser drives Google Chrome through the Chrome DevTools MCP server. Its context is isolated, every session is recorded as a WebM artifact, and it is hidden from the normal subagent list. It is not available in the IDE, and admins can turn it off.
Automations (App) run prompts on a schedule. /schedule sets a timer or recurring check inside a conversation.

Permissions, Execution Modes & Terminal Sandbox

Permission rules: allow / ask / deny lists with typed matchers: command(npm test), read_file(path), write_file(src/), read_url, execute_url, mcp. Deny > Ask > Allow.

Defaults when no rule matches: reading and writing inside the workspace is allowed. Web actions (read_url, execute_url) default to Ask. Everything else (commands, MCP, files outside the workspace) defaults to Ask.

CLI agentMode (cycle with Shift+Tab)

Mode	Behavior
`default`	Asks you to review a diff before every file write
`accept-edits`	Auto-approves file edits in the workspace. Commands still follow `toolPermission`
`auto` (Preview)	Auto-approves edits and runs commands in the sandbox. Commands that need to run outside the sandbox are auto-evaluated: safe, reversible ones run, risky ones pause
`plan`	Plans before editing (adds `/plan` to the prompt)

CLI toolPermission: request-review (default) · proceed-in-sandbox · strict (asks before every tool call, even reads) · always-proceed (also turned on by --dangerously-skip-permissions). strict and always-proceed override auto.

Terminal sandbox (`enableTerminalSandbox` / `--sandbox`; off by default, turned on automatically in `auto` mode)

Project folders are mounted read-write. read_file paths are mounted read-only and write_file paths read-write. Everything else is invisible (macOS/Linux). Files such as .env are blocked.
Network: in the CLI, sandboxed commands get no network by default. Domains allowed under read_url are added to the outbound allowlist.
A command that runs outside the sandbox runs on the host with full privileges. Business and enterprise accounts use unsandboxed(...) rules for this.
App security presets (Default, Full machine, Turbo) never turn the sandbox on. You must enable sandbox mode yourself. A common combo is sandbox + Proceed in Sandbox.

Other settings: non-workspace file access (off by default), internet access policy, command allow/deny lists, browser domain allowlist. Project settings override global settings.

Secure Dev Environments: Cloud Workstations & GKE

Cloud Workstations: managed dev environments on Google Cloud

Cluster: region + VPC (not related to GKE clusters). Configuration: the template (VM type, persistent disk, container image, IDE, idle and running timeouts; access through IAM). Workstation: an instance started or stopped on demand.
Access through a browser IDE, local VS Code or JetBrains IDEs, or SSH. You can bring your own Linux container image, as long as its entrypoint runs a blocking process.
Lock it down: put it inside a VPC Service Controls perimeter, use a private cluster (clients connect through Private Service Connect), turn off public IPs (org policy constraints/compute.vmExternalIpAccess), and also restrict the Compute Engine API.
Agent-optimized development: set idleAction=SUSPEND with an idleTimeout (for example 1800s). Add keep-alive lifecycle hooks: start /google/scripts/keep_alive.sh when the agent starts working and kill it when the agent waits for input. Samples for Claude Code and Antigravity CLI ship in /google/samples/agents/keepalive/. A suspended workstation keeps RAM, processes and agent context, and stops vCPU and memory charges.

Agent Sandbox on GKE

A managed add-on that gives kernel-level isolation (gVisor) to untrusted, LLM-generated code. Pieces: SandboxTemplate (the blueprint) and SandboxWarmPool (pre-warmed pods). A core security policy that you cannot override requires gVisor and blocks hostNetwork and hostPath.

Need	Pick
Stop a local coding agent from running wild on a laptop	Antigravity terminal sandbox + deny rules
Corporate, exfiltration-safe dev box for humans and their coding agents	Cloud Workstations (private cluster, VPC-SC, no public IP)
Run agent-generated code at scale inside a product	Agent Sandbox on GKE

Agents CLI: Build → Evaluate → Deploy → Publish

What it is: a single, machine-readable interface that coding agents use to drive ADK projects end to end. It packages expert knowledge of ADK, evaluation and Google Cloud deployment as skills. Source: github.com/google/agents-cli.

Install. This is the only command you run yourself:

Bash — install Agents CLI

uvx google-agents-cli setup        # installs agents-cli, ADK packages and skills into the coding agents on this machine
# alternatives: pipx/pip install google-agents-cli && agents-cli setup
# skills only:  npx skills add google/agents-cli

Prerequisites: Python 3.11+, uv, Node.js (for the skills), a coding agent. For deployment you also need the gcloud CLI and Terraform.

Positioning: Agents CLI vs. ADK CLI vs. gcloud vs. Antigravity

Tool	Type	Role & behavior
Agents CLI (`agents-cli`)	Lifecycle toolchain plus a skill bundle	Scaffolds, evaluates, deploys, publishes and provisions infra for ADK projects. Built for coding agents, but every command also runs standalone in a terminal
ADK CLI (`adk`)	Framework CLI shipped with ADK	Inner-loop work on the framework itself (`adk create` for a single-file learning agent, `adk run` to chat with an agent in the terminal). No production scaffolding, eval synthesis or Gemini registration
gcloud	General Google Cloud CLI	Manages individual APIs, IAM and network resources one at a time. Agents CLI drives Cloud tooling for you and suppresses gcloud prompts (`CLOUDSDK_CORE_DISABLE_PROMPTS=1`) unless you pass `-i`
Antigravity	Coding agent (the harness)	Reads the Agents CLI skills and runs `agents-cli` commands on your behalf. Agents CLI is a tool for a coding agent, not a coding agent itself

Rule of thumb

Use adk to learn the framework, agents-cli to ship a project, and gcloud for one-off resource changes outside the agent stack.

Bundled skills

Installed into your coding agent by agents-cli setup (refresh them with agents-cli update).

Skill	What the coding agent learns
`google-agents-cli-workflow`	Always active: the end-to-end flow (scaffold, build, evaluate, deploy, publish, observe), rules for preserving existing code, model choice
`google-agents-cli-scaffold`	`scaffold create`, `scaffold enhance`, `scaffold upgrade`, templates, deployment targets, prototype-first
`google-agents-cli-adk-code`	ADK API: agent types, tools, orchestration, callbacks, state
`google-agents-cli-eval`	Eval datasets, metrics, LLM-as-judge, comparing runs, failure clusters, prompt optimization
`google-agents-cli-deploy`	Agent Runtime, Cloud Run, GKE, CI/CD, secrets, service accounts, rollback
`google-agents-cli-publish`	Gemini registration: ADK vs. A2A registration types, flags, auto-detection from deployment metadata
`google-agents-cli-observability`	Cloud Trace, prompt-response logging, BigQuery Agent Analytics, third-party tracing tools

Installing and scoping skills

Goal	Command	Effect
CLI plus skills, machine-wide	`uvx google-agents-cli setup`	Installs the tool and pushes skills to every detected coding agent (global scope is the default)
Skills for this repo only	`agents-cli setup --workspace`	Installs skills relative to the current directory, so teammates get them through Git
Target specific agents	`agents-cli setup --agent claude-code`	Repeatable flag; `--agent all` covers every supported agent
Preview first	`agents-cli setup --dry-run`	Shows what would change without writing anything
Skills only, no CLI	`npx skills add google/agents-cli`	Copies the skill folders; the coding agent installs the CLI when it needs it

Extensions (experimental)

agents-cli extension add <ref> adds third-party skills and command overrides. Project scope (default) records the pin in agents-cli-extensions.yaml and copies skills to <project>/.agents/skills/; --global uses ~/.agents/skills/. When both scopes define the same command, project scope wins.
Trust: any org/repo reference prompts before install because its commands run arbitrary code. --yes skips that prompt, so keep it for automation you control.
Claude Code caveat: Claude Code reads .claude/skills/, not .agents/skills/, so link or copy extension skills there yourself.

Relation to Skill Registry

Aspect	Agents CLI skills	Skill Registry (Agent Platform, Preview)
Where skills live	`SKILL.md` folders on disk, inside each coding agent or repo	A private, managed Google Cloud repository
Who loads them	The developer's coding agent (Antigravity, Claude Code, Codex)	Agents that discover and load skills dynamically based on user intent
Versioning	Git, or the commit pin of an extension	API resources: a mutable skill plus immutable skill revisions
Built-in helper	None needed	The `gcp-skill-registry` skill lets an agent create, search and manage registry skills

Key point

Both use the SKILL.md folder format, so a skill written for a coding agent can later be packaged for the registry. Standalone skills can also be governed centrally in Agent Registry.

Lifecycle commands

The coding agent usually runs these for you; every one also works by hand.

Stage	Command	Purpose and notable flags
Setup	`agents-cli setup`	Install the CLI and skills (`--workspace`, `--agent`, `--skip-auth`, `--dry-run`)
Auth	`agents-cli login`	Sign in to Google Cloud or AI Studio; `--status` shows the current state
Scaffold	`agents-cli create <name>`	Alias of `scaffold create`. `-y` uses defaults (`adk_python` template, `agent_runtime` target); `-p` / `--prototype` skips CI/CD and Terraform; `-d` sets the target
Scaffold	`agents-cli scaffold enhance`	Add a target (`-d agent_runtime`, `cloud_run` or `gke`) or a `--cicd-runner` (`github_actions`, `google_cloud_build`) to an existing project; `--dry-run` previews
Scaffold	`agents-cli scaffold upgrade`	Move a project to a newer Agents CLI template version
Develop	`agents-cli install`, `agents-cli run "<prompt>"`	Install dependencies; send one prompt to the agent (non-interactive)
Develop	`agents-cli playground`	ADK web UI with hot reload, default `--port 8080`
Develop	`agents-cli lint`	Code quality checks (Ruff)
Evaluate	`agents-cli eval dataset synthesize`	Generate multi-turn eval scenarios for the local agent
Evaluate	`agents-cli eval run`	Run inference over the eval dataset and grade the traces (`eval generate` and `eval grade` split the two halves)
Evaluate	`agents-cli eval analyze`	Cluster failure modes from grade results
Evaluate	`agents-cli eval compare`	Compare two eval result files (regression check)
Evaluate	`agents-cli eval optimize`	Tune agent prompts from eval data
Deploy	`agents-cli deploy`	Deploy to Agent Runtime, Cloud Run or GKE. Useful flags: `--dry-run`, `--no-wait` then `--status`, `--update-only`, `--agent-identity` (Agent Runtime only)
Infra	`agents-cli infra single-project`	Terraform for one project (dedicated service account, secrets, IAM). Plans by default; `--apply` applies. Optional, because `deploy` works without it
Infra	`agents-cli infra cicd`	CI/CD pipeline plus staging and prod infrastructure
Publish	`agents-cli publish gemini`	Register the deployed agent with a Gemini Enterprise app (`--gemini-app-id`, `--agent-runtime-id`, `--registration-type adk` or `a2a`). `publish gemini-enterprise` is the older name, kept as a hidden alias
Inspect	`agents-cli info`	Project config, paths, CLI version and active extensions; `--json` for machine output

Note

Command names and flags come from the google/agents-cli README, docs and CLI source at writing time. The tool ships often: confirm with agents-cli <command> --help before relying on a flag.

Bash: Agents CLI lifecycle

agents-cli create support-agent --prototype -y   # scaffold with defaults, no CI/CD
agents-cli run "Where is my order 1234?"          # smoke test, one prompt
agents-cli eval run                              # release gate
agents-cli scaffold enhance -d cloud_run         # add a deploy target later
agents-cli deploy --dry-run                      # preview, then drop --dry-run
agents-cli publish gemini --gemini-app-id "$GEMINI_APP_ID"

Project layout

app/agent.py, app/fast_api_app.py, tests/{eval,integration,unit}, agents-cli-manifest.yaml, Dockerfile, GEMINI.md (guidance for coding agents) and .env.

Eval files

The default dataset is tests/eval/datasets/basic-dataset.json and metrics live in tests/eval/eval_config.yaml. Older projects with tests/eval/evalsets/*.evalset.json must migrate to the new dataset format. Pass --dataset and --metrics to eval run to target other files; eval compare baseline.json candidate.json diffs two result files.

Auth

A Gemini API key in .env (comment out the GOOGLE_CLOUD_* lines), or Application Default Credentials (gcloud auth application-default login) with the GOOGLE_CLOUD_* lines set.

Observability

Cloud Trace is on by default. Asking the agent to "set up observability" provisions a service account, a Cloud Storage bucket and a BigQuery dataset.

Templates

--agent adk_python (alias adk, the -y default) or --agent adk_go; --agent also accepts a template repository (org/repo, optionally with --ref) or local@<path>; confirm the exact syntax with agents-cli create --help. RAG is no longer a built-in template (it is now a clone-and-study recipe). For a single-file learning agent, use adk create instead.

Agent vs. human mode

Agents CLI serves two callers with the same commands and syntax. There is no documented --mode agent or --mode human flag. The difference is how prompts and output are handled.

Dimension	Agent mode (coding agent or CI)	Human mode (developer at a terminal)
Caller	Antigravity or another coding agent following the `google-agents-cli-*` skills; CI runners	You, typing commands directly
Prompts	`-y` / `--yes` (alias `--auto-approve`) skips prompts and fills missing values with defaults; gcloud prompts stay suppressed	`-i` / `--interactive` shows menus and prompts (for example `create -i`, or `publish gemini -i`, which lists your Gemini apps)
Inputs	Explicit flags or env vars (`publish gemini` reads `GEMINI_APP_ID` and `AGENT_RUNTIME_ID`)	Interactive answers, plus the `playground` browser UI
Output	Single-shot commands (`run "<prompt>"`) and `info --json` for parsing	Console output and local URLs meant for reading
Best for	Build-eval-deploy loops, CI/CD, repeatable releases	First login, exploration, debugging in `playground`

Exam trap: `run --mode` is not agent vs. human

agents-cli run --mode exists, but it selects the protocol used to talk to the agent (adk, a2a, adk_live). It has nothing to do with agent vs. human mode. Anti-pattern: passing -i from a coding agent or CI job leaves the command waiting on a prompt nobody answers.

Example: build and ship a new agent with Antigravity

Brief: ask Antigravity to "use agents-cli to build a support agent for order lookups". The workflow and scaffold skills activate, and Antigravity asks about tools, inputs, outputs and success criteria.
Scaffold: Antigravity runs agents-cli create support-agent --prototype -y, then writes app/agent.py with the adk-code skill.
Check locally: agents-cli run "<prompt>" and agents-cli lint; you open agents-cli playground to try it yourself.
Gate: agents-cli eval run must pass before any cloud step.
Ship: agents-cli deploy to Agent Runtime, then agents-cli publish gemini to register the agent in your Gemini Enterprise app.

Example: fix a quality regression on a deployed agent

Widen coverage: agents-cli eval dataset synthesize adds scenarios around the reported failure.
Measure: agents-cli eval run, then agents-cli eval analyze to cluster the failures by cause.
Repair: agents-cli eval optimize, or patch the instructions by hand.
Prove it: re-run eval run and use agents-cli eval compare on the old and new result files to confirm nothing regressed.
Roll out: agents-cli deploy --update-only updates the existing Agent Runtime deployment instead of creating a duplicate.

Example: harden a prototype for production

Add a target and pipeline: agents-cli scaffold enhance -d cloud_run --cicd-runner github_actions (preview with --dry-run).
Provision: agents-cli infra single-project to plan, then rerun with --apply; or agents-cli infra cicd for a staging and prod split.
Observe: ask Antigravity to "set up observability"; the observability skill covers Cloud Trace, prompt-response logging and BigQuery Agent Analytics.
Verify: agents-cli info confirms the project config and CLI version before the first pipeline run.

Dev-to-Prod Lifecycle & Claude Code Comparison

Plan

Plan in Antigravity (/plan) → design spec.

Scaffold

Agents CLI skills scaffold the ADK project → agents-cli run / playground.

Evaluate

Write eval datasets → agents-cli eval run → iterate until they pass.

Deploy

agents-cli deploy → Agent Runtime, Cloud Run or GKE.

Publish

Publish to Gemini Enterprise. Gemini Enterprise passes the user's email to the agent. The Agent Runtime ↔ Gemini Enterprise connection is VPC-SC compliant.

Observe & govern

Observe with Cloud Trace. Govern with the Agent Platform services (see the Agent Platform guides).

Vendor-neutral comparison (see the Claude Code guide)

Concept	Antigravity	Claude Code
Always-on project memory	`AGENTS.md` / `GEMINI.md`	`CLAUDE.md`
Skills	`.agents/skills/<name>/SKILL.md`	`.claude/skills/<name>/SKILL.md`
Subagents	`.agents/agents/<name>.md`	`.claude/agents/<name>.md`
MCP config	`mcp_config.json`	`.mcp.json`
Hooks	`hooks.json` (`PreToolUse`, `PostToolUse`, `Stop`, …)	`settings.json` hooks (`PreToolUse`, …)
Permission precedence	Deny > Ask > Allow	deny → ask → allow
Agent-building helper	Agents CLI works with both	Agents CLI works with both
Surfaces	App, CLI (`agy`), IDE and Python SDK	Terminal CLI plus IDE integrations
Models	Gemini by default; the model selector also lists some Claude and GPT-OSS models (availability depends on your plan)	Claude models only; on Google Cloud they are served as Agent Platform partner models
Google Cloud auth and billing	Google sign-in; Google Cloud credentials when it drives `gcloud` or `agents-cli`	`CLAUDE_CODE_USE_VERTEX=1` plus ADC; usage is billed to your Google Cloud project, Provisioned Throughput optional
Built-in isolation	Terminal sandbox, permission rules, Git worktrees for subagents	Permission rules and Claude Code's own sandboxing settings
Hardened environment	Cloud Workstations, Agent Sandbox on GKE	Same options: Cloud Workstations, GKE Sandbox (gVisor)
Best fit	Teams that want parallel subagents, artifacts review and Gemini-first workflows	Teams standardized on Claude that still need Google Cloud IAM, residency and billing

Key point

MCP servers and SKILL.md skills carry over between harnesses. Agents CLI installs the same skills into Antigravity, Claude Code and Codex.

Claude Code on Agent Platform: model access

Claude Code on Google Cloud solves for: teams that want Anthropic's coding agent but need the traffic, identity and bill to stay inside their Google Cloud project instead of a separate Anthropic API account.

Architecture

Laptop / Cloud Workstation / GKE pod
  Claude Code ── ADC (user or attached SA) ──► Agent Platform partner endpoint (Claude)
       │                                         global | multi-region (us, eu) | regional
       └── MCP calls ──► Google remote MCP servers (Model Armor floor setting)
                     └─► custom MCP on Cloud Run / GKE (Agent Gateway + Model Armor)

Enable the API

Turn on aiplatform.googleapis.com in the project that will carry the usage (a dedicated project keeps cost tracking and IAM simple).

Enable the model

In Model Garden, open the Claude model card and click Enable to accept the partner terms. Requires roles/consumerprocurement.entitlementManager; the org policy must allow cloudcommerceconsumerprocurement.googleapis.com.

Grant invoke rights

Give developers or the runtime service account roles/aiplatform.user (it carries aiplatform.endpoints.predict), or a custom role with just that permission.

Point Claude Code at the project

Set the env vars below, or run claude, pick the third-party platform login and let the wizard write them into ~/.claude/settings.json (/setup-vertex reopens it).

Verify

/status inside Claude Code must show Google Vertex AI as the API provider, with your project, region and model.

Reseller caveat

If a prohibited reseller manages your billing account, you cannot accept the Claude terms at all; the fix is on the reseller side.

Choosing the endpoint (CLOUD_ML_REGION)

Endpoint	Value	Data residency	Prompt caching	Provisioned Throughput	Pick it when
Global	`global`	No: requests are served from any supported region	Yes	No	You want the best availability and fewest capacity errors, with no residency rule
Multi-region	`us`, `eu`	Yes, within the jurisdiction	Yes	No	You need residency but still want pooled capacity
Regional	for example `us-east5`	Yes, in that region	Yes	Yes, where offered	You need a single region or reserved capacity

Endpoint and model settings

CMEK: Cloud KMS keys cannot live in the global location, so any customer-managed key requirement already rules out the global endpoint. Check the Agent Platform CMEK page for partner-model coverage before promising key control over prompts.
Per-model overrides: with CLOUD_ML_REGION=global, a model that lacks global support can be routed elsewhere through its VERTEX_REGION_CLAUDE_* variable. A malformed region value is ignored and Claude Code falls back to us-east5.
Pin models: set ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL to IDs enabled in your project. Unpinned aliases follow Claude Code's built-in defaults, which may not be enabled for you and default to Opus pricing.

Bash: point Claude Code at Agent Platform

gcloud auth application-default login          # laptop only; skip on a VM or pod with an attached SA
export CLAUDE_CODE_USE_VERTEX=1                # route Claude Code to Agent Platform
export ANTHROPIC_VERTEX_PROJECT_ID=my-proj     # wins over GOOGLE_CLOUD_PROJECT and the ADC file
export CLOUD_ML_REGION=global                  # or us / eu / us-east5
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5 # per-model region override
# export ENABLE_PROMPT_CACHING_1H=1            # 1-hour cache TTL instead of 5 minutes
# export DISABLE_PROMPT_CACHING=1              # turn caching off (on by default)
claude                                         # then /status to confirm the provider

Claude Code on Agent Platform: cost and capacity

Prompt caching is on by default in Claude Code. A coding session resends the same system prompt, tool schemas and repo context on every turn, so cached prefixes cut both latency and input cost. Caches are scoped to one Google Cloud project.
Default TTL: 5 minutes. Extended TTL: 1 hour, requested with ENABLE_PROMPT_CACHING_1H=1.
Billing shape: writing to the cache costs more than a normal input token (more again for the 1-hour TTL); reading from it costs far less.
Provisioned Throughput reserves capacity for some partner models for a fixed fee, in the regions you choose, and is bought through sales. Reserved requests are served ahead of pay-as-you-go traffic when the system is busy. It works only on regional endpoints, not global or multi-region.
Quota errors (429): on regional endpoints, check that both the primary and the background model are offered in that region, or move to global. Rate-limit increases go through Google Cloud quotas, not Anthropic.

Note

The cache multipliers on the Agent Platform pricing page at writing time: 5-minute writes cost 1.25x base input, 1-hour writes 2x, and cache reads 0.1x. Treat these as directional and recheck the pricing page before quoting them.

Claude Code on Agent Platform: keyless auth and isolation

Where Claude Code runs	Identity	Least-privilege roles	Isolation
Laptop	User ADC from `gcloud auth application-default login`	`roles/aiplatform.user` on the model project	Claude Code permission rules only; the shell sees your whole home folder
Cloud Workstations	Service account set on the workstation configuration, read through the metadata server	`roles/aiplatform.user`, plus `roles/mcp.toolUser` if it calls Google remote MCP servers	Private cluster, VPC Service Controls, no public IP (section 08)
GKE pod	Workload Identity Federation for GKE	Same roles, bound to the pod's principal	GKE Sandbox (gVisor) for agent-run builds and tests

Credentials

No API keys: none of these paths needs ANTHROPIC_API_KEY. Avoid service account key files too; use ADC from a user login or an attached identity.
Workstation tip: Cloud Workstations ships keep-alive samples for Claude Code so a suspended workstation keeps the agent's session (see section 08).
Expiring user credentials: Claude Code's gcpAuthRefresh setting runs a command (typically the ADC login) when it detects expired credentials, instead of failing mid-session.
Anti-pattern (keys in the repo): a service account key in .env or GOOGLE_APPLICATION_CREDENTIALS on a laptop is a long-lived secret the agent can read and leak.

Governing MCP traffic

Google remote MCP servers: enable a Model Armor floor setting with MCP sanitization (integrated service GOOGLE_MCP_SERVER) in the project. Every tool call and response to a supported Google MCP server is screened for prompt injection and sensitive data, whatever harness made the call.
Custom MCP servers: host them on Cloud Run or GKE behind Agent Gateway, which applies access policies and Model Armor templates to agent egress traffic.
Residency: some Google MCP servers route Model Armor calls across jurisdictions, so check the supported-products list if residency matters.

Claude Code on Agent Platform: organization policy guardrails

Constraint	What it governs	What to set for Claude Code
`constraints/vertexai.allowedModels`	Which Model Garden models principals can use, per action, written as `publishers/PUBLISHER/models/MODEL:ACTION` (`predict`, `deploy`, `tune`)	Allow `:predict` on every Claude model the team pins (primary and background), plus `publishers/anthropic/models/count-tokens:predict`, because Claude token counting has its own publisher model ID
`constraints/vertexai.allowedPartnerModelFeatures`	Advanced partner-model features: `web_search` and `structured_outputs`. In projects under an organization both are blocked until allowed	Allow at publisher (`publishers/anthropic`), model, or `model:feature` granularity, and only for features the sessions need
Restrict service usage	Which Google APIs can be enabled	Keep `cloudcommerceconsumerprocurement.googleapis.com` allowed so an entitlement manager can accept Claude terms
`constraints/iam.disableServiceAccountKeyCreation`	Creation of new external service account keys	Enforce it so the keyless pattern above cannot be bypassed with a JSON key

Allowlist semantics and limits

A custom allow list implicitly denies every model not listed; with no policy set or inherited, every model is allowed. An explicit deny at the folder wins over an allow at the project, unless the project policy is set to override its parents. List each model individually (there is no "all third-party models" value) and stay under 500 allowed plus denied values per policy. The policy applies to every principal in the resource, not per user, and only to Model Garden models (not Model Registry). Anti-pattern: allowing the Claude model but not count-tokens, so token-count requests stay blocked.

Claude Code on Agent Platform: Developer Knowledge MCP server

The Developer Knowledge MCP server (https://developerknowledge.googleapis.com/mcp, remote HTTP transport) lets Claude Code ground its answers in current Google developer documentation through three tools: search_documents, get_documents and answer_query.

Auth path	How Claude Code sends it	Watch out for
API key (the path Google documents for Claude Code)	`X-Goog-Api-Key` header	Restrict the key to the Developer Knowledge API; keep it out of committed files
ADC bearer token	`Authorization: Bearer` plus `X-Goog-User-Project`	Tokens from `print-access-token` last one hour; the quota project header needs `serviceusage.services.use` (for example `roles/serviceusage.serviceUsageConsumer`)

Bash: add the server (local scope)

gcloud services enable developerknowledge.googleapis.com
claude mcp add google-developer-knowledge --transport http \
  https://developerknowledge.googleapis.com/mcp --header "X-Goog-Api-Key: $DK_KEY"

That command writes to local scope. For a team-shared, keyless setup, commit a project-scoped .mcp.json whose headersHelper script prints a fresh ADC token on every connection:

JSON: .mcp.json

{
  "mcpServers": {
    "google-developer-knowledge": {
      "type": "http",
      "url": "https://developerknowledge.googleapis.com/mcp",
      "headersHelper": "/usr/local/bin/dk-headers"
    }
  }
}

Helper contract, approval and errors

Helper contract: the command must print a JSON object of string headers (here Authorization and X-Goog-User-Project); Claude Code reruns it on reconnect, so expiring tokens do not break the session.
Approval: project-scoped servers stay pending until each developer trusts the workspace and approves them; a cloned repo cannot pre-approve its own servers.
Errors: a 403 asking for a quota project means the X-Goog-User-Project header is missing; a 404 or 403 on /mcp usually means the API is not enabled.

Claude Code on Cloud Workstations

Layer	Setting	Why it matters for a coding agent
Cluster	Private cluster, reached through a Private Service Connect endpoint and a private DNS zone for the cluster hostname	No one can open the workstation from the public internet
Perimeter	VPC Service Controls; restrict the Compute Engine API whenever the Cloud Workstations API is restricted, and keep Cloud Storage and Artifact Registry VPC-accessible for image pulls	Source code and model traffic stay inside the perimeter
VM network	`--disable-public-ip-addresses` on the configuration, plus Private Google Access or Cloud NAT (one is required)	Private Google Access is how Claude Code still reaches the Agent Platform and MCP endpoints on `googleapis.com`
Image	Custom container image with Claude Code, gcloud, linters, managed settings and the MCP header helper baked in	Every developer starts from the same reviewed toolchain
Service account	Set on the configuration; needs Artifact Registry Reader for a private image and log and metric write permissions	It is the identity ADC resolves to inside the workstation (see the table above)
Audit	`--enable-audit-agent` turns on Linux `auditd` logging (the service account needs `logging.buckets.write`)	Records what agent-run commands did on the VM

Bash: SSH tunnel for a local IDE

gcloud workstations start-tcp-tunnel --project=PROJECT --region=REGION \
  --cluster=CLUSTER --config=CONFIG --local-host-port=:2222 WORKSTATION 22
# then point VS Code Remote-SSH (or any SSH client) at localhost:2222

Workstation access notes

Local IDE access: the tunnel forwards a local port to the workstation's SSH port; it authenticates with your gcloud credentials and is authorized by the workstation's IAM policy, so nothing listens publicly. gcloud workstations ssh does the same in one command.
Private cluster caveat: the laptop must sit on a network that reaches the PSC endpoint (for example over VPN or Interconnect), or the tunnel cannot connect.
Keep TCP on: --disable-tcp-connections blocks plain TCP connections, so leave it unset when developers rely on the SSH tunnel.
Org policy interplay: if constraints/compute.trustedImageProjects is enforced, allow projects/cos-cloud, because workstation VMs boot from Container-Optimized OS images.

Claude Code on Agent Platform: setup pitfalls

Pitfall	Symptom	Fix
Model not enabled	"Model not found" (404) even though the caller has `roles/aiplatform.user`	Enable the model in Model Garden; an entitlement manager must accept the partner terms
Org policy blocks procurement	Nobody can enable the Claude model, even with the entitlement manager role	Allow `cloudcommerceconsumerprocurement.googleapis.com` in the restrict-service-usage policy
Unsupported region	404 for one model, or 429 on a regional endpoint	Pick a region listed for that model, use `global` or `us`/`eu`, or set the model's `VERTEX_REGION_CLAUDE_*` override
Wrong project billed	Calls land in an unexpected project	`ANTHROPIC_VERTEX_PROJECT_ID` takes priority over `GOOGLE_CLOUD_PROJECT` and the ADC file; set it explicitly
Expired ADC	"Could not load the default credentials" mid-session	Re-run the ADC login, set `gcpAuthRefresh`, or move to a workstation with an attached service account
Global plus residency or CMEK	Compliance review fails	Switch to a regional or `us`/`eu` endpoint; global has no residency guarantee
Expecting Provisioned Throughput on global	Reserved capacity is never used	Provisioned Throughput applies to regional endpoints only
Unrestricted shell on a laptop	The agent reads `~/.ssh`, kubeconfigs or cloud credentials, or pushes outside the perimeter	Move sessions to a VPC-SC Cloud Workstation, keep deny rules, and never run `--dangerously-skip-permissions` outside a sandbox
Model missing from the org allowlist	The model is enabled in Model Garden, yet calls to it are refused	Add `publishers/anthropic/models/MODEL:predict` (and `count-tokens:predict`) to `vertexai.allowedModels`, or check for a deny inherited from a folder
Partner feature blocked	Requests that use web search or structured outputs are rejected in an organization project	Allow the feature in `vertexai.allowedPartnerModelFeatures` at the narrowest granularity that works
Static ADC token in MCP headers	The Developer Knowledge server starts returning auth errors about an hour into the session	Replace the pasted token with a `headersHelper` script, or use an API key
Tunnel from outside the private network	`start-tcp-tunnel` cannot reach a private-cluster workstation	Connect from a network that reaches the PSC endpoint (VPN or Interconnect); private clusters accept no public clients, browser or tunnel

Exam Traps & Failure Modes

Symptom	Root cause	Fix
A rule in `.agents/rules/` never applies	Missing or camelCase `trigger`, or file in a nested subfolder	Use snake_case `trigger`, keep the file flat, or register it in `rules.json`
A skill never activates	Vague `description`	Say what the skill does and when to use it
A huge always-on rule gets ignored	20k-token rules budget exceeded → reduced to a pointer	Switch to `model_decision` or a skill
A remote MCP server fails	Legacy SSE endpoint	Point to the Streamable HTTP `/mcp` endpoint, or use a stdio bridge
The agent wipes files on the host	`always-proceed` / `--dangerously-skip-permissions` without a sandbox	Sandbox + `proceed-in-sandbox` + deny rules
Parallel subagents overwrite each other	Shared workspace, overlapping scope	`branch` (Git worktree) and non-overlapping scopes
The agent slows to a crawl	Slow synchronous hook	Keep hooks fast. Move heavy work out of the loop
A workstation loses agent state overnight	Idle timeout stops the VM	`idleAction=SUSPEND` + keep-alive hooks
Data exfiltration risk from dev VMs	Public IPs, public cluster	Private cluster, VPC-SC, `vmExternalIpAccess` constraint
The agent shipped without evals	Deploy before evaluating	`agents-cli eval run` with an eval dataset is a release gate
A coding agent or CI job hangs on an `agents-cli` command	`-i` / `--interactive` passed in an unattended run	Use `-y` / `--yes` plus explicit flags or env vars
`agents-cli publish gemini-enterprise` missing from `--help`	Renamed to `publish gemini`; the old name is a hidden alias	Use `agents-cli publish gemini`
Treating Antigravity as the agent runtime	Mixing up the dev harness and production	Deploy the ADK agent to Agent Runtime, Cloud Run or GKE

Glossary, Resources & Practice Quiz

Artifact

A structured deliverable (plan, diff, walkthrough, recording) that you review in place of individual tool calls.

Planning vs. Fast mode

Plan-first execution vs. direct execution.

Progressive disclosure

Only the name and description of skills (and model_decision rules) go into the context until they are needed.

Plugin

A namespaced bundle of skills, rules, hooks, MCP servers and agents.

Terminal sandbox

An OS-level boundary for agent shell commands.

Agents CLI

A skills and command toolkit that lets any coding agent build, evaluate, deploy and publish ADK agents.

Agent Sandbox on GKE

A gVisor-isolated runtime for untrusted, LLM-generated code.

Workstation suspension

idleAction=SUSPEND keeps VM memory and agent state through idle periods.

ADK CLI (adk)

The framework-level CLI bundled with ADK (adk create, adk run), used for learning and inner-loop work.

Agents CLI extension

An experimental, commit-pinned add-on that contributes skills and command overrides at project or --global scope.

Skill Registry

A private Agent Platform repository (Preview) from which agents discover and load versioned skills.

Skill revision

An immutable snapshot of one version of a Skill Registry skill.

Non-interactive mode

Running agents-cli with -y / --yes so missing values fall back to defaults and no prompt blocks a coding agent or CI job.

Partner model (Claude on Agent Platform)

An Anthropic model served by Agent Platform after you enable it in Model Garden; billing, IAM and quotas are Google Cloud's.

Global endpoint

The global location for partner models; best availability, separate quotas, no data residency and no Provisioned Throughput.

Multi-region endpoint

The us or eu location; keeps processing inside the jurisdiction while pooling capacity.

Prompt caching

Reuse of a repeated prompt prefix for 5 minutes by default or 1 hour on request; cache reads are billed far below normal input.

Provisioned Throughput

Reserved, fixed-fee model capacity in chosen regions that takes priority over pay-as-you-go traffic.

CLAUDE_CODE_USE_VERTEX

The Claude Code env var that switches it from the Anthropic API to Agent Platform, used with ANTHROPIC_VERTEX_PROJECT_ID and CLOUD_ML_REGION.

Model Armor floor setting

Project-wide minimum filters; with the GOOGLE_MCP_SERVER integration it screens calls to Google remote MCP servers.

vertexai.allowedModels

The list constraint that allows or denies Model Garden models per action (predict, deploy, tune); a custom allow list implicitly denies everything else.

vertexai.allowedPartnerModelFeatures

The list constraint that unlocks partner-model features such as web_search and structured_outputs, which are blocked by default in organization projects.

Developer Knowledge MCP server

Google's remote MCP endpoint for searching and retrieving official developer documentation (search_documents, get_documents, answer_query).

headersHelper

A Claude Code MCP setting that runs a command at connection time and sends the JSON headers it prints, used for short-lived tokens.

Workstation TCP tunnel

gcloud workstations start-tcp-tunnel, an IAM-authorized forward from a local port to a workstation port, used for SSH from a local IDE.

Characterization test

A test that records what existing code does today, so a refactor can prove behavior did not change.

Revision traffic split

An Agent Runtime setting (Preview) that sends set percentages of traffic to active revisions; the default sends all traffic to the latest revision.

CodeMender

Google's code security agent on Agent Platform (Preview) that verifies a vulnerability with an exploit and proposes a validated patch (cm fix).

Official sources: antigravity.google/docs (overview, artifacts, implementation-plan, rules, skills, hooks, plugins, mcp, subagents, permissions, sandbox, settings, cli/gcli-migration) · adk.dev/get-started/agents-cli · github.com/google/agents-cli (README, CLI and skills reference, extensions guide, evaluation guide) · google.github.io/agents-cli · docs.cloud.google.com/gemini-enterprise-agent-platform/build/skill-registry · docs.cloud.google.com/gemini-enterprise-agent-platform/agents/quickstart-adk · docs.cloud.google.com/gemini/enterprise/docs/register-and-manage-an-adk-agent · docs.cloud.google.com/workstations (overview, agent-optimized-development, VPC-SC & private clusters) · docs.cloud.google.com/kubernetes-engine/docs/concepts/machine-learning/agent-sandbox · docs.cloud.google.com/gemini-enterprise-agent-platform/models/partner-models (use-partner-models, claude/use-claude, claude/prompt-caching) · docs.cloud.google.com/gemini-enterprise-agent-platform/resources/locations · docs.cloud.google.com/gemini-enterprise-agent-platform/machine-learning/general/cmek · docs.cloud.google.com/model-armor/model-armor-mcp-google-cloud-integration · docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-overview · docs.cloud.google.com/gemini-enterprise-agent-platform/models/control-model-access · docs.cloud.google.com/organization-policy/reference/org-policy-constraints · docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-revisions-and-traffic · docs.cloud.google.com/gemini-enterprise-agent-platform/agents/codemender/fix-and-patch · docs.cloud.google.com/workstations/docs (develop-code-using-local-vscode-editor, ssh-support, customize-development-environment) · docs.cloud.google.com/sdk/gcloud/reference/workstations (start-tcp-tunnel, configs/create) · developers.google.com/knowledge/mcp · adk.dev/context/caching · code.claude.com/docs/en/google-vertex-ai and code.claude.com/docs/en/mcp (Anthropic).

Related guides

Agent Development Kit (ADK): the framework Agents CLI scaffolds, evaluates and deploys.
Claude Code & Agent SDK: the equivalent harness concepts (CLAUDE.md, skills, subagents, hooks, permissions).
MCP: transports and server design behind mcp_config.json.
AgentOps and Responsible AI: evaluation gates, observability and governance after deployment.

Audio Deep Dive & Study Downloads

Listen to the 69-minute Antigravity & Agents CLI audio deep dive, open the 21-slide architectural deck and sketchnote infographic in the Hub Viewer, or drill scenario questions on surfaces, rules vs. skills, MCP transports, hooks, subagent isolation, sandboxing, and the Agents CLI lifecycle.

Antigravity & Agents CLI (Video Walkthrough)

Google Antigravity & Agents CLI: Dev-to-Prod Lifecycle (Podcast)

Open Slide Deck & Infographic in Hub Viewer Launch Interactive Antigravity Practice Quiz →

Self-Assessment Questions (Click to Reveal)

Q1. Your new file in .agents/rules/ has trigger: alwaysOn and the agent ignores it. Why?

The trigger value is invalid (camelCase), so the rule is silently discarded. Use always_on, and keep the file directly in .agents/rules/ (nested folders need rules.json).

Q2. When should a piece of guidance be a rule and when a skill?

A rule is a persistent constraint ("never import internal/"). A skill is an on-demand procedure ("how to run DB migrations"). Skills load through progressive disclosure: only the name and description sit in context until the task matches.

Q3. A remote MCP server only exposes the legacy HTTP+SSE transport. How do you connect it?

Antigravity does not support legacy SSE. Point to a Streamable HTTP endpoint (url) if one exists, or run a stdio bridge such as mcp-remote (command/args).

Q4. Two parallel subagents edit the same files and overwrite each other. What do you change?

Use the branch workspace mode so each subagent works in its own Git worktree, and give them non-overlapping scopes.

Q5. You picked the App's "Full machine" preset. Are agent commands sandboxed?

No. App security presets never turn the terminal sandbox on. Enable sandbox mode yourself, typically with Proceed in Sandbox. Commands that run outside the sandbox have full host privileges.

Q6. A coding agent on a Cloud Workstation loses its in-memory state after lunch. What is the fix?

Set idleAction=SUSPEND with an idleTimeout and add keep-alive lifecycle hooks (start keep_alive.sh while the agent works, kill it when it waits for input). Suspension keeps RAM, processes and agent context.

Q7. List the Agents CLI path from an empty folder to Gemini Enterprise.

uvx google-agents-cli setup → agents-cli create + install → run / playground → eval run (release gate) → scaffold enhance --deployment-target if needed → deploy → register with Gemini Enterprise in one Agents CLI command (agents-cli publish gemini; publish gemini-enterprise is the older hidden alias).

Q8. Is Antigravity where your shipped ADK agent runs in production?

No. Antigravity is the developer's harness. The ADK agent you ship runs on Agent Runtime, Cloud Run or GKE, and can be distributed through Gemini Enterprise.

Antigravity & Agents CLI

About these notes

Overview & Mental Model

Google Antigravity

Agents CLI

Rule 0: harness ≠ runtime

Surfaces: App, CLI, IDE & SDK

Facts to remember

Agent-First Workflow: Plans, Artifacts & Verification

Planning mode

Fast mode

Analysis & discovery

Clarifying interview

Implementation plan

Review → execute

Exam trap: plans vs. file edits

Multi-file refactoring & runtime optimization

Automated vulnerability patching

Refactoring and runtime optimization playbook

Key point

Walkthrough: rename a module boundary across a monorepo

Walkthrough: cut response latency of a deployed ADK agent

Why the Stop hook carries the test gate

Anti-patterns

Rules, Skills & Workflows

Rule mechanics

Skills: on-demand procedures and runbooks

Workflows (legacy, IDE)

MCP, Hooks & Plugins

MCP servers: mcp_config.json (mcpServers map)

Hook outputs & limits

Plugins: namespaced bundles

Discovery & Precedence

Workspace

Directory rules

Global

Team pattern

Subagents, Browser Agent & Parallel Work

How subagents work

CLI & SDK

Browser subagent & Automations

Permissions, Execution Modes & Terminal Sandbox

Terminal sandbox (enableTerminalSandbox / --sandbox; off by default, turned on automatically in auto mode)

Secure Dev Environments: Cloud Workstations & GKE

Cloud Workstations: managed dev environments on Google Cloud

Agent Sandbox on GKE

Agents CLI: Build → Evaluate → Deploy → Publish

Positioning: Agents CLI vs. ADK CLI vs. gcloud vs. Antigravity

Rule of thumb

Bundled skills

Installing and scoping skills

Extensions (experimental)

Relation to Skill Registry

Key point

Lifecycle commands

Note

Agent vs. human mode

Exam trap: run --mode is not agent vs. human

Example: build and ship a new agent with Antigravity

Example: fix a quality regression on a deployed agent

Example: harden a prototype for production

Dev-to-Prod Lifecycle & Claude Code Comparison

Plan

Scaffold

Evaluate

Deploy

Publish

Observe & govern

Key point

Claude Code on Agent Platform: model access

Enable the API

Enable the model

Grant invoke rights

Point Claude Code at the project

Verify

Reseller caveat

Endpoint and model settings

Claude Code on Agent Platform: cost and capacity

Note

Claude Code on Agent Platform: keyless auth and isolation

Why the `Stop` hook carries the test gate

MCP servers: `mcp_config.json` (`mcpServers` map)

Terminal sandbox (`enableTerminalSandbox` / `--sandbox`; off by default, turned on automatically in `auto` mode)

Exam trap: `run --mode` is not agent vs. human