Skip to content

Python: Feature/azure ai search agentic rag (search as separate package)#2328

Merged
eavanvalkenburg merged 28 commits intomicrosoft:mainfrom
farzad528:feature/azure-ai-search-agentic-rag-separate
Nov 20, 2025
Merged

Python: Feature/azure ai search agentic rag (search as separate package)#2328
eavanvalkenburg merged 28 commits intomicrosoft:mainfrom
farzad528:feature/azure-ai-search-agentic-rag-separate

Conversation

@farzad528
Copy link
Contributor

@farzad528 farzad528 commented Nov 19, 2025

Motivation and Context

This change is required to align with the Agent Framework design guidance that preview dependencies should not be included in the core package. The existing Azure AI Search integration relied on the beta SDK (azure-search-documents==11.7.0b2), which created blockers for enterprise users who cannot consume preview libraries in production.

By moving Azure AI Search integration into a dedicated agent-framework-aisearch package, users gain explicit control over adopting preview features (pip install agent-framework-aisearch --pre) while keeping the core framework stable and compliant. This improves enterprise adoption, future-proofs the architecture, and maintains backward compatibility for existing users.

This PR addresses all feedback from #1546 and resolves that issue.

Description

This PR introduces a new top-level package, agent-framework-aisearch, and relocates all Azure AI Search–specific functionality out of the core package. Key changes include:

  • New package: Added python/packages/aisearch/ containing the AzureAISearchContextProvider and related utilities.
  • Dependency isolation: Removed the beta Azure AI Search SDK from core to avoid forcing preview adoption.
  • Backward compatibility: Implemented lazy loading in agent_framework.azure so existing imports continue to work without modification.
  • Configuration improvements: Added AzureAISearchSettings for automatic environment variable loading; added support for direct API key strings; corrected type hints for the async embedding function.
  • Reviewer feedback: Incorporated feedback from @eavanvalkenburg, @pablocastro, and @moonbox3 (import cleanup, monorepo structure alignment, typing fixes).
  • Documentation: Updated README, clarified top_k semantics, and improved parameter-level docstrings.
  • Testing: All linting, typing, and unit test checks pass; semantic, agentic, and authentication scenarios validated manually.

No breaking changes. Existing users can continue importing via agent_framework.azure transparently.

Contribution Checklist

Farzad Sunavala and others added 16 commits November 2, 2025 15:00
Python: Fix pyright errors and move search provider to core (microsof…
ed8af31 
…t#1546)
address pablo coments
8de2673
@farzad528
update azure ai search pypi version to latest prev
0cd48ab
@farzad528
Merge remote-tracking branch 'origin/main' into feature/azure-ai-sear…
88886a3 
…ch-agentic-rag
@farzad528
init update
a9244c2
@farzad528
Merge branch 'microsoft:main' into feature/azure-ai-search-agentic-rag
5aa6c32
@farzad528
Merge branch 'main' into feature/azure-ai-search-agentic-rag
c0d2e51
@farzad528
Fix MyPy type annotation errors in search provider
c7d1e79 
- Add type annotation to DEFAULT_CONTEXT_PROMPT
- Add type annotation to vectorizable_fields
- Add union type annotation to vector_queries
@farzad528
Merge branch 'main' into feature/azure-ai-search-agentic-rag
69e5841
@farzad528
Fix DEFAULT_CONTEXT_PROMPT MyPy error and update test
df2aaac 
- Rename DEFAULT_CONTEXT_PROMPT to _DEFAULT_SEARCH_CONTEXT_PROMPT to avoid conflict with base class Final variable
- Update test to use new constant name
- All core package tests passing (1123 passed)
@farzad528
Merge remote-tracking branch 'origin/feature/azure-ai-search-agentic-…
f9e6cab 
…rag' into feature/azure-ai-search-agentic-rag
@farzad528
Merge branch 'main' into feature/azure-ai-search-agentic-rag
8043512
@farzad528
Merge branch 'main' into feature/azure-ai-search-agentic-rag
8923716
@farzad528
Merge branch 'microsoft:main' into feature/azure-ai-search-agentic-rag
316b39e
@farzad528 @claude
Python: Move Azure AI Search to separate package per PR feedback
a02b1c7 
Addresses reviewer feedback from PR microsoft#1546 by isolating the beta dependency
(azure-search-documents==11.7.0b2) into a new agent-framework-aisearch package.

Changes:
- Created new agent-framework-aisearch package with complete structure
- Moved AzureAISearchContextProvider from core to aisearch package
- Added AzureAISearchSettings class for environment variable auto-loading
- Added support for direct API key string (auto-converts to AzureKeyCredential)
- Added azure_openai_api_key parameter for Knowledge Base authentication
- Updated embedding_function type to Callable[[str], Awaitable[list[float]]]
- Moved Role import to top-level imports
- Maintained lazy loading through agent_framework.azure module
- Removed beta dependency from core package
- Updated all tests to use new package location
- All quality checks pass: ruff format/lint, pyright, mypy (0 errors)
- All 21 unit tests pass with 59% coverage

Semantic search mode verified working with both API key and managed identity authentication.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@farzad528 @claude
Python: Clarify top_k parameter only applies to semantic mode
be6b61f 
Updated documentation to clarify that the top_k parameter only affects
semantic search mode. In agentic mode, the server-side Knowledge Base
determines retrieval based on query complexity and reasoning effort.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings November 19, 2025 14:54
@markwallace-microsoft markwallace-microsoft added documentation Improvements or additions to documentation python labels Nov 19, 2025
@github-actions github-actions bot changed the title Feature/azure ai search agentic rag (search as separate package) Python: Feature/azure ai search agentic rag (search as separate package) Nov 19, 2025
Copilot AI reviewed Nov 19, 2025
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR successfully extracts Azure AI Search integration into a dedicated agent-framework-aisearch package, addressing enterprise adoption concerns around preview dependencies in the core framework. The change separates the beta azure-search-documents SDK from core while maintaining full backward compatibility through lazy loading.

Key changes include:

  • New standalone package structure with comprehensive implementation and test coverage
  • Lazy import mechanism enabling transparent backward compatibility for existing users
  • Enhanced configuration options including Settings class for environment variable management and direct API key string support

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 Added dependency entries for the new agent-framework-aisearch package and azure-search-documents==11.7.0b2
python/samples/getting_started/agents/azure_ai/azure_ai_with_search_context.py New comprehensive sample demonstrating both semantic (fast hybrid search) and agentic (Knowledge Base multi-hop reasoning) retrieval modes with proper credential handling and environment variable configuration
python/samples/getting_started/agents/azure_ai/README.md Added documentation entry for the new search context sample
python/packages/core/agent_framework/azure/__init__.py Extended lazy loading mechanism to include AzureAISearchContextProvider and AzureAISearchSettings for transparent backward compatibility
python/packages/aisearch/tests/test_search_provider.py Comprehensive unit test suite covering initialization, semantic search, Knowledge Base setup, lifecycle management, message filtering, citations, and vector field auto-discovery
python/packages/aisearch/tests/__init__.py Test package initialization file with copyright notice
python/packages/aisearch/pyproject.toml Package configuration defining dependencies, build system, and tool settings aligned with monorepo structure
python/packages/aisearch/agent_framework_aisearch/_search_provider.py Core implementation providing AzureAISearchContextProvider with semantic and agentic modes, auto-discovery of vector fields, and AzureAISearchSettings for configuration management
python/packages/aisearch/agent_framework_aisearch/__init__.py Package initialization exposing public API with version metadata
python/packages/aisearch/README.md Package documentation describing installation and usage with links to examples
python/packages/aisearch/LICENSE MIT license file for the new package
python/.env.example Added environment variable examples for Azure AI Search configuration

@farzad528 @claude
Python: Add Knowledge Base output mode and retrieval reasoning effort…
f743aaa 
… parameters

Added support for configurable Knowledge Base behavior in agentic mode:

- knowledge_base_output_mode: "extractive_data" (default) or "answer_synthesis"
  Some knowledge sources require answer_synthesis mode for proper functionality.

- retrieval_reasoning_effort: "minimal" (default), "medium", or "low"
  Controls query planning complexity and multi-hop reasoning depth.

These parameters give users fine-grained control over Knowledge Base behavior
and enable support for knowledge sources that require answer synthesis.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
eavanvalkenburg
eavanvalkenburg reviewed Nov 19, 2025
View reviewed changes
eavanvalkenburg
eavanvalkenburg reviewed Nov 19, 2025
View reviewed changes
eavanvalkenburg
eavanvalkenburg reviewed Nov 19, 2025
View reviewed changes
@farzad528
effort and outputmode query params
004a55c
@farzad528
Merge branch 'main' into feature/azure-ai-search-agentic-rag-separate
86ee4af 
Resolved conflict in python/samples/getting_started/agents/azure_ai/README.md
by keeping both azure_ai_with_search_context.py and azure_ai_with_sharepoint.py entries.
@markwallace-microsoft
Copy link
Member

markwallace-microsoft commented Nov 19, 2025 •
edited
Loading

Python Test Coverage

Python Test Coverage Report •
FileStmtsMissCoverMissing
TOTAL15445235484% 
report-only-changed-files is enabled. No files were changed during this commit :)

Python Unit Test Overview

Tests Skipped Failures Errors Time
2210 127 💤 0 ❌ 0 🔥 54.868s ⏱️

eavanvalkenburg
eavanvalkenburg reviewed Nov 20, 2025
View reviewed changes
eavanvalkenburg
eavanvalkenburg reviewed Nov 20, 2025
View reviewed changes
Copy link
Member

@eavanvalkenburg eavanvalkenburg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really close, small things now!

eavanvalkenburg
eavanvalkenburg approved these changes Nov 20, 2025
View reviewed changes
Copy link
Member

@eavanvalkenburg eavanvalkenburg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love it! Thanks Farzad!

@eavanvalkenburg eavanvalkenburg added this pull request to the merge queue Nov 20, 2025
Merged via the queue into microsoft:main with commit 04e711c Nov 20, 2025
24 checks passed
@farzad528 farzad528 deleted the feature/azure-ai-search-agentic-rag-separate branch November 24, 2025 13:58
@farzad528 farzad528 mentioned this pull request Nov 24, 2025
Closed
arisng pushed a commit to arisng/agent-framework that referenced this pull request Feb 2, 2026
@farzad528 @claude
Python: Feature/azure ai search agentic rag (search as separate packa…
f59deb0 
…ge) (microsoft#2328)

* Python: Fix pyright errors and move search provider to core (microsoft#1546)

* address pablo coments

* update azure ai search pypi version to latest prev

* init update

* Fix MyPy type annotation errors in search provider

- Add type annotation to DEFAULT_CONTEXT_PROMPT
- Add type annotation to vectorizable_fields
- Add union type annotation to vector_queries

* Fix DEFAULT_CONTEXT_PROMPT MyPy error and update test

- Rename DEFAULT_CONTEXT_PROMPT to _DEFAULT_SEARCH_CONTEXT_PROMPT to avoid conflict with base class Final variable
- Update test to use new constant name
- All core package tests passing (1123 passed)

* Python: Move Azure AI Search to separate package per PR feedback

Addresses reviewer feedback from PR microsoft#1546 by isolating the beta dependency
(azure-search-documents==11.7.0b2) into a new agent-framework-aisearch package.

Changes:
- Created new agent-framework-aisearch package with complete structure
- Moved AzureAISearchContextProvider from core to aisearch package
- Added AzureAISearchSettings class for environment variable auto-loading
- Added support for direct API key string (auto-converts to AzureKeyCredential)
- Added azure_openai_api_key parameter for Knowledge Base authentication
- Updated embedding_function type to Callable[[str], Awaitable[list[float]]]
- Moved Role import to top-level imports
- Maintained lazy loading through agent_framework.azure module
- Removed beta dependency from core package
- Updated all tests to use new package location
- All quality checks pass: ruff format/lint, pyright, mypy (0 errors)
- All 21 unit tests pass with 59% coverage

Semantic search mode verified working with both API key and managed identity authentication.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Python: Clarify top_k parameter only applies to semantic mode

Updated documentation to clarify that the top_k parameter only affects
semantic search mode. In agentic mode, the server-side Knowledge Base
determines retrieval based on query complexity and reasoning effort.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Python: Add Knowledge Base output mode and retrieval reasoning effort parameters

Added support for configurable Knowledge Base behavior in agentic mode:

- knowledge_base_output_mode: "extractive_data" (default) or "answer_synthesis"
  Some knowledge sources require answer_synthesis mode for proper functionality.

- retrieval_reasoning_effort: "minimal" (default), "medium", or "low"
  Controls query planning complexity and multi-hop reasoning depth.

These parameters give users fine-grained control over Knowledge Base behavior
and enable support for knowledge sources that require answer synthesis.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* effort and outputmode query params

* Address PR review feedback for Azure AI Search context provider

* comments eduward

* ed latest comments

---------

Co-authored-by: Farzad Sunavala <farzad.sunavala.enovate.ai>
Co-authored-by: farzad528 <farzad528@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@eavanvalkenburg eavanvalkenburg eavanvalkenburg approved these changes

@moonbox3 moonbox3 moonbox3 approved these changes

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation python

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@farzad528 @markwallace-microsoft @eavanvalkenburg @moonbox3