Python: support knowledge_source_params in AzureAISearchContextProvider - #6612
Python: support knowledge_source_params in AzureAISearchContextProvider#6612WERCK Ayrton (Athosone) wants to merge 2 commits into
Conversation
There was a problem hiding this comment.
✅ Ready to approve
The change is narrowly scoped, preserves back-compat via a None default, includes a clear semantic-mode guard, and adds targeted tests for the new behavior.
Note: this review does not count toward required approvals for merging.
Pull request overview
Adds a new optional knowledge_source_params keyword-only argument to the Python AzureAISearchContextProvider so callers can pass Azure AI Search Knowledge Base per-source retrieval options (notably filter_add_on and include_reference_source_data) into agentic retrieval requests without subclassing or using private APIs.
Changes:
- Extend
AzureAISearchContextProvider(agentic mode) to accept and storeknowledge_source_params, and forward it into bothKnowledgeBaseRetrievalRequestconstructions in_agentic_search. - Add a runtime guard to reject
knowledge_source_paramsin semantic mode (with semantic overloads also excluding the parameter for static type-checking). - Add tests covering: forwarding in both agentic request branches and default
Nonebehavior; update docs/sample usage to mention per-source parameters.
File summaries
| File | Description |
|---|---|
| python/packages/azure-ai-search/agent_framework_azure_ai_search/_context_provider.py | Adds knowledge_source_params to the provider API and forwards it into agentic retrieval requests with a semantic-mode guard. |
| python/packages/azure-ai-search/tests/test_aisearch_context_provider.py | Adds unit tests validating semantic-mode rejection and agentic request forwarding/default behavior. |
| python/packages/azure-ai-search/README.md | Documents support for per-source retrieval parameters in agentic mode. |
| python/samples/02-agents/context_providers/azure_ai_search/search_context_agentic.py | Shows how to configure per-source parameters (e.g., OData filter_add_on) when using agentic mode. |
Copilot's findings
- Files reviewed: 4/4 changed files
- Comments generated: 0
Note
Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.
Add an optional keyword-only `knowledge_source_params` to the agentic overloads of `AzureAISearchContextProvider`, forwarded verbatim into both `KnowledgeBaseRetrievalRequest` constructions in `_agentic_search`. This lets callers set per-source agentic retrieval options such as `filter_add_on` (OData filtering), `include_reference_source_data`, and similar. Default `None` keeps existing behavior unchanged. The parameter is agentic-only: it is omitted from the semantic overload (a type-level contract) and a runtime ValueError guards untyped callers that pass it in semantic mode. Superset of microsoft#5095 / microsoft#5100. Refs microsoft#5560
03a0454 to
76f1a08
Compare
Evan Mattson (moonbox3)
added
documentation
The agentic-retrieval tests fail the zuban/pyrefly/ty type-checking gate (mypy is lenient and passes): the parametrized `effort` was typed `str` but assigned to a `Literal[...]` attribute, and `params` was inferred as `list[SearchIndexKnowledgeSourceParams]` where a `list[KnowledgeSourceParams] | None` is expected (list invariance). Annotate the parametrized `effort` and the `params` list with their proper types so all five gating type-checkers pass. Test-only; no behavior change. Refs microsoft#5560
|
there was a recent update to the this class, can you catch up with main and see if this is still relevant WERCK Ayrton (@Athosone) |
| retrieval_reasoning_effort=reasoning_effort, | ||
| output_mode=output_mode, | ||
| include_activity=True, | ||
| knowledge_source_params=self._knowledge_source_params, |
There was a problem hiding this comment.
Should this preserve the source-data params that are now built on main before forwarding caller params? Current main resolves _knowledge_source_names and sends include_reference_source_data=True; this branch sends None on the default path, so existing agentic retrieval loses ref.source_data again after the conflict is resolved this way. Could we merge caller-supplied fields with the resolved-source defaults instead of replacing them?
|
Please re-open when ready to address the conflicts, and if the fix is needed as it may not be any longer. |
Summary
Adds an optional keyword-only
knowledge_source_params: list[KnowledgeSourceParams] | None = Noneto
AzureAISearchContextProvider, forwarded verbatim into bothKnowledgeBaseRetrievalRequestconstructions in_agentic_search.This lets callers set per-source agentic retrieval options — most importantly
filter_add_on(server-side OData filtering), and alsoinclude_reference_source_dataand the otherKnowledgeSourceParamsfields —without subclassing the provider or reaching into private methods.
Behavior
Nonemeans retrieval requests are built exactly as before.in semantic mode is a type error; a runtime
ValueErroralso guards untyped callers.Relationship to existing work
Superset of #5095 / #5100 (which hardcodes
include_reference_source_data): this exposesthe full
KnowledgeSourceParamssurface generically.Tests
knowledge_source_paramsreaches the request in both the minimal (intents) andnon-minimal (messages) agentic branches.
None(back-compat).uv run poe test -P azure-ai-search(121 passed, 97% coverage),uv run poe syntax -P azure-ai-search,and
uv run poe pyright -P azure-ai-searchall pass.Closes #5560