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

* Deprecate Azure AI v1 (Persistent Agents API) helper methods

Add DeprecationWarning to v1 classes and functions that have been
superseded by the v2 (Projects/Responses) API:

- AzureAIAgentsProvider -> use AzureAIProjectAgentProvider
- AzureAIAgentClient -> use AzureAIClient
- AzureAIAgentOptions -> use AzureAIProjectAgentOptions
- to_azure_ai_agent_tools() -> use to_azure_ai_tools()
- from_azure_ai_agent_tools() -> use from_azure_ai_tools()
- AzureAIAgentClient static tool factory methods -> use AzureAIClient equivalents

All v1 components still function but emit warnings to guide migration.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add deprecation warnings to AzureAIAgentsProvider methods

Mark create_agent(), get_agent(), and as_agent() as deprecated
individually, pointing to AzureAIProjectAgentProvider equivalents.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: giles17

python/packages/azure-ai/agent_framework_azure_ai/_agent_provider.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import sys
+import warnings
 from collections.abc import Callable, Sequence
 from typing import Any, Generic, cast
 
@@ -49,6 +50,10 @@
 class AzureAIAgentsProvider(Generic[OptionsCoT]):
     """Provider for Azure AI Agent Service V1 (Persistent Agents API).
 
+    .. deprecated::
+        AzureAIAgentsProvider is deprecated and will be removed in a future release.
+        Use :class:`AzureAIProjectAgentProvider` instead for the V2 (Projects/Responses) API.
+
     This provider enables creating, retrieving, and wrapping Azure AI agents as Agent
     instances. It manages the underlying AgentsClient lifecycle and provides a high-level
     interface for agent operations.
@@ -114,6 +119,12 @@ def __init__(
         Raises:
             ValueError: If required parameters are missing or invalid.
         """
+        warnings.warn(
+            "AzureAIAgentsProvider is deprecated and will be removed in a future release; "
+            "use AzureAIProjectAgentProvider instead for the V2 (Projects/Responses) API.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self._settings = load_settings(
             AzureAISettings,
             env_prefix="AZURE_AI_",
@@ -177,6 +188,10 @@ async def create_agent(
     ) -> Agent[OptionsCoT]:
         """Create a new agent on the Azure AI service and return a Agent.
 
+        .. deprecated::
+            This method is deprecated and will be removed in a future release.
+            Use :meth:`AzureAIProjectAgentProvider.create_agent` instead.
+
         This method creates a persistent agent on the Azure AI service with the specified
         configuration and returns a local Agent instance for interaction.
 
@@ -209,6 +224,12 @@ async def create_agent(
                     tools=get_weather,
                 )
         """
+        warnings.warn(
+            "AzureAIAgentsProvider.create_agent() is deprecated and will be removed in a future release; "
+            "use AzureAIProjectAgentProvider.create_agent() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         resolved_model = model or self._settings.get("model_deployment_name")
         if not resolved_model:
             raise ValueError(
@@ -271,6 +292,10 @@ async def get_agent(
     ) -> Agent[OptionsCoT]:
         """Retrieve an existing agent from the service and return a Agent.
 
+        .. deprecated::
+            This method is deprecated and will be removed in a future release.
+            Use :meth:`AzureAIProjectAgentProvider.get_agent` instead.
+
         This method fetches an agent by ID from the Azure AI service
         and returns a local Agent instance for interaction.
 
@@ -299,6 +324,12 @@ async def get_agent(
                 # With function tools
                 agent = await provider.get_agent("agent-123", tools=my_function)
         """
+        warnings.warn(
+            "AzureAIAgentsProvider.get_agent() is deprecated and will be removed in a future release; "
+            "use AzureAIProjectAgentProvider.get_agent() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         agent = await self._agents_client.get_agent(id)
 
         # Validate function tools
@@ -323,6 +354,10 @@ def as_agent(
     ) -> Agent[OptionsCoT]:
         """Wrap an existing Agent SDK object as a Agent without making HTTP calls.
 
+        .. deprecated::
+            This method is deprecated and will be removed in a future release.
+            Use :meth:`AzureAIProjectAgentProvider.as_agent` instead.
+
         Use this method when you already have an Agent object from a previous
         SDK operation and want to use it with the Agent Framework.
 
@@ -354,6 +389,12 @@ def as_agent(
                 # Wrap as Agent
                 chat_agent = provider.as_agent(sdk_agent)
         """
+        warnings.warn(
+            "AzureAIAgentsProvider.as_agent() is deprecated and will be removed in a future release; "
+            "use AzureAIProjectAgentProvider.as_agent() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         # Validate function tools
         normalized_tools = normalize_tools(tools)
         self._validate_function_tools(agent.tools, normalized_tools)

python/packages/azure-ai/agent_framework_azure_ai/_chat_client.py

@@ -8,6 +8,7 @@
 import os
 import re
 import sys
+import warnings
 from collections.abc import AsyncIterable, Awaitable, Callable, Mapping, MutableMapping, Sequence
 from typing import Any, ClassVar, Generic, TypedDict, cast
 
@@ -118,6 +119,10 @@
 class AzureAIAgentOptions(ChatOptions, total=False):
     """Azure AI Foundry Agent Service-specific options dict.
 
+    .. deprecated::
+        AzureAIAgentOptions is deprecated and will be removed in a future release.
+        Use :class:`AzureAIProjectAgentOptions` instead for the V2 (Projects/Responses) API.
+
     Extends base ChatOptions with Azure AI Agent Service parameters.
     Azure AI Agents provides a managed agent runtime with built-in
     tools for code interpreter, file search, and web search.
@@ -212,7 +217,12 @@ class AzureAIAgentClient(
     BaseChatClient[AzureAIAgentOptionsT],
     Generic[AzureAIAgentOptionsT],
 ):
-    """Azure AI Agent Chat client with middleware, telemetry, and function invocation support."""
+    """Azure AI Agent Chat client with middleware, telemetry, and function invocation support.
+
+    .. deprecated::
+        AzureAIAgentClient is deprecated and will be removed in a future release.
+        Use :class:`AzureAIClient` instead for the V2 (Projects/Responses) API.
+    """
 
     OTEL_PROVIDER_NAME: ClassVar[str] = "azure.ai"  # type: ignore[reportIncompatibleVariableOverride, misc]
     STORES_BY_DEFAULT: ClassVar[bool] = True  # type: ignore[reportIncompatibleVariableOverride, misc]
@@ -227,6 +237,10 @@ def get_code_interpreter_tool(
     ) -> CodeInterpreterTool:
         """Create a code interpreter tool configuration for Azure AI Agents.
 
+        .. deprecated::
+            This method is deprecated and will be removed in a future release.
+            Use :meth:`AzureAIClient.get_code_interpreter_tool` instead.
+
         Keyword Args:
             file_ids: List of uploaded file IDs or Content objects to make available to
                 the code interpreter. Accepts plain strings or Content.from_hosted_file()
@@ -256,6 +270,12 @@ def get_code_interpreter_tool(
 
                 agent = ChatAgent(client, tools=[tool])
         """
+        warnings.warn(
+            "AzureAIAgentClient.get_code_interpreter_tool() is deprecated and will be removed in a future release; "
+            "use AzureAIClient.get_code_interpreter_tool() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         resolved = resolve_file_ids(file_ids)
         return CodeInterpreterTool(file_ids=resolved, data_sources=data_sources)
 
@@ -266,6 +286,10 @@ def get_file_search_tool(
     ) -> FileSearchTool:
         """Create a file search tool configuration for Azure AI Agents.
 
+        .. deprecated::
+            This method is deprecated and will be removed in a future release.
+            Use :meth:`AzureAIClient.get_file_search_tool` instead.
+
         Keyword Args:
             vector_store_ids: List of vector store IDs to search within.
 
@@ -282,6 +306,12 @@ def get_file_search_tool(
                 )
                 agent = ChatAgent(client, tools=[tool])
         """
+        warnings.warn(
+            "AzureAIAgentClient.get_file_search_tool() is deprecated and will be removed in a future release; "
+            "use AzureAIClient.get_file_search_tool() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return FileSearchTool(vector_store_ids=vector_store_ids)
 
     @staticmethod
@@ -293,6 +323,10 @@ def get_web_search_tool(
     ) -> BingGroundingTool | BingCustomSearchTool:
         """Create a web search tool configuration for Azure AI Agents.
 
+        .. deprecated::
+            This method is deprecated and will be removed in a future release.
+            Use :meth:`AzureAIClient.get_web_search_tool` instead.
+
         For Azure AI Agents, web search uses Bing Grounding or Bing Custom Search.
         If no arguments are provided, attempts to read from environment variables.
         If no connection IDs are found, raises ValueError.
@@ -333,6 +367,12 @@ def get_web_search_tool(
 
                 agent = ChatAgent(client, tools=[tool])
         """
+        warnings.warn(
+            "AzureAIAgentClient.get_web_search_tool() is deprecated and will be removed in a future release; "
+            "use AzureAIClient.get_web_search_tool() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         # Try explicit Bing Custom Search parameters first, then environment variables
         resolved_custom_connection = bing_custom_connection_id or os.environ.get("BING_CUSTOM_CONNECTION_ID")
         resolved_custom_instance = bing_custom_instance_id or os.environ.get("BING_CUSTOM_INSTANCE_NAME")
@@ -368,6 +408,10 @@ def get_mcp_tool(
     ) -> McpTool:
         """Create a hosted MCP tool configuration for Azure AI Agents.
 
+        .. deprecated::
+            This method is deprecated and will be removed in a future release.
+            Use :meth:`AzureAIClient.get_mcp_tool` instead.
+
         This configures an MCP (Model Context Protocol) server that will be called
         by Azure AI's service. The tools from this MCP server are executed remotely
         by Azure AI, not locally by your application.
@@ -400,6 +444,12 @@ def get_mcp_tool(
                 )
                 agent = ChatAgent(client, tools=[tool])
         """
+        warnings.warn(
+            "AzureAIAgentClient.get_mcp_tool() is deprecated and will be removed in a future release; "
+            "use AzureAIClient.get_mcp_tool() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         mcp_tool = McpTool(
             server_label=name.replace(" ", "_"),
             server_url=url or "",
@@ -511,6 +561,12 @@ class MyOptions(AzureAIAgentOptions, total=False):
                 client: AzureAIAgentClient[MyOptions] = AzureAIAgentClient(credential=credential)
                 response = await client.get_response("Hello", options={"my_custom_option": "value"})
         """
+        warnings.warn(
+            "AzureAIAgentClient is deprecated and will be removed in a future release; "
+            "use AzureAIClient instead for the V2 (Projects/Responses) API.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         azure_ai_settings = load_settings(
             AzureAISettings,
             env_prefix="AZURE_AI_",

python/packages/azure-ai/agent_framework_azure_ai/_shared.py

@@ -4,6 +4,7 @@
 
 import logging
 import sys
+import warnings
 from collections.abc import Mapping, MutableMapping, Sequence
 from typing import Any, cast
 
@@ -158,6 +159,10 @@ def to_azure_ai_agent_tools(
 ) -> list[ToolDefinition | dict[str, Any]]:
     """Convert Agent Framework tools to Azure AI V1 SDK tool definitions.
 
+    .. deprecated::
+        This function is deprecated and will be removed in a future release.
+        Use :func:`to_azure_ai_tools` instead for the V2 (Projects/Responses) API.
+
     Handles FunctionTool instances and dict-based tools from static factory methods.
 
     Args:
@@ -170,6 +175,12 @@ def to_azure_ai_agent_tools(
     Raises:
         ValueError: If tool configuration is invalid.
     """
+    warnings.warn(
+        "to_azure_ai_agent_tools() is deprecated and will be removed in a future release; "
+        "use to_azure_ai_tools() instead for the V2 (Projects/Responses) API.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     if not tools:
         return []
 
@@ -208,12 +219,22 @@ def from_azure_ai_agent_tools(
 ) -> list[dict[str, Any]]:
     """Convert Azure AI V1 SDK tool definitions to dict-based tools.
 
+    .. deprecated::
+        This function is deprecated and will be removed in a future release.
+        Use :func:`from_azure_ai_tools` instead for the V2 (Projects/Responses) API.
+
     Args:
         tools: Sequence of Azure AI V1 SDK tool definitions.
 
     Returns:
         List of dict-based tool definitions.
     """
+    warnings.warn(
+        "from_azure_ai_agent_tools() is deprecated and will be removed in a future release; "
+        "use from_azure_ai_tools() instead for the V2 (Projects/Responses) API.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     if not tools:
         return []