How to Manage Secrets and Environment Variables for Different Agents-CLI Deployment Targets

Use a layered approach where local development relies on .env files, production deployments inject secrets via Terraform and CI/CD pipelines, and runtime code reads standardized environment variables through language-specific helpers.

The google/agents-cli framework supports multiple deployment targets including Cloud Run, GKE, and Agent Runtime. Each environment requires distinct configuration values and secrets, from API keys to project identifiers. The scaffold provides a consistent pattern for handling these across local development and production deployments.

Local Development Configuration

During local development, agents-cli projects use environment files to simulate production configuration without hardcoding sensitive values.

Go Projects and godotenv

Go-based scaffolds automatically load local environment variables from a .env file. In src/google/agents/cli/scaffold/base_templates/go/main.go, the initialization code uses godotenv.Load to import local settings:

import (
    "os"
    "github.com/joho/godotenv"
)

func init() {
    // Load .env only when it exists; production injects env vars via the platform
    _ = godotenv.Load(".env")
}

// Example usage
projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
appURL := os.Getenv("APP_URL")

This pattern ensures that local secrets override defaults while allowing the application to fail gracefully when the file is absent in production.

Python Projects and Environment Variables

Python scaffolds read configuration directly through os.getenv. While the base templates do not mandate a specific .env loader, you can use python-dotenv or uv run commands to load local files. The ADK helper in src/google/agents/cli/scaffold/base_templates/python/{{cookiecutter.agent_directory}}/app_utils/a2a.py defines standard variables:

import os

# Common variables used by the ADK helper

APP_URL = os.getenv("APP_URL", "http://0.0.0.0:8000")
PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
AGENT_ENGINE_ID = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_ID")
AGENT_LOCATION = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_LOCATION", "us-east1")

Production Deployment Patterns

Production deployments leverage infrastructure-as-code and CI/CD systems to inject secrets securely without exposing them in source control.

Terraform Variable Injection

The scaffold generates a deployment/ directory containing Terraform scripts that export variables as Cloud Run or GKE environment variables. As shown in src/google/agents/cli/scaffold/base_templates/python/README.md, you define variables in Terraform configuration:

variable "app_url" {
  description = "Base URL for the agent service"
}

variable "agent_api_key" {
  description = "API key for the external service"
  type        = string
  sensitive   = true
}

resource "google_cloud_run_service" "agent" {
  # …

  env {
    name  = "APP_URL"
    value = var.app_url
  }
  env {
    name  = "AGENT_API_KEY"
    value = var.agent_api_key
  }
}

When Terraform applies the plan, these values populate the runtime environment, accessible via standard library calls.

CI/CD Secret Management

For the agents-cli publish command, secrets such as AGENT_CARD_URL, ID, and GEMINI_ENTERPRISE_APP_ID are read from the environment at execution time. In src/google/agents/cli/publish/cmd_publish.py, the implementation expects these values to be set by your CI pipeline.

Configure GitHub Actions or Cloud Build to inject secrets from Google Secret Manager or GitHub Secrets:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Set secret as env var
        env:
          AGENT_API_KEY: ${{ secrets.AGENT_API_KEY }}
        run: |
          export AGENT_API_KEY=$AGENT_API_KEY
          agents-cli deploy --deployment-target=cloud_run

Runtime Configuration Retrieval

At runtime, agents retrieve configuration through language-agnostic helpers that abstract platform differences.

Go Runtime Implementation

Go agents use os.Getenv to obtain values such as GOOGLE_CLOUD_PROJECT and APP_URL. The implementation in src/google/agents/cli/scaffold/base_templates/go/main.go demonstrates this pattern for both required and optional configuration.

Python Runtime Implementation

Python agents follow the same pattern. Target-specific implementations like src/google/agents/cli/scaffold/deployment_targets/gke/python/{{cookiecutter.agent_directory}}/fast_api_app.py read optional values such as ALLOW_ORIGINS to configure CORS settings specific to the deployment environment.

Target-Specific Scaffold Generation

The agents-cli create command uses the deployment_target flag (e.g., cloud_run, gke, agent_runtime, none) to generate appropriate configuration files. In src/google/agents/cli/scaffold/utils/template.py, the template engine substitutes target-specific values and ensures each deployment target receives its own set of environment files and Terraform modules.

When switching targets, update the flag:

agents-cli create --deployment-target=gke

This generates the correct Terraform modules and environment variable wiring for GKE-specific deployment patterns.

Summary

• Local development: Use .env files with godotenv (Go) or python-dotenv (Python) to simulate configuration without committing secrets.
• Production deployment: Inject secrets via Terraform variables and CI/CD environment variables, storing actual values in Google Secret Manager or GitHub Secrets.
• Runtime access: Retrieve configuration using os.Getenv (Go) or os.getenv (Python) through standardized helper modules.
• Target switching: Use the --deployment-target flag to generate scaffold-specific configurations for Cloud Run, GKE, or Agent Runtime.
• Publish workflow: Provide AGENT_CARD_URL, ID, and GEMINI_ENTERPRISE_APP_ID via environment variables when running agents-cli publish.

Frequently Asked Questions

How does agents-cli handle secrets differently for local development versus production?

Local development uses .env files loaded by godotenv.Load(".env") in Go or optional dotenv loaders in Python, allowing developers to override settings without affecting production. Production deployments rely on Terraform and CI/CD pipelines to inject secrets as runtime environment variables, ensuring sensitive values never exist in source code.

What environment variables are required for the agents-cli publish command?

The agents-cli publish command expects AGENT_CARD_URL, ID, and GEMINI_ENTERPRISE_APP_ID to be set in the environment. According to src/google/agents/cli/publish/cmd_publish.py, these values are read at execution time from the process environment, allowing integration with secret managers in CI/CD pipelines.

Can I use the same Terraform configuration for both Cloud Run and GKE deployments?

No. The scaffold generates target-specific Terraform modules based on the deployment_target value. The template engine in src/google/agents/cli/scaffold/utils/template.py ensures each target receives specialized configuration files. You should maintain separate variable definitions for each deployment target to handle platform-specific requirements like service account mappings or networking configurations.

How do I switch between deployment targets without recreating my agent?

Use the --deployment-target flag when running agents-cli create to generate the appropriate scaffold files for your desired platform. While this generates new target-specific files, your core agent logic remains portable. Ensure your code reads configuration through standard environment variable accessors (os.getenv or os.Getenv) so it adapts automatically to the new runtime environment injected by the target's Terraform configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}