Python: Deprecate Azure AI v1 (Persistent Agents API) helper methods

[giles17]

Motivation and Context

The Azure AI package has v1 (Persistent Agents API) classes and helper functions that have been superseded by the v2 (Projects/Responses) API. These v1 components should be marked as deprecated to guide users toward migration before eventual removal.

Description

Adds DeprecationWarning via warnings.warn() to all v1 Azure AI components, following the existing deprecation pattern used elsewhere in the codebase. All v1 components still function but now emit warnings pointing users to their v2 replacements:

Classes:

• AzureAIAgentsProvider -> use AzureAIProjectAgentProvider
• AzureAIAgentClient -> use AzureAIClient
• AzureAIAgentOptions -> use AzureAIProjectAgentOptions (docstring only; TypedDict has no runtime constructor)

Provider methods (AzureAIAgentsProvider):

• create_agent() -> use AzureAIProjectAgentProvider.create_agent()
• get_agent() -> use AzureAIProjectAgentProvider.get_agent()
• as_agent() -> use AzureAIProjectAgentProvider.as_agent()

Functions (_shared.py):

• to_azure_ai_agent_tools() -> use to_azure_ai_tools()
• from_azure_ai_agent_tools() -> use from_azure_ai_tools()

Static tool factory methods on AzureAIAgentClient:

• get_code_interpreter_tool() -> use AzureAIClient.get_code_interpreter_tool()
• get_file_search_tool() -> use AzureAIClient.get_file_search_tool()
• get_web_search_tool() -> use AzureAIClient.get_web_search_tool()
• get_mcp_tool() -> use AzureAIClient.get_mcp_tool()

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add BREAKING prefix to the title of the PR.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/azure-ai/agent_framework_azure_ai
_agent_provider.py	114	1	99%	270
_chat_client.py	495	78	84%	465–466, 468, 658, 663–664, 666–667, 670, 673, 675, 680, 941–942, 944, 947, 950, 953–958, 961, 963, 971, 983–985, 989, 992–993, 1001–1004, 1014, 1022–1025, 1027–1028, 1030–1031, 1038, 1046–1047, 1055–1068, 1073, 1076, 1084, 1090, 1098–1100, 1103, 1123–1124, 1257, 1284, 1299, 1415, 1465, 1471
_shared.py	256	23	91%	112, 193, 251, 253–255, 287, 330, 342–344, 373, 375, 377, 381, 446, 451, 456, 493, 530, 537, 549, 568
TOTAL	27144	3222	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5277	20 💤	0 ❌	0 🔥	1m 24s ⏱️

[Copilot]

Pull request overview

This PR deprecates the Azure AI v1 (Persistent Agents API) helper surface in the Python agent_framework_azure_ai package by adding runtime DeprecationWarnings and deprecation notes, guiding users toward the v2 (Projects/Responses) equivalents.

Changes:

• Added warnings.warn(..., DeprecationWarning, stacklevel=2) to v1 tool-conversion helpers in _shared.py.
• Added deprecation warnings (and docstring deprecation notes) to AzureAIAgentClient and its static hosted-tool factory methods.
• Added a deprecation warning (and docstring deprecation note) to AzureAIAgentsProvider.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
python/packages/azure-ai/agent_framework_azure_ai/_shared.py	Deprecates v1 tool conversion helpers (to_azure_ai_agent_tools, from_azure_ai_agent_tools) via DeprecationWarning + docstring notice.
python/packages/azure-ai/agent_framework_azure_ai/_chat_client.py	Deprecates AzureAIAgentClient (constructor + docstring) and its static hosted-tool factory methods via DeprecationWarning.
python/packages/azure-ai/agent_framework_azure_ai/_agent_provider.py	Deprecates AzureAIAgentsProvider initialization via DeprecationWarning + docstring notice.

[chetantoshniwal]

The new name looks a bit odd. Let's evaluate if we want to rename them before surfacing the warnings.