Add STORES_BY_DEFAULT ClassVar to skip redundant InMemoryHistoryProvider injection

Chat clients that store history server-side by default (OpenAI Responses API,
Azure AI Agent) now declare STORES_BY_DEFAULT = True. The agent checks this
during auto-injection and skips InMemoryHistoryProvider unless the user
explicitly sets store=False.

Author: eavanvalkenburg

python/packages/azure-ai-search/agent_framework_azure_ai_search/_context_provider.py

@@ -10,13 +10,12 @@
 
 import sys
 from collections.abc import Awaitable, Callable
-from typing import TYPE_CHECKING, Any, ClassVar, Literal
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypedDict
 
 from agent_framework import AGENT_FRAMEWORK_USER_AGENT, Message
 from agent_framework._logging import get_logger
-from agent_framework._pydantic import AFBaseSettings
 from agent_framework._sessions import AgentSession, BaseContextProvider, SessionContext
-from agent_framework._settings import load_settings
+from agent_framework._settings import SecretString, load_settings
 from agent_framework.exceptions import ServiceInitializationError
 from azure.core.credentials import AzureKeyCredential
 from azure.core.credentials_async import AsyncTokenCredential
@@ -42,54 +41,6 @@
     VectorizableTextQuery,
     VectorizedQuery,
 )
-from pydantic import SecretStr
-
-
-class AzureAISearchSettings(AFBaseSettings):
-    """Settings for Azure AI Search Context Provider with auto-loading from environment.
-
-    The settings are first loaded from environment variables with the prefix 'AZURE_SEARCH_'.
-    If the environment variables are not found, the settings can be loaded from a .env file.
-
-    Keyword Args:
-        endpoint: Azure AI Search endpoint URL.
-            Can be set via environment variable AZURE_SEARCH_ENDPOINT.
-        index_name: Name of the search index.
-            Can be set via environment variable AZURE_SEARCH_INDEX_NAME.
-        knowledge_base_name: Name of an existing Knowledge Base (for agentic mode).
-            Can be set via environment variable AZURE_SEARCH_KNOWLEDGE_BASE_NAME.
-        api_key: API key for authentication (optional, use managed identity if not provided).
-            Can be set via environment variable AZURE_SEARCH_API_KEY.
-        env_file_path: If provided, the .env settings are read from this file path location.
-        env_file_encoding: The encoding of the .env file, defaults to 'utf-8'.
-
-    Examples:
-        .. code-block:: python
-
-            from agent_framework_aisearch import AzureAISearchSettings
-
-            # Using environment variables
-            # Set AZURE_SEARCH_ENDPOINT=https://mysearch.search.windows.net
-            # Set AZURE_SEARCH_INDEX_NAME=my-index
-            settings = AzureAISearchSettings()
-
-            # Or passing parameters directly
-            settings = AzureAISearchSettings(
-                endpoint="https://mysearch.search.windows.net",
-                index_name="my-index",
-            )
-
-            # Or loading from a .env file
-            settings = AzureAISearchSettings(env_file_path="path/to/.env")
-    """
-
-    env_prefix: ClassVar[str] = "AZURE_SEARCH_"
-
-    endpoint: str | None = None
-    index_name: str | None = None
-    knowledge_base_name: str | None = None
-    api_key: SecretStr | None = None
-
 
 if TYPE_CHECKING:
     from agent_framework._agents import SupportsAgentRun
@@ -157,6 +108,29 @@ class AzureAISearchSettings(AFBaseSettings):
 _DEFAULT_AGENTIC_MESSAGE_HISTORY_COUNT = 10
 
 
+class AzureAISearchSettings(TypedDict, total=False):
+    """Settings for Azure AI Search Context Provider with auto-loading from environment.
+
+    The settings are first loaded from environment variables with the prefix 'AZURE_SEARCH_'.
+    If the environment variables are not found, the settings can be loaded from a .env file.
+
+    Keys:
+        endpoint: Azure AI Search endpoint URL.
+            Can be set via environment variable AZURE_SEARCH_ENDPOINT.
+        index_name: Name of the search index.
+            Can be set via environment variable AZURE_SEARCH_INDEX_NAME.
+        knowledge_base_name: Name of an existing Knowledge Base (for agentic mode).
+            Can be set via environment variable AZURE_SEARCH_KNOWLEDGE_BASE_NAME.
+        api_key: API key for authentication (optional, use managed identity if not provided).
+            Can be set via environment variable AZURE_SEARCH_API_KEY.
+    """
+
+    endpoint: str | None
+    index_name: str | None
+    knowledge_base_name: str | None
+    api_key: SecretString | None
+
+
 class AzureAISearchContextProvider(BaseContextProvider):
     """Azure AI Search context provider using the new BaseContextProvider hooks pattern.
 
@@ -220,10 +194,18 @@ def __init__(
         """
         super().__init__(source_id)
 
+        # Determine which fields are required based on mode
+        required: list[str | tuple[str, ...]] = ["endpoint"]
+        if mode == "semantic":
+            required.append("index_name")
+        elif mode == "agentic":
+            required.append(("index_name", "knowledge_base_name"))
+
         # Load settings from environment/file
         settings = load_settings(
             AzureAISearchSettings,
             env_prefix="AZURE_SEARCH_",
+            required_fields=required,
             endpoint=endpoint,
             index_name=index_name,
             knowledge_base_name=knowledge_base_name,
@@ -232,32 +214,11 @@ def __init__(
             env_file_encoding=env_file_encoding,
         )
 
-        if not settings.get("endpoint"):
+        if mode == "agentic" and settings.get("index_name") and not model_deployment_name:
             raise ServiceInitializationError(
-                "Azure AI Search endpoint is required. Set via 'endpoint' parameter "
-                "or 'AZURE_SEARCH_ENDPOINT' environment variable."
+                "model_deployment_name is required for agentic mode when creating Knowledge Base from index."
             )
 
-        if mode == "semantic":
-            if not settings.get("index_name"):
-                raise ServiceInitializationError(
-                    "Azure AI Search index name is required for semantic mode. "
-                    "Set via 'index_name' parameter or 'AZURE_SEARCH_INDEX_NAME' environment variable."
-                )
-        elif mode == "agentic":
-            if settings.get("index_name") and settings.get("knowledge_base_name"):
-                raise ServiceInitializationError(
-                    "For agentic mode, provide either 'index_name' OR 'knowledge_base_name', not both."
-                )
-            if not settings.get("index_name") and not settings.get("knowledge_base_name"):
-                raise ServiceInitializationError(
-                    "For agentic mode, provide either 'index_name' or 'knowledge_base_name'."
-                )
-            if settings.get("index_name") and not model_deployment_name:
-                raise ServiceInitializationError(
-                    "model_deployment_name is required for agentic mode when creating Knowledge Base from index."
-                )
-
         resolved_credential: AzureKeyCredential | AsyncTokenCredential
         if credential:
             resolved_credential = credential

python/packages/azure-ai-search/tests/test_aisearch_context_provider.py

@@ -7,7 +7,7 @@
 import pytest
 from agent_framework import Message
 from agent_framework._sessions import AgentSession, SessionContext
-from agent_framework.exceptions import ServiceInitializationError
+from agent_framework.exceptions import ServiceInitializationError, SettingNotFoundError
 
 from agent_framework_azure_ai_search._context_provider import AzureAISearchContextProvider
 
@@ -88,7 +88,7 @@ def test_source_id_set(self) -> None:
         assert provider.source_id == "my-source"
 
     def test_missing_endpoint_raises(self) -> None:
-        with patch.dict(os.environ, {}, clear=True), pytest.raises(ServiceInitializationError, match="endpoint"):
+        with patch.dict(os.environ, {}, clear=True), pytest.raises(SettingNotFoundError, match="endpoint"):
             AzureAISearchContextProvider(
                 source_id="s",
                 endpoint=None,
@@ -97,7 +97,7 @@ def test_missing_endpoint_raises(self) -> None:
             )
 
     def test_missing_index_name_semantic_raises(self) -> None:
-        with pytest.raises(ServiceInitializationError, match="index name"):
+        with pytest.raises(SettingNotFoundError, match="index_name"):
             AzureAISearchContextProvider(
                 source_id="s",
                 endpoint="https://test.search.windows.net",
@@ -124,7 +124,7 @@ class TestInitAgenticValidation:
     """Initialization validation tests for agentic mode."""
 
     def test_both_index_and_kb_raises(self) -> None:
-        with pytest.raises(ServiceInitializationError, match="not both"):
+        with pytest.raises(SettingNotFoundError, match="multiple were set"):
             AzureAISearchContextProvider(
                 source_id="s",
                 endpoint="https://test.search.windows.net",
@@ -137,7 +137,7 @@ def test_both_index_and_kb_raises(self) -> None:
             )
 
     def test_neither_index_nor_kb_raises(self) -> None:
-        with pytest.raises(ServiceInitializationError, match="provide either"):
+        with pytest.raises(SettingNotFoundError, match="none was set"):
             AzureAISearchContextProvider(
                 source_id="s",
                 endpoint="https://test.search.windows.net",

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

@@ -210,6 +210,7 @@ class AzureAIAgentClient(
     """Azure AI Agent Chat client with middleware, telemetry, and function invocation support."""
 
     OTEL_PROVIDER_NAME: ClassVar[str] = "azure.ai"  # type: ignore[reportIncompatibleVariableOverride, misc]
+    STORES_BY_DEFAULT: ClassVar[bool] = True  # type: ignore[reportIncompatibleVariableOverride, misc]
 
     # region Hosted Tool Factory Methods
 

python/packages/core/agent_framework/_agents.py

@@ -67,14 +67,9 @@
 if TYPE_CHECKING:
     from ._types import ChatOptions
 
-
-ResponseModelT = TypeVar("ResponseModelT", bound=BaseModel | None, default=None, covariant=True)
-ResponseModelBoundT = TypeVar("ResponseModelBoundT", bound=BaseModel)
-
-
 logger = get_logger("agent_framework")
 
-ThreadTypeT = TypeVar("ThreadTypeT", bound="AgentSession")
+ResponseModelBoundT = TypeVar("ResponseModelBoundT", bound=BaseModel)
 OptionsCoT = TypeVar(
     "OptionsCoT",
     bound=TypedDict,  # type: ignore[valid-type]
@@ -978,6 +973,10 @@ async def _prepare_run_context(
             and not session.service_session_id
             and not opts.get("conversation_id")
             and not opts.get("store")
+            and not (
+                getattr(self.client, "STORES_BY_DEFAULT", False)
+                and opts.get("store") is not False
+            )
         ):
             self.context_providers.append(InMemoryHistoryProvider("memory"))
 

python/packages/core/agent_framework/_clients.py

@@ -262,7 +262,15 @@ async def _stream():
 
     OTEL_PROVIDER_NAME: ClassVar[str] = "unknown"
     DEFAULT_EXCLUDE: ClassVar[set[str]] = {"additional_properties"}
-    # This is used for OTel setup, should be overridden in subclasses
+    STORES_BY_DEFAULT: ClassVar[bool] = False
+    """Whether this client stores conversation history server-side by default.
+
+    Clients that use server-side storage (e.g., OpenAI Responses API with ``store=True``
+    as default, Azure AI Agent threads) should override this to ``True``.
+    When ``True``, the agent skips auto-injecting ``InMemoryHistoryProvider`` unless the
+    user explicitly sets ``store=False``.
+    """
+    # OTEL_PROVIDER_NAME is used for OTel setup, should be overridden in subclasses
 
     def __init__(
         self,

python/packages/core/agent_framework/_settings.py

@@ -12,14 +12,17 @@
     class MySettings(TypedDict, total=False):
         api_key: str | None  # optional — resolves to None if not set
         model_id: str | None  # optional by default
+        source_a: str | None
+        source_b: str | None
 
 
-    # Make model_id required at call time:
+    # Make model_id required; require exactly one of source_a / source_b:
     settings = load_settings(
         MySettings,
         env_prefix="MY_APP_",
-        required_fields=["model_id"],
+        required_fields=["model_id", ("source_a", "source_b")],
         model_id="gpt-4",
+        source_a="value",
     )
     settings["api_key"]  # type-checked dict access
     settings["model_id"]  # str | None per type, but guaranteed not None at runtime
@@ -167,7 +170,7 @@ def load_settings(
     env_prefix: str = "",
     env_file_path: str | None = None,
     env_file_encoding: str | None = None,
-    required_fields: Sequence[str] | None = None,
+    required_fields: Sequence[str | tuple[str, ...]] | None = None,
     **overrides: Any,
 ) -> SettingsT:
     """Load settings from environment variables, a ``.env`` file, and explicit overrides.
@@ -181,26 +184,28 @@ def load_settings(
     4. Default values — fields with class-level defaults on the TypedDict, or
        ``None`` for optional fields.
 
-    Fields listed in *required_fields* are validated after resolution.  If any
-    required field resolves to ``None``, a ``SettingNotFoundError`` is raised.
-    This allows callers to decide which fields are required based on runtime
-    context (e.g. ``endpoint`` is only required when no pre-built client is
-    provided).
+    Entries in *required_fields* are validated after resolution:
+
+    - A **string** entry means the field must resolve to a non-``None`` value.
+    - A **tuple** entry means exactly one field in the group must be non-``None``
+      (mutually exclusive).
 
     Args:
         settings_type: A ``TypedDict`` class describing the settings schema.
         env_prefix: Prefix for environment variable lookup (e.g. ``"OPENAI_"``).
         env_file_path: Path to ``.env`` file.  Defaults to ``".env"`` when omitted.
         env_file_encoding: Encoding for reading the ``.env`` file.  Defaults to ``"utf-8"``.
-        required_fields: Field names that must resolve to a non-``None`` value.
+        required_fields: Field names (``str``) that must resolve to a non-``None``
+            value, or tuples of field names where exactly one must be set.
         **overrides: Field values.  ``None`` values are ignored so that callers can
             forward optional parameters without masking env-var / default resolution.
 
     Returns:
         A populated dict matching *settings_type*.
 
     Raises:
-        SettingNotFoundError: If a required field could not be resolved from any source.
+        SettingNotFoundError: If a required field could not be resolved from any
+            source, or if a mutually exclusive constraint is violated.
         ServiceInitializationError: If an override value has an incompatible type.
     """
     encoding = env_file_encoding or "utf-8"
@@ -215,7 +220,6 @@ def load_settings(
 
     # Get field type hints from the TypedDict
     hints = get_type_hints(settings_type)
-    required: set[str] = set(required_fields) if required_fields else set()
 
     result: dict[str, Any] = {}
     for field_name, field_type in hints.items():
@@ -249,14 +253,30 @@ def load_settings(
             result[field_name] = None
 
     # Validate required fields after all resolution
-    if required:
-        for field_name in required:
-            if result.get(field_name) is None:
-                env_var_name = f"{env_prefix}{field_name.upper()}"
-                raise SettingNotFoundError(
-                    f"Required setting '{field_name}' was not provided. "
-                    f"Set it via the '{field_name}' parameter or the "
-                    f"'{env_var_name}' environment variable."
-                )
+    if required_fields:
+        for entry in required_fields:
+            if isinstance(entry, str):
+                # Single required field
+                if result.get(entry) is None:
+                    env_var_name = f"{env_prefix}{entry.upper()}"
+                    raise SettingNotFoundError(
+                        f"Required setting '{entry}' was not provided. "
+                        f"Set it via the '{entry}' parameter or the "
+                        f"'{env_var_name}' environment variable."
+                    )
+            else:
+                # Mutually exclusive group — exactly one must be set
+                set_fields = [f for f in entry if result.get(f) is not None]
+                if len(set_fields) == 0:
+                    names = ", ".join(f"'{f}'" for f in entry)
+                    raise SettingNotFoundError(
+                        f"Exactly one of {names} must be provided, but none was set."
+                    )
+                if len(set_fields) > 1:
+                    all_names = ", ".join(f"'{f}'" for f in entry)
+                    set_names = ", ".join(f"'{f}'" for f in set_fields)
+                    raise SettingNotFoundError(
+                        f"Only one of {all_names} may be provided, but multiple were set: {set_names}."
+                    )
 
     return result  # type: ignore[return-value]

python/packages/core/agent_framework/openai/_responses_client.py

@@ -13,7 +13,7 @@
 )
 from datetime import datetime, timezone
 from itertools import chain
-from typing import TYPE_CHECKING, Any, Generic, Literal, NoReturn, TypedDict, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, NoReturn, TypedDict, cast
 
 from openai import AsyncOpenAI, BadRequestError
 from openai.types.responses.file_search_tool_param import FileSearchToolParam
@@ -238,6 +238,8 @@ class RawOpenAIResponsesClient(  # type: ignore[misc]
         Use ``OpenAIResponsesClient`` instead for a fully-featured client with all layers applied.
     """
 
+    STORES_BY_DEFAULT: ClassVar[bool] = True  # type: ignore[reportIncompatibleVariableOverride, misc]
+
     FILE_SEARCH_MAX_RESULTS: int = 50
 
     # region Inner Methods