gadk-cli
gadk, the gadk deploy CLI. It deploys a gadk agent, a Cargo binary target, to Cloud Run or to
Vertex AI Agent Engine with the flags, checks, generated Dockerfile CMD, gcloud invocations,
Reasoning Engine requests and console output of ADK's deploy tool, adapted to Cargo (the entry
point is a Cargo package and the image is built remotely with cargo).
Install
Usage
gadk deploy cloudrun [flags] # Cloud Run, built remotely by Cloud Build
gadk deploy agentengine [flags] # Vertex AI Agent Engine (Reasoning Engine)
gadk deploy <command> --help # every flag with its default
The entry point is a Cargo package: -e/--entry_point_path names its directory or its
Cargo.toml (default: the current directory), and --bin picks the binary target when the
package has more than one. The package's Cargo workspace root must hold a Cargo.lock; the
image builds with cargo build --release --locked. A path dependency outside the staged
directory is rejected before anything is staged.
The builder image is rust:<version>-bookworm, where the version is the
rust-toolchain.toml [toolchain] channel of the workspace root, else the package's
rust-version, else the rustc gadk was built with, else rust:bookworm. The runtime image is
gcr.io/distroless/cc-debian12.
Cloud Run
Steps: compute flags and create a temp dir (-t, default the system temp dir) → stage the
Cargo workspace root into it → write the two-stage Dockerfile → gcloud run deploy <service> --source . … in the temp dir → remove the temp dir → gcloud run services proxy <service> --port <proxy_port> … (a local authenticating proxy on 127.0.0.1:<proxy_port>, default
8081). gcloud must be on PATH and authenticated (gcloud auth login); the service reads
GOOGLE_API_KEY from Secret Manager (--set-secrets=GOOGLE_API_KEY=GOOGLE_API_KEY:latest).
--api, --debug_api, --webui, --a2a, --pubsub and --eventarc choose the sub-launchers
the container starts.
Agent Engine
Steps: compute flags and create a temp dir → write the Dockerfile → archive the source
directory (-d, default the Cargo workspace root; it must be the root or an ancestor of it)
with the Dockerfile as a .tar.gz → create a Reasoning Engine, or update the one named by
--agent_engine_id, and wait for the operation (at most 45 minutes) → remove the temp dir.
Credentials are Application Default Credentials (gcloud auth application-default login).
--mem_deploy adds a Memory Bank (--mem_ttl, --mem_model).
--env NAME=VALUE (repeatable) sets the engine's environment on top of the defaults
GOOGLE_CLOUD_REGION, NUM_WORKERS=1, GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true and
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true (--default_env=false drops them); an
update replaces the environment only when --env or --default_env is given. Values are never
printed. agentengine takes no positional arguments.
Notes and limitations
-
Unix only (Linux and macOS).
gadkuses Unix file permissions and symbolic links when staging; it does not build on Windows. -
Cloud Build timeout. Cloud Run images are built remotely, from source, on Cloud Build. A cold release build of a gadk agent can take longer than Cloud Build's default timeout (10 minutes). Raise it once for your gcloud configuration:
gadkdoes not change your gcloud configuration. -
.gcloudignore.gcloud run deploy --sourceuploads the staged directory filtered by its.gcloudignore. A.gcloudignoreat your workspace root is staged unchanged, so its exclusions apply (do not excludeCargo.lockor sources the build needs). Without one,gadkwrites a one-comment.gcloudignore, so gcloud does not fall back to your.gitignore(which may listCargo.lock). -
Excluded directories. Staging (Cloud Run) and the source archive (Agent Engine) leave out every file or directory named
.gitortarget, at any depth, and the temp dir when it lies inside the workspace. A source directory that is itself namedtarget(for example a modulesrc/target/) is therefore not deployed; rename it. -
build.target. The builder runscargo build --target-dir /gadk-targetand copies/gadk-target/release/<bin>. A staged.cargo/config.tomlthat setsbuild.targetputs the binary under/gadk-target/<triple>/release/instead, and the image build fails at thatCOPY(visible in the Cloud Build log). Removebuild.targetfrom the staged config. -
A root
Dockerfilein your workspace is replaced by the generated one in the staged copy (Cloud Run) and left out of the archive (Agent Engine). -
No local build:
gadkdoes not cross-compile; the image is always built remotely.