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

[Farzad Sunavala (farzad528)]

Motivation & Context

The agent-framework-azure-ai-search package pinned azure-search-documents>=11.7.0b2,<11.7.0b3 and hard-imported Knowledge Base symbols from a single preview SDK 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), and the two SDK layouts diverge: the preview adds agentic output modes and low/medium reasoning effort on the knowledge base definition and retrieve request, which the stable SDK/wire does not expose. On the current pin the package cannot use the stable channel, and on the 12.x SDKs it would fail to import or send fields the GA wire rejects.

This change lets the package 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. Context: https://devblogs.microsoft.com/foundry/foundry-iq-agent-framework-integration/

Description & Review Guide

• What are the major changes?

  • Bump the dependency to azure-search-documents>=12.0.0,<13 so a normal install resolves the stable SDK (12.0.0, api-version 2026-04-01) and --pre resolves the preview SDK (12.1.0b1, api-version 2026-05-01-preview). Bump the package to 1.0.0b260618.
  • Add an api_version parameter to AzureAISearchContextProvider, threaded into SearchClient, SearchIndexClient, and KnowledgeBaseRetrievalClient, plus exported STABLE_API_VERSION / PREVIEW_API_VERSION constants (also re-exported from agent_framework.azure). None (default) defers to the installed SDK's default.
  • Make knowledge-base imports SDK-version resilient (split core vs preview-only symbols) and auto-detect preview-only agentic features via _preview_features_active(), which requires both the preview SDK and a preview api-version. Defaults (extractive output + minimal effort) work on both channels; a stable api-version never sends preview-only fields, and explicitly requesting answer_synthesis / low / medium without preview support raises an actionable error.
  • Fix two 12.x-surface compatibility issues used by semantic + agentic parsing: VectorizableTextQuery/VectorizedQuery use k_nearest_neighbors (was k), and reference parsing reads additional_properties defensively.
  • Update unit tests (pass on both SDKs), the package README/AGENTS docs, samples + sample README (and fix an invalid model_deployment_name sample argument), CHANGELOG.md, and uv.lock.

• What is the impact of these changes?

  • Semantic and agentic RAG work on the stable/released SDK by default and on the preview SDK when installed with --pre. No breakage for existing default usage (extractive + minimal). Preview-only agentic options surface a clear error instead of a server-side 400 when used on the stable wire. Unit tests pass on both 12.0.0 and 12.1.0b1; the flow was also validated live against a preview knowledge base across default / stable-pinned / preview-pinned api-versions.

• What do you want reviewers to focus on?

  • The capability-gating model in _preview_features_active() (SDK capability AND preview api-version) and the resulting error/branching in __init__ validation, _ensure_knowledge_base, and _agentic_search.
  • The dependency bound >=12.0.0,<13 and the stable-by-default / preview-opt-in behavior.

Related Issue

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/azure-ai-search/agent_framework_azure_ai_search
_context_provider.py	387	19	95%	93–94, 109, 112, 116–119, 555, 647–648, 775–776, 863, 868, 873, 956–957, 1005
TOTAL	39880	4506	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
8001	34 💤	0 ❌	0 🔥	2m 6s ⏱️

[Copilot]

Pull request overview

This PR updates the Python agent-framework-azure-ai-search integration to work with both the stable (GA) and preview Azure AI Search / Foundry IQ data-plane API versions exposed via azure-search-documents 12.x, while keeping stable behavior as the default and gating preview-only agentic features behind explicit preview support.

Changes:

• Bumps agent-framework-azure-ai-search to 1.0.0b260618 and updates the dependency range to azure-search-documents>=12.0.0,<13 (stable/preview compatible).
• Adds api_version plumbing plus exported STABLE_API_VERSION / PREVIEW_API_VERSION constants, and gates preview-only agentic options (output mode + low/medium reasoning effort) via _preview_features_active().
• Updates tests, docs, and samples to reflect the stable vs preview split and SDK surface differences (including vector query parameter changes in 12.x).

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
python/uv.lock	Updates lockfile to reflect azure-search-documents 12.0.0 and the bumped azure-ai-search package version.
python/samples/02-agents/context_providers/azure_ai_search/search_context_semantic.py	Documents optional api_version pinning for semantic mode usage.
python/samples/02-agents/context_providers/azure_ai_search/search_context_agentic.py	Updates agentic sample to use model=... and documents preview-only options + optional api_version pinning.
python/samples/02-agents/context_providers/azure_ai_search/README.md	Adds stable vs preview API-version guidance and corrects installation package names.
python/packages/core/agent_framework/azure/init.py	Re-exports STABLE_API_VERSION / PREVIEW_API_VERSION via the lazy agent_framework.azure namespace.
python/packages/azure-ai-search/tests/test_aisearch_context_provider.py	Adds explicit tests for api-version forwarding and stable/preview feature gating; introduces preview-feature stubs to keep tests SDK-agnostic.
python/packages/azure-ai-search/README.md	Documents stable vs preview channels, pinning via constants, and preview-only agentic capabilities.
python/packages/azure-ai-search/pyproject.toml	Updates package version and dependency bounds for azure-search-documents 12.x.
python/packages/azure-ai-search/AGENTS.md	Documents new constants and the preview gating model.
python/packages/azure-ai-search/agent_framework_azure_ai_search/_context_provider.py	Implements api_version forwarding, preview feature gating, SDK-resilient imports, and 12.x query/response compatibility adjustments.
python/packages/azure-ai-search/agent_framework_azure_ai_search/init.py	Re-exports STABLE_API_VERSION / PREVIEW_API_VERSION from the package root.
python/CHANGELOG.md	Adds an Unreleased entry describing the stable/preview support and new API surface.