agents-cli
CLI Toolgoogle/agents-cli
CLI and skills for building AI agents on Google Cloud.
Overview
A command-line interface and skill set that turns any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud. It provides commands for scaffolding, evaluation, deployment, and observability, integrating with the ADK framework.
README Preview
\n \n agents-cli\n The CLI and skills for building agents on Gemini Enterprise Agent Platform.\n\n \n Get Started | \n Skills | \n Commands | \n PyPI | \n Issues | \n Docs | \n Release Notes | \n Star us\n \n\n\n---\n\nTurn your favorite coding assistant into an expert at building and deploying agents on Google Cloud.\n\n**Agents CLI in Agent Platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.\n\n**Works seamlessly with:**\n[Antigravity CLI](https://antigravity.google/) • [Claude Code](https://docs.anthropic.com/en/docs/claude-code) • [Codex](https://github.com/openai/codex) • *and any other coding agent.*\n\n## Get Started\n\n**Prerequisites:** Python 3.11+, [uv](https://docs.astral.sh/uv/getting-started/installation/), and [Node.js](https://nodejs.org/en/download).\n\n### 1. Install\n\n```bash\nuvx google-agents-cli setup\n```\n\n\nOr just the skills — your coding agent will handle the rest\n\n```bash\nnpx skills add google/agents-cli\n```\n\n\n\n### 2. Open your coding agent\n\nLaunch [Antigravity CLI](https://antigravity.google/), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or any coding agent you prefer.\n\n### 3. Build your first agent\n\nAsk your coding agent to build something — e.g. *"Use agents-cli to build a caveman-style agent that compresses verbose text into terse, technical grunts"*\n\nSee the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tutorial/) for a step-by-step walkthrough.\n\n**[Browse the full documentation →](https://google.github.io/agents-cli/)**\n\n---\n\n## Agent Skills\n\n| Skill | What you
FAQ (5)
TroubleshootingHow do I fix PermissionError [WinError 5] Access denied when running agents-cli setup or other commands on Windows?
This happens in agents-cli versions before 1.9.0 when a tool such as uv.exe is found on disk but Windows blocks it from executing, commonly because of AppLocker, Defender, or NTFS permission policies. shutil.which() finds the executable on Windows without verifying that it can actually run, and the old subprocess helpers did not catch the resulting PermissionError.
Fix by upgrading agents-cli to 1.9.0 or newer:
python -m pip install --upgrade agents-cliVerify the installation:
agents-cli infoAfter the upgrade, the CLI reports a clean tool-resolution error instead of a raw Python traceback. To make the command succeed, you must also ensure uv.exe is allowed to execute:
uv --versionIf that still returns "Access is denied", ask your IT administrator to allow uv.exe under AppLocker/Defender, reinstall uv in a permitted location, or run the CLI in an environment where uv is not blocked. The same issue could affect setup, lint, login, deploy, publish, and scaffold commands because they share the same subprocess runner.
TroubleshootingWhy does agents-cli info show "Installed skills: none" even after running setup?
This is a bug in agents-cli v1.9.0 where agents-cli info runs npx skills list --json without the -g flag, so it only detects project-scoped skills and misses globally installed ones (installed by agents-cli setup to ~/.agents/skills/). The skills are actually installed correctly — verify with ls ~/.agents/skills/google-agents-cli-*/SKILL.md or npx -y skills list -g --json. The bug is fixed in v1.12.0, so upgrade your CLI: uv tool install google-agents-cli --upgrade (or re-run uvx google-agents-cli@latest setup).
TroubleshootingWhy do the Agent Runtime deploy and observability guides give conflicting instructions about running `agents-cli infra single-project` before deployment?
The contradiction was a documentation bug fixed in agents-cli v1.8.0. Use this ordering rule:
- **Basic Agent Runtime / Cloud Run:** deploy directly; do not run infra single-project first.
- **GKE:** run deployment normally; the deploy process performs the required targeted Terraform.
- **Terraform-managed observability, any target:** run agents-cli infra single-project --apply before the first deploy.
- **Existing imperative deployment:** do not apply Terraform afterward unless you first import or delete the existing resources before switching ownership. Otherwise, keep imperative ownership and configure observability manually.
Applying Terraform after an imperative Agent Runtime deployment can create or target a second Runtime. Upgrade to v1.8.0 or later for the corrected README, migration guide, and skill documentation.
TroubleshootingHow do I prevent concurrent `agents-cli deploy --no-wait` processes from overwriting each other's pending Agent Runtime operations?
Upgrade to **agents-cli v1.8.0 or newer**, which fixes the v1.3.1 race by atomically claiming deployment_metadata.json with a unique owner ID, holding a cross-process lock during Runtime revalidation and remote submission, and making cleanup/finish operations owner-aware.
python -m pip install --upgrade agents-cli==1.8.0If you cannot upgrade immediately, serialize deployments so only one CLI process runs per agent project:
flock -n /tmp/my-agent-deploy.lock agents-cli deploy --no-waitDo not run parallel deploy jobs in CI. If a process fails after remote submission with an unknown outcome, leave the operation in fail-closed state=starting and reconcile it manually rather than clearing the metadata.
TroubleshootingWhy does agents-cli scaffold from a remote Git template omit symlinked shared files and cause ImportError?
This is a regression in agents-cli 1.4.1–1.5.0: remote template scaffolding skipped every symlink as a security warning but still reported success, so directories such as app/shared -> ../../shared were missing. Upgrade to agents-cli 1.7.0 or newer, then rerun the scaffold command and verify the target exists, for example demo/app/shared/config.py. If you cannot upgrade, replace intra-repo symlinks with physical copied directories and keep them synchronized with a script and CI drift check. Do not rely on local@ testing alone: it dereferences symlinks during pre-copy and can hide the remote-template failure.