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

[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

Fixes #6604

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	386	17	95%	93–94, 119–122, 556, 648–649, 776–777, 864, 869, 874, 957–958, 1006
TOTAL	40077	4489	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
8036	34 💤	0 ❌	0 🔥	2m 10s ⏱️

[Copilot]

Pull request overview

This PR updates the Python Azure AI Search integration to work across both the stable (GA) and preview azure-search-documents 12.x channels by adding explicit api_version support, gating preview-only agentic features, and adjusting request/response model compatibility for the 12.x SDK surface.

Changes:

• Bumped agent-framework-azure-ai-search to depend on azure-search-documents>=12.0.0,<13 and added exported STABLE_API_VERSION / PREVIEW_API_VERSION constants (also re-exported via agent_framework.azure).
• Threaded an optional api_version through Search/Index/KB clients and added _preview_features_active() gating to prevent sending preview-only fields on GA wires (with actionable errors).
• Updated tests and samples/docs for the new API version behavior and 12.x compatibility changes (e.g., vector query k_nearest_neighbors, defensive reference parsing).

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
python/uv.lock	Updates the lock to agent-framework-azure-ai-search 1.0.0b260618 and resolves azure-search-documents to 12.0.0 with a widened <13 bound.
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 sample args for the provider (uses model=) and adds api-version pinning guidance for agentic mode.
python/samples/02-agents/context_providers/azure_ai_search/README.md	Adds stable vs preview API version guidance and documents preview-only agentic options.
python/packages/core/agent_framework/azure/init.py	Re-exports STABLE_API_VERSION / PREVIEW_API_VERSION lazily from the optional azure-ai-search connector package.
python/packages/azure-ai-search/tests/test_aisearch_context_provider.py	Adds unit coverage for api-version forwarding and stable/preview feature gating; adds stubs to exercise preview paths on stable installs.
python/packages/azure-ai-search/README.md	Documents stable vs preview channel behavior and the api-version pinning approach.
python/packages/azure-ai-search/pyproject.toml	Bumps package version and updates dependency range to azure-search-documents>=12.0.0,<13.
python/packages/azure-ai-search/AGENTS.md	Documents the new constants and explains preview feature gating behavior.
python/packages/azure-ai-search/agent_framework_azure_ai_search/_context_provider.py	Implements api-version plumbing, preview-feature gating, 12.x vector query arg updates, and more defensive reference parsing; exports constants.
python/packages/azure-ai-search/agent_framework_azure_ai_search/init.py	Re-exports the api-version constants from the package root.
python/CHANGELOG.md	Notes the Azure AI Search integration update in Unreleased.

[moonbox3]

LGTM, just need to fix the CI/CD checks that are failing