Python: [BREAKING] Scope provider state by source_id and standardize source IDs (#3995)

* Initial plan * Add FoundryMemoryProvider and tests Co-authored-by: eavanvalkenburg <13749212+eavanvalkenburg@users.noreply.github.com> * Add sample and documentation for FoundryMemoryProvider Co-authored-by: eavanvalkenburg <13749212+eavanvalkenburg@users.noreply.github.com> * Address code review feedback for FoundryMemoryProvider Co-authored-by: eavanvalkenburg <13749212+eavanvalkenburg@users.noreply.github.com> * Address PR review comments: Add DEFAULT_SOURCE_ID, use logging.getLogger, move state to session.state Co-authored-by: eavanvalkenburg <13749212+eavanvalkenburg@users.noreply.github.com> * Fix Foundry memory ItemParam usage and exports Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Refactor provider hook state and standardize source IDs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Support endpoint-based Foundry memory init Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix core README workflows link Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * updated implementation and sample * Split out Foundry memory provider changes Remove FoundryMemoryProvider implementation/tests/sample plus export and docs mentions from this branch so only non-Foundry changes remain. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Trigger CI rerun for PR #3995 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: eavanvalkenburg <13749212+eavanvalkenburg@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2026-02-17 19:12:28 +00:00
parent a5f948c215
commit cc98d5b6f7
28 changed files with 359 additions and 148 deletions
@@ -1072,6 +1072,50 @@ Rationale for B1 over B2: Simpler is better. The whole state dict is passed to e
 > **Note on trust:** Since all `ContextProvider` instances reason over conversation messages (which may contain sensitive user data), they should be **trusted by default**. This is also why we allow all plugins to see all state - if a plugin is untrusted, it shouldn't be in the pipeline at all. The whole state dict is passed rather than isolated slices because plugins that handle messages already have access to the full conversation context.


+### Addendum (2026-02-17): Provider-scoped hook state and default source IDs
+
+This addendum introduces a **breaking change** that supersedes earlier references in this ADR where hooks received the
+entire `session.state` object as their `state` parameter.
+
+#### Hook state contract
+
+- `before_run` and `after_run` now receive a **provider-scoped** mutable state dict.
+- The framework passes `session.state.setdefault(provider.source_id, {})` to hook `state`.
+- Cross-provider/global inspection remains available through `session.state` on `AgentSession`.
+
+#### Session requirement and fallback behavior
+
+- Provider hooks must use session-backed scoped state; there is no ad-hoc `{}` fallback state.
+- If providers run without a caller-supplied session, the framework creates an internal run-scoped `AgentSession` and
+  passes provider-scoped state from that session.
+
+#### Migration guidance
+
+Migrate provider implementations and samples from nested access to scoped access:
+
+- `state[self.source_id]["key"]` → `state["key"]`
+- `state.setdefault(self.source_id, {})["key"]` → `state["key"]`
+
+#### DEFAULT_SOURCE_ID standardization
+
+Aligned with and extending [PR #3944](https://github.com/microsoft/agent-framework/pull/3944), all built-in/connector
+providers in this surface now define a `DEFAULT_SOURCE_ID` and allow constructor override via `source_id`.
+
+Naming convention:
+
+- snake_case
+- close to the provider class name
+- history providers may use `*_memory` where differentiation is useful
+
+Defaults introduced by this change:
+
+- `InMemoryHistoryProvider.DEFAULT_SOURCE_ID = "in_memory"`
+- `Mem0ContextProvider.DEFAULT_SOURCE_ID = "mem0"`
+- `RedisContextProvider.DEFAULT_SOURCE_ID = "redis"`
+- `RedisHistoryProvider.DEFAULT_SOURCE_ID = "redis_memory"`
+- `AzureAISearchContextProvider.DEFAULT_SOURCE_ID = "azure_ai_search"`
+
+
 ## Comparison to .NET Implementation

 The .NET Agent Framework provides equivalent functionality through a different structure. Both implementations achieve the same goals using idioms natural to their respective languages.