Repository navigation
Description
Observed Behavior
AzureAISearchCollection and AzureAISearchStore reject a supplied SearchClient or SearchIndexClient when endpoint, credential, API-key, or .env options are also present. They raise before using the working injected client. The same constructors also allow managed_client=True to transfer cleanup of an injected client to the framework.
Affected file: python/packages/azure-ai-search/agent_framework_azure_ai_search/_vector_store.py.
Expected Behavior
An injected SDK client should take precedence over explicit connection arguments, environment settings, and defaults. Connection-creation settings should not be read or validated when a suitable client is present. The injected client should remain caller-owned for its full lifecycle.
Collection-specific settings that are not part of client creation should continue to apply normally.
Steps to Reproduce
- Create a caller-owned
SearchIndexClient. - Pass it to
AzureAISearchStoretogether with any endpoint or.envoption. - Observe the early
ValueErroreven though the client is sufficient. - Alternatively, pass
managed_client=True, close the store, and observe framework-managed cleanup of the injected client.
Minimal Reproduction
from unittest.mock import MagicMock
from agent_framework_azure_ai_search import AzureAISearchStore
index_client = MagicMock()
AzureAISearchStore(index_client=index_client, endpoint="https://ignored.search.windows.net")Error Messages and Stack Traces
ValueError: Injected clients cannot be combined with endpoint, credential, api_key, or env_file options.
Package Versions
agent-framework-azure-ai-search: 1.0.0b261030; main at 93c346f
Python Version
Python 3.13.1
Operating System
macOS
Regression
Unknown
Additional Context
Compatibility impact: this changes beta behavior by removing conflict errors and by making injected clients unconditionally caller-owned. managed_client=True for injected clients may need deprecation or a beta-breaking removal.
Focused acceptance tests:
- Injected index/search clients bypass explicit connection and
.envsettings. - Missing or invalid environment settings cannot block an injected client.
- Client factories are not called for injected clients.
- Closing a store or collection never closes injected clients.
- No-client initialization keeps explicit arguments > environment > defaults/errors.
AI assistance: I used an AI coding assistant to audit and reproduce the behavior.
Acknowledgements
- I searched existing issues and did not find a duplicate.
- I personally verified this behavior and the reproduction details are authentic.
Metadata
Metadata
Labels
Type
Projects
- StatusShow more project fieldsNo status
Activity
[-]Python: [Bug]: Azure AI Search injected clients do not take precedence over connection settings[/-][+].NET: Python: [Bug]: Azure AI Search injected clients do not take precedence over connection settings[/+][-].NET: Python: [Bug]: Azure AI Search injected clients do not take precedence over connection settings[/-][+]Python: [Bug]: Azure AI Search injected clients do not take precedence over connection settings[/+]FOWEPJF255 commentedon Nov 3, 2026
I reproduced the constructor failure on current main (4bb5ffa) with a supplied SearchIndexClient and explicit endpoint. I’ll implement the agreed client-precedence and caller-ownership behavior with focused tests for store and collection construction, settings bypass, and close lifecycle.
eavanvalkenburg commentedon Nov 9, 2026
/plan Use the maintainer-defined client precedence and caller-ownership scope and the existing #10001 implementation; do not start a parallel PR. Resolve the public managed_client compatibility contract for injected clients (retain-and-ignore, deprecate, or remove), including version placement and any migration guidance. Distinguish borrowed clients from search clients the connector creates from an injected index client. Preserve query_source_credential validation, preview/schema constraints, owned-client cleanup, and no-injection settings precedence. Cover store/collection, mixed ownership, derived clients, and cleanup failures. Estimate the smallest correct production-code change before treating this as a minor-ready transition. Planning only; no new implementation or assignment is authorized by this request.
github-actions commentedon Nov 9, 2026
Summary
AzureAISearchStoreandAzureAISearchCollectionraise aValueErrorwhen an injectedSearchIndexClientorSearchClientis combined with endpoint, credential, API key or.envoptions. They also letmanaged_client=Truehand cleanup of an injected client to the framework. The ask is: an injected client always wins, connection settings are never read for it, and the caller always owns it. This follows your direction to use the maintainer-defined scope and the existing #10001 work. I did not read #10001's diff, and no parallel PR is proposed.Recommendation
Code change is warranted (a small one, plus README and test updates). I read
_vector_store.pyon main only.Confirmed in the current code:
managed_clientappends an injected index client and an injected search client to_owned_clients(~L347, ~L355).owned = index_client is None or managed_client is True(~L951) decides whetherclose()closes the index client.index_clientis given, the collection creates its ownSearchClientviaget_search_client(...)and always owns it (~L353). The README line "remain caller-owned unlessmanaged_client=True" describes the behaviour being removed.query_source_credentialvalidation (~L303, ~L943) sits before the conflict check and is separate from client creation.allow_preview,_preview_schema) do not touch client creation.Decision on the public
managed_clientcontractI recommend retain-and-ignore with a deprecation warning for injected clients, in the current beta line (
1.0.0b261106), then remove the parameter in a later beta.TypeError.async withon the client) or let the framework create the client by passing connection options instead."managed_client=Truestops closing injected clients. It needs a changelog note, but the package is pre-1.0 stable, so I would not call it minor-ready until the three items below are settled._vectors.py. The base classes still takemanaged_client(_vectors.pyL1194, L1508), soself.managed_clientstays an internal flag.Ownership model to preserve
index_clientorsearch_clientSearchClientthe collection derives from an injectedindex_clientclose().envProposed plan
ValueErrorblocks. When a client is injected, skip_create_index_clientcompletely, so.envis neither read nor validated. With no injection, keep today's order (explicit arguments, then environment, then errors), including the "credential or api_key, not both" check._owned_clients. Keep adding a derived search client. Asearch_client-only collection owns nothing and has no index client, as now. Setself.managed_clientfrom "owns anything" as today.owned = index_client is None. Storeclose()closes its own index client (if created) and then every collection it handed out. Those collections borrow the store's index client and close only the search clients they derived.managed_clientis passed asTruewith an injected client, emit aDeprecationWarningwith the migration text above and ignore it.managed_client=FalseorNonestays silent.AsyncExitStackbehaviour: one failingclose()must not stop the others. Add tests for this on the store (index client plus collections) and on a collection with several owned clients.managed_clientargs ~L294 and ~L937, "mutually exclusive with connection/file overrides" at ~L293 and ~L934).Estimated size: about 20–40 changed production lines in one file: two deleted blocks, two ownership lines, one warning helper and docstrings. Most of the work is test changes.
Tests
.env: no error, and the factory is not called.close()never closes injected clients. Update the existingmanaged_client=Truetests at ~L889, ~L898, ~L940, ~L956 and ~L1210 to the new contract, plus one test for the warning.store.get_collectioncloses its derived search client, never the store's index client.close()still closes the rest.query_source_credentialstill raisesTypeErrorfor an invalid credential, even alongside an injected client.allow_preview, permission-aware schema) behave the same with injected clients.Done when
The focused acceptance tests from the issue pass, the existing suite passes with the updated lifecycle tests, and the README states the new contract.
Open questions for maintainers
managed_client.managed_client=Trueusers.Nothing has been changed; this is a proposal only.