Python: [Feature]: Support stable + preview Azure AI Search (Foundry IQ) API versions in agent-framework-azure-ai-search

[farzad528]

Description

The agent-framework-azure-ai-search package currently pins azure-search-documents>=11.7.0b2,<11.7.0b3 (a single preview SDK) and hard-imports Knowledge Base symbols from that one layout. Azure AI Search / Foundry IQ has since shipped a stable/GA data-plane API (2026-04-01, served by azure-search-documents 12.0.0) alongside the latest preview API (2026-05-01-preview, served by 12.1.0b1).

The two SDK layouts diverge: the preview adds agentic output modes (answer_synthesis) and low/medium reasoning effort on the knowledge base definition and retrieve request, which the stable SDK / GA wire does not expose. On the current pin the package cannot use the stable channel at all, and on the 12.x SDKs it would either fail to import or send fields the GA wire rejects.

What problem does it solve?
AzureAISearchContextProvider should work across both channels — stable (released) by default and preview opt-in — for both semantic and agentic modes, following the azure-search-documents stable/preview convention and the Agent Framework package guidance.

Expected behavior

• Depend on azure-search-documents>=12.0.0,<13 so a normal install resolves the stable SDK (api-version 2026-04-01) and --pre resolves the preview SDK (api-version 2026-05-01-preview).
• Add an api_version parameter and STABLE_API_VERSION / PREVIEW_API_VERSION constants.
• Auto-detect preview-only agentic features (require both the preview SDK and a preview api-version); keep defaults working on both channels, and raise an actionable error if a preview-only option is requested on the stable wire.

Alternatives considered

• Pinning to the preview SDK only (always --pre) — rejected: it forces all consumers onto a prerelease and doesn't honor the stable-by-default convention.

Context: https://devblogs.microsoft.com/foundry/foundry-iq-agent-framework-integration/

Code Sample

from agent_framework.azure import (
    AzureAISearchContextProvider,
    STABLE_API_VERSION,
    PREVIEW_API_VERSION,
)

# Stable / GA by default (api-version 2026-04-01)
provider = AzureAISearchContextProvider(
    endpoint="https://my-search.search.windows.net",
    index_name="my-index",
    mode="semantic",
)

# Opt into preview agentic features (needs `pip install --pre azure-search-documents`)
provider = AzureAISearchContextProvider(
    endpoint="https://my-search.search.windows.net",
    knowledge_base_name="my-kb",
    mode="agentic",
    api_version=PREVIEW_API_VERSION,
    knowledge_base_output_mode="answer_synthesis",
    retrieval_reasoning_effort="medium",
)

Language/SDK

Python