ADK Agent Versioning

As ADK agents evolve, managing multiple versions becomes essential - you need to test new instructions without breaking production, roll back quickly if regressions appear, and run A/B experiments across agent versions. ShopMax India versions its agents with a config-driven approach, keeping agent definitions in version-controlled YAML files and loading them at runtime.

The pattern involves separating agent configuration (instruction, tools, model) from application logic. Each version is a named config entry. The active version is controlled via an environment variable or feature flag, enabling instant rollback without redeployment.

The below example shows a versioned agent factory that loads agent configuration from a YAML file.

It gives the following output,

Loading agent version: v1
Active agent: shopmax_support_v1
Instruction: You are a ShopMax India support agent. Help with ...

The below example shows an A/B routing pattern that splits traffic between two agent versions based on customer ID.

It gives the following output,

Loading agent version: v1
Customer CUST-MUM-001 -> agent v1 (bucket 73)
Loading agent version: v1
Customer CUST-BLR-042 -> agent v1 (bucket 55)
Loading agent version: v2
Customer CUST-HYD-117 -> agent v2 (bucket 11)
Loading agent version: v1
Customer CUST-DEL-208 -> agent v1 (bucket 84)

ShopMax India maintains three live agent versions at any time: stable (80% traffic), candidate (15%), and experimental (5%). Version promotion is a one-line environment variable change followed by a deployment. Rollback is equally instant. This approach eliminated production incidents from agent instruction changes - the team now catches regressions in the candidate tier before they reach full traffic.