Skip to content

Python: [Bug]: Azure AI Search injected clients do not take precedence over connection settings #9956

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

  1. Create a caller-owned SearchIndexClient.
  2. Pass it to AzureAISearchStore together with any endpoint or .env option.
  3. Observe the early ValueError even though the client is sufficient.
  4. 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 .env settings.
  • 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.

Activity

  1. changed the title [-]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[/+] on Nov 2, 2026
  2. changed the title [-].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[/+] on Nov 2, 2026
  3. added
    ready-for-implementationMaintainers agree the problem and direction are ready for implementation.
    and removed
    .NETUsage: [Issues, PRs], Target: .Net
    on Nov 2, 2026
  4. FOWEPJF255 commented on Nov 3, 2026

    @FOWEPJF255
    Contributor

    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.

  5. eavanvalkenburg commented on Nov 9, 2026

    @eavanvalkenburg
    MemberAuthor

    /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.

  6. github-actions commented on Nov 9, 2026

    @github-actions
    Contributor

    Summary

    AzureAISearchStore and AzureAISearchCollection raise a ValueError when an injected SearchIndexClient or SearchClient is combined with endpoint, credential, API key or .env options. They also let managed_client=True hand 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.py on main only.

    Confirmed in the current code:

    • Both constructors raise the conflict error before using the client (collection ~L305, store ~L945).
    • Collection: managed_client appends an injected index client and an injected search client to _owned_clients (~L347, ~L355).
    • Store: owned = index_client is None or managed_client is True (~L951) decides whether close() closes the index client.
    • When only an index_client is given, the collection creates its own SearchClient via get_search_client(...) and always owns it (~L353). The README line "remain caller-owned unless managed_client=True" describes the behaviour being removed.
    • query_source_credential validation (~L303, ~L943) sits before the conflict check and is separate from client creation.
    • Preview and schema checks (allow_preview, _preview_schema) do not touch client creation.

    Decision on the public managed_client contract

    I 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.

    • A hard removal breaks existing callers with a TypeError.
    • Silently ignoring it would leave callers who rely on framework cleanup with leaked connections. A warning gives them migration guidance.
    • Migration text: "Injected clients are caller-owned. Close them yourself (e.g. async with on the client) or let the framework create the client by passing connection options instead."
    • This is a beta-breaking change either way: the conflict error disappears and managed_client=True stops 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.
    • Before merge, a maintainer should confirm the deprecation pattern and removal version, since I did not find one to copy in _vectors.py. The base classes still take managed_client (_vectors.py L1194, L1508), so self.managed_client stays an internal flag.

    Ownership model to preserve

    Case Owner Closed by
    Injected index_client or search_client Caller Never
    SearchClient the collection derives from an injected index_client Connector The collection's close()
    Clients built from endpoint, credential, API key or .env Connector The store or collection
    Credentials, embedding clients Caller Never

    Proposed plan

    1. Constructors. Remove both conflict ValueError blocks. When a client is injected, skip _create_index_client completely, so .env is 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.
    2. Collection ownership. Stop adding injected clients to _owned_clients. Keep adding a derived search client. A search_client-only collection owns nothing and has no index client, as now. Set self.managed_client from "owns anything" as today.
    3. Store ownership. Set owned = index_client is None. Store close() 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.
    4. Warning. If managed_client is passed as True with an injected client, emit a DeprecationWarning with the migration text above and ignore it. managed_client=False or None stays silent.
    5. Cleanup failures. Keep AsyncExitStack behaviour: one failing close() must not stop the others. Add tests for this on the store (index client plus collections) and on a collection with several owned clients.
    6. Docs. Update the README paragraph and the docstrings (class text ~L251, managed_client args ~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

    • Injected index or search client plus endpoint, credential, API key or bad .env: no error, and the factory is not called.
    • Injected client with invalid or missing environment settings is unaffected.
    • Store/collection close() never closes injected clients. Update the existing managed_client=True tests at ~L889, ~L898, ~L940, ~L956 and ~L1210 to the new contract, plus one test for the warning.
    • Derived search client is closed by the collection, and the borrowed index client is not.
    • Mixed ownership: a collection from store.get_collection closes its derived search client, never the store's index client.
    • Cleanup failure: a failing close() still closes the rest.
    • No injection: argument beats environment beats default or error is unchanged.
    • query_source_credential still raises TypeError for an invalid credential, even alongside an injected client.
    • Preview and schema checks (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

    • Confirm the removal version for managed_client.
    • Confirm that a warning-only approach is acceptable, since it still changes cleanup behaviour for existing managed_client=True users.

    Nothing has been changed; this is a proposal only.

    Generated by Issue Planning for #9956 · copilot · auto · ~15 AIC · ⌖ ~1 AIC · ⊞ 4.8K · ◷

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

pythonUsage: [Issues, PRs], Target: Pythonready-for-implementationMaintainers agree the problem and direction are ready for implementation.

Type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions