Support and test the shared JSON configuration contract in the Python SDK

[matthewmeyer]

Summary

Implement Python SDK support and conformance testing for the shared Agents JSON configuration contract defined by microsoft/Agents#738.

This issue covers adding a JSON-document normalization/validation boundary compatible with Python's existing environment configuration, declaring Python capabilities, and executing the central fixture suite through the real Python configuration and authorization classes.

Parent specification

• Define a shared cross-SDK JSON configuration contract and conformance suite Agents#738

Existing Python behavior

The Python SDK currently builds nested configuration primarily through load_configuration_from_env, preserves many raw string values until later coercion, and passes dictionaries into ConnectionManager, AgentAuthConfiguration, authorization, and application construction.

Python does not need to replace this model or adopt Pydantic to participate. It needs a narrow canonical document boundary and an adapter that proves how existing environment and JSON inputs normalize into runtime behavior.

Scope

JSON configuration support

Add a supported way to load or normalize a JSON configuration document into the same effective shape used by existing Python configuration consumers. The implementation should:

• accept the portable shared document shape;
• preserve existing environment-variable behavior and aliases;
• define deterministic source precedence when JSON and environment settings are both provided;
• retain raw-value coercion behavior where required for backward compatibility;
• provide field-path diagnostics without exposing secrets;
• avoid introducing a new public model framework solely for schema support.

Capability inventory

Contribute and maintain the Python capability manifest in the central contract, including:

• connection and route support;
• authentication types and accepted spellings;
• current environment aliases and casing behavior;
• certificate/PFX or other Python-specific representations;
• effective defaults and coercions;
• currently unsupported shared fields;
• fields passed through provider settings;
• constructor-only features that should remain outside the JSON contract.

Repository adapter

Add a repository-internal configuration-contract adapter that:

1. accepts a central fixture document and metadata;
2. loads or normalizes it through the supported Python JSON path;
3. optionally exercises equivalent environment-variable input for alias fixtures;
4. passes normalized data through ConnectionManager, AgentAuthConfiguration, and applicable application configuration;
5. returns a stable machine-readable result with validity, normalized values, warnings, and safe paths;
6. never returns secret values.

Suggested command:

python eng/configuration_contract_adapter.py <fixture-directory>

Fixture conformance

Run shared fixtures through:

• the shared schema and Python manifest;
• the new JSON normalization boundary;
• load_configuration_from_env for environment-equivalence fixtures;
• real connection and authorization classes;
• existing coercion utilities.

Add Python-specific fixture expectations for:

• upper-case and legacy environment aliases;
• raw string-to-boolean/integer/list coercion;
• required SERVICE_CONNECTION compatibility and canonical connection names;
• Python authentication type spellings;
• provider-settings pass-through behavior;
• supported certificate representation;
• recognized but unsupported shared fields;
• secret-safe diagnostics.

Build integration

Invoke the central reusable workflow for relevant PRs and run the adapter before pytest. Start in warning mode for pre-existing differences; fail newly introduced disagreement between the Python manifest, shared fixtures, and runtime behavior.

Do not copy the central schema, manifests, or fixtures into this repository.

Compatibility requirements

• Preserve existing environment-variable loading and aliases.
• Define JSON/environment precedence explicitly and test it.
• Avoid adding Pydantic or replacing existing public configuration classes solely for this work.
• Do not introduce network access into runtime configuration loading.
• Do not expose secrets through adapter output or validation errors.
• Generated Python profile schemas, if used, remain derived artifacts.

Acceptance criteria

• A supported Python JSON configuration normalization/loading path is implemented and documented.
• The Python capability manifest accurately classifies the initial shared field inventory.
• A repository-internal fixture adapter is implemented.
• Shared valid, invalid, and runtime-specific fixtures execute through real Python configuration consumers.
• JSON and equivalent environment configurations normalize consistently where promised.
• Source precedence, aliases, coercion, defaults, and provider settings are covered.
• Unsupported fields produce stable warning/error identifiers and safe paths.
• The central reusable workflow runs for relevant Python PRs.
• Existing package builds, pytest suites, and samples remain green.
• Any generated Python schema is reproducible from the shared schema plus manifest.