Python: [BREAKING] Python: Provider-leading client design & OpenAI package extraction (#4818)

* Python: Provider-leading client design & OpenAI package extraction Major refactoring of the Python Agent Framework client architecture: - Extract OpenAI clients into new `agent-framework-openai` package - Core package no longer depends on openai, azure-identity, azure-ai-projects - Rename clients for discoverability: OpenAIResponsesClient → OpenAIChatClient, OpenAIChatClient → OpenAIChatCompletionClient - Unify `model_id`/`deployment_name`/`model_deployment_name` → `model` param - New FoundryChatClient for Azure AI Foundry Responses API - New FoundryAgent/FoundryAgentClient for connecting to pre-configured Foundry agents - Remove OpenAIBase/OpenAIConfigMixin from non-deprecated client MRO - Deprecate AzureOpenAI* clients, AzureAIClient, OpenAIAssistantsClient - Reorganize samples: azure_openai+azure_ai+azure_ai_agent → azure/ - ADR-0020: Provider-Leading Client Design Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: missing Agent imports in samples, .model_id → .model in foundry_local sample Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: CI failures — mypy errors, coverage targets, sample imports - azure-ai mypy: add type ignores for TypedDict total=, model arg, forward ref - Coverage: replace core.azure/openai targets with openai package target - project_provider: add type annotation for opts dict Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: populate openai .pyi stub, fix broken README links, coverage targets Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fixes * updated observabilitty * reset azure init.pyi * fix errors * updated adr number * fix foundry local * fixed not renamed docstrings and comments, and added deprecated markers to old classes * fix tests and pyprojects * fix test vars * updated function tests * update durable * updated test setup for functions * Fix Foundry auth in workflow samples Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Stabilize Python integration workflows Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update hosting samples for Foundry Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Trigger full CI rerun Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Trigger CI rerun again Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * trigger rerun * trigger rerun * fix for litellm * undo durabletask changes * Move Foundry APIs into foundry namespace Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix Foundry pyproject formatting Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Split provider samples by Foundry surface Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Restore hosting sample requirements Also fix the Foundry Local sample link after the provider sample move. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * updated tests * udpated foundry integration tests * removed dist from azurefunctions tests * Use separate Foundry clients for concurrent agents Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix client setup in azfunc and durable * disabled two tests * updated setup for some function and durable tests * improved azure openai setup with new clients * ignore deprecated * fixes * skip 11 * remove openai assistants int tests --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2026-03-25 10:56:29 +01:00
parent 4b533608b6
commit 5e056b672e
485 changed files with 9784 additions and 12084 deletions
@@ -11,7 +11,7 @@ Integration with Azure AI Foundry Local for local model inference.
 ## Usage

 ```python
-from agent_framework_foundry_local import FoundryLocalClient
+from agent_framework.foundry import FoundryLocalClient

 client = FoundryLocalClient(model_id="your-local-model")
 response = await client.get_response("Hello")
@@ -20,5 +20,5 @@ response = await client.get_response("Hello")
 ## Import Path

 ```python
-from agent_framework_foundry_local import FoundryLocalClient
+from agent_framework.foundry import FoundryLocalClient
 ```
@@ -10,4 +10,4 @@ and see the [README](https://github.com/microsoft/agent-framework/tree/main/pyth

 ## Foundry Local Sample

-See the [Foundry Local provider sample](../../samples/02-agents/providers/foundry_local/foundry_local_agent.py) for a runnable example.
+See the [Foundry Local provider sample](../../samples/02-agents/providers/foundry/foundry_local_agent.py) for a runnable example.
@@ -15,7 +15,7 @@ from agent_framework import (
 )
 from agent_framework._settings import load_settings
 from agent_framework.observability import ChatTelemetryLayer
-from agent_framework.openai._chat_client import RawOpenAIChatClient
+from agent_framework_openai._chat_completion_client import RawOpenAIChatCompletionClient
 from foundry_local import FoundryLocalManager
 from foundry_local.models import DeviceType
 from openai import AsyncOpenAI
@@ -126,21 +126,21 @@ class FoundryLocalSettings(TypedDict, total=False):
            (Env var FOUNDRY_LOCAL_MODEL_ID)
    """

-    model_id: str | None
+    model: str | None


 class FoundryLocalClient(
    FunctionInvocationLayer[FoundryLocalChatOptionsT],
    ChatMiddlewareLayer[FoundryLocalChatOptionsT],
    ChatTelemetryLayer[FoundryLocalChatOptionsT],
-    RawOpenAIChatClient[FoundryLocalChatOptionsT],
+    RawOpenAIChatCompletionClient[FoundryLocalChatOptionsT],
    Generic[FoundryLocalChatOptionsT],
 ):
    """Foundry Local Chat completion class with middleware, telemetry, and function invocation support."""

    def __init__(
        self,
-        model_id: str | None = None,
+        model: str | None = None,
        *,
        bootstrap: bool = True,
        timeout: float | None = None,
@@ -155,7 +155,7 @@ class FoundryLocalClient(
        """Initialize a FoundryLocalClient.

        Keyword Args:
-            model_id: The Foundry Local model ID or alias to use. If not provided,
+            model: The Foundry Local model ID or alias to use. If not provided,
                it will be loaded from the FoundryLocalSettings.
            bootstrap: Whether to start the Foundry Local service if not already running.
                Default is True.
@@ -180,7 +180,7 @@ class FoundryLocalClient(
            .. code-block:: python

                # Create a FoundryLocalClient with a specific model ID:
-                from agent_framework_foundry_local import FoundryLocalClient
+                from agent_framework.foundry import FoundryLocalClient

                client = FoundryLocalClient(model_id="phi-4-mini")

@@ -225,7 +225,7 @@ class FoundryLocalClient(

                # Using custom ChatOptions with type safety:
                from typing import TypedDict
-                from agent_framework_foundry_local import FoundryLocalChatOptions
+                from agent_framework.foundry import FoundryLocalChatOptions

                class MyOptions(FoundryLocalChatOptions, total=False):
                    my_custom_option: str
@@ -242,25 +242,23 @@ class FoundryLocalClient(
        settings = load_settings(
            FoundryLocalSettings,
            env_prefix="FOUNDRY_LOCAL_",
-            required_fields=["model_id"],
-            model_id=model_id,
+            required_fields=["model"],
+            model=model,
            env_file_path=env_file_path,
            env_file_encoding=env_file_encoding,
        )
-        model_id_setting: str = settings["model_id"]  # type: ignore[assignment]  # pyright: ignore[reportTypedDictNotRequiredAccess]
+        model_setting: str = settings["model"]  # type: ignore[assignment]  # pyright: ignore[reportTypedDictNotRequiredAccess]

        manager = FoundryLocalManager(bootstrap=bootstrap, timeout=timeout)
        model_info = manager.get_model_info(
-            alias_or_model_id=model_id_setting,
+            alias_or_model_id=model_setting,
            device=device,
        )
        if model_info is None:
            message = (
-                f"Model with ID or alias '{model_id_setting}:{device.value}' not found in Foundry Local."
+                f"Model with ID or alias '{model_setting}:{device.value}' not found in Foundry Local."
                if device
-                else (
-                    f"Model with ID or alias '{model_id_setting}' for your current device not found in Foundry Local."
-                )
+                else (f"Model with ID or alias '{model_setting}' for your current device not found in Foundry Local.")
            )
            raise ValueError(message)
        if prepare_model:
@@ -268,8 +266,8 @@ class FoundryLocalClient(
            manager.load_model(alias_or_model_id=model_info.id, device=device)

        super().__init__(
-            model_id=model_info.id,
-            client=AsyncOpenAI(base_url=manager.endpoint, api_key=manager.api_key),
+            model=model_info.id,
+            async_client=AsyncOpenAI(base_url=manager.endpoint, api_key=manager.api_key),
            additional_properties=additional_properties,
            middleware=middleware,
            function_invocation_configuration=function_invocation_configuration,
@@ -24,6 +24,7 @@ classifiers = [
 ]
 dependencies = [
    "agent-framework-core>=1.0.0rc5",
+    "agent-framework-openai>=1.0.0rc5",
    "foundry-local-sdk>=0.5.1,<0.5.2",
 ]

@@ -27,7 +27,7 @@ def foundry_local_unit_test_env(monkeypatch: Any, exclude_list: list[str], overr
        override_env_param_dict = {}

    env_vars = {
-        "FOUNDRY_LOCAL_MODEL_ID": "test-model-id",
+        "FOUNDRY_LOCAL_MODEL": "test-model-id",
    }

    env_vars.update(override_env_param_dict)
@@ -6,8 +6,8 @@ import pytest
 from agent_framework import SupportsChatGetResponse
 from agent_framework._settings import load_settings
 from agent_framework.exceptions import SettingNotFoundError
+from agent_framework.foundry import FoundryLocalClient

-from agent_framework_foundry_local import FoundryLocalClient
 from agent_framework_foundry_local._foundry_local_client import FoundryLocalSettings

 # Settings Tests
@@ -17,7 +17,7 @@ def test_foundry_local_settings_init_from_env(foundry_local_unit_test_env: dict[
    """Test FoundryLocalSettings initialization from environment variables."""
    settings = load_settings(FoundryLocalSettings, env_prefix="FOUNDRY_LOCAL_")

-    assert settings["model_id"] == foundry_local_unit_test_env["FOUNDRY_LOCAL_MODEL_ID"]
+    assert settings["model"] == foundry_local_unit_test_env["FOUNDRY_LOCAL_MODEL"]


 def test_foundry_local_settings_init_with_explicit_values() -> None:
@@ -25,29 +25,29 @@ def test_foundry_local_settings_init_with_explicit_values() -> None:
    settings = load_settings(
        FoundryLocalSettings,
        env_prefix="FOUNDRY_LOCAL_",
-        model_id="custom-model-id",
+        model="custom-model-id",
    )

-    assert settings["model_id"] == "custom-model-id"
+    assert settings["model"] == "custom-model-id"


-@pytest.mark.parametrize("exclude_list", [["FOUNDRY_LOCAL_MODEL_ID"]], indirect=True)
-def test_foundry_local_settings_missing_model_id(foundry_local_unit_test_env: dict[str, str]) -> None:
+@pytest.mark.parametrize("exclude_list", [["FOUNDRY_LOCAL_MODEL"]], indirect=True)
+def test_foundry_local_settings_missing_model(foundry_local_unit_test_env: dict[str, str]) -> None:
    """Test FoundryLocalSettings when model_id is missing raises error."""
-    with pytest.raises(SettingNotFoundError, match="Required setting 'model_id'"):
+    with pytest.raises(SettingNotFoundError, match="Required setting 'model'"):
        load_settings(
            FoundryLocalSettings,
            env_prefix="FOUNDRY_LOCAL_",
-            required_fields=["model_id"],
+            required_fields=["model"],
        )


 def test_foundry_local_settings_explicit_overrides_env(foundry_local_unit_test_env: dict[str, str]) -> None:
    """Test that explicit values override environment variables."""
-    settings = load_settings(FoundryLocalSettings, env_prefix="FOUNDRY_LOCAL_", model_id="override-model-id")
+    settings = load_settings(FoundryLocalSettings, env_prefix="FOUNDRY_LOCAL_", model="override-model-id")

-    assert settings["model_id"] == "override-model-id"
-    assert settings["model_id"] != foundry_local_unit_test_env["FOUNDRY_LOCAL_MODEL_ID"]
+    assert settings["model"] == "override-model-id"
+    assert settings["model"] != foundry_local_unit_test_env["FOUNDRY_LOCAL_MODEL"]


 # Client Initialization Tests
@@ -59,9 +59,9 @@ def test_foundry_local_client_init(mock_foundry_local_manager: MagicMock) -> Non
        "agent_framework_foundry_local._foundry_local_client.FoundryLocalManager",
        return_value=mock_foundry_local_manager,
    ):
-        client = FoundryLocalClient(model_id="test-model-id")
+        client = FoundryLocalClient(model="test-model-id")

-        assert client.model_id == "test-model-id"
+        assert client.model == "test-model-id"
        assert client.manager is mock_foundry_local_manager
        assert isinstance(client, SupportsChatGetResponse)

@@ -72,7 +72,7 @@ def test_foundry_local_client_init_with_bootstrap_false(mock_foundry_local_manag
        "agent_framework_foundry_local._foundry_local_client.FoundryLocalManager",
        return_value=mock_foundry_local_manager,
    ) as mock_manager_class:
-        FoundryLocalClient(model_id="test-model-id", bootstrap=False)
+        FoundryLocalClient(model="test-model-id", bootstrap=False)

        mock_manager_class.assert_called_once_with(
            bootstrap=False,
@@ -86,7 +86,7 @@ def test_foundry_local_client_init_with_timeout(mock_foundry_local_manager: Magi
        "agent_framework_foundry_local._foundry_local_client.FoundryLocalManager",
        return_value=mock_foundry_local_manager,
    ) as mock_manager_class:
-        FoundryLocalClient(model_id="test-model-id", timeout=60.0)
+        FoundryLocalClient(model="test-model-id", timeout=60.0)

        mock_manager_class.assert_called_once_with(
            bootstrap=True,
@@ -105,7 +105,7 @@ def test_foundry_local_client_init_model_not_found(mock_foundry_local_manager: M
        ),
        pytest.raises(ValueError, match="not found in Foundry Local"),
    ):
-        FoundryLocalClient(model_id="unknown-model")
+        FoundryLocalClient(model="unknown-model")


 def test_foundry_local_client_uses_model_info_id(mock_foundry_local_manager: MagicMock) -> None:
@@ -118,9 +118,9 @@ def test_foundry_local_client_uses_model_info_id(mock_foundry_local_manager: Mag
        "agent_framework_foundry_local._foundry_local_client.FoundryLocalManager",
        return_value=mock_foundry_local_manager,
    ):
-        client = FoundryLocalClient(model_id="model-alias")
+        client = FoundryLocalClient(model="model-alias")

-        assert client.model_id == "resolved-model-id"
+        assert client.model == "resolved-model-id"


 def test_foundry_local_client_init_from_env(
@@ -133,7 +133,7 @@ def test_foundry_local_client_init_from_env(
    ):
        client = FoundryLocalClient()

-        assert client.model_id == foundry_local_unit_test_env["FOUNDRY_LOCAL_MODEL_ID"]
+        assert client.model == foundry_local_unit_test_env["FOUNDRY_LOCAL_MODEL"]


 def test_foundry_local_client_init_with_device(mock_foundry_local_manager: MagicMock) -> None:
@@ -144,7 +144,7 @@ def test_foundry_local_client_init_with_device(mock_foundry_local_manager: Magic
        "agent_framework_foundry_local._foundry_local_client.FoundryLocalManager",
        return_value=mock_foundry_local_manager,
    ):
-        FoundryLocalClient(model_id="test-model-id", device=DeviceType.CPU)
+        FoundryLocalClient(model="test-model-id", device=DeviceType.CPU)

        mock_foundry_local_manager.get_model_info.assert_called_once_with(
            alias_or_model_id="test-model-id",
@@ -173,7 +173,7 @@ def test_foundry_local_client_init_model_not_found_with_device(mock_foundry_loca
        ),
        pytest.raises(ValueError, match="unknown-model:GPU.*not found"),
    ):
-        FoundryLocalClient(model_id="unknown-model", device=DeviceType.GPU)
+        FoundryLocalClient(model="unknown-model", device=DeviceType.GPU)


 def test_foundry_local_client_init_with_prepare_model_false(mock_foundry_local_manager: MagicMock) -> None:
@@ -182,7 +182,7 @@ def test_foundry_local_client_init_with_prepare_model_false(mock_foundry_local_m
        "agent_framework_foundry_local._foundry_local_client.FoundryLocalManager",
        return_value=mock_foundry_local_manager,
    ):
-        FoundryLocalClient(model_id="test-model-id", prepare_model=False)
+        FoundryLocalClient(model="test-model-id", prepare_model=False)

        mock_foundry_local_manager.download_model.assert_not_called()
        mock_foundry_local_manager.load_model.assert_not_called()
@@ -194,7 +194,7 @@ def test_foundry_local_client_init_calls_download_and_load(mock_foundry_local_ma
        "agent_framework_foundry_local._foundry_local_client.FoundryLocalManager",
        return_value=mock_foundry_local_manager,
    ):
-        FoundryLocalClient(model_id="test-model-id")
+        FoundryLocalClient(model="test-model-id")

        mock_foundry_local_manager.download_model.assert_called_once_with(
            alias_or_model_id="test-model-id",