microsoft · eavanvalkenburg · Jun 29, 2026 · Jun 18, 2026
diff --git a/python/CHANGELOG.md b/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` and auto-detect the installed build: preview-only agentic features (output mode, low/medium reasoning effort) are enabled when a preview build is installed and otherwise raise an actionable error. The installed SDK selects its own data-plane api-version (no `api_version` parameter to configure). Also fixes semantic search with a semantic configuration on the 12.x SDK by passing string values for `query_type`/`query_caption` (the 12.x non-`str` enums serialized to a form the service rejected).
+
 ## [1.10.0] - 2026-06-25
 
 ### Added

diff --git a/python/packages/azure-ai-search/AGENTS.md b/python/packages/azure-ai-search/AGENTS.md
@@ -7,6 +7,26 @@ 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
 
+## API versions: stable vs preview
+
+The package depends on `azure-search-documents>=12.0.0,<13`, which spans both channels, and
+auto-detects which build is installed — there is no `api_version` parameter:
+
+| Channel | Install | SDK | Data-plane `api-version` (chosen by the SDK) |
+| --- | --- | --- | --- |
+| **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` |
+
+The provider never pins an `api-version`; the installed build picks its own default, so newer
+releases work without code changes (single source of truth = the install).
+
+Capability gating keys off `_preview_agentic_features_available` — whether the preview build's
+agentic symbols (`KnowledgeRetrieval{Low,Medium}ReasoningEffort`, `KnowledgeRetrievalOutputMode`)
+can be imported. Agentic **output mode** (`answer_synthesis`) and **extended reasoning effort**
+(`low`/`medium`) ship only in the preview build; on a stable build the provider omits them
+(extractive + minimal) and raises an actionable `ValueError` (citing the installed version) if
+they are explicitly requested. Semantic mode is unaffected.
+
 ## Usage
 
 ```python

diff --git a/python/packages/azure-ai-search/README.md b/python/packages/azure-ai-search/README.md
@@ -13,6 +13,24 @@ 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 auto-detects which build of `azure-search-documents` is installed — there is
+nothing to configure in code:
+
+| Channel | Install | Data-plane `api-version` (chosen by the SDK) |
+| --- | --- | --- |
+| **Stable** | `pip install azure-search-documents` (`>=12.0.0`) | `2026-04-01` |
+| **Preview** | `pip install --pre azure-search-documents` (e.g. `12.1.0b1`) | `2026-05-01-preview` |
+
+The provider never pins an `api-version`; the installed build selects its own, so newer
+releases work without code changes.
+
+Agentic **output modes** (`answer_synthesis`) and **extended reasoning effort** (`low`/`medium`)
+ship only in the preview build. When a stable build is installed, the provider uses extractive
+output with minimal reasoning effort and raises an actionable error if a preview-only option is
+explicitly requested. Switching channels is a single change — the install — with no code edits.
+
 ### Basic Usage Example
 
 See the [Azure AI Search context provider examples](../../samples/02-agents/context_providers/azure_ai_search/) which demonstrate:

diff --git a/python/packages/azure-ai-search/agent_framework_azure_ai_search/_context_provider.py b/python/packages/azure-ai-search/agent_framework_azure_ai_search/_context_provider.py
diff --git a/python/packages/azure-ai-search/pyproject.toml b/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]