Skip to content

feat(cli): configure Agent Engine deployment environment - #1981

Merged
wolo-lab merged 5 commits into
google:mainfrom
jabrailkhalil:feat/agentengine-env
Nov 6, 2026
Merged

wolo-lab merged 5 commits into
google:mainfrom
jabrailkhalil:feat/agentengine-env

Conversation

@jabrailkhalil

@jabrailkhalil jabrailkhalil commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Closes: #848

Agent Engine deployments expose only four built-in environment variables. I added repeated --env=NAME=VALUE flags and --default_env=false, following the accepted request and the review of #975.

I validate names, unique custom names and UTF-8 values before entry-point processing or temporary-file creation. Empty values, commas and additional = characters are preserved. Custom variables override defaults by name and retain flag order, since the API expands references to previously defined variables. I removed the raw flags dump so environment values are not printed.

Behavior change

Creates without the new flags receive the same four defaults in the original order. Updates without either environment flag preserve the existing environment. Explicitly supplying either flag on update replaces the environment with the selected defaults and custom values; --default_env=false alone clears it. Other deployment settings are preserved by the update mask.

The help names all four defaults, including telemetry and message-content capture being enabled. Updates using --env include those defaults unless --default_env=false is also set.

Previously ignored positional arguments now fail with a count-only error before deployment preparation. In particular, --default_env false and --env A=1 B=2 are rejected: boolean values use =, and each variable needs its own --env. Malformed UTF-8 values also fail early without echoing the value. I have not changed the exported Go API or dependencies.

Companion guide: google/adk-docs#2504.

My change was merged on November 6 in c7087e3e. Upstream CI passed on the accepted head 4f438dbf. I verified that all three PR files are byte-identical to the author-validated source below.

Testing plan

Author-validated source before the final upstream merges: 464920ac2dadef90d312476accbb387e77d17698. I ran Linux/amd64 checks with Go 1.26.10 and CI-pinned golangci-lint 2.3.1:

  • Both modules pass readonly build, vet, uncached shuffled race tests, lint, formatting and go mod tidy -diff. Root: 7,252 test/subtest pass records, 2 skips; analytics: 1,602 pass records, 0 skips.
  • The full Agent Engine package passes three race-test repetitions. Tests cover Cobra parsing and completed create/update requests through the generated gRPC client against a loopback service, including unchanged updates, overrides, opt-out, clearing, reference ordering, Unicode and empty/comma/equals values.
  • The reviewed source 6564abf fails six new leaf regressions. Six additional mutations are caught: removing argument validation, echoing positional values via cobra.NoArgs, disabling UTF-8 validation, moving the default worker variable, and printing values late in either create or update. Output capture includes both completed request paths.
  • The built adkgo rejects both erroneous command forms before preparation, accepts the documented equals syntax up to a bounded invalid-entry-point check, and exposes the defaults in --help. No values are echoed and no deployment temp files are created.
  • A clean merge with current main beea418caa2b5cc9417251a37e7ee527ae7f99df passes workspace build and the full Agent Engine package under the race detector.

I have not performed a live Google Cloud deployment. Request serialization and operation completion were checked offline, without credentials or paid resources. The companion guide's earlier strict site build is documented in #2504.

Python alignment

I checked Python's agent_config['env_vars'] deployment path and its --env_file deprecation. I use the Go-specific repeated flags requested in #848/#975 and retain Go's four existing defaults.

@karolpiotrowicz karolpiotrowicz left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A stray word after either new flag is silently ignored. --default_env false resets a deployed agent's environment variables to the defaults instead of clearing them, and --env A=1 B=2 drops B=2.

Must change before merge:

  • A word typed after --default_env or --env either takes effect or stops the command with an error that does not repeat the word.

The command accepts positional arguments and discards them (agentengine.go#L99-L107, pinned to the PR head (6564abf)). Cobra's flag parser (pflag) gives a boolean flag written without = the value true, so --default_env false sets it to true and leaves false behind as a positional argument. Changed("default_env") is then true (agentengine.go#L104). An update therefore replaces the existing environment with all four defaults. The user asked for none of them, and two of them enable telemetry and message-content capture. --env A=1 B=2 has the same cause. --env takes A=1, and B=2 is left as a positional argument that the command discards without an error.

The root cause predates this PR. --mem_deploy false is already read as true the same way on main. This PR adds two flags where the dropped word silently changes a deployed agent's environment variables, so stray arguments need handling in this PR. cobra.NoArgs alone does not meet the requirement above, because its error repeats the word, which can be a secret value: unknown command "B=2" for "adkgo deploy agentengine".

Reproduction

Put this test in cmd/adkgo/internal/deploy/agentengine on this branch and run go test -run '^TestDefaultEnvSpaceSeparated$' -v ./cmd/adkgo/internal/deploy/agentengine/:

package agentengine

import (
	"os"
	"testing"

	"cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb"

	"google.golang.org/adk/v2/cmd/adkgo/internal/root"
)

func TestDefaultEnvSpaceSeparated(t *testing.T) {
	root.RootCmd.SetArgs([]string{"deploy", "agentengine", "--temp_dir", t.TempDir(),
		"--region", "r", "--project_name", "p", "--agent_engine_id", "existing",
		"--default_env", "false", "-e", "not-a-go-file"})
	err := root.RootCmd.Execute() // stops at the entry point, with no argument error
	t.Logf("err=%v defaultEnv=%v updateEnv=%v", err, flags.agentEngine.defaultEnv, flags.agentEngine.updateEnv)

	flags.source.entryPointPath = "main.go"
	if err := flags.computeFlags(); err != nil {
		t.Fatal(err)
	}
	if err := os.WriteFile(flags.build.archivePath, []byte("a"), 0o600); err != nil {
		t.Fatal(err)
	}
	srv := &environmentDeploymentServer{
		created: make(chan *aiplatformpb.CreateReasoningEngineRequest, 1),
		updated: make(chan *aiplatformpb.UpdateReasoningEngineRequest, 1),
	}
	if err := flags.gcloudUpdateAgentEngine(environmentClientOptions(t, srv)...); err != nil {
		t.Fatal(err)
	}
	req := <-srv.updated
	t.Logf("mask=%v", req.GetUpdateMask().GetPaths())
	for _, e := range req.GetReasoningEngine().GetSpec().GetDeploymentSpec().GetEnv() {
		t.Logf("env %s=%s", e.GetName(), e.GetValue())
	}
}
err=cannot strip '.go' extension from entry point path 'not-a-go-file': Cannot find extension in 'not-a-go-file' defaultEnv=true updateEnv=true
mask=[spec.source_code_spec spec.class_methods spec.deployment_spec.env]
env GOOGLE_CLOUD_REGION=r
env NUM_WORKERS=1
env GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
env OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

With --default_env=false the same test sends an empty environment, as intended.

Name validation, first-= splitting, overriding by name, flag order and the update mask otherwise behave as the description says. I checked them on this branch (6564abf) merged with current main, including runs through the real adkgo deploy agentengine command. No validation error echoes an --env value.

@jabrailkhalil

Copy link
Copy Markdown
Contributor Author

I reject positional arguments with cobra.ExactArgs(0) and invalid UTF-8 before deployment preparation in 464920ac. Help now names the telemetry/capture defaults; tests pin all four defaults' order and capture both completed request paths. The original-source control and six mutations fail as intended; both module race suites, build, vet, lint/format and tidy pass. I haven't run a live Cloud deployment.

@wolo-lab wolo-lab left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@karolpiotrowicz
karolpiotrowicz self-requested a review November 6, 2026 12:32
@wolo-lab
wolo-lab merged commit c7087e3 into google:main Nov 6, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add custom list of Env Variables to Agent Engine deployment

3 participants