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>

python/packages/foundry/tests/conftest.py

@@ -0,0 +1,78 @@
+# Copyright (c) Microsoft. All rights reserved.
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+from pytest import fixture
+
+
+@fixture
+def exclude_list(request: Any) -> list[str]:
+    """Fixture that returns a list of environment variables to exclude."""
+    return request.param if hasattr(request, "param") else []
+
+
+@fixture
+def override_env_param_dict(request: Any) -> dict[str, str]:
+    """Fixture that returns a dict of environment variables to override."""
+    return request.param if hasattr(request, "param") else {}
+
+
+@fixture()
+def foundry_unit_test_env(monkeypatch, exclude_list, override_env_param_dict):  # type: ignore
+    """Fixture to set environment variables for Foundry settings."""
+
+    if exclude_list is None:
+        exclude_list = []
+
+    if override_env_param_dict is None:
+        override_env_param_dict = {}
+
+    env_vars = {
+        "FOUNDRY_PROJECT_ENDPOINT": "https://test-project.services.ai.azure.com/",
+        "FOUNDRY_MODEL": "test-gpt-4o",
+    }
+
+    env_vars.update(override_env_param_dict)  # type: ignore
+
+    for key, value in env_vars.items():
+        if key in exclude_list:
+            monkeypatch.delenv(key, raising=False)  # type: ignore
+            continue
+        monkeypatch.setenv(key, value)  # type: ignore
+
+    return env_vars
+
+
+@fixture
+def mock_agents_client() -> MagicMock:
+    """Fixture that provides a mock AgentsClient."""
+    mock_client = MagicMock()
+
+    # Mock agents property
+    mock_client.create_agent = AsyncMock()
+    mock_client.delete_agent = AsyncMock()
+
+    # Mock agent creation response
+    mock_agent = MagicMock()
+    mock_agent.id = "test-agent-id"
+    mock_client.create_agent.return_value = mock_agent
+
+    # Mock threads property
+    mock_client.threads = MagicMock()
+    mock_client.threads.create = AsyncMock()
+    mock_client.messages.create = AsyncMock()
+
+    # Mock runs property
+    mock_client.runs = MagicMock()
+    mock_client.runs.list = AsyncMock()
+    mock_client.runs.cancel = AsyncMock()
+    mock_client.runs.stream = AsyncMock()
+    mock_client.runs.submit_tool_outputs_stream = AsyncMock()
+
+    return mock_client
+
+
+@fixture
+def mock_azure_credential() -> MagicMock:
+    """Fixture that provides a mock AsyncTokenCredential."""
+    return MagicMock()

python/packages/foundry/tests/test_foundry_agent.py

@@ -0,0 +1,374 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for FoundryAgentClient and FoundryAgent classes."""
+
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from agent_framework._tools import tool
+
+
+class TestRawFoundryAgentChatClient:
+    """Tests for RawFoundryAgentChatClient."""
+
+    def test_init_requires_agent_name(self) -> None:
+        """Test that agent_name is required."""
+        from agent_framework_foundry._foundry_agent_client import RawFoundryAgentChatClient
+
+        with pytest.raises(ValueError, match="Agent name is required"):
+            RawFoundryAgentChatClient(
+                project_client=MagicMock(),
+            )
+
+    def test_init_with_agent_name(self) -> None:
+        """Test construction with agent_name and project_client."""
+        from agent_framework_foundry._foundry_agent_client import RawFoundryAgentChatClient
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        client = RawFoundryAgentChatClient(
+            project_client=mock_project,
+            agent_name="test-agent",
+            agent_version="1.0",
+        )
+
+        assert client.agent_name == "test-agent"
+        assert client.agent_version == "1.0"
+
+    def test_get_agent_reference_with_version(self) -> None:
+        """Test agent reference includes version when provided."""
+        from agent_framework_foundry._foundry_agent_client import RawFoundryAgentChatClient
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        client = RawFoundryAgentChatClient(
+            project_client=mock_project,
+            agent_name="my-agent",
+            agent_version="2.0",
+        )
+
+        ref = client._get_agent_reference()
+        assert ref == {"name": "my-agent", "version": "2.0", "type": "agent_reference"}
+
+    def test_get_agent_reference_without_version(self) -> None:
+        """Test agent reference omits version for HostedAgents."""
+        from agent_framework_foundry._foundry_agent_client import RawFoundryAgentChatClient
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        client = RawFoundryAgentChatClient(
+            project_client=mock_project,
+            agent_name="hosted-agent",
+        )
+
+        ref = client._get_agent_reference()
+        assert ref == {"name": "hosted-agent", "type": "agent_reference"}
+        assert "version" not in ref
+
+    def test_as_agent_returns_foundry_agent_and_preserves_client_type(self) -> None:
+        """Test that as_agent() wraps the client in FoundryAgent using the same client class."""
+        from agent_framework_foundry._foundry_agent import FoundryAgent
+        from agent_framework_foundry._foundry_agent_client import RawFoundryAgentChatClient
+
+        class CustomClient(RawFoundryAgentChatClient):
+            pass
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        client = CustomClient(
+            project_client=mock_project,
+            agent_name="test-agent",
+            agent_version="1.0",
+        )
+
+        agent = client.as_agent(instructions="You are helpful.")
+
+        assert isinstance(agent, FoundryAgent)
+        assert agent.name == "test-agent"
+        assert isinstance(agent.client, CustomClient)
+        assert agent.client.project_client is mock_project
+        assert agent.client.agent_name == "test-agent"
+        assert agent.client.agent_version == "1.0"
+
+        named_agent = client.as_agent(name="display-name", instructions="You are helpful.")
+        assert named_agent.name == "display-name"
+        assert named_agent.client.agent_name == "test-agent"
+
+    async def test_prepare_options_validates_tools(self) -> None:
+        """Test that _prepare_options rejects non-FunctionTool objects."""
+        from agent_framework import Message
+
+        from agent_framework_foundry._foundry_agent_client import RawFoundryAgentChatClient
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        client = RawFoundryAgentChatClient(
+            project_client=mock_project,
+            agent_name="test-agent",
+        )
+
+        # A dict tool should be rejected
+        with pytest.raises(TypeError, match="Only FunctionTool objects are accepted"):
+            await client._prepare_options(
+                messages=[Message(role="user", contents="hi")],
+                options={"tools": [{"type": "function", "function": {"name": "bad"}}]},
+            )
+
+    async def test_prepare_options_accepts_function_tools(self) -> None:
+        """Test that _prepare_options accepts FunctionTool objects."""
+        from agent_framework import Message
+
+        from agent_framework_foundry._foundry_agent_client import RawFoundryAgentChatClient
+
+        mock_project = MagicMock()
+        mock_openai = MagicMock()
+        mock_project.get_openai_client.return_value = mock_openai
+
+        client = RawFoundryAgentChatClient(
+            project_client=mock_project,
+            agent_name="test-agent",
+        )
+
+        @tool(approval_mode="never_require")
+        def my_func() -> str:
+            """A test function."""
+            return "ok"
+
+        # Should not raise — patch the parent's _prepare_options
+        with patch(
+            "agent_framework_openai._chat_client.RawOpenAIChatClient._prepare_options",
+            new_callable=AsyncMock,
+            return_value={},
+        ):
+            result = await client._prepare_options(
+                messages=[Message(role="user", contents="hi")],
+                options={"tools": [my_func]},
+            )
+            assert "extra_body" in result
+            assert result["extra_body"]["agent_reference"]["name"] == "test-agent"
+
+    def test_check_model_presence_is_noop(self) -> None:
+        """Test that _check_model_presence does nothing (model is on service)."""
+        from agent_framework_foundry._foundry_agent_client import RawFoundryAgentChatClient
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        client = RawFoundryAgentChatClient(
+            project_client=mock_project,
+            agent_name="test-agent",
+        )
+
+        options: dict[str, Any] = {}
+        client._check_model_presence(options)
+        assert "model" not in options
+
+
+class TestFoundryAgentChatClient:
+    """Tests for _FoundryAgentChatClient (full middleware)."""
+
+    def test_init(self) -> None:
+        """Test construction of the full-middleware client."""
+        from agent_framework_foundry._foundry_agent_client import _FoundryAgentChatClient
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        client = _FoundryAgentChatClient(
+            project_client=mock_project,
+            agent_name="test-agent",
+            agent_version="1.0",
+        )
+
+        assert client.agent_name == "test-agent"
+
+
+class TestRawFoundryAgent:
+    """Tests for RawFoundryAgent."""
+
+    def test_init_creates_client(self) -> None:
+        """Test that RawFoundryAgent creates a client internally."""
+        from agent_framework_foundry._foundry_agent import RawFoundryAgent
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        agent = RawFoundryAgent(
+            project_client=mock_project,
+            agent_name="test-agent",
+            agent_version="1.0",
+        )
+
+        assert agent.client is not None
+        assert agent.client.agent_name == "test-agent"
+
+    def test_init_with_custom_client_type(self) -> None:
+        """Test that client_type parameter is respected."""
+        from agent_framework_foundry._foundry_agent import RawFoundryAgent
+        from agent_framework_foundry._foundry_agent_client import RawFoundryAgentChatClient
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        agent = RawFoundryAgent(
+            project_client=mock_project,
+            agent_name="test-agent",
+            client_type=RawFoundryAgentChatClient,
+        )
+
+        assert isinstance(agent.client, RawFoundryAgentChatClient)
+
+    def test_init_rejects_invalid_client_type(self) -> None:
+        """Test that invalid client_type raises TypeError."""
+        from agent_framework_foundry._foundry_agent import RawFoundryAgent
+
+        with pytest.raises(TypeError, match="must be a subclass of RawFoundryAgentChatClient"):
+            RawFoundryAgent(
+                project_client=MagicMock(),
+                agent_name="test-agent",
+                client_type=object,  # type: ignore[arg-type]
+            )
+
+    def test_init_with_function_tools(self) -> None:
+        """Test that FunctionTool and callables are accepted."""
+        from agent_framework_foundry._foundry_agent import RawFoundryAgent
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        @tool(approval_mode="never_require")
+        def my_func() -> str:
+            """A test function."""
+            return "ok"
+
+        agent = RawFoundryAgent(
+            project_client=mock_project,
+            agent_name="test-agent",
+            tools=[my_func],
+        )
+
+        assert agent.default_options.get("tools") is not None
+
+
+class TestFoundryAgent:
+    """Tests for FoundryAgent (full middleware)."""
+
+    def test_init(self) -> None:
+        """Test construction of the full-middleware agent."""
+        from agent_framework_foundry._foundry_agent import FoundryAgent
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        agent = FoundryAgent(
+            project_client=mock_project,
+            agent_name="test-agent",
+            agent_version="1.0",
+        )
+
+        assert agent.client is not None
+        assert agent.client.agent_name == "test-agent"
+
+    def test_init_with_middleware(self) -> None:
+        """Test that agent-level middleware is accepted."""
+        from agent_framework import ChatContext, ChatMiddleware
+
+        from agent_framework_foundry._foundry_agent import FoundryAgent
+
+        mock_project = MagicMock()
+        mock_project.get_openai_client.return_value = MagicMock()
+
+        class MyMiddleware(ChatMiddleware):
+            async def process(self, context: ChatContext) -> None:
+                pass
+
+        agent = FoundryAgent(
+            project_client=mock_project,
+            agent_name="test-agent",
+            middleware=[MyMiddleware()],
+        )
+
+        assert agent.client is not None
+
+
+class TestFoundryChatClientToolMethods:
+    """Tests for RawFoundryChatClient tool factory methods."""
+
+    def test_get_code_interpreter_tool(self) -> None:
+        """Test code interpreter tool creation."""
+        from agent_framework_foundry._foundry_chat_client import RawFoundryChatClient
+
+        tool_obj = RawFoundryChatClient.get_code_interpreter_tool()
+        assert tool_obj is not None
+
+    def test_get_code_interpreter_tool_with_file_ids(self) -> None:
+        """Test code interpreter tool with file IDs."""
+        from agent_framework_foundry._foundry_chat_client import RawFoundryChatClient
+
+        tool_obj = RawFoundryChatClient.get_code_interpreter_tool(file_ids=["file-abc123"])
+        assert tool_obj is not None
+
+    def test_get_file_search_tool(self) -> None:
+        """Test file search tool creation."""
+        from agent_framework_foundry._foundry_chat_client import RawFoundryChatClient
+
+        tool_obj = RawFoundryChatClient.get_file_search_tool(vector_store_ids=["vs_abc123"])
+        assert tool_obj is not None
+
+    def test_get_file_search_tool_requires_vector_store_ids(self) -> None:
+        """Test that empty vector_store_ids raises ValueError."""
+        from agent_framework_foundry._foundry_chat_client import RawFoundryChatClient
+
+        with pytest.raises(ValueError, match="vector_store_ids"):
+            RawFoundryChatClient.get_file_search_tool(vector_store_ids=[])
+
+    def test_get_web_search_tool(self) -> None:
+        """Test web search tool creation."""
+        from agent_framework_foundry._foundry_chat_client import RawFoundryChatClient
+
+        tool_obj = RawFoundryChatClient.get_web_search_tool()
+        assert tool_obj is not None
+
+    def test_get_web_search_tool_with_location(self) -> None:
+        """Test web search tool with user location."""
+        from agent_framework_foundry._foundry_chat_client import RawFoundryChatClient
+
+        tool_obj = RawFoundryChatClient.get_web_search_tool(
+            user_location={"city": "Seattle", "country": "US"},
+            search_context_size="high",
+        )
+        assert tool_obj is not None
+
+    def test_get_image_generation_tool(self) -> None:
+        """Test image generation tool creation."""
+        from agent_framework_foundry._foundry_chat_client import RawFoundryChatClient
+
+        tool_obj = RawFoundryChatClient.get_image_generation_tool()
+        assert tool_obj is not None
+
+    def test_get_mcp_tool(self) -> None:
+        """Test MCP tool creation."""
+        from agent_framework_foundry._foundry_chat_client import RawFoundryChatClient
+
+        tool_obj = RawFoundryChatClient.get_mcp_tool(
+            name="my_mcp",
+            url="https://mcp.example.com",
+        )
+        assert tool_obj is not None
+
+    def test_get_mcp_tool_with_connection_id(self) -> None:
+        """Test MCP tool with project connection ID."""
+        from agent_framework_foundry._foundry_chat_client import RawFoundryChatClient
+
+        tool_obj = RawFoundryChatClient.get_mcp_tool(
+            name="github_mcp",
+            project_connection_id="conn_abc123",
+            description="GitHub MCP via Foundry",
+        )
+        assert tool_obj is not None

python/packages/foundry/tests/test_foundry_memory_provider.py

@@ -0,0 +1,507 @@
+# Copyright (c) Microsoft. All rights reserved.
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import os
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
+from agent_framework import AGENT_FRAMEWORK_USER_AGENT, AgentResponse, Message
+from agent_framework._sessions import AgentSession, SessionContext
+
+from agent_framework_foundry._foundry_memory_provider import FoundryMemoryProvider
+
+
+@pytest.fixture
+def mock_project_client() -> AsyncMock:
+    """Create a mock AIProjectClient."""
+    mock_client = AsyncMock()
+    mock_client.beta = AsyncMock()
+    mock_client.beta.memory_stores = AsyncMock()
+    mock_client.beta.memory_stores.search_memories = AsyncMock()
+    mock_client.beta.memory_stores.begin_update_memories = AsyncMock()
+    mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+    mock_client.__aexit__ = AsyncMock()
+    return mock_client
+
+
+@pytest.fixture
+def mock_credential() -> Mock:
+    """Create a mock Azure credential."""
+    return Mock()
+
+
+# -- Initialization tests ------------------------------------------------------
+
+
+class TestInit:
+    """Test FoundryMemoryProvider initialization."""
+
+    def test_init_with_all_params(self, mock_project_client: AsyncMock) -> None:
+        provider = FoundryMemoryProvider(
+            source_id="custom_source",
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+            context_prompt="Custom prompt",
+            update_delay=60,
+        )
+        assert provider.source_id == "custom_source"
+        assert provider.project_client is mock_project_client
+        assert provider.memory_store_name == "test_store"
+        assert provider.scope == "user_123"
+        assert provider.context_prompt == "Custom prompt"
+        assert provider.update_delay == 60
+
+    def test_init_default_source_id(self, mock_project_client: AsyncMock) -> None:
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        assert provider.source_id == FoundryMemoryProvider.DEFAULT_SOURCE_ID
+
+    def test_init_default_context_prompt(self, mock_project_client: AsyncMock) -> None:
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        assert provider.context_prompt == FoundryMemoryProvider.DEFAULT_CONTEXT_PROMPT
+
+    def test_init_default_update_delay(self, mock_project_client: AsyncMock) -> None:
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        assert provider.update_delay == 300
+
+    def test_init_with_project_endpoint_and_credential(
+        self, mock_project_client: AsyncMock, mock_credential: Mock
+    ) -> None:
+        with patch("agent_framework_foundry._foundry_memory_provider.AIProjectClient") as mock_ai_project_client:
+            mock_ai_project_client.return_value = mock_project_client
+            provider = FoundryMemoryProvider(
+                project_endpoint="https://test.project.endpoint",
+                credential=mock_credential,  # type: ignore[arg-type]
+                allow_preview=True,
+                memory_store_name="test_store",
+                scope="user_123",
+            )
+            assert provider.project_client is mock_project_client
+            mock_ai_project_client.assert_called_once_with(
+                endpoint="https://test.project.endpoint",
+                credential=mock_credential,
+                allow_preview=True,
+                user_agent=AGENT_FRAMEWORK_USER_AGENT,
+            )
+
+    def test_init_requires_project_endpoint_without_project_client(self) -> None:
+        with (
+            patch("agent_framework_foundry._foundry_memory_provider.load_settings") as mock_load_settings,
+            patch.dict(os.environ, {}, clear=True),
+            pytest.raises(ValueError, match="project endpoint is required"),
+        ):
+            mock_load_settings.return_value = {"project_endpoint": None}
+            FoundryMemoryProvider(
+                memory_store_name="test_store",
+                scope="user_123",
+            )
+
+    def test_init_requires_credential_without_project_client(self) -> None:
+        with pytest.raises(ValueError, match="Azure credential is required"):
+            FoundryMemoryProvider(
+                project_endpoint="https://test.project.endpoint",
+                memory_store_name="test_store",
+                scope="user_123",
+            )
+
+    def test_init_requires_memory_store_name(self, mock_project_client: AsyncMock) -> None:
+        with pytest.raises(ValueError, match="memory_store_name is required"):
+            FoundryMemoryProvider(
+                project_client=mock_project_client,
+                memory_store_name="",
+                scope="user_123",
+            )
+
+    def test_init_requires_scope(self, mock_project_client: AsyncMock) -> None:
+        with pytest.raises(ValueError, match="scope is required"):
+            FoundryMemoryProvider(
+                project_client=mock_project_client,
+                memory_store_name="test_store",
+                scope="",
+            )
+
+
+# -- before_run tests ----------------------------------------------------------
+
+
+class TestBeforeRun:
+    """Test before_run hook."""
+
+    async def test_retrieves_static_memories_on_first_run(self, mock_project_client: AsyncMock) -> None:
+        """First call retrieves static (user profile) memories."""
+        mem1 = Mock()
+        mem1.memory_item.content = "User prefers Python"
+        mem2 = Mock()
+        mem2.memory_item.content = "User is based in Seattle"
+        mock_search_result = Mock()
+        mock_search_result.memories = [mem1, mem2]
+        mock_project_client.beta.memory_stores.search_memories.return_value = mock_search_result
+
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(input_messages=[Message(role="user", text="Hello")], session_id="s1")
+
+        await provider.before_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+
+        # Should call search_memories twice: once for static, once for contextual
+        assert mock_project_client.beta.memory_stores.search_memories.call_count == 2
+        # Static memories should be cached
+        assert len(session.state[provider.source_id]["static_memories"]) == 2
+        assert session.state[provider.source_id]["initialized"] is True
+
+    async def test_contextual_memories_added_to_context(self, mock_project_client: AsyncMock) -> None:
+        """Contextual search returns memories → messages added to context with prompt."""
+        # Mock static search (first call)
+        static_mem = Mock()
+        static_mem.memory_item.content = "User prefers Python"
+        static_result = Mock()
+        static_result.memories = [static_mem]
+
+        # Mock contextual search (second call)
+        contextual_mem = Mock()
+        contextual_mem.memory_item.content = "Last discussed async patterns"
+        contextual_result = Mock()
+        contextual_result.memories = [contextual_mem]
+        contextual_result.search_id = "search-123"
+
+        mock_project_client.beta.memory_stores.search_memories.side_effect = [static_result, contextual_result]
+
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(input_messages=[Message(role="user", text="Hello")], session_id="s1")
+
+        await provider.before_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+
+        # Check that memories were added to context
+        assert provider.source_id in ctx.context_messages
+        added = ctx.context_messages[provider.source_id]
+        assert len(added) == 1
+        assert "User prefers Python" in added[0].text  # type: ignore[operator]
+        assert "Last discussed async patterns" in added[0].text  # type: ignore[operator]
+        assert provider.context_prompt in added[0].text  # type: ignore[operator]
+        assert session.state[provider.source_id]["previous_search_id"] == "search-123"
+
+    async def test_empty_input_skips_contextual_search(self, mock_project_client: AsyncMock) -> None:
+        """Empty input messages → only static search performed, no contextual search."""
+        static_result = Mock()
+        static_result.memories = []
+        mock_project_client.beta.memory_stores.search_memories.return_value = static_result
+
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(input_messages=[Message(role="user", text="")], session_id="s1")
+
+        await provider.before_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+
+        # Should only call search_memories once for static memories
+        assert mock_project_client.beta.memory_stores.search_memories.call_count == 1
+        assert provider.source_id not in ctx.context_messages
+
+    async def test_empty_search_results_no_messages(self, mock_project_client: AsyncMock) -> None:
+        """Empty search results → no messages added."""
+        mock_search_result = Mock()
+        mock_search_result.memories = []
+        mock_project_client.beta.memory_stores.search_memories.return_value = mock_search_result
+
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(input_messages=[Message(role="user", text="test")], session_id="s1")
+
+        await provider.before_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+
+        assert provider.source_id not in ctx.context_messages
+
+    async def test_static_memories_only_retrieved_once(self, mock_project_client: AsyncMock) -> None:
+        """Static memories are only retrieved on the first call."""
+        static_mem = Mock()
+        static_mem.memory_item.content = "Static memory"
+        static_result = Mock()
+        static_result.memories = [static_mem]
+        contextual_result = Mock()
+        contextual_result.memories = []
+
+        mock_project_client.beta.memory_stores.search_memories.side_effect = [static_result, contextual_result]
+
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(input_messages=[Message(role="user", text="Hello")], session_id="s1")
+
+        # First call
+        await provider.before_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+        assert mock_project_client.beta.memory_stores.search_memories.call_count == 2
+
+        # Reset mock for second call
+        mock_project_client.beta.memory_stores.search_memories.reset_mock()
+        contextual_result2 = Mock()
+        contextual_result2.memories = []
+        mock_project_client.beta.memory_stores.search_memories.return_value = contextual_result2
+
+        # Second call - should only search contextual, not static
+        ctx2 = SessionContext(input_messages=[Message(role="user", text="World")], session_id="s1")
+        await provider.before_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx2, state=session.state.setdefault(provider.source_id, {})
+        )
+        assert mock_project_client.beta.memory_stores.search_memories.call_count == 1
+
+    async def test_handles_search_exception_gracefully(self, mock_project_client: AsyncMock) -> None:
+        """Search exception is logged but doesn't fail the operation."""
+        mock_project_client.beta.memory_stores.search_memories.side_effect = Exception("API error")
+
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(input_messages=[Message(role="user", text="Hello")], session_id="s1")
+
+        # Should not raise exception
+        await provider.before_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+
+        # No memories added
+        assert provider.source_id not in ctx.context_messages
+
+
+# -- after_run tests -----------------------------------------------------------
+
+
+class TestAfterRun:
+    """Test after_run hook."""
+
+    async def test_stores_input_and_response(self, mock_project_client: AsyncMock) -> None:
+        """Stores input+response messages via begin_update_memories."""
+        mock_poller = Mock()
+        mock_poller.update_id = "update-456"
+        mock_project_client.beta.memory_stores.begin_update_memories.return_value = mock_poller
+
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(input_messages=[Message(role="user", text="question")], session_id="s1")
+        ctx._response = AgentResponse(messages=[Message(role="assistant", text="answer")])
+
+        await provider.after_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+
+        mock_project_client.beta.memory_stores.begin_update_memories.assert_awaited_once()
+        call_kwargs = mock_project_client.beta.memory_stores.begin_update_memories.call_args.kwargs
+        assert call_kwargs["name"] == "test_store"
+        assert call_kwargs["scope"] == "user_123"
+        assert len(call_kwargs["items"]) == 2
+        assert call_kwargs["items"][0]["content"] == "question"
+        assert call_kwargs["items"][1]["content"] == "answer"
+        assert session.state[provider.source_id]["previous_update_id"] == "update-456"
+
+    async def test_only_stores_user_assistant_system(self, mock_project_client: AsyncMock) -> None:
+        """Only stores user/assistant/system messages with text."""
+        mock_poller = Mock()
+        mock_project_client.beta.memory_stores.begin_update_memories.return_value = mock_poller
+
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(
+            input_messages=[
+                Message(role="user", text="hello"),
+                Message(role="tool", text="tool output"),
+            ],
+            session_id="s1",
+        )
+        ctx._response = AgentResponse(messages=[Message(role="assistant", text="reply")])
+
+        await provider.after_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+
+        call_kwargs = mock_project_client.beta.memory_stores.begin_update_memories.call_args.kwargs
+        items = call_kwargs["items"]
+        assert len(items) == 2
+        assert items[0]["content"] == "hello"
+        assert items[1]["content"] == "reply"
+
+    async def test_skips_empty_messages(self, mock_project_client: AsyncMock) -> None:
+        """Skips messages with empty text."""
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(
+            input_messages=[
+                Message(role="user", text=""),
+                Message(role="user", text="   "),
+            ],
+            session_id="s1",
+        )
+        ctx._response = AgentResponse(messages=[])
+
+        await provider.after_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+
+        mock_project_client.beta.memory_stores.begin_update_memories.assert_not_awaited()
+
+    async def test_uses_configured_update_delay(self, mock_project_client: AsyncMock) -> None:
+        """Uses the configured update_delay parameter."""
+        mock_poller = Mock()
+        mock_project_client.beta.memory_stores.begin_update_memories.return_value = mock_poller
+
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+            update_delay=60,
+        )
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(input_messages=[Message(role="user", text="hi")], session_id="s1")
+        ctx._response = AgentResponse(messages=[Message(role="assistant", text="hey")])
+
+        await provider.after_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+
+        call_kwargs = mock_project_client.beta.memory_stores.begin_update_memories.call_args.kwargs
+        assert call_kwargs["update_delay"] == 60
+
+    async def test_uses_previous_update_id_for_incremental_updates(self, mock_project_client: AsyncMock) -> None:
+        """Uses previous_update_id for incremental updates."""
+        mock_poller1 = Mock()
+        mock_poller1.update_id = "update-1"
+        mock_poller2 = Mock()
+        mock_poller2.update_id = "update-2"
+
+        mock_project_client.beta.memory_stores.begin_update_memories.side_effect = [mock_poller1, mock_poller2]
+
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        session = AgentSession(session_id="test-session")
+        ctx1 = SessionContext(input_messages=[Message(role="user", text="first")], session_id="s1")
+        ctx1._response = AgentResponse(messages=[Message(role="assistant", text="response1")])
+
+        # First update
+        await provider.after_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx1, state=session.state.setdefault(provider.source_id, {})
+        )
+        assert session.state[provider.source_id]["previous_update_id"] == "update-1"
+
+        # Second update should use previous_update_id
+        ctx2 = SessionContext(input_messages=[Message(role="user", text="second")], session_id="s1")
+        ctx2._response = AgentResponse(messages=[Message(role="assistant", text="response2")])
+
+        await provider.after_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx2, state=session.state.setdefault(provider.source_id, {})
+        )
+
+        call_kwargs = mock_project_client.beta.memory_stores.begin_update_memories.call_args.kwargs
+        assert call_kwargs["previous_update_id"] == "update-1"
+        assert session.state[provider.source_id]["previous_update_id"] == "update-2"
+
+    async def test_handles_update_exception_gracefully(self, mock_project_client: AsyncMock) -> None:
+        """Update exception is logged but doesn't fail the operation."""
+        mock_project_client.beta.memory_stores.begin_update_memories.side_effect = Exception("API error")
+
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        session = AgentSession(session_id="test-session")
+        ctx = SessionContext(input_messages=[Message(role="user", text="hi")], session_id="s1")
+        ctx._response = AgentResponse(messages=[Message(role="assistant", text="hey")])
+
+        # Should not raise exception
+        await provider.after_run(  # type: ignore[arg-type]
+            agent=None, session=session, context=ctx, state=session.state.setdefault(provider.source_id, {})
+        )
+
+
+# -- Context manager tests -----------------------------------------------------
+
+
+class TestContextManager:
+    """Test __aenter__/__aexit__ delegation."""
+
+    async def test_aenter_delegates_to_client(self, mock_project_client: AsyncMock) -> None:
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        result = await provider.__aenter__()
+        assert result is provider
+        mock_project_client.__aenter__.assert_awaited_once()
+
+    async def test_aexit_delegates_to_client(self, mock_project_client: AsyncMock) -> None:
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        await provider.__aexit__(None, None, None)
+        mock_project_client.__aexit__.assert_awaited_once()
+
+    async def test_async_with_syntax(self, mock_project_client: AsyncMock) -> None:
+        provider = FoundryMemoryProvider(
+            project_client=mock_project_client,
+            memory_store_name="test_store",
+            scope="user_123",
+        )
+        async with provider as p:
+            assert p is provider