feat: add AdkConfiguration abstraction layer for programmatic config injection

[YuqiGuo105]

Summary

Resolves #1022 — replaces all hardcoded System.getenv() calls in the SDK's critical configuration paths with a new AdkConfiguration abstraction layer that supports a three-tier fallback chain.

Problem

System.getenv() returns an immutable OS-level snapshot that cannot be modified at runtime. This blocks Spring Boot and other modern Java frameworks from injecting configuration values (from application.yaml, Secret Manager, etc.) into the ADK SDK without resorting to unsafe JVM reflection hacks or external CI/CD wrappers.

Solution

New file: AdkConfiguration.java

A fully static, thread-safe configuration provider with the following fallback chain (highest priority first):

1. Programmatic overrides — set via AdkConfiguration.set(key, value) at runtime
2. JVM system properties — -DGOOGLE_API_KEY=xxx or Spring's application.properties bridge
3. OS environment variables — System.getenv(), unchanged behavior for existing users

Public API:

AdkConfiguration.set("GOOGLE_API_KEY", value);       // inject programmatically
AdkConfiguration.get("GOOGLE_API_KEY");               // Optional<String>
AdkConfiguration.getOrDefault("GOOGLE_GENAI_USE_VERTEXAI", "false");
AdkConfiguration.clear("GOOGLE_API_KEY");             // remove single override
AdkConfiguration.clearAll();                          // reset (for tests)

Modified files

File	Change
sessions/ApiClient.java	3 × getenv → AdkConfiguration.get() (GOOGLE_API_KEY, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION)
tools/retrieval/VertexAiRagRetrieval.java	1 × getenv → AdkConfiguration.getOrDefault() (GOOGLE_GENAI_USE_VERTEXAI)
models/ApigeeLlm.java	2 × getenv → AdkConfiguration.get() (APIGEE_PROXY_URL, isEnvEnabled helper — preserves "1" semantics)

New test file: AdkConfigurationTest.java

8 unit tests covering: fallback priority ordering, clear/clearAll behaviour, null key/value safety, and getOrDefault with and without resolved values.

Backward Compatibility

Fully backward compatible. Users who rely on environment variables see no behaviour change — System.getenv() remains the lowest-priority fallback.

Spring Boot Integration Example

@Component
public class AdkInitializer {
    @Value("${google.api-key}") private String apiKey;
    @Value("${google.cloud.project}") private String project;

    @PostConstruct
    void init() {
        AdkConfiguration.set("GOOGLE_API_KEY", apiKey);
        AdkConfiguration.set("GOOGLE_CLOUD_PROJECT", project);
    }
}

Test Results

• AdkConfigurationTest: 8/8 pass
• Full core module: 1255 tests run, 0 failures attributable to this change (pre-existing LocalSkillSourceTest Windows path separator failure is unrelated)

Fixes #1022

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[hemasekhar-p]

Hi @YuqiGuo105, thank you for your contribution! We appreciate you taking the time to submit this pull request. I noticed that there are merge conflicts. Could you please take a look and address those conflicts?

[YuqiGuo105]

Hi @YuqiGuo105, thank you for your contribution! We appreciate you taking the time to submit this pull request. I noticed that there are merge conflicts. Could you please take a look and address those conflicts?

Hi @hemasekhar-p , rebased and resolved the conflicts :)