Python: Support stable + preview Azure AI Search (Foundry IQ) API versions

python/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **agent-framework-azure-ai-search**: Support the stable/GA (`azure-search-documents` `12.0.0`, api-version `2026-04-01`) and preview (`12.1.0b1`, api-version `2026-05-01-preview`) Azure AI Search SDKs across semantic and agentic modes. Bump the dependency to `>=12.0.0,<13`, add an `api_version` parameter plus `STABLE_API_VERSION`/`PREVIEW_API_VERSION` constants, and auto-detect preview-only agentic features (output mode, low/medium reasoning effort) with actionable errors on the stable SDK.
+
 ## [1.9.0] - 2026-06-18
 
 ### Added

python/packages/azure-ai-search/AGENTS.md

@@ -7,6 +7,31 @@ Integration with Azure AI Search for RAG (Retrieval-Augmented Generation).
 - **`AzureAISearchContextProvider`** - Context provider that retrieves relevant documents from Azure AI Search
 - **`AzureAISearchSettings`** - Pydantic settings for Azure AI Search configuration
 
+## Constants
+
+- **`STABLE_API_VERSION`** (`"2026-04-01"`) - data-plane REST api-version of the stable/GA SDK
+- **`PREVIEW_API_VERSION`** (`"2026-05-01-preview"`) - data-plane REST api-version of the preview SDK
+
+## API versions: stable vs preview
+
+The package depends on `azure-search-documents>=12.0.0,<13`, which spans both channels:
+
+| Channel | Install | SDK | Default REST `api-version` |
+| --- | --- | --- | --- |
+| **Stable / GA** | `pip install azure-search-documents` | `12.0.0` | `2026-04-01` |
+| **Preview** | `pip install --pre azure-search-documents` | `12.1.0b1` | `2026-05-01-preview` |
+
+`AzureAISearchContextProvider(..., api_version=...)` forwards the api-version to the
+`SearchClient`, `SearchIndexClient`, and `KnowledgeBaseRetrievalClient`. When `api_version`
+is `None` (default), the installed SDK chooses its own default.
+
+Capability gating is auto-detected via `_preview_features_active()`, which requires **both**
+the preview SDK (`_preview_agentic_features_available`) **and** a preview `api_version` (a
+pinned stable api-version such as `2026-04-01` uses the GA wire and disables preview fields).
+Agentic **output mode** (`answer_synthesis`) and **extended reasoning effort** (`low`/`medium`)
+are preview-only; otherwise the provider omits them (extractive + minimal) and raises an
+actionable `ValueError` if they are explicitly requested. Semantic mode is unaffected.
+
 ## Usage
 
 ```python

python/packages/azure-ai-search/README.md

@@ -13,6 +13,29 @@ The Azure AI Search integration provides context providers for RAG (Retrieval Au
 - **Semantic Mode**: Fast hybrid search (vector + keyword) with semantic ranking
 - **Agentic Mode**: Multi-hop reasoning using Knowledge Bases for complex queries
 
+### API versions: stable vs preview
+
+The integration follows the `azure-search-documents` SDK's stable/preview channels:
+
+| Channel | Install | Default REST `api-version` |
+| --- | --- | --- |
+| **Stable** | `pip install azure-search-documents` (`>=12.0.0`) | `2026-04-01` |
+| **Preview** | `pip install --pre azure-search-documents` (`12.1.0b1`) | `2026-05-01-preview` |
+
+By default the provider lets the installed SDK pick its `api-version`. Pass `api_version`
+to pin it explicitly using the exported constants:
+
+```python
+from agent_framework_azure_ai_search import PREVIEW_API_VERSION, STABLE_API_VERSION
+
+provider = AzureAISearchContextProvider(..., api_version=STABLE_API_VERSION)
+```
+
+Agentic **output modes** (`answer_synthesis`) and **extended reasoning effort**
+(`low`/`medium`) are preview-only: they require the preview SDK and `PREVIEW_API_VERSION`.
+On the stable SDK the provider uses extractive output with minimal reasoning effort, and
+raises an actionable error if a preview-only option is requested.
+
 ### Basic Usage Example
 
 See the [Azure AI Search context provider examples](../../samples/02-agents/context_providers/azure_ai_search/) which demonstrate:

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

@@ -2,14 +2,21 @@
 
 import importlib.metadata
 
-from ._context_provider import AzureAISearchContextProvider, AzureAISearchSettings
+from ._context_provider import (
+    PREVIEW_API_VERSION,
+    STABLE_API_VERSION,
+    AzureAISearchContextProvider,
+    AzureAISearchSettings,
+)
 
 try:
     __version__ = importlib.metadata.version(__name__)
 except importlib.metadata.PackageNotFoundError:
     __version__ = "0.0.0"  # Fallback for development mode
 
 __all__ = [
+    "PREVIEW_API_VERSION",
+    "STABLE_API_VERSION",
     "AzureAISearchContextProvider",
     "AzureAISearchSettings",
     "__version__",

python/packages/azure-ai-search/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure AI Search integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260521"
+version = "1.0.0b260618"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -24,7 +24,9 @@ classifiers = [
 ]
 dependencies = [
     "agent-framework-core>=1.6.0,<2",
-    "azure-search-documents>=11.7.0b2,<11.7.0b3",
+    # Stable/GA (12.0.0) targets Azure AI Search api-version 2026-04-01; the preview
+    # line (e.g. 12.1.0b1, installed with --pre) targets api-version 2026-05-01-preview.
+    "azure-search-documents>=12.0.0,<13",
 ]
 
 [tool.uv]