All notable changes to this project will be documented in this file.
- First-party extensions and templates move to
google/agents-cli-extensions. Installing one fromgoogle/agents-clishows a deprecation warning that points to the new location.- The
google-agents-cli-extensionspackage installs from PyPI without a trust prompt.
- The
- A git extension pinned to a commit SHA must be on a branch or tag of the repo it names.
- The LangChain extension template supports
--session-type cloud_sql, which stores conversation checkpoints and long-term memory in Cloud SQL for PostgreSQL. agents-cli createno longer reports success when the Google Cloud credential or API check fails.- When
agents-clican't get a Google Cloud access token, it explains why and suggestsagents-cli login. - Generated projects ignore the
artifacts/and.google-agents-cli/directories thatagents-cli evalandagents-cli runwrite. - Go projects serve
/apps/{app_name}/app-infofrom ADK Go'sexp/appinfopackage, and new projects no longer contain anappinfo/folder.- Action needed: if you kept a customized
main.goduringagents-cli scaffold upgrade, change the import"<project>/appinfo"to"google.golang.org/adk/v2/exp/appinfo".
- Action needed: if you kept a customized
agents-cli deployruns pre-flight checks before source builds.- Before uploading, it checks for issues that would break the remote build and explains each one: a
uv.lockpointing at a package index the builder can't reach, a missing or stale lock, build inputs excluded by.gcloudignoreor.gitignore, path dependencies outside the upload, or a base image Python that doesn't matchrequires-python. --skip-preflightskips the checks.deploy --dry-runexits 1 on pre-flight errors. Scripts and CI jobs that run it may need an update.- #95
- Before uploading, it checks for issues that would break the remote build and explains each one: a
agents-cli deployadds--remove-env-vars KEY,...,--clear-env-vars,--remove-secrets KEY,...and--clear-secretsfor Cloud Run and Agent Runtime.- A key that is in the project
.envcan't be removed (delete it from.envinstead), and env vars agents-cli sets itself (such asAGENT_VERSION) are set again on every deploy. --clear-secretsalso removes secrets set outside agents-cli (such as by Terraform) and secrets mounted as volumes.- #60
- A key that is in the project
agents-cli deployshows the error reason and help links when an Agent Runtime request fails.agents-cli extension add pypi@<package>[==<version>][#<folder>]installs an extension from a wheel on PyPI, or on the index set inUV_DEFAULT_INDEX,UV_INDEX_URLorPIP_INDEX_URL, pinned to the wheel's sha256.agents-cli extension update <name> --to <version>or--to :latestmoves the pin.agents-cli scaffold enhance --from-adk-projectwrites a minimalagents-cli-manifest.yamlfor an existing ADK project without rendering a template, soeval,infoandplaygroundcan find it. Use--dry-runto preview and--forceto replace an existing manifest.agents-cli scaffold create -a claude --memory-bankscaffolds a Claude agent with long-term memory in Vertex AI Memory Bank, which works the way ADK's does. The agent recalls the user's memories at the start of each turn, learns from each finished turn, and can call asearch_memorytool. Other agents reject the flag; ADK agents can follow thecross-session-memoryrecipe.- Memory is per user. For A2A callers without authentication, it lasts one conversation, as in ADK.
- With
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTon, Claude agents record the system prompt the model got, recalled memories included, asgen_ai.system_instructionson the turn span.
- Claude Agent SDK projects send
x-goog-api-client: agents-cli-app/<version>+claude-agent-sdkon model calls, so Google can count usage from agents-cli projects. SetDO_NOT_TRACK=1orAGENTS_CLI_TELEMETRY=0to turn it off; your ownANTHROPIC_CUSTOM_HEADERSare always sent. Existing projects are unchanged until they adopt the new template code. agents-cli login --status,login -iandsetupwarn when Google Cloud credentials work but agents can't call Gemini yet, and say how to fix it.agents-cli loginwith the Gemini API key option prints the.envchanges a generated project needs to use the key, instead of reporting "Continuing without authentication".agents-cli createexplains which Google Cloud setup step failed.agents-cli runandagents-cli playgroundcheck the agent's Google Cloud credentials before starting it.- Model errors from
agents-cli run, such as permission denied, disabled API, billing disabled, quota, or an invalid API key, include a one-line fix.
- Model errors from
agents-cli runprints the local-server banner and a failed run's error once, and shows auth errors as plain text instead of Python object reprs.agents-cli infra single-projectstops withterraform importinstructions when an existing Agent Runtime engine is missing from Terraform state, instead of creating a duplicate. On a new project the first run may log "Skipping the Agent Runtime import check" until Terraform enables the Vertex AI API.google-agents-clino longer installs scikit-learn, scipy, litellm, jsonschema or ruamel.yaml, which roughly halves its install size. Eval commands work as before.- New ADK Python projects pin FastAPI below 0.142.0, so traces from agents on Agent Runtime and Cloud Run are no longer dropped for requests the platform forwards as unsampled.
- New Go projects use ADK Go v2.7.1.
- For Go projects on ADK Go v2.5.0 or later,
agents-cli playgroundhonors--hostand binds127.0.0.1by default, the same as Python projects. Pass--host 0.0.0.0to reach it from another machine. Older projects keep binding all interfaces. - Action needed: when you run
agents-cli scaffold upgradeon a Go project and keep your ownDockerfile, add"--host", "0.0.0.0"after"web"in itsENTRYPOINT. ADK Go v2.5.0 and later listen only on localhost by default, so the container would otherwise get no traffic.
- For Go projects on ADK Go v2.5.0 or later,
- The
setup.mdprompt no longer stops after install to ask for a new session. The coding agent reads the installed workflow skill and continues.
- Cloud Run deployments support Agent Identity.
agents-cli deploy --agent-identitydeploys a Cloud Run service with Agent Identity.- New projects default using Agent Identity for Cloud Run deployments. To migrate an old project so that it uses Agent Identity, run
agents-cli scaffold enhancewith--cloud-run-identity-type agent_identity. - To create a new project that uses a service account instead, run
agents-cli scaffold createwith--cloud-run-identity-type service_account.
agents-cli eval runandagents-cli eval gradeend with aRESULT: PASSorRESULT: FAIL (...)line, preceded on failure by the metrics and cases that failed and a next step.- Set a minimum mean score per metric with a
thresholds:map in the eval config, or for one run with--fail-under METRIC=SCORE(repeatable, one metric each). A missed threshold exits 1.pass_ratein the results is filled from the threshold when the eval service doesn't report one. - Breaking: a run where any case errored now exits 1, even without thresholds. If the errors are rate limits, lower
--qps.
- Set a minimum mean score per metric with a
agents-cli loginsigns in both the gcloud CLI and Application Default Credentials (gcloud auth login --update-adc), so commands that rungcloudwork right after login.- When only Application Default Credentials are available and gcloud has no credentials of its own, agents-cli passes an ADC access token to the
gcloudcommands it runs. GKE deploys in that setup are not covered yet. - Note: the account you sign in with also becomes gcloud's active account.
- When only Application Default Credentials are available and gcloud has no credentials of its own, agents-cli passes an ADC access token to the
- New projects record
create_params.app_nameinagents-cli-manifest.yaml: the name the server serves the agent under (/apps/{app_name}/...).run,eval,playground,deployandpublishuse it; projects without it keep using the basename ofagent_directory.eval generate --app-nameandeval run --app-namedefault to the project's app name instead ofapp.
agents-cli deploy --image <artifact-registry-uri>works for Agent Runtime. The Agent Runtime service agent needsroles/artifactregistry.readeron the repository.--build-argscan't be combined with--image, and an existing agent can't switch between a source build and--image.- Agent Runtime deploys of A2A agents register the agent card in Agent Registry, so the agent shows up as A2A-capable in Gemini Enterprise.
agents-cli deploy --dry-runalso validates a GKE deployment against Google Cloud.agents-cli extension add <name>pins a first-party extension to the latest release compatible with your agents-cli instead ofmain. Pass--ref mainto trackmain.agents-cli extension update --to <ref|:latest>moves a pin. First-party extensions installed frommainmove to the latest release on their nextupdate.
agents-cli extension add langchainandagents-cli extension add claudeinstall instead of failing with "has no agents-cli-extension.yaml".agents-cli extension addinstalls extensions from agents-cli pre-approved repositories without a trust prompt, whether given as a shorthand, anorg/reporeference or a URL.- Usage telemetry names an extension when it serves a command if the extension comes from Google.
- Extensions can share files through symlinks that stay inside their repository. These links are copied as regular files when the extension is vendored and when its skills are installed.
- A project, template, or deployment metadata that declares a language this version of agents-cli doesn't support fails with an error listing the supported languages and suggesting
uv tool upgrade google-agents-cli, instead of being treated as Python. agents-cli scaffold enhance .in a project without a manifest records the base template it rendered (adk_python,adk_go), so laterenhanceandupgraderuns work. Before, they failed with "Base template 'local_' not found". In projects already affected, setbase_templateinagents-cli-manifest.yamltoadk_python(oradk_go) by hand.agents-cli scaffold enhance --region <region>writes the region toagents-cli-manifest.yamland to the files it renders, such as the Terraform variables. Enhancing a project without--regionkeeps the region recorded in its manifest.agents-cli publish geminirejects a response that isn't a valid A2A agent card.- Local A2A agent cards advertise the server's real port instead of
http://localhost:8000. - Claude Agent SDK projects: a turn fails when its transcript can't be saved to the session store (Cloud SQL, or the agent's own
session_store), instead of succeeding while the conversation can't be fully resumed on another instance. agents-cli setuptells a coding agent running it mid-session to read the workflow skill directly, since newly installed skills only load in the next session.- The bundled ADK code skill no longer points coding agents straight at
scaffold createfor a new project. It has them load the workflow skill and agree the agent's spec with you before scaffolding. - The bundled deploy skill now points to
GoogleCloudPlatform/genai-factoryand itsagents-cliextension for enterprise agent infrastructure. - The docs site has a new homepage and layout, a "Debug a failing agent" guide, a "Control cost" page, and guides updated to match the bundled skills.
- ADK Go is now Generally Available. The
adk_gotemplate is out of Preview: it is stable, production-ready and supported on the same terms asadk_python. This release also brings:agents-cli create --agent <template>supports ADK Go v2 templates whosemanifest.yamldeclareslanguage: go. Templates built for other ADK Go versions are rejected. A declared language that contradicts the base template (or--base-template) fails with an error explaining how to fix it.- The server e2e tests in new ADK Go projects time out after 120s instead of 60s, so multi-step agents no longer time out.
- The Python agent template is now
adk_python, selected with--agent adk_python(or-a adk_python).adkstill works as an alias. New projects recordadk_pythoninagents-cli-manifest.yaml, and upgrading a project recorded asadkrecordsadk_pythontoo. Enhancing or upgrading these projects requires this CLI version or newer. - New experimental Claude Agent SDK extension. Create a project with
agents-cli scaffold create --agent google/agents-cli/extensions/claude/template@<version>, or migrate an existing agent withscaffold enhanceand that template. It deploys to Agent Runtime or Cloud Run over A2A, calls Claude on Gemini platform only, and comes with Cloud Trace, Cloud Logging, Cloud Monitoring, optional BigQuery Agent Analytics and Cloud SQL sessions.playground,eval dataset synthesizeandeval optimizearen't supported, andpublish geminiis refused on Agent Runtime.- On Agent Runtime, these agents also serve
:query(async_create_session) and:streamQuery(async_stream_query), so an ingress Agent Gateway can govern them (for example with Model Armor) andagents-cli run --mode adkworks.
- On Agent Runtime, these agents also serve
- The agent template directory can be a nested folder, such as
src/my_agent, both in remote templates and with--agent-directory. agents-cli scaffold enhance <template>on a project agents-cli didn't create writes the template's files ascreatewould, and moves each of your files it replaces (such aspyproject.toml,README.md,Dockerfile,.env) to.agents-cli-original/, keeping its path. Your other files stay where they are. Port what you need from the folder, then delete it; enhance won't run again while it exists. New projects'.gitignoreand.gcloudignoreexclude the folder.- Extension templates can set
settings.session_types, socreateoffers and accepts only those session types, with the first as the default. A template whose list is empty or names an unknown session type is rejected. agents-cli scaffold enhance --dry-runexits with code 2 (was 0) when combined with--force, when run with-yand no override flags, or when run without a savedagents-cli-manifest.yaml.- Cloud Run projects run their Cloud Run service on the
hashicorp/google-betaprovider, pinned to~> 8.7. Other resources keephashicorp/google ~> 7.28. Existing projects pick it up throughagents-cli scaffold upgrade; ifterraform initthen reports a lockedgoogle-betaolder than 8.7, runterraform init -upgradeonce. - The server e2e tests in new Python projects time out after 120s instead of 60s, so multi-step agents no longer time out.
agents-cli deploy --dry-runfor Agent Runtime prints the plan even when a check fails. It still exits with code 1.agents-cli deploy --dry-runfor Agent Runtime warns that it could not verify the secrets when the Secret Manager API is disabled, instead of skipping the check silently.agents-cli deploy --dry-runalso validates a Cloud Run deployment against Google Cloud.- A malformed
--env-vars,--secretsor--labelsvalue fails before the project prompt. - A failed
agents-cli publish geminireports the API's reason (for example a SERVICE_DISABLED message with the enable link) instead of a bare HTTP error. - A failed terraform step in
agents-cli infraexits with a short error naming the step and how to rerun it, instead of a Python traceback. agents-cli infolists globally installed skills.agents-cli run --mode a2ano longer prints a streamed reply twice when the agent ends with the full reply as its last chunk.- The bundled skills point to
google/adk-recipesand call its agents "recipes". The ADK catalog is nowreferences/recipes.md.
- Breaking: The
adk@<name>shortcut has been removed. Pass the recipe's GitHub URL toagents-cli createinstead, and browse recipes at https://github.com/google/adk-recipes.- The scaffold's "Browse ADK recipes" option lists recipes from both
core/python/andcontrib/python/in google/adk-recipes. - Projects created with
adk@still upgrade. Theirbase_templateis rewritten to the recipe URL on the first applied change.
- The scaffold's "Browse ADK recipes" option lists recipes from both
- New projects use
google-adk>=2.12.0andgoogle-cloud-aiplatform>=2.2,<3. Agent Runtime projects also depend ongoogle-cloud-agentplatform, and the LangChain extension template moves togoogle-cloud-aiplatform>=2.2,<3. agents-cli deployto Agent Runtime registers the ADK artifact methods (async_save_artifact,async_load_artifact, and others).agents-cli deployto Agent Runtime shows the last 40 lines of the build log when a build fails, instead of only "Build failed".deploy --statusshows it too.- agents-cli's
uvcommands use public PyPI even when a machine-wideuvconfig points at a mirror, sodeployno longer breaks.agents-cli installwarns whenuv.lockuses a mirror and shows the command to re-lock.install --lockednow fails on such a lock. Scripts and CI jobs that runinstall --lockedmay need an update. agents-cli createfinds the agent code in any remote template, not only adk-recipes ones. When bothapp/and a folder-named package exist,app/wins; use--agent-directoryto pick the other. A top-levelagent_directoryin a template'sagents-cli-manifest.yamlis now respected.- LangChain agents are now named after your project, or the name you pass with
--root-agent-name, like ADK agents.- Template authors can list files under
render_filesin.template/templateconfig.yaml. Placeholders such as the agent name are then filled in in those files when a project is created.
- Template authors can list files under
- Traces from LangChain agents now record which conversation each request belongs to (
gen_ai.conversation.id), so you can follow a conversation across requests, as you already can for ADK agents. agents-cli run --mode a2ashows why an agent's task failed, was rejected or was canceled ([error]: <reason>) instead of "(no response content)".- ADK Go agents no longer lose replies for turns that take longer than 15 seconds on
/runor A2A. - The Cloud Build pipelines and Dockerfile in generated ADK Go projects retry Go module downloads, so a dropped connection to the Go module proxy no longer fails the build.
- ADK Go projects include only the session backend chosen at creation time.
agents-cli scaffold upgradestops instead of reporting success when it cannot build the template of the project's original version. It shows why, and suggests--forcewhen that can help.agents-cli scaffold upgradeno longer warns about a legacy eval file that an earlier, stopped upgrade already migrated.agents-cli setup --workspacelists each installed skill's folder once.- Extensions can no longer override
agents-cli info,login,setuporupdate. agents-cli --help, the docs and error hints showcreatecommands that work as written:-ito choose options in prompts,-yto accept the defaults (adktemplate,agent_runtimetarget).- Warnings print as
⚠️ Warning: <message>with a yellow prefix on stderr. Some warnings that used to go to stdout now go to stderr. Scripts that read warnings from stdout may need an update. - Errors that agents-cli logs print with the same red
❌ Error:prefix as other errors, and--debugoutput prints as dimDebug: …lines. - agents-cli no longer prints the google-auth quota-project warning or google-genai's automatic function calling advice.
eval runno longer prints "Could not obtain credentials" when it talks to the local agent server.
- New projects use Agent Identity by default.
agents-cli scaffold createrecordsagent_runtime_identity_default: agent_identity. Thenagents-cli deploycreates the Agent Runtime agent under its own Agent Identity principal, and the generated Terraform (infra single-project,infra cicd) does the same. To keep a service account, pass--agent-runtime-identity-default service_accounttoscaffold createorscaffold enhance. Existing projects are not changed: if the setting is missing, it reads asservice_account, andscaffold upgradedoes not migrate it.deployuses this default only when it creates a new agent. A redeploy without--agent-identityor--no-agent-identitydoes not change the identity of an existing agent.
- Extensions can ship skills. An extension declares skills in the
skills:field ofagents-cli-extension.yaml:agents-cli extension addcopies them to<project>/.agents/skills/, or to~/.agents/skills/with--global.agents-cli extension updatereplaces them with the new version's skills and lists the skills it removed.agents-cli extension removedeletes them. The new--globalflag removes the user-scope install.agents-cli installrestores the skills of every recorded extension.- A skill folder copied by an extension is managed by that extension, and manual modifications to it might be overwritten.
agents-cli extension updatekeeps the old local copy when it refuses a new version or a copy fails.- New
agents-cli deployflags for Agent Runtime and Cloud Run:--remove-labels KEY,...and--clear-labels. New aliases that matchgcloud run deploy:--update-labels,--update-secretsand--env-vars. agents-cli deploynow rejects--iap,--port,--service-accountand--cluster-nameon targets that ignored them. Before, they were silently ignored. Scripts that pass them may need an update.agents-cli runfails withAgent run failed: <reason>and a non-zero exit code when the ADK stream sends an error. Before, the run looked successful.agents-cli scaffold createshows the dependency changes, likeenhanceandupgradedo.agents-cli scaffold createkeeps the detected project in.envwhen credential checks fail, instead of writing theyour-gcp-project-idplaceholder. It also warns when--session-typeis ignored for--deployment-target none.agents-cli scaffold enhancecreates missing config and dependency files instead of skipping them.- Values in
agents-cli-manifest.yamlare now escaped, so a quote or newline in a value no longer breaks the file. Project names are limited toa-z,0-9and-. - Terminology has been adjusted in various places to use appropriate names for the Gemini ecosystem. No functional change, as old variants are kept as aliases where applicable.
- The CLI now uses
google-cloud-aiplatform2.x, andgcsfsis pinned to>=2026.10.0. The template lock files are updated. - The bundled skills list the Ambient Quality Agent (AQuA) recipe.
- Usage telemetry is now on by default. Each command writes one log entry to your own Google Cloud project with the command name, exit code, error class, duration, and CLI, Python and OS versions, never arguments or file contents. Its purpose is to provide users with analytics regarding their tool use, process efficiency, and help diagnose potential issues. The request also sends Google the CLI, Python and OS versions, CPU architecture and command name for usage analytics; no sensitive data is sent. Opt out with
AGENTS_CLI_TELEMETRY=0orDO_NOT_TRACK=1.agents-cli infonow always shows whether telemetry is on. agents-cli deploy --keyencrypts an Agent Runtime agent with a customer-managed Cloud KMS key (CMEK), so deploys work in projects that enforceconstraints/gcp.restrictNonCmekServices. The key can only be set when the agent is created, anddeploy --listshows it in a new Encryption column.agents-cli deploy --dry-runchecks an Agent Runtime deployment against Google Cloud: enabled APIs, the target engine, IAM permissions,actAson the service account, and secrets. A definite problem exits with code 1, and a check that cannot run only warns. A dry run now makes read-only network calls. A real deploy is unchanged.agents-cli deployreports unsupported flags in one format,<flag> is only supported for <targets> deployments (current target: <target>), and names only the flags you passed. An empty value for such a flag, such as--key ""on Cloud Run, is now rejected instead of ignored. Scripts that match the old error text may need updating.- New ADK Python projects set
GOOGLE_GENAI_USE_ENTERPRISE=trueinstead of the deprecatedGOOGLE_GENAI_USE_VERTEXAI. Existing projects keep working:agents-cli deployto Agent Runtime respects whichever name your.envsets. Go projects keep the old name. - New ADK Go projects enable the
gofmtandgoimportsformatters, soagents-cli lintreports formatting issues andlint --fixfixes them. - Re-applying the Terraform generated by this release, for example with
agents-cli infra single-projectorinfra cicd, no longer replaces the BigQuery log sink tables once logs have arrived. The replacement deleted every exported log.completions_viewalso gains aservice_versioncolumn with the deployment revision. Runagents-cli scaffold upgradeto get this in an existing project. - Scaffolded ADK projects no longer append a duplicate
JSONRPC 0.3interface to the agent card on every request to.well-known/agent-card.json. - A tool that exists but cannot run, such as
uv.exeblocked by AppLocker on Windows, now fails with a clear error naming the tool and the OS reason instead of aPermissionErrortraceback. - Installed extensions no longer print a warning on every command. A notice appears only when a command overridden by an extension runs.
- New flag for
agents-cli scaffold upgrade:--force. A fallback for when the 3-way merge cannot run or leaves too many conflicts, similar to the existing flag foragents-cli scaffold enhance. It generates only the new template and overwrites the scaffolding files:- Agent code, config files and files you own are kept: your tests, custom eval metrics, eval datasets, READMEs, agent guidance files,
.gitignore,deployment_metadata.jsonand Terraformenv.tfvarsfiles. - Dependencies are merged as a union. For a dependency in both files the template's version wins, and dependencies only your project has are kept.
- Agent code, config files and files you own are kept: your tests, custom eval metrics, eval datasets, READMEs, agent guidance files,
agents-cli scaffold upgradekeeps your Terraformenv.tfvarsfiles instead of treating them as template files.agents-cli scaffold upgradeandagents-cli scaffold enhancestop with an error when writing the merged dependencies fails. Previously they reported success and stamped the new version, so a rerun said "already at version" and could not retry.agents-cli run --mode a2asends messages and your bearer token only to the--urlhost, not to the endpoint declared in the agent card.- Two concurrent
agents-cli deploydeploys no longer overwrite each other's deployment state. - Clarified the documentation on when to use
agents-cli infra single-project --applyfor deployments. - Generated CI/CD Terraform for Cloud Build now waits for the CI/CD service account's IAM grants to propagate before creating build triggers, so the first push after
agents-cli infra cicdno longer fails on missing permissions. - Generated CI/CD Terraform grants Artifact Registry read access on the app's own repository instead of the whole CI/CD project. Destroying one project's infrastructure no longer breaks image pulls for other projects sharing the CI/CD project. A deploy project that relied on the project-wide grant to read another repository loses that access.
agents-cli deployprints pod state, pod descriptions and namespace events when a GKE rollout does not finish.- Changed the formatting of some error messages so that they stand out more.
- Updated the ADK version in scaffolded projects to
google-adk>=2.9.2,<3.0.0. - Added experimental usage telemetry, off by default. Enable it with
AGENTS_CLI_EXPERIMENTS='{"cli_telemetry": true}'. It writes one log entry per command to your own Cloud project, with the command, exit code, error class, duration, and CLI, Python and OS versions (but not arguments). Opt out withAGENTS_CLI_TELEMETRY=0orDO_NOT_TRACK=1.
- Live (voice) agents now work in
runandeval. Pass--mode adk_livewherever you already pass--mode adk:agents-cli run --mode adk_livesends a prompt over ADK's/run_liveWebSocket, against a local server or any deployment target. A turn that answers only in audio says so instead of printing nothing.agents-cli eval generateandagents-cli eval runplay each case over one persistent Live socket, with the same dataset format, trace output and grading as the SSE path.- The
gemini-3.8-livemodels answer one prompt with several model turns. The CLI reads the end of a turn frominteractionStatusinstead of stopping at the firstturnComplete. - The bundled skills cover Live: an ADK Live reference, which models support it, and how to deploy a voice agent.
agents-cli run --mode a2atalks A2A to the local server. A local run used to ignore--modeand always use ADK SSE.agents-cli deploy --ingresssets Cloud Run ingress toall,internalorinternal-and-cloud-load-balancing, so a deploy works in a project whereconstraints/run.allowedIngressrejects a public service.agents-cli deployupdates the Agent Runtime engine whose resource id is recorded indeployment_metadata.json, and scans display names only when no id is recorded. A deleted engine, a display name that no longer matches, or a scan that finds duplicates stops the deploy instead of mutating the wrong engine.agents-cli deployand scaffolded Terraform both setidentity_type = SERVICE_ACCOUNTon the Agent Runtime engine, so an agent keeps its service account when Agent Runtime changes that default to Agent Identity.agents-cli scaffold create --agent <remote URL>handles symlinks again. Since 1.4.1 every symlink in a remote template was dropped, so a template that shared a library across variants scaffolded a project that failed at import. Links inside the cloned repo are copied as real file contents, and a link pointing outside it stops the scaffold with an error.agents-cli deploygets a new flag--framework, which sets theagent_frameworkproperty on the deployed agents.- The generated Cloud SQL password no longer lands in Terraform state. State lives in
gs://{cicd_project}-terraform-state, whose default IAM let anyone with Viewer on the CI/CD project read the prod database password. Generated Terraform now needs Terraform 1.11.0 or later. - Scaffolded projects need
google-adk>=2.8.0. 2.7.x does not emitinteractionStatus, so a Live turn boundary falls back to a heuristic there. The<2.9.0cap from 1.6.1 is unchanged. - The deprecated
--trace-to-cloudalias is gone fromagents-cli playgroundandagents-cli run. Use--otel-to-cloud.
- ADK Go is now available to everyone (Preview). The
adk_gotemplate ("Go agent with A2A") now appears inagents-cli scaffold createwith no experiment override, and Go projects get the toolchain Python already has:- Deploy to Agent Runtime, Cloud Run and GKE, with session methods exposed to
agent_engines.get()clients. - CloudSQL, Agent Platform and in-memory session services.
- Prompts and responses in BigQuery Agent Analytics, and telemetry through OTLP.
- CI/CD templates at parity with Python.
- The bundled skills cover Go and Python.
- Deploy to Agent Runtime, Cloud Run and GKE, with session methods exposed to
- Scaffolds now default to
gemini-3.8-flash. agents-cli scaffold createno longer asks for a region when the deployment target isnone.- The one-off
agents-cli runno longer prints stop and resume hints for a server it did not leave running. agents-cli deployprints how to talk to a Cloud Run agent once the deploy finishes.agents-cli deploycan change the identity type on an existing agent.agents-cli deploynow reports the correct identity after a deploy, instead of the wrong principal for agents using Agent Identity.- Exclude vendored extensions from the deploy payload, where they could add megabytes to every deploy.
agents-cli infra single-projectnow correctly enables the Service Usage API, so a new project bootstraps without enabling it by hand.- Fix remote ADK samples generating two agent directories and an unbuildable project.
- Scaffolded Dockerfiles install uv from a pinned image instead of
pip install. agents-cli runandagents-cli evalno longer stop a background server they only borrowed.- Startup and version notices now go to stderr, so
--jsonoutput stays machine-readable. agents-cli eval generateno longer silently drops per-case session state.agents-cli run --mode a2anow shows status updates, errors and empty turns instead of staying silent.- The
runresume hint includes--urland the other routing flags. agents-cli info --jsonreportsroot_agent_name.agents-cli extension addno longer copies ignored files from alocal@source.- Pin
google-adkbelow 2.9.0. On 2.9.0 a Cloud Run agent's prompts and responses stopped reaching BigQuery Agent Analytics. - Fix the macOS-only
sedin the Starter Pack migration guide and spell out the dry-run and apply steps.
- Extension system with a LangChain template.
agents-clican now be extended with custom commands and add-on agent templates, shipped with a LangChain extension and authoring guides. Extensions install from GitHub, other git hosts (including self-hosted and enterprise servers), or a local path for development. - Add
agents-cli infra showto inspect the Terraform configuration provisioned byagents-cli infra single-project. - Add
--update-onlytoagents-cli deploy, so a deploy updates an existing Agent Runtime engine instead of creating a duplicate. - Add a
--labelsflag toagents-cli deployto tag Agent Runtime and Cloud Run deployments. - Add
--qpstoagents-cli evalthat controls the request rate instead of being throttled to the default value. - Name the scaffolded root agent after its project instead of a generic default.
agents-cli deploynow retries throttled Agent Platform calls.agents-cli createnow reports precondition failures as clear errors instead of exiting successfully or printing a traceback.- Fix background server reuse ignoring the requested session mode.
- Fix
reasoning_engine_adapterstreaming returning an empty response. - Prevent multi-region deployments in scaffold and deploy.
- Give a clear error for malformed project manifests instead of silently defaulting or printing a traceback.
- Fix stale command references in docs and CLI hints.
- Scaffolded A2A agents now forward tool calls and responses to clients, not just text.
agents-cli setupnow works without network or git access, with skills bundled into the package.- Fix a Windows failure loading a scaffolded project whose config points at a local path.
- Adds upper-bound for google-cloud-aiplatform dependency.
- Scaffolds now default to
gemini-3.7-flash. agents-cli eval generateno longer fails to generate traces for some agents.agents-cli deploynow defaults to--min-instances 0(was1) on Agent Runtime and Cloud Run, so that idle dev and demo agents don't take up resources.agents-cli scaffold upgradenow creates a project backup before applying changes, just likeagents-cli scaffold enhance.- Fixed
npx skills findto use the pinnedskillsversion. - Fixed an arbitrary file write vulnerability in
agents-cli scaffold create.
- Add Agent Gateway support to
agents-cli deploy - Improve A2A-on-Agent-Runtime and MCP Agent Registry guidance in skills
- Use token-based context compaction in ADK cheatsheet
- Add held-out case guidance during iteration to the eval skill
- Remove built-in feedback endpoint, add guidance on building a feedback mechanism to the observability skill instead
- Display project language in
agents-cli info - Use $GH_TOKEN and $GITHUB_TOKEN environment variables as fallbacks for
--github-pat - Populate class_methods contract on agent_runtime deploy
- Add agent-plugins.org plugin manifest
- Smarter backoff handling for CICD command
- Rollback to npx skills 1.5.9 to avoid a spurious error message during
setup
- Update to use A2A 1.0 throughout, with a compatibility layer for A2A 0.3 clients
- Improve retry for Cloud Run deploy
- Streamline retry handing for
infra cicdcommand - Fix
npx skillsoutput formatting during setup and update - Print Cloud Logging URL at Agent Runtime deploy start
- Add --concurrency and --header flags to eval generate/run
- Tweak messages around
--session-typewhen used withagent_runtime
- Fix an import problem on
uv synccaused by a yankedopentelemetry-resourcedetector-gcpversion - Add optional HTTP-based path for
eval generateusing--url(in-progress feature, stay tuned)
- Cloud telemetry moved to ADK's
otel_to_cloud, across the CLI and deploys.playgroundandrungain an--otel-to-cloudflag that forwards ADK's current--otel_to_cloud; the old--trace-to-cloudstays as a hidden, still-functional alias that warns when used. On the deployment side, Agent Runtime now exports throughotel_to_cloud(gated onGOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY) and generated projects configure Cloud telemetry declaratively in Terraform instead of at runtime. Bundledgoogle-adkmoves to>=2.2.0with theotel-gcpextra, and the observability skill was updated to match. - Scaffolds now default to
gemini-3.6-flash. - Agent Analytics now captures GenAI completions on Agent Runtime. The BigQuery telemetry log sink is configured per deployment target, so Agent Runtime deployments route their GenAI request/response logs into BigQuery instead of leaving the completions view empty.
- Managed Agents guidance in the ADK code skill. The bundled ADK cheatsheet gained a Managed Agents section covering when to use
ManagedAgent, Gemini API vs Agent Platform (GEAP) setup, and a runnable create-and-use example.
- Guided brainstorming for new agents. The workflow skill's Phase 0 is now an interactive brainstorming dialogue that helps you shape an agent's spec before any code is written, and surfaces its assumptions for review when it can't ask.
eval generateandeval gradeno longer clutter output with benign third-party warnings and progress bars that never affected results. This output is still shown on failure and can be re-enabled for debugging.- Generated projects now name the default scaffolded eval metric module
tests/eval/response_quality.py(wasmetrics.py) to match the metric it implements. - Broad Windows compatibility fixes across the CLI.
- Fixed a command-name typo in user-facing hints so they point to the correct
agents-clicommand. - Refreshed the bundled skills, including pointing the RAG samples at
core/python/ingoogle/adk-samples.
Agents CLI is now 1.0 — Generally Available. This is our first GA release: a stable, production-ready CLI for scaffolding, evaluating, and deploying ADK agents on Google Cloud.
- Redeploys now preserve the existing deployment spec on Agent Runtime and Cloud Run instead of resetting unspecified settings.
- Agent Runtime deploys now honor
.gcloudignoreand.gitignorewhen packaging source, so uploads no longer include ignored files. - RAG is now a clone-and-study recipe: start from the
rag-vector-search/rag-agent-searchsamples ingoogle/adk-samples(surfaced via the workflow skill). Theagentic_ragtemplate, the--datastoreflag, and theinfra datastore/data-ingestioncommands were removed and now print a redirect. - Generated projects now consolidate Python environment configuration into a single templated
.envfile. - Eval commands now tolerate ADK toolsets when introspecting eval metadata, so agents that use toolsets no longer fail metadata collection.
- GKE Cloud Build deploys are now resilient to log-streaming limits and no longer fail when the build log stream is truncated.
- Refreshed the bundled skills: RAG samples point to
core/on adk-samplesmain, the always-active workflow skill was generalized and trimmed, and the ADK code guidance notesstreaming_agent_run_with_eventsfor debugging on Agent Runtime.
publish gemini-enterprisenow registers Agent Runtime deployments via ADK by default, which Gemini Enterprise invokes natively and reliably. A2A registration remains the default for Cloud Run and GKE; requesting A2A on Agent Runtime now warns and recommends ADK. Re-publishing an A2A agent no longer creates duplicate registrations, and A2A agent cards now carry the correct public URL on the first deploy.agents-cli updatenow exits non-zero and clearly reports when a skill fails to update, instead of always printing a misleading green "Skills updated." banner. Also fixes failure messages rendering in the wrong color on Windows PowerShell.- Refreshed the generated project
uv.lockfiles for all templated agents, updating bundledgoogle-adkfrom 2.2.0 to 2.3.0.
- Agent Runtime deploys now serve ADK web, A2A, and the reasoning engine from a single unified container app.
- Cloud Trace spans no longer capture LLM prompts and responses, keeping sensitive content out of traces.
- Refreshed the bundled skills: correctness fixes, de-duplication, and a leaner always-active workflow guide, plus a2ui documented in the ADK code cheatsheet.
- Fixed run and playground commands on Windows
- Fixed stale GCS bucket in failure-investigation guide
- Added Agent Registry fleet management to publish skill
deploynow surfaces machine-shape parameters as flags for Agent Runtime and Cloud Run.deployadds a--service-nameoverride.runprints a copy-pasteable resume command in the session footer.runno longer tears down a reused local server on a plain run.scaffold upgradenow builds the prior-version template viauvx.- Skills setup/update no longer hangs on large
npxoutput (a pipe-buffer deadlock). - The project-root notice now only prints when the command actually changes directory.
- Fixed pre-existing inaccuracies in the bundled skills and generated project READMEs.
- Source code is now published to the public GitHub repo: https://github.com/google/agents-cli
- Scaffolded Python templates now use ADK 2.0 GA. New
adk,adk_a2a, andagentic_ragprojects pingoogle-adk[gcp]>=2.0.0,<3.0.0; the[gcp]extra restores the OpenTelemetry GCP exporters and bundles the BigQuery client, so the separate[bigquery-analytics]extra is no longer needed. Cloud SQL sessions on Cloud Run and GKE keep working under 2.0. The bundled ADK coding skill and its reference docs were refreshed for 2.0. - Agent Runtime deploys no longer overwrite a user-supplied
AGENT_VERSION(orNUM_WORKERS) passed via--update-env-vars, matching Cloud Run behavior. The "version not found" warning now names thepyproject.tomlfield to set. - Fixed a stale
deployment/terraform/dev/path in the Cloud Trace observability guide so it matches the currentsingle-projectterraform layout.
eval generatenow works on ADK 2.x projects that use built-in tools such asVertexAiSearchTool. Raised thegoogle-cloud-aiplatformfloor to 1.156.0, which carries the SDK fix.- Skills installed via
agents-cli setupare now visible to Antigravity. Global skills are mirrored into the Antigravity skill directories. updatenow surfaces errors clearly instead of failing silently.- Agent deploys tolerate a corrupt or malformed
deployment_metadata.jsoninstead of crashing. - Deployment timestamps are now timezone-aware.
- A malformed
AGENTS_CLI_EXPERIMENTSvalue no longer crashes the CLI. agents-cli installnow runs with--locked, so a drifteduv.lockfails fast instead of silently resolving new dependency versions.
- The eval data format changed from ADK
EvalSetto Vertex AIEvaluationDataset. Existingtests/eval/evalsets/*.evalset.jsonfiles are no longer read byagents-cli eval generateand friends. See Migrating Eval Datasets for the conversion.scaffold upgradenow prints a notice when legacy files are detected.
- Added
eval dataset synthesizefor LLM-driven user-simulation dataset generation. - Added
eval generateto run agent inference over anEvaluationDatasetand emit traces. - Added
eval gradeto score agent traces against built-in or custom metrics. - Added
eval submitto submit an end-to-end cloud-side evaluation run on Vertex AI Eval Service. - Added
eval resultsto fetch results from a completed cloud evaluation run. - Added
eval analyzefor failure-mode analysis over graded results. - Added
eval metric listto discover built-in evaluation metrics. - Rewrote the
evalskill end-to-end to cover the Quality Flywheel workflow (dataset, generate, grade, analyze, optimize).
- Minor skills consistency fixes
- Add --dryrun as an alias for --dry-run
- Smarter skills installation
- Cache credentials for better performance
- Fix is_authenticated to work without gcloud
- Fix agent runtime deploy error to be clearer
- Remove 'beta' from gcloud commands that no longer need them
- Fix broken doc links
- Auto gen lockfile if it is missing before trying to export it in deploy
- Moved agent-cli project config into a language-independent agents-cli-manifest.yaml file
- Old config embedded in pyproject.toml can be automatically migrated with
agents-cli scaffold upgrade
- Old config embedded in pyproject.toml can be automatically migrated with
- Added
eval optimizecommand - add --network-attachment and --dns-peering-* flags to deploy
- Misc startup performance improvements
- Avoid crashes related to terminal encodings
- Fixes #15
- Smarter tool path resolution, especially for Windows
- Fixes #14
- Updated dependency version locks
- Fixes #13
- Added manifest support for Claude and Gemini CLI plugin support
- Fix some bugs around preserving the right config metadata when scaffolding and enhancing and/or upgrading
- Misc doc and skill fixes
- Visual Explainer page for Agents CLI lifecycle at https://google.github.io/agents-cli/
- Cleaned up some dead template code
- Default
infracommands to terraform plan instead of apply - Fix
playgroundto work for Cloud Shell and other similar envs and be more transparent about the underlying command - Update skills to cover need for cloud sql role
- Make
agents-cli infoprint OS info for easier bug reporting - Make
runonly start a background server when requested with--start-server - Clearer display string for ADC auth
- Fix broken doc links
- Fix missing target description for agent_runtime
- Document & image fixes
- Project metadata fixes
- Preserve multi-hop traces in completions_view BigQuery SQL
- Detect legacy ADK skills during setup
- Save inline artifacts to .google-agents-cli/artifacts/
- Fix some Windows shell interaction issues
- Remove unprocessed pass-through args for
deploy, updated skills and --help text - Fix agents-cli considering the user as authenticated when auth got stale
- Auto stop local
runserver on error
- Performance improvements, particularly for CLI startup time
- Doc cleanups
- Initial public release