Python: Enable Agentic Mode to Use Existing Knowledge Bases Without index_name

[farzad528]

Motivation and Context

When using agentic mode with Azure AI Search, users with an existing Knowledge Base should be able to use it directly by providing knowledge_base_name without needing to specify index_name. Previously, the validation logic required index_name for agentic mode, which forced users to go through the KB auto-creation path even when they already had a Knowledge Base set up.

Description

Updated the AzureAISearchContextProvider validation logic for agentic mode to support two paths:

Option 1: Use existing Knowledge Base (simplest)

• Provide knowledge_base_name only
• No index_name or model_deployment_name required

Option 2: Auto-create Knowledge Base from index

• Provide index_name + model_deployment_name + azure_openai_resource_url
• KB is auto-created with name {index_name}-kb

Validation rules:

• Agentic mode requires exactly ONE of index_name OR knowledge_base_name (not both, not neither)
• If using index_name, model_deployment_name is required
• Values can come from explicit parameters OR environment variables (AZURE_SEARCH_INDEX_NAME / AZURE_SEARCH_KNOWLEDGE_BASE_NAME)

Changes:

• Added knowledge_base_name field to AzureAISearchSettings for env var support
• Updated validation to use resolved settings (explicit param OR env var)
• Updated sample to demonstrate both approaches

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? No - existing code using index_name continues to work

[Copilot]

Pull request overview

This PR refactors the Azure AI Search Knowledge Base initialization logic to support two distinct paths for using agentic mode: users can now either provide an existing knowledge_base_name directly (simplest approach) or provide index_name to auto-create a Knowledge Base. Previously, all parameters were required even when using an existing KB.

Key Changes

• Added knowledge_base_name field to AzureAISearchSettings for environment variable support
• Updated validation logic to require exactly ONE of index_name OR knowledge_base_name for agentic mode
• Removed unnecessary azure_ai_project_endpoint parameter
• Simplified the sample to demonstrate both usage patterns

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
python/packages/azure-ai-search/agent_framework_azure_ai_search/_search_provider.py	Core refactoring: added knowledge_base_name to settings, updated validation logic to support both KB paths, made _search_client optional, and refactored _ensure_knowledge_base() to handle existing KB vs auto-creation
python/packages/azure-ai-search/tests/test_search_provider.py	Updated tests to cover both agentic mode paths, added tests for validation rules, and cleared environment variables in tests to prevent interference
python/samples/getting_started/context_providers/azure_ai_search/azure_ai_with_search_context_agentic.py	Updated sample to demonstrate both usage patterns: using existing KB (simplest) and auto-creating KB from index, with improved documentation

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
TOTAL	15861	2419	84%

report-only-changed-files is enabled. No files were changed during this commit :)

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2263	130 💤	0 ❌	0 🔥	54.396s ⏱️