	In Browser
	StumbleUpon
	del.icio.us
	Google
	Google Buzz
	reddit
	LinkedIn

	Facebook
	Twitter
	Linkedin
	E-Mail

Generative AI > Google Gemini API > ADK Agent Versioning Strategy

ADK Agent Versioning Strategy

Author: Venkata Sudhakar

ADK agents evolve continuously - prompts are tuned, tools are added, and models are upgraded. Without a versioning strategy, it becomes impossible to know what is running in production, reproduce a past behaviour, or roll back safely. ShopMax India versions every agent with a semantic version tag, a changelog, and a Firestore record of what changed and why.

The versioning approach combines Docker image tags (for the code and prompt snapshot) with agent metadata stored in Firestore. Each deployment writes a version record with the version number, the model name, a summary of changes, the deployer, and a timestamp. The rollback procedure reads the previous version record and redeploysa the matching image tag.

The below example shows the version record schema and a deploy/rollback utility for the ShopMax support agent.

from google.cloud import firestore
import subprocess, datetime, os

PROJECT_ID  = os.environ["GOOGLE_CLOUD_PROJECT"]
REGION      = "asia-south1"
SERVICE     = "shopmax-support-agent"
IMAGE_BASE  = f"asia-south1-docker.pkg.dev/{PROJECT_ID}/agents/support"

db = firestore.Client(project=PROJECT_ID)

def deploy_version(version: str, model: str, changes: str, deployer: str):
    """Deploy a versioned agent image and record the deployment in Firestore."""
    image = f"{IMAGE_BASE}:{version}"
    # Deploy to Cloud Run
    subprocess.run([
        "gcloud", "run", "deploy", SERVICE,
        f"--image={image}",
        f"--region={REGION}",
        "--no-traffic",
    ], check=True)
    # Promote to 100% traffic
    subprocess.run([
        "gcloud", "run", "services", "update-traffic", SERVICE,
        f"--region={REGION}", "--to-latest",
    ], check=True)
    # Record version in Firestore
    record = {
        "version":   version,
        "model":     model,
        "image":     image,
        "changes":   changes,
        "deployer":  deployer,
        "deployed_at": datetime.datetime.utcnow().isoformat(),
        "status":    "active",
    }
    db.collection("agent_versions").document(f"{SERVICE}_{version}").set(record)
    print(f"Deployed {SERVICE} version {version}")
    return record

def rollback(target_version: str):
    """Roll back to a specific previous version."""
    doc = db.collection("agent_versions").document(f"{SERVICE}_{target_version}").get()
    if not doc.exists:
        raise ValueError(f"Version {target_version} not found in registry")
    rec = doc.to_dict()
    subprocess.run([
        "gcloud", "run", "deploy", SERVICE,
        f"--image={rec['image']}",
        f"--region={REGION}",
    ], check=True)
    print(f"Rolled back {SERVICE} to version {target_version}")

def list_versions(limit: int = 5):
    """List recent deployed versions."""
    docs = (db.collection("agent_versions")
            .where("version", "!=", "")
            .order_by("deployed_at", direction=firestore.Query.DESCENDING)
            .limit(limit).stream())
    for d in docs:
        r = d.to_dict()
        print(f"  {r['version']} | {r['model']} | {r['deployed_at'][:10]} | {r['changes'][:50]}")

# Deploy version 2.1.0
deploy_version(
    version="2.1.0",
    model="gemini-2.0-flash",
    changes="Added product comparison tool; tuned system prompt for upsell tone",
    deployer="ops-team@shopmax.in",
)
list_versions()

It gives the following output,

Deployed shopmax-support-agent version 2.1.0

Recent versions:
  2.1.0 | gemini-2.0-flash | 2026-04-06 | Added product comparison tool; tuned system prom
  2.0.1 | gemini-2.0-flash | 2026-03-28 | Fixed refund tool parameter validation bug
  2.0.0 | gemini-2.0-flash | 2026-03-15 | Upgraded from gemini-1.5-flash to gemini-2.0-fl
  1.9.2 | gemini-1.5-flash | 2026-03-01 | Added order tracking tool
  1.9.1 | gemini-1.5-flash | 2026-02-18 | Prompt tuning for Hindi query handling

Enforce versioning in CI/CD by requiring a version bump and changelog entry as part of the pull request checklist. Use semantic versioning conventions: increment the patch version for prompt tuning, minor version for new tools, and major version for model upgrades or breaking changes to the agent API. Integrate the version registry with Cloud Monitoring so dashboards display the currently active version alongside error rate and latency metrics.

Send your comments, suggestions or queries regarding this site to [email protected].