Python: Warn on unsupported AzureAIClient runtime tool/structured_output overrides

[eavanvalkenburg]

Summary

• track AzureAIClient agent-creation tool names and structured output configuration
• log a warning when runtime tools or structured_output differ from creation-time configuration and direct users to ResponsesClient
• update AzureAIClient run option pruning to only remove keys that map to the concrete options TypedDict
• add tests in the existing azure-ai client test file for runtime warnings and typed-dict-based option pruning behavior

Validation

• uv run ruff format packages/azure-ai/agent_framework_azure_ai/_client.py packages/azure-ai/tests/test_azure_ai_client.py
• uv run ruff check packages/azure-ai/agent_framework_azure_ai/_client.py packages/azure-ai/tests/test_azure_ai_client.py
• uv run --directory packages/azure-ai pytest tests/test_azure_ai_client.py -k runtime_tools_override_logs_warning or runtime_structured_output_override_logs_warning or prepare_options_excludes_response_format or prepare_options_keeps_values_for_unsupported_option_keys -q

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/azure-ai/agent_framework_azure_ai
_client.py	272	37	86%	377, 379, 425, 433–445, 458, 519, 534–539, 582, 617, 619, 652, 860, 863, 866–867, 869–872, 919
TOTAL	20532	3262	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3921	225 💤	0 ❌	0 🔥	1m 9s ⏱️

[Copilot]

Pull request overview

This PR improves AzureAIClient ergonomics by tracking agent-creation configuration (tools + structured output) and warning when callers attempt unsupported runtime overrides, while also changing how request options are pruned to be based on the concrete client options TypedDict.

Changes:

• Track creation-time tool names and structured output configuration; warn on runtime mismatches and point users to ResponsesClient.
• Replace fixed “exclude list” pruning with TypedDict-driven pruning logic.
• Add unit tests for runtime-override warnings and TypedDict-based option pruning.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
python/packages/azure-ai/agent_framework_azure_ai/_client.py	Adds runtime override warnings + refactors run option pruning to depend on concrete options TypedDict.
python/packages/azure-ai/tests/test_azure_ai_client.py	Adds tests for the new warnings and for TypedDict-based pruning behavior; updates test client factory.

[TaoChenOSU]

Why do we have to check if the tools or other parameters are changed? Wouldn't it be easier if we just warn users that these runtime options are not supported and the agent will use whatever is provided at creation time?

[eavanvalkenburg]

I thought about that, but if you call run without first creating an agent then you would be warned but nothing is wrong, it's only once the agent is there that there's an issue. And we do need function tools to be available and the only way to set that is through the same param, where if the tool was already registered and you're just passing in the actual function it will work and you shouldn't get a warning.

[TaoChenOSU]

Then we only need to track if the agent has been created, no?