Python: Create/Get Agent API for Azure V1 (#3192)

* Added provider implementation for Azure AI V1

* Small fixes

* Fixed OpenAPI example

* Fixed local MCP example

* Fixed hosted MCP example

* Fixed file search sample

* Small fixes

* Resolved comments

* Doc updates

python/packages/azure-ai/tests/test_agent_provider.py

@@ -0,0 +1,803 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import os
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from agent_framework import (
+    ChatAgent,
+    HostedCodeInterpreterTool,
+    HostedFileSearchTool,
+    HostedMCPTool,
+    HostedVectorStoreContent,
+    HostedWebSearchTool,
+    ai_function,
+)
+from agent_framework.exceptions import ServiceInitializationError
+from azure.ai.agents.models import (
+    Agent,
+    CodeInterpreterToolDefinition,
+)
+from pydantic import BaseModel
+
+from agent_framework_azure_ai import (
+    AzureAIAgentsProvider,
+    AzureAISettings,
+)
+from agent_framework_azure_ai._shared import (
+    from_azure_ai_agent_tools,
+    to_azure_ai_agent_tools,
+)
+
+skip_if_azure_ai_integration_tests_disabled = pytest.mark.skipif(
+    os.getenv("RUN_INTEGRATION_TESTS", "false").lower() != "true"
+    or os.getenv("AZURE_AI_PROJECT_ENDPOINT", "") in ("", "https://test-project.cognitiveservices.azure.com/"),
+    reason="No real AZURE_AI_PROJECT_ENDPOINT provided; skipping integration tests."
+    if os.getenv("RUN_INTEGRATION_TESTS", "false").lower() == "true"
+    else "Integration tests are disabled.",
+)
+
+
+# region Provider Initialization Tests
+
+
+def test_provider_init_with_agents_client(mock_agents_client: MagicMock) -> None:
+    """Test AzureAIAgentsProvider initialization with existing AgentsClient."""
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    assert provider._agents_client is mock_agents_client  # type: ignore
+    assert provider._should_close_client is False  # type: ignore
+
+
+def test_provider_init_with_credential(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_azure_credential: MagicMock,
+) -> None:
+    """Test AzureAIAgentsProvider initialization with credential."""
+    with patch("agent_framework_azure_ai._agent_provider.AgentsClient") as mock_client_class:
+        mock_client_instance = MagicMock()
+        mock_client_class.return_value = mock_client_instance
+
+        provider = AzureAIAgentsProvider(credential=mock_azure_credential)
+
+        mock_client_class.assert_called_once()
+        assert provider._agents_client is mock_client_instance  # type: ignore
+        assert provider._should_close_client is True  # type: ignore
+
+
+def test_provider_init_with_explicit_endpoint(mock_azure_credential: MagicMock) -> None:
+    """Test AzureAIAgentsProvider initialization with explicit endpoint."""
+    with patch("agent_framework_azure_ai._agent_provider.AgentsClient") as mock_client_class:
+        mock_client_instance = MagicMock()
+        mock_client_class.return_value = mock_client_instance
+
+        provider = AzureAIAgentsProvider(
+            project_endpoint="https://custom-endpoint.com/",
+            credential=mock_azure_credential,
+        )
+
+        mock_client_class.assert_called_once()
+        call_kwargs = mock_client_class.call_args.kwargs
+        assert call_kwargs["endpoint"] == "https://custom-endpoint.com/"
+        assert provider._should_close_client is True  # type: ignore
+
+
+def test_provider_init_missing_endpoint_raises(
+    mock_azure_credential: MagicMock,
+) -> None:
+    """Test AzureAIAgentsProvider raises error when endpoint is missing."""
+    # Mock AzureAISettings to return None for project_endpoint
+    with patch("agent_framework_azure_ai._agent_provider.AzureAISettings") as mock_settings_class:
+        mock_settings = MagicMock()
+        mock_settings.project_endpoint = None
+        mock_settings.model_deployment_name = "test-model"
+        mock_settings_class.return_value = mock_settings
+
+        with pytest.raises(ServiceInitializationError) as exc_info:
+            AzureAIAgentsProvider(credential=mock_azure_credential)
+
+        assert "project endpoint is required" in str(exc_info.value).lower()
+
+
+def test_provider_init_missing_credential_raises(azure_ai_unit_test_env: dict[str, str]) -> None:
+    """Test AzureAIAgentsProvider raises error when credential is missing."""
+    with pytest.raises(ServiceInitializationError) as exc_info:
+        AzureAIAgentsProvider()
+
+    assert "credential is required" in str(exc_info.value).lower()
+
+
+# endregion
+
+
+# region Context Manager Tests
+
+
+async def test_provider_context_manager_closes_client(mock_agents_client: MagicMock) -> None:
+    """Test that context manager closes client when it was created by provider."""
+    with patch("agent_framework_azure_ai._agent_provider.AgentsClient") as mock_client_class:
+        mock_client_instance = AsyncMock()
+        mock_client_class.return_value = mock_client_instance
+
+        with patch.object(AzureAIAgentsProvider, "__init__", lambda self: None):  # type: ignore
+            provider = AzureAIAgentsProvider.__new__(AzureAIAgentsProvider)
+            provider._agents_client = mock_client_instance  # type: ignore
+            provider._should_close_client = True  # type: ignore
+            provider._settings = AzureAISettings(project_endpoint="https://test.com")  # type: ignore
+
+        async with provider:
+            pass
+
+        mock_client_instance.close.assert_called_once()
+
+
+async def test_provider_context_manager_does_not_close_external_client(mock_agents_client: MagicMock) -> None:
+    """Test that context manager does not close externally provided client."""
+    mock_agents_client.close = AsyncMock()
+
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    async with provider:
+        pass
+
+    mock_agents_client.close.assert_not_called()
+
+
+# endregion
+
+
+# region create_agent Tests
+
+
+async def test_create_agent_basic(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_agents_client: MagicMock,
+) -> None:
+    """Test creating a basic agent."""
+    mock_agent = MagicMock(spec=Agent)
+    mock_agent.id = "test-agent-id"
+    mock_agent.name = "TestAgent"
+    mock_agent.description = "A test agent"
+    mock_agent.instructions = "Be helpful"
+    mock_agent.model = "gpt-4"
+    mock_agent.temperature = 0.7
+    mock_agent.top_p = 0.9
+    mock_agent.tools = []
+    mock_agents_client.create_agent = AsyncMock(return_value=mock_agent)
+
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    agent = await provider.create_agent(
+        name="TestAgent",
+        instructions="Be helpful",
+        description="A test agent",
+    )
+
+    assert isinstance(agent, ChatAgent)
+    assert agent.name == "TestAgent"
+    assert agent.id == "test-agent-id"
+    mock_agents_client.create_agent.assert_called_once()
+
+
+async def test_create_agent_with_model(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_agents_client: MagicMock,
+) -> None:
+    """Test creating an agent with explicit model."""
+    mock_agent = MagicMock(spec=Agent)
+    mock_agent.id = "test-agent-id"
+    mock_agent.name = "TestAgent"
+    mock_agent.description = None
+    mock_agent.instructions = None
+    mock_agent.model = "custom-model"
+    mock_agent.temperature = None
+    mock_agent.top_p = None
+    mock_agent.tools = []
+    mock_agents_client.create_agent = AsyncMock(return_value=mock_agent)
+
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    await provider.create_agent(name="TestAgent", model="custom-model")
+
+    call_kwargs = mock_agents_client.create_agent.call_args.kwargs
+    assert call_kwargs["model"] == "custom-model"
+
+
+async def test_create_agent_with_tools(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_agents_client: MagicMock,
+) -> None:
+    """Test creating an agent with tools."""
+    mock_agent = MagicMock(spec=Agent)
+    mock_agent.id = "test-agent-id"
+    mock_agent.name = "TestAgent"
+    mock_agent.description = None
+    mock_agent.instructions = None
+    mock_agent.model = "gpt-4"
+    mock_agent.temperature = None
+    mock_agent.top_p = None
+    mock_agent.tools = []
+    mock_agents_client.create_agent = AsyncMock(return_value=mock_agent)
+
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    @ai_function
+    def get_weather(city: str) -> str:
+        """Get weather for a city."""
+        return f"Weather in {city}"
+
+    await provider.create_agent(name="TestAgent", tools=get_weather)
+
+    call_kwargs = mock_agents_client.create_agent.call_args.kwargs
+    assert "tools" in call_kwargs
+    assert len(call_kwargs["tools"]) > 0
+
+
+async def test_create_agent_with_response_format(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_agents_client: MagicMock,
+) -> None:
+    """Test creating an agent with structured response format via default_options."""
+
+    class WeatherResponse(BaseModel):
+        temperature: float
+        description: str
+
+    mock_agent = MagicMock(spec=Agent)
+    mock_agent.id = "test-agent-id"
+    mock_agent.name = "TestAgent"
+    mock_agent.description = None
+    mock_agent.instructions = None
+    mock_agent.model = "gpt-4"
+    mock_agent.temperature = None
+    mock_agent.top_p = None
+    mock_agent.tools = []
+    mock_agents_client.create_agent = AsyncMock(return_value=mock_agent)
+
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    await provider.create_agent(
+        name="TestAgent",
+        default_options={"response_format": WeatherResponse},
+    )
+
+    call_kwargs = mock_agents_client.create_agent.call_args.kwargs
+    assert "response_format" in call_kwargs
+
+
+async def test_create_agent_missing_model_raises(
+    mock_agents_client: MagicMock,
+) -> None:
+    """Test that create_agent raises error when model is not specified."""
+    # Create provider with mocked settings that has no model
+    with patch("agent_framework_azure_ai._agent_provider.AzureAISettings") as mock_settings_class:
+        mock_settings = MagicMock()
+        mock_settings.project_endpoint = "https://test.com"
+        mock_settings.model_deployment_name = None  # No model configured
+        mock_settings_class.return_value = mock_settings
+
+        provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+        with pytest.raises(ServiceInitializationError) as exc_info:
+            await provider.create_agent(name="TestAgent")
+
+        assert "model deployment name is required" in str(exc_info.value).lower()
+
+
+# endregion
+
+
+# region get_agent Tests
+
+
+async def test_get_agent_by_id(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_agents_client: MagicMock,
+) -> None:
+    """Test getting an agent by ID."""
+    mock_agent = MagicMock(spec=Agent)
+    mock_agent.id = "existing-agent-id"
+    mock_agent.name = "ExistingAgent"
+    mock_agent.description = "An existing agent"
+    mock_agent.instructions = "Be helpful"
+    mock_agent.model = "gpt-4"
+    mock_agent.temperature = 0.7
+    mock_agent.top_p = 0.9
+    mock_agent.tools = []
+    mock_agents_client.get_agent = AsyncMock(return_value=mock_agent)
+
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    agent = await provider.get_agent("existing-agent-id")
+
+    assert isinstance(agent, ChatAgent)
+    assert agent.id == "existing-agent-id"
+    mock_agents_client.get_agent.assert_called_once_with("existing-agent-id")
+
+
+async def test_get_agent_with_function_tools(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_agents_client: MagicMock,
+) -> None:
+    """Test getting an agent that has function tools requires tool implementations."""
+    mock_function_tool = MagicMock()
+    mock_function_tool.type = "function"
+    mock_function_tool.function = MagicMock()
+    mock_function_tool.function.name = "get_weather"
+
+    mock_agent = MagicMock(spec=Agent)
+    mock_agent.id = "agent-with-tools"
+    mock_agent.name = "AgentWithTools"
+    mock_agent.description = None
+    mock_agent.instructions = None
+    mock_agent.model = "gpt-4"
+    mock_agent.temperature = None
+    mock_agent.top_p = None
+    mock_agent.tools = [mock_function_tool]
+    mock_agents_client.get_agent = AsyncMock(return_value=mock_agent)
+
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    with pytest.raises(ServiceInitializationError) as exc_info:
+        await provider.get_agent("agent-with-tools")
+
+    assert "get_weather" in str(exc_info.value)
+
+
+async def test_get_agent_with_provided_function_tools(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_agents_client: MagicMock,
+) -> None:
+    """Test getting an agent with function tools when implementations are provided."""
+    mock_function_tool = MagicMock()
+    mock_function_tool.type = "function"
+    mock_function_tool.function = MagicMock()
+    mock_function_tool.function.name = "get_weather"
+
+    mock_agent = MagicMock(spec=Agent)
+    mock_agent.id = "agent-with-tools"
+    mock_agent.name = "AgentWithTools"
+    mock_agent.description = None
+    mock_agent.instructions = None
+    mock_agent.model = "gpt-4"
+    mock_agent.temperature = None
+    mock_agent.top_p = None
+    mock_agent.tools = [mock_function_tool]
+    mock_agents_client.get_agent = AsyncMock(return_value=mock_agent)
+
+    @ai_function
+    def get_weather(city: str) -> str:
+        """Get weather for a city."""
+        return f"Weather in {city}"
+
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    agent = await provider.get_agent("agent-with-tools", tools=get_weather)
+
+    assert isinstance(agent, ChatAgent)
+    assert agent.id == "agent-with-tools"
+
+
+# endregion
+
+
+# region as_agent Tests
+
+
+def test_as_agent_wraps_without_http(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_agents_client: MagicMock,
+) -> None:
+    """Test as_agent wraps Agent object without making HTTP calls."""
+    mock_agent = MagicMock(spec=Agent)
+    mock_agent.id = "wrap-agent-id"
+    mock_agent.name = "WrapAgent"
+    mock_agent.description = "Wrapped agent"
+    mock_agent.instructions = "Be helpful"
+    mock_agent.model = "gpt-4"
+    mock_agent.temperature = 0.5
+    mock_agent.top_p = 0.8
+    mock_agent.tools = []
+
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    agent = provider.as_agent(mock_agent)
+
+    assert isinstance(agent, ChatAgent)
+    assert agent.id == "wrap-agent-id"
+    assert agent.name == "WrapAgent"
+    # Ensure no HTTP calls were made
+    mock_agents_client.get_agent.assert_not_called()
+    mock_agents_client.create_agent.assert_not_called()
+
+
+def test_as_agent_with_function_tools_validates(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_agents_client: MagicMock,
+) -> None:
+    """Test as_agent validates that function tool implementations are provided."""
+    mock_function_tool = MagicMock()
+    mock_function_tool.type = "function"
+    mock_function_tool.function = MagicMock()
+    mock_function_tool.function.name = "my_function"
+
+    mock_agent = MagicMock(spec=Agent)
+    mock_agent.id = "agent-id"
+    mock_agent.name = "Agent"
+    mock_agent.description = None
+    mock_agent.instructions = None
+    mock_agent.model = "gpt-4"
+    mock_agent.temperature = None
+    mock_agent.top_p = None
+    mock_agent.tools = [mock_function_tool]
+
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    with pytest.raises(ServiceInitializationError) as exc_info:
+        provider.as_agent(mock_agent)
+
+    assert "my_function" in str(exc_info.value)
+
+
+def test_as_agent_with_hosted_tools(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_agents_client: MagicMock,
+) -> None:
+    """Test as_agent handles hosted tools correctly."""
+    mock_code_interpreter = MagicMock()
+    mock_code_interpreter.type = "code_interpreter"
+
+    mock_agent = MagicMock(spec=Agent)
+    mock_agent.id = "agent-id"
+    mock_agent.name = "Agent"
+    mock_agent.description = None
+    mock_agent.instructions = None
+    mock_agent.model = "gpt-4"
+    mock_agent.temperature = None
+    mock_agent.top_p = None
+    mock_agent.tools = [mock_code_interpreter]
+
+    provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
+
+    agent = provider.as_agent(mock_agent)
+
+    assert isinstance(agent, ChatAgent)
+    # Should have HostedCodeInterpreterTool in the default_options tools
+    assert any(isinstance(t, HostedCodeInterpreterTool) for t in (agent.default_options.get("tools") or []))
+
+
+# endregion
+
+
+# region Tool Conversion Tests - to_azure_ai_agent_tools
+
+
+def test_to_azure_ai_agent_tools_empty() -> None:
+    """Test converting empty tools list."""
+    result = to_azure_ai_agent_tools(None)
+    assert result == []
+
+    result = to_azure_ai_agent_tools([])
+    assert result == []
+
+
+def test_to_azure_ai_agent_tools_function() -> None:
+    """Test converting AIFunction to Azure tool definition."""
+
+    @ai_function
+    def get_weather(city: str) -> str:
+        """Get weather for a city."""
+        return f"Weather in {city}"
+
+    result = to_azure_ai_agent_tools([get_weather])
+
+    assert len(result) == 1
+    assert result[0]["type"] == "function"
+    assert result[0]["function"]["name"] == "get_weather"
+
+
+def test_to_azure_ai_agent_tools_code_interpreter() -> None:
+    """Test converting HostedCodeInterpreterTool."""
+    tool = HostedCodeInterpreterTool()
+
+    result = to_azure_ai_agent_tools([tool])
+
+    assert len(result) == 1
+    assert isinstance(result[0], CodeInterpreterToolDefinition)
+
+
+def test_to_azure_ai_agent_tools_file_search() -> None:
+    """Test converting HostedFileSearchTool with vector stores."""
+    tool = HostedFileSearchTool(inputs=[HostedVectorStoreContent(vector_store_id="vs-123")])
+    run_options: dict[str, Any] = {}
+
+    result = to_azure_ai_agent_tools([tool], run_options)
+
+    assert len(result) == 1
+    assert "tool_resources" in run_options
+
+
+def test_to_azure_ai_agent_tools_web_search_bing_grounding(monkeypatch: Any) -> None:
+    """Test converting HostedWebSearchTool for Bing Grounding."""
+    # Use a properly formatted connection ID as required by Azure SDK
+    valid_conn_id = (
+        "/subscriptions/test-sub/resourceGroups/test-rg/"
+        "providers/Microsoft.CognitiveServices/accounts/test-account/"
+        "projects/test-project/connections/test-connection"
+    )
+    monkeypatch.setenv("BING_CONNECTION_ID", valid_conn_id)
+    tool = HostedWebSearchTool()
+
+    result = to_azure_ai_agent_tools([tool])
+
+    assert len(result) > 0
+
+
+def test_to_azure_ai_agent_tools_web_search_custom(monkeypatch: Any) -> None:
+    """Test converting HostedWebSearchTool for Custom Bing Search."""
+    monkeypatch.setenv("BING_CUSTOM_CONNECTION_ID", "custom-conn-id")
+    monkeypatch.setenv("BING_CUSTOM_INSTANCE_NAME", "my-instance")
+    tool = HostedWebSearchTool()
+
+    result = to_azure_ai_agent_tools([tool])
+
+    assert len(result) > 0
+
+
+def test_to_azure_ai_agent_tools_web_search_missing_config(monkeypatch: Any) -> None:
+    """Test converting HostedWebSearchTool raises error when config is missing."""
+    monkeypatch.delenv("BING_CONNECTION_ID", raising=False)
+    monkeypatch.delenv("BING_CUSTOM_CONNECTION_ID", raising=False)
+    monkeypatch.delenv("BING_CUSTOM_INSTANCE_NAME", raising=False)
+    tool = HostedWebSearchTool()
+
+    with pytest.raises(ServiceInitializationError):
+        to_azure_ai_agent_tools([tool])
+
+
+def test_to_azure_ai_agent_tools_mcp() -> None:
+    """Test converting HostedMCPTool."""
+    tool = HostedMCPTool(
+        name="my mcp server",
+        url="https://mcp.example.com",
+        allowed_tools=["tool1", "tool2"],
+    )
+
+    result = to_azure_ai_agent_tools([tool])
+
+    assert len(result) > 0
+
+
+def test_to_azure_ai_agent_tools_dict_passthrough() -> None:
+    """Test that dict tools are passed through."""
+    tool = {"type": "custom_tool", "config": {"key": "value"}}
+
+    result = to_azure_ai_agent_tools([tool])
+
+    assert len(result) == 1
+    assert result[0] == tool
+
+
+def test_to_azure_ai_agent_tools_unsupported_type() -> None:
+    """Test that unsupported tool types raise error."""
+
+    class UnsupportedTool:
+        pass
+
+    with pytest.raises(ServiceInitializationError):
+        to_azure_ai_agent_tools([UnsupportedTool()])  # type: ignore
+
+
+# endregion
+
+
+# region Tool Conversion Tests - from_azure_ai_agent_tools
+
+
+def test_from_azure_ai_agent_tools_empty() -> None:
+    """Test converting empty tools list."""
+    result = from_azure_ai_agent_tools(None)
+    assert result == []
+
+    result = from_azure_ai_agent_tools([])
+    assert result == []
+
+
+def test_from_azure_ai_agent_tools_code_interpreter() -> None:
+    """Test converting CodeInterpreterToolDefinition."""
+    tool = CodeInterpreterToolDefinition()
+
+    result = from_azure_ai_agent_tools([tool])
+
+    assert len(result) == 1
+    assert isinstance(result[0], HostedCodeInterpreterTool)
+
+
+def test_from_azure_ai_agent_tools_code_interpreter_dict() -> None:
+    """Test converting code_interpreter dict."""
+    tool = {"type": "code_interpreter"}
+
+    result = from_azure_ai_agent_tools([tool])
+
+    assert len(result) == 1
+    assert isinstance(result[0], HostedCodeInterpreterTool)
+
+
+def test_from_azure_ai_agent_tools_file_search_dict() -> None:
+    """Test converting file_search dict with vector store IDs."""
+    tool = {
+        "type": "file_search",
+        "file_search": {"vector_store_ids": ["vs-123", "vs-456"]},
+    }
+
+    result = from_azure_ai_agent_tools([tool])
+
+    assert len(result) == 1
+    assert isinstance(result[0], HostedFileSearchTool)
+    assert len(result[0].inputs or []) == 2
+
+
+def test_from_azure_ai_agent_tools_bing_grounding_dict() -> None:
+    """Test converting bing_grounding dict."""
+    tool = {
+        "type": "bing_grounding",
+        "bing_grounding": {"connection_id": "conn-123"},
+    }
+
+    result = from_azure_ai_agent_tools([tool])
+
+    assert len(result) == 1
+    assert isinstance(result[0], HostedWebSearchTool)
+
+    additional_properties = result[0].additional_properties
+
+    assert additional_properties
+    assert additional_properties.get("connection_id") == "conn-123"
+
+
+def test_from_azure_ai_agent_tools_bing_custom_search_dict() -> None:
+    """Test converting bing_custom_search dict."""
+    tool = {
+        "type": "bing_custom_search",
+        "bing_custom_search": {
+            "connection_id": "custom-conn",
+            "instance_name": "my-instance",
+        },
+    }
+
+    result = from_azure_ai_agent_tools([tool])
+
+    assert len(result) == 1
+    assert isinstance(result[0], HostedWebSearchTool)
+    additional_properties = result[0].additional_properties
+
+    assert additional_properties
+    assert additional_properties.get("custom_connection_id") == "custom-conn"
+
+
+def test_from_azure_ai_agent_tools_mcp_dict() -> None:
+    """Test that mcp dict is skipped (hosted on Azure, no local handling needed)."""
+    tool = {
+        "type": "mcp",
+        "mcp": {
+            "server_label": "my_server",
+            "server_url": "https://mcp.example.com",
+            "allowed_tools": ["tool1"],
+        },
+    }
+
+    result = from_azure_ai_agent_tools([tool])
+
+    # MCP tools are hosted on Azure agent, skipped in conversion
+    assert len(result) == 0
+
+
+def test_from_azure_ai_agent_tools_function_dict() -> None:
+    """Test converting function tool dict (returned as-is)."""
+    tool: dict[str, Any] = {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get weather",
+            "parameters": {},
+        },
+    }
+
+    result = from_azure_ai_agent_tools([tool])
+
+    assert len(result) == 1
+    assert result[0] == tool
+
+
+def test_from_azure_ai_agent_tools_unknown_dict() -> None:
+    """Test converting unknown tool type dict."""
+    tool = {"type": "unknown_tool", "config": "value"}
+
+    result = from_azure_ai_agent_tools([tool])
+
+    assert len(result) == 1
+    assert result[0] == tool
+
+
+# endregion
+
+
+# region Integration Tests
+
+
+@skip_if_azure_ai_integration_tests_disabled
+async def test_integration_create_agent() -> None:
+    """Integration test: Create an agent using the provider."""
+    from azure.identity.aio import AzureCliCredential
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="IntegrationTestAgent",
+            instructions="You are a helpful assistant for testing.",
+        )
+
+        try:
+            assert isinstance(agent, ChatAgent)
+            assert agent.name == "IntegrationTestAgent"
+            assert agent.id is not None
+        finally:
+            # Cleanup: delete the agent
+            if agent.id:
+                await provider._agents_client.delete_agent(agent.id)  # type: ignore
+
+
+@skip_if_azure_ai_integration_tests_disabled
+async def test_integration_get_agent() -> None:
+    """Integration test: Get an existing agent using the provider."""
+    from azure.identity.aio import AzureCliCredential
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        # First create an agent
+        created = await provider._agents_client.create_agent(  # type: ignore
+            model=os.getenv("AZURE_AI_MODEL_DEPLOYMENT_NAME", "gpt-4o"),
+            name="GetAgentTest",
+            instructions="Test agent",
+        )
+
+        try:
+            # Then get it using the provider
+            agent = await provider.get_agent(created.id)
+
+            assert isinstance(agent, ChatAgent)
+            assert agent.id == created.id
+        finally:
+            await provider._agents_client.delete_agent(created.id)  # type: ignore
+
+
+@skip_if_azure_ai_integration_tests_disabled
+async def test_integration_create_and_run() -> None:
+    """Integration test: Create an agent and run a conversation."""
+    from azure.identity.aio import AzureCliCredential
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="RunTestAgent",
+            instructions="You are a helpful assistant. Always respond with 'Hello!' to any greeting.",
+        )
+
+        try:
+            result = await agent.run("Hi there!")
+
+            assert result is not None
+            assert len(result.messages) > 0
+        finally:
+            if agent.id:
+                await provider._agents_client.delete_agent(agent.id)  # type: ignore
+
+
+# endregion

python/packages/azure-ai/tests/test_azure_ai_agent_client.py

@@ -11,7 +11,6 @@ from agent_framework import (
     AgentResponse,
     AgentResponseUpdate,
     AgentThread,
-    AIFunction,
     ChatAgent,
     ChatClientProtocol,
     ChatMessage,
@@ -28,7 +27,6 @@ from agent_framework import (
     HostedFileSearchTool,
     HostedMCPTool,
     HostedVectorStoreContent,
-    HostedWebSearchTool,
     Role,
     TextContent,
     UriContent,
@@ -38,7 +36,6 @@ from agent_framework.exceptions import ServiceInitializationError
 from azure.ai.agents.models import (
     AgentsNamedToolChoice,
     AgentsNamedToolChoiceType,
-    CodeInterpreterToolDefinition,
     FileInfo,
     MessageDeltaChunk,
     MessageDeltaTextContent,
@@ -672,60 +669,6 @@ def test_azure_ai_chat_client_service_url_method(mock_agents_client: MagicMock)
     assert url == "https://test-endpoint.com/"
 
 
-async def test_azure_ai_chat_client_prepare_tools_for_azure_ai_ai_function(mock_agents_client: MagicMock) -> None:
-    """Test _prepare_tools_for_azure_ai with AIFunction tool."""
-
-    chat_client = create_test_azure_ai_chat_client(mock_agents_client, agent_id="test-agent")
-
-    # Create a mock AIFunction
-    mock_ai_function = MagicMock(spec=AIFunction)
-    mock_ai_function.to_json_schema_spec.return_value = {"type": "function", "function": {"name": "test_function"}}
-
-    result = await chat_client._prepare_tools_for_azure_ai([mock_ai_function])  # type: ignore
-
-    assert len(result) == 1
-    assert result[0] == {"type": "function", "function": {"name": "test_function"}}
-    mock_ai_function.to_json_schema_spec.assert_called_once()
-
-
-async def test_azure_ai_chat_client_prepare_tools_for_azure_ai_code_interpreter(mock_agents_client: MagicMock) -> None:
-    """Test _prepare_tools_for_azure_ai with HostedCodeInterpreterTool."""
-
-    chat_client = create_test_azure_ai_chat_client(mock_agents_client, agent_id="test-agent")
-
-    code_interpreter_tool = HostedCodeInterpreterTool()
-
-    result = await chat_client._prepare_tools_for_azure_ai([code_interpreter_tool])  # type: ignore
-
-    assert len(result) == 1
-    assert isinstance(result[0], CodeInterpreterToolDefinition)
-
-
-async def test_azure_ai_chat_client_prepare_tools_for_azure_ai_mcp_tool(mock_agents_client: MagicMock) -> None:
-    """Test _prepare_tools_for_azure_ai with HostedMCPTool."""
-
-    chat_client = create_test_azure_ai_chat_client(mock_agents_client, agent_id="test-agent")
-
-    mcp_tool = HostedMCPTool(name="Test MCP Tool", url="https://example.com/mcp", allowed_tools=["tool1", "tool2"])
-
-    # Mock McpTool to have a definitions attribute
-    with patch("agent_framework_azure_ai._chat_client.McpTool") as mock_mcp_tool_class:
-        mock_mcp_tool = MagicMock()
-        mock_mcp_tool.definitions = [{"type": "mcp", "name": "test_mcp"}]
-        mock_mcp_tool_class.return_value = mock_mcp_tool
-
-        result = await chat_client._prepare_tools_for_azure_ai([mcp_tool])  # type: ignore
-
-        assert len(result) == 1
-        assert result[0] == {"type": "mcp", "name": "test_mcp"}
-        # Check that the call was made (order of allowed_tools may vary)
-        mock_mcp_tool_class.assert_called_once()
-        call_args = mock_mcp_tool_class.call_args[1]
-        assert call_args["server_label"] == "Test_MCP_Tool"
-        assert call_args["server_url"] == "https://example.com/mcp"
-        assert set(call_args["allowed_tools"]) == {"tool1", "tool2"}
-
-
 async def test_azure_ai_chat_client_prepare_options_mcp_never_require(mock_agents_client: MagicMock) -> None:
     """Test _prepare_options with HostedMCPTool having never_require approval mode."""
     chat_client = create_test_azure_ai_chat_client(mock_agents_client)
@@ -735,8 +678,7 @@ async def test_azure_ai_chat_client_prepare_options_mcp_never_require(mock_agent
     messages = [ChatMessage(role=Role.USER, text="Hello")]
     chat_options: ChatOptions = {"tools": [mcp_tool], "tool_choice": "auto"}
 
-    with patch("agent_framework_azure_ai._chat_client.McpTool") as mock_mcp_tool_class:
-        # Mock _prepare_tools_for_azure_ai to avoid actual tool preparation
+    with patch("agent_framework_azure_ai._shared.McpTool") as mock_mcp_tool_class:
         mock_mcp_tool_instance = MagicMock()
         mock_mcp_tool_instance.definitions = [{"type": "mcp", "name": "test_mcp"}]
         mock_mcp_tool_class.return_value = mock_mcp_tool_instance
@@ -768,8 +710,7 @@ async def test_azure_ai_chat_client_prepare_options_mcp_with_headers(mock_agents
     messages = [ChatMessage(role=Role.USER, text="Hello")]
     chat_options: ChatOptions = {"tools": [mcp_tool], "tool_choice": "auto"}
 
-    with patch("agent_framework_azure_ai._chat_client.McpTool") as mock_mcp_tool_class:
-        # Mock _prepare_tools_for_azure_ai to avoid actual tool preparation
+    with patch("agent_framework_azure_ai._shared.McpTool") as mock_mcp_tool_class:
         mock_mcp_tool_instance = MagicMock()
         mock_mcp_tool_instance.definitions = [{"type": "mcp", "name": "test_mcp"}]
         mock_mcp_tool_class.return_value = mock_mcp_tool_instance
@@ -787,121 +728,6 @@ async def test_azure_ai_chat_client_prepare_options_mcp_with_headers(mock_agents
         assert mcp_resource["headers"] == headers
 
 
-async def test_azure_ai_chat_client_prepare_tools_for_azure_ai_web_search_bing_grounding(
-    mock_agents_client: MagicMock,
-) -> None:
-    """Test _prepare_tools_for_azure_ai with HostedWebSearchTool using Bing Grounding."""
-
-    chat_client = create_test_azure_ai_chat_client(mock_agents_client, agent_id="test-agent")
-
-    web_search_tool = HostedWebSearchTool(
-        additional_properties={
-            "connection_id": "test-connection-id",
-            "count": 5,
-            "freshness": "Day",
-            "market": "en-US",
-            "set_lang": "en",
-        }
-    )
-
-    # Mock BingGroundingTool
-    with patch("agent_framework_azure_ai._chat_client.BingGroundingTool") as mock_bing_grounding:
-        mock_bing_tool = MagicMock()
-        mock_bing_tool.definitions = [{"type": "bing_grounding"}]
-        mock_bing_grounding.return_value = mock_bing_tool
-
-        result = await chat_client._prepare_tools_for_azure_ai([web_search_tool])  # type: ignore
-
-        assert len(result) == 1
-        assert result[0] == {"type": "bing_grounding"}
-        call_args = mock_bing_grounding.call_args[1]
-        assert call_args["count"] == 5
-        assert call_args["freshness"] == "Day"
-        assert call_args["market"] == "en-US"
-        assert call_args["set_lang"] == "en"
-        assert "connection_id" in call_args
-
-
-async def test_azure_ai_chat_client_prepare_tools_for_azure_ai_web_search_bing_grounding_with_connection_id(
-    mock_agents_client: MagicMock,
-) -> None:
-    """Test _prepare_tools_... with HostedWebSearchTool using Bing Grounding with connection_id (no HTTP call)."""
-
-    chat_client = create_test_azure_ai_chat_client(mock_agents_client, agent_id="test-agent")
-
-    web_search_tool = HostedWebSearchTool(
-        additional_properties={
-            "connection_id": "direct-connection-id",
-            "count": 3,
-        }
-    )
-
-    # Mock BingGroundingTool
-    with patch("agent_framework_azure_ai._chat_client.BingGroundingTool") as mock_bing_grounding:
-        mock_bing_tool = MagicMock()
-        mock_bing_tool.definitions = [{"type": "bing_grounding"}]
-        mock_bing_grounding.return_value = mock_bing_tool
-
-        result = await chat_client._prepare_tools_for_azure_ai([web_search_tool])  # type: ignore
-
-        assert len(result) == 1
-        assert result[0] == {"type": "bing_grounding"}
-        mock_bing_grounding.assert_called_once_with(connection_id="direct-connection-id", count=3)
-
-
-async def test_azure_ai_chat_client_prepare_tools_for_azure_ai_web_search_custom_bing(
-    mock_agents_client: MagicMock,
-) -> None:
-    """Test _prepare_tools_for_azure_ai with HostedWebSearchTool using Custom Bing Search."""
-
-    chat_client = create_test_azure_ai_chat_client(mock_agents_client, agent_id="test-agent")
-
-    web_search_tool = HostedWebSearchTool(
-        additional_properties={
-            "custom_connection_id": "custom-connection-id",
-            "custom_instance_name": "custom-instance",
-            "count": 10,
-        }
-    )
-
-    # Mock BingCustomSearchTool
-    with patch("agent_framework_azure_ai._chat_client.BingCustomSearchTool") as mock_custom_bing:
-        mock_custom_tool = MagicMock()
-        mock_custom_tool.definitions = [{"type": "bing_custom_search"}]
-        mock_custom_bing.return_value = mock_custom_tool
-
-        result = await chat_client._prepare_tools_for_azure_ai([web_search_tool])  # type: ignore
-
-        assert len(result) == 1
-        assert result[0] == {"type": "bing_custom_search"}
-
-
-async def test_azure_ai_chat_client_prepare_tools_for_azure_ai_file_search_with_vector_stores(
-    mock_agents_client: MagicMock,
-) -> None:
-    """Test _prepare_tools_for_azure_ai with HostedFileSearchTool using vector stores."""
-
-    chat_client = create_test_azure_ai_chat_client(mock_agents_client, agent_id="test-agent")
-
-    vector_store_input = HostedVectorStoreContent(vector_store_id="vs-123")
-    file_search_tool = HostedFileSearchTool(inputs=[vector_store_input])
-
-    # Mock FileSearchTool
-    with patch("agent_framework_azure_ai._chat_client.FileSearchTool") as mock_file_search:
-        mock_file_tool = MagicMock()
-        mock_file_tool.definitions = [{"type": "file_search"}]
-        mock_file_tool.resources = {"vector_store_ids": ["vs-123"]}
-        mock_file_search.return_value = mock_file_tool
-
-        run_options = {}
-        result = await chat_client._prepare_tools_for_azure_ai([file_search_tool], run_options)  # type: ignore
-
-        assert len(result) == 1
-        assert result[0] == {"type": "file_search"}
-        assert run_options["tool_resources"] == {"vector_store_ids": ["vs-123"]}
-        mock_file_search.assert_called_once_with(vector_store_ids=["vs-123"])
-
-
 async def test_azure_ai_chat_client_create_agent_stream_submit_tool_approvals(
     mock_agents_client: MagicMock,
 ) -> None:
@@ -943,28 +769,6 @@ async def test_azure_ai_chat_client_create_agent_stream_submit_tool_approvals(
         assert call_args["tool_approvals"][0].approve is True
 
 
-async def test_azure_ai_chat_client_prepare_tools_for_azure_ai_dict_tool(mock_agents_client: MagicMock) -> None:
-    """Test _prepare_tools_for_azure_ai with dictionary tool definition."""
-    chat_client = create_test_azure_ai_chat_client(mock_agents_client, agent_id="test-agent")
-
-    dict_tool = {"type": "custom_tool", "config": {"param": "value"}}
-
-    result = await chat_client._prepare_tools_for_azure_ai([dict_tool])  # type: ignore
-
-    assert len(result) == 1
-    assert result[0] == dict_tool
-
-
-async def test_azure_ai_chat_client_prepare_tools_for_azure_ai_unsupported_tool(mock_agents_client: MagicMock) -> None:
-    """Test _prepare_tools_for_azure_ai with unsupported tool type."""
-    chat_client = create_test_azure_ai_chat_client(mock_agents_client, agent_id="test-agent")
-
-    unsupported_tool = "not_a_tool"
-
-    with pytest.raises(ServiceInitializationError, match="Unsupported tool type: <class 'str'>"):
-        await chat_client._prepare_tools_for_azure_ai([unsupported_tool])  # type: ignore
-
-
 async def test_azure_ai_chat_client_get_active_thread_run_with_active_run(mock_agents_client: MagicMock) -> None:
     """Test _get_active_thread_run when there's an active run."""
 

python/packages/azure-ai/tests/test_provider.py

@@ -86,7 +86,7 @@ def test_provider_init_with_credential_and_endpoint(
     mock_azure_credential: MagicMock,
 ) -> None:
     """Test AzureAIProjectAgentProvider initialization with credential and endpoint."""
-    with patch("agent_framework_azure_ai._provider.AIProjectClient") as mock_ai_project_client:
+    with patch("agent_framework_azure_ai._project_provider.AIProjectClient") as mock_ai_project_client:
         mock_client = MagicMock()
         mock_ai_project_client.return_value = mock_client
 
@@ -104,7 +104,7 @@ def test_provider_init_with_credential_and_endpoint(
 
 def test_provider_init_missing_endpoint() -> None:
     """Test AzureAIProjectAgentProvider initialization when endpoint is missing."""
-    with patch("agent_framework_azure_ai._provider.AzureAISettings") as mock_settings:
+    with patch("agent_framework_azure_ai._project_provider.AzureAISettings") as mock_settings:
         mock_settings.return_value.project_endpoint = None
         mock_settings.return_value.model_deployment_name = "test-model"
 
@@ -127,7 +127,7 @@ async def test_provider_create_agent(
     azure_ai_unit_test_env: dict[str, str],
 ) -> None:
     """Test AzureAIProjectAgentProvider.create_agent method."""
-    with patch("agent_framework_azure_ai._provider.AzureAISettings") as mock_settings:
+    with patch("agent_framework_azure_ai._project_provider.AzureAISettings") as mock_settings:
         mock_settings.return_value.project_endpoint = azure_ai_unit_test_env["AZURE_AI_PROJECT_ENDPOINT"]
         mock_settings.return_value.model_deployment_name = azure_ai_unit_test_env["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
 
@@ -165,7 +165,7 @@ async def test_provider_create_agent_with_env_model(
     azure_ai_unit_test_env: dict[str, str],
 ) -> None:
     """Test AzureAIProjectAgentProvider.create_agent uses model from env var."""
-    with patch("agent_framework_azure_ai._provider.AzureAISettings") as mock_settings:
+    with patch("agent_framework_azure_ai._project_provider.AzureAISettings") as mock_settings:
         mock_settings.return_value.project_endpoint = azure_ai_unit_test_env["AZURE_AI_PROJECT_ENDPOINT"]
         mock_settings.return_value.model_deployment_name = azure_ai_unit_test_env["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
 
@@ -197,7 +197,7 @@ async def test_provider_create_agent_with_env_model(
 
 async def test_provider_create_agent_missing_model(mock_project_client: MagicMock) -> None:
     """Test AzureAIProjectAgentProvider.create_agent raises when model is missing."""
-    with patch("agent_framework_azure_ai._provider.AzureAISettings") as mock_settings:
+    with patch("agent_framework_azure_ai._project_provider.AzureAISettings") as mock_settings:
         mock_settings.return_value.project_endpoint = "https://test.com"
         mock_settings.return_value.model_deployment_name = None
 
@@ -326,12 +326,12 @@ def test_provider_as_agent(mock_project_client: MagicMock) -> None:
 
 async def test_provider_context_manager(mock_project_client: MagicMock) -> None:
     """Test AzureAIProjectAgentProvider async context manager."""
-    with patch("agent_framework_azure_ai._provider.AIProjectClient") as mock_ai_project_client:
+    with patch("agent_framework_azure_ai._project_provider.AIProjectClient") as mock_ai_project_client:
         mock_client = MagicMock()
         mock_client.close = AsyncMock()
         mock_ai_project_client.return_value = mock_client
 
-        with patch("agent_framework_azure_ai._provider.AzureAISettings") as mock_settings:
+        with patch("agent_framework_azure_ai._project_provider.AzureAISettings") as mock_settings:
             mock_settings.return_value.project_endpoint = "https://test.com"
             mock_settings.return_value.model_deployment_name = "test-model"
 
@@ -355,12 +355,12 @@ async def test_provider_context_manager_with_provided_client(mock_project_client
 
 async def test_provider_close_method(mock_project_client: MagicMock) -> None:
     """Test AzureAIProjectAgentProvider.close method."""
-    with patch("agent_framework_azure_ai._provider.AIProjectClient") as mock_ai_project_client:
+    with patch("agent_framework_azure_ai._project_provider.AIProjectClient") as mock_ai_project_client:
         mock_client = MagicMock()
         mock_client.close = AsyncMock()
         mock_ai_project_client.return_value = mock_client
 
-        with patch("agent_framework_azure_ai._provider.AzureAISettings") as mock_settings:
+        with patch("agent_framework_azure_ai._project_provider.AzureAISettings") as mock_settings:
             mock_settings.return_value.project_endpoint = "https://test.com"
             mock_settings.return_value.model_deployment_name = "test-model"