[Saquib Jawed (saquibjawedbit)]

Motivation & Context

AzureAISearchContextProvider builds the per-source knowledge_source_params for agentic retrieval itself (one entry per knowledge source, with include_reference_source_data=True). Callers have no way to set any other per-source option, most importantly filter_add_on for server-side OData filtering, without subclassing the provider or touching private state.

#6612 proposed this earlier but was closed after the provider changed underneath it (source kinds are now resolved per source, #7875). This PR builds on the current code.

Description & Review Guide

• What are the major changes?
  • New keyword-only knowledge_source_params: Sequence[KnowledgeSourceParams] | None on the agentic overloads. The semantic overload types it as None, and passing it in semantic mode raises ValueError.
  • Caller entries replace the provider's default entry for the source with the same knowledge_source_name. Entries for sources the provider did not resolve are appended. Other sources keep their defaults.
  • If a caller entry leaves include_reference_source_data unset, it defaults to True (on a copy, so the caller's object isn't changed). This keeps ref.source_data populated (Python: AzureAISearchContextProvider agentic mode: source_data is always None on references — missing include_reference_source_data parameter #5095). An explicit False is respected.
  • Duplicate knowledge_source_name values are rejected at construction.
  • Short README note.
• What is the impact of these changes? Additive. With the default None, requests are built exactly as before.
• What do you want reviewers to focus on? The merge semantics: replacing the matched entry vs. merging individual fields into it.

Related Issue

Fixes #5560

The only earlier PR for this issue (#6612) is closed. This PR works on current main and applies overrides to both the existing-KB and index-backed setup paths.

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.

Validation: uv run poe test -P azure-ai-search (389 passed), uv run poe syntax -P azure-ai-search, uv run poe pyright -P azure-ai-search, uv run poe mypy -P azure-ai-search.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Eduard van Valkenburg (eavanvalkenburg)]

/review

[github-actions]

MAF Automated Review — Iteration 1

Result: No findings
Scope: full PR (1 commit(s)): df7c618d6cfd
Model: gpt-5.6-sol-fast

Overview

The change adds agentic-only per-source retrieval overrides while preserving prior defaults, source ordering, explicit opt-out behavior, and caller object ownership. Constructor guards reject duplicate names and nonempty semantic-mode usage, and focused tests cover both existing and index-backed knowledge bases. No concrete Critical, High, or Medium defect remained after reconciling the proposed failure cases against the implementation and tests.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
No publishable findings remained after source verification for this scope.

[Eduard van Valkenburg (eavanvalkenburg)]

Saquib Jawed (@saquibjawedbit) Thanks — the per-source override and defaulting behavior is well covered, the dedicated review found no issues, and all reported checks are green.