Python: [BREAKING] Scope provider state by source_id and standardize source IDs

[eavanvalkenburg]

Summary

• Implements provider-scoped hook state across Python agent execution paths by passing session.state.setdefault(provider.source_id, {}) into provider hooks.
• Standardizes default provider source IDs and constructor overrides across built-in/connector providers (InMemoryHistoryProvider, Mem0ContextProvider, RedisContextProvider, RedisHistoryProvider, AzureAISearchContextProvider).
• Updates tests, docs, and samples to use the scoped-state model and the new source-id defaults.

Breaking changes

• InMemoryHistoryProvider default source ID changed from "memory" to "in_memory".
• Provider hooks now receive provider-scoped state (use state["..."]) instead of requiring nested access via state[self.source_id]["..."].

Validation

• uv run pytest packages/core/tests/core/test_agents.py packages/core/tests/core/test_middleware_with_agent.py packages/core/tests/core/test_sessions.py packages/azure-ai-search/tests/test_aisearch_context_provider.py packages/mem0/tests/test_mem0_context_provider.py packages/redis/tests/test_providers.py
• Result: 230 passed

Tracking

• Fixes Python: Export default history provider source_id ("memory") as a public constant #3941
• Foundry-specific provider implementation remains in Python: Add Foundry Memory Context Provider #3943.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/azure-ai-search/agent_framework_azure_ai_search
_context_provider.py	266	131	50%	103–104, 225, 227, 231, 258–259, 261, 270–271, 274–275, 291, 301, 342–343, 356, 364–369, 372–374, 381–383, 388–391, 393–398, 400–406, 410, 414–419, 423, 425, 428–429, 431, 439–441, 444–446, 452, 454–456, 459, 472–473, 475–476, 478, 480–482, 488–489, 491–498, 500–504, 511, 513, 520, 525, 530, 532, 540–541, 543–544, 553, 555, 560, 562, 568–571, 578, 586, 593–595, 597–605, 607, 617–621, 624
packages/core/agent_framework
_agents.py	321	42	86%	425, 429, 481, 846, 882, 959–962, 1023–1025, 1141, 1157, 1159, 1172, 1178, 1214, 1216, 1225–1230, 1235, 1237, 1243–1244, 1251, 1253–1254, 1262–1263, 1266–1268, 1276–1277, 1279, 1284, 1286
_sessions.py	168	16	90%	67–69, 71–74, 91–92, 94–98, 573, 586
packages/core/agent_framework/_workflows
_agent.py	354	70	80%	66, 74–80, 116–117, 207, 253, 255, 313, 315, 361–362, 368–369, 375, 377, 382, 442–443, 452, 459, 485, 518–520, 522, 524, 526, 531, 536, 583, 613, 630, 669–672, 678, 684, 688–689, 692–698, 702–703, 709, 770, 777, 783–784, 795, 827, 834, 855, 864, 868, 870–872, 879
packages/mem0/agent_framework_mem0
_context_provider.py	80	1	98%	129
packages/redis/agent_framework_redis
_context_provider.py	179	56	68%	221, 239, 242, 248–249, 251–252, 254–256, 258–260, 262–264, 266–277, 279–280, 282–288, 316, 318, 322–327, 348, 359, 369–370, 383–384, 408, 410–411, 415–416
_history_provider.py	59	1	98%	176
TOTAL	20587	3243	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3955	225 💤	0 ❌	0 🔥	1m 10s ⏱️

[Copilot]

Pull request overview

This PR extracts and lands the non-Foundry context/session updates by standardizing provider-scoped state handling and default source_id conventions across core, connectors, tests, and samples.

Changes:

• Switched context/history provider hooks to receive provider-scoped state dicts (session.state[provider.source_id]) and updated call sites accordingly.
• Standardized DEFAULT_SOURCE_ID across built-in and connector providers and updated samples/tests to use these defaults.
• Updated docs/ADR and sample/test references to match the new session/state contract.

Reviewed changes

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

Show a summary per file

File	Description
python/samples/getting_started/sessions/simple_context_provider.py	Updates sample provider to use provider-scoped state and standardized default source id.
python/samples/03-workflows/checkpoint/workflow_as_agent_checkpoint.py	Aligns sample history state lookup with InMemoryHistoryProvider.DEFAULT_SOURCE_ID.
python/samples/03-workflows/agents/workflow_as_agent_with_session.py	Aligns sample history state lookup with default history provider id.
python/samples/03-workflows/agents/azure_ai_agents_with_shared_session.py	Uses default InMemoryHistoryProvider() and updates shared-session state key usage.
python/samples/02-agents/providers/openai/openai_chat_client_with_session.py	Aligns sample history state lookup with default history provider id.
python/samples/02-agents/providers/custom/custom_agent.py	Aligns sample history state lookup with default history provider id and reformats greeting contents.
python/samples/02-agents/providers/azure_openai/azure_chat_client_with_session.py	Aligns sample history state lookup with default history provider id.
python/samples/02-agents/middleware/session_behavior_middleware.py	Updates middleware sample to read history from the default provider-scoped state.
python/samples/02-agents/context_providers/simple_context_provider.py	Migrates sample context provider to provider-scoped state and standardized source id constant.
python/samples/02-agents/chat_client/custom_chat_client.py	Aligns sample history state lookup with default history provider id.
python/packages/redis/tests/test_providers.py	Updates redis provider tests to pass provider-scoped state to hooks.
python/packages/redis/agent_framework_redis/_history_provider.py	Introduces DEFAULT_SOURCE_ID and defaulted constructor source_id.
python/packages/redis/agent_framework_redis/_context_provider.py	Introduces DEFAULT_SOURCE_ID and defaulted constructor source_id.
python/packages/mem0/tests/test_mem0_context_provider.py	Updates mem0 provider tests to pass provider-scoped state to hooks.
python/packages/mem0/agent_framework_mem0/_context_provider.py	Introduces DEFAULT_SOURCE_ID and defaulted constructor source_id.
python/packages/lab/tau2/tests/test_sliding_window.py	Updates tau2 tests to reflect provider-scoped history state shape and default source id.
python/packages/lab/tau2/agent_framework_lab_tau2/runner.py	Updates tau2 runner to read in-memory history under the default provider id key.
python/packages/lab/tau2/agent_framework_lab_tau2/_sliding_window.py	Defaults sliding window provider source id to InMemoryHistoryProvider.DEFAULT_SOURCE_ID.
python/packages/core/tests/core/test_sessions.py	Updates core session/history tests to pass provider-scoped state and use default ids.
python/packages/core/tests/core/test_middleware_with_agent.py	Updates middleware tests to read history under the default provider id key.
python/packages/core/tests/core/test_agents.py	Updates agent tests to use InMemoryHistoryProvider() and default provider-scoped state keys.
python/packages/core/agent_framework/_workflows/_agent.py	Updates workflow agent to create internal sessions when needed and pass provider-scoped state to hooks.
python/packages/core/agent_framework/_sessions.py	Documents provider-scoped hook state and refactors InMemoryHistoryProvider to use scoped state["messages"].
python/packages/core/agent_framework/_agents.py	Updates agent pipeline to pass provider-scoped state and create internal sessions when needed.
python/packages/core/README.md	Fixes relative link to .NET workflows samples.
python/packages/azure-ai-search/tests/test_aisearch_context_provider.py	Updates tests to use provider default source id and pass provider-scoped hook state.
python/packages/azure-ai-search/agent_framework_azure_ai_search/_context_provider.py	Introduces DEFAULT_SOURCE_ID and defaulted constructor source_id.
docs/decisions/0016-python-context-middleware.md	Adds ADR addendum documenting provider-scoped hook state and default source id standardization.

Comments suppressed due to low confidence (2)

python/packages/core/agent_framework/_agents.py:1

• conversation_id can be unintentionally dropped when an internal active_session is created (e.g., providers configured but caller passes conversation_id via opts and no session). In that case active_session.service_session_id is typically None, overwriting the user-supplied conversation_id. Prefer active_session.service_session_id only when it is not None, otherwise fall back to opts.pop("conversation_id", None) (or equivalent).

# Copyright (c) Microsoft. All rights reserved.

python/packages/lab/tau2/tests/test_sliding_window.py:1

• The helper docstring says it creates a "session state dict", but the structure now matches the provider-scoped state (i.e., the dict that contains "messages" directly). Update the docstring to reflect that this is provider-scoped state to avoid confusion with the full session.state shape.

# Copyright (c) Microsoft. All rights reserved.