Python: Fix per-service-call history persistence with server-storing clients by eavanvalkenburg · Pull Request #6310 · microsoft/agent-framework · GitHub

Motivation and Context

When an Agent was configured with require_per_service_call_history_persistence=True together with a HistoryProvider, and the underlying chat client stored history server-side by default (e.g. OpenAIChatClient, where STORES_BY_DEFAULT=True), the external history provider was silently never persisted. The per-service-call middleware was skipped because the service was assumed to own history, and the once-per-run path also skipped the provider — so neither persisted.

Fixes #5798

Description

Unify persistence on the per-service-call middleware. When require_per_service_call_history_persistence=True and a HistoryProvider exists, the PerServiceCallHistoryPersistingMiddleware is now always installed and owns persistence. service_stores_history only selects how the middleware behaves, never whether it persists:

Service does not store: the middleware loads providers and drives the function loop with a local sentinel conversation id.
Service stores: the middleware skips loading (the service owns history) and persists each service call while the real conversation id flows through. A warning is logged for any provider with load_messages=True whose load is bypassed.

The observable contract: with the flag on, persistence happens per service call — in a function-call → final-completion run, the function-call turn is persisted before the second call starts.

Rationalize chat-options handling in _prepare_run_context:

_merge_options now skips None overrides and strips remaining None values in a single pass, so an unset store is never forwarded to the client and the service decides its own default (STORES_BY_DEFAULT is only an internal behavior hint).
store and conversation_id are resolved once from a single combined view (effective_options) instead of probing both the agent-default and runtime dicts separately. The InMemoryHistoryProvider auto-injection and the per-service-call resolution now agree on conversation_id (an agent-level default is honored consistently).

Tests are added to test_agents.py as a scenario matrix (sync + streaming) that asserts the per-service-call persistence timing across storing/non-storing clients and store overrides.

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? If yes, add "[BREAKING]" prefix to the title of the PR.

Pull request overview

This PR fixes a Python SDK bug where require_per_service_call_history_persistence=True combined with an external HistoryProvider could silently skip external persistence when the underlying chat client stores history server-side by default (e.g., OpenAI clients with STORES_BY_DEFAULT=True). The fix centralizes history persistence responsibility in the per-service-call middleware and rationalizes option-merging so unset values (notably store=None) are not forwarded to clients.

Changes:

Always installs PerServiceCallHistoryPersistingMiddleware when per-service-call persistence is required and a HistoryProvider is present; service-side storage now only changes how the middleware behaves (load+persist vs persist-only).
Updates _prepare_run_context to resolve store/conversation_id from a single merged options view and to treat None as “unset” (not forwarded).
Adds a scenario-matrix test suite validating persistence timing across storing/non-storing clients, streaming/non-streaming runs, and store overrides.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
python/packages/core/agent_framework/_agents.py	Unifies option resolution and ensures per-service-call persistence is owned by middleware in both local and service-managed cases, with warning logging when load is bypassed.
python/packages/core/agent_framework/_sessions.py	Extends per-service-call middleware to support a “service stores history” mode (persist-only; no provider load; no local sentinel behavior).
python/packages/core/agent_framework/_clients.py	Updates as_agent() docstring to describe the per-service-call persistence behavior (note: one doc line currently contradicts implementation).
python/packages/core/tests/core/test_agents.py	Adds regression tests and a scenario matrix asserting per-service-call persistence timing and store=None non-forwarding.

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_agents.py	418	51	87%	465, 477, 532, 1030, 1075, 1148–1152, 1248, 1276, 1313, 1335, 1355–1356, 1361, 1408, 1450, 1476, 1478, 1491, 1542, 1544, 1553–1558, 1563, 1565, 1571–1572, 1579, 1581–1582, 1590–1591, 1594–1596, 1606–1611, 1615, 1620, 1622
_clients.py	138	7	94%	325, 376, 539–542, 660
_sessions.py	395	33	91%	105–107, 109–110, 127–128, 130–132, 209–210, 300, 561–565, 614, 620, 654, 725, 729, 739, 872, 888, 1021, 1035–1036, 1059, 1081, 1091, 1133
TOTAL	38420	4391	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
7720	34 💤	0 ❌	0 🔥	2m 1s ⏱️

Automated Code Review

Reviewers: 4 | Confidence: 84% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Design Approach

Automated review by eavanvalkenburg's agents

When an Agent set require_per_service_call_history_persistence=True together with a HistoryProvider, and the chat client stored history server-side by default (e.g. OpenAIChatClient, STORES_BY_DEFAULT=True), the external history provider was silently never persisted. Unify persistence on the per-service-call middleware: when the flag is set and a HistoryProvider exists, the middleware is always installed and owns persistence. service_stores_history now only selects middleware behavior: - service does not store: load providers and drive the function loop with a local sentinel conversation id, or - service stores: skip loading (the service owns history) and persist each service call while the real conversation id flows through. Also rationalize chat-options handling in _prepare_run_context: - _merge_options now skips None overrides and strips remaining None values, so an unset `store` is never forwarded and the service decides its own default. - Resolve `store` and `conversation_id` once from a single combined view (effective_options) instead of probing both default and runtime dicts; the auto-injection and per-service-call resolution now agree on conversation_id. Fixes microsoft#5798 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ce per run Address PR review: when the client stores history server-side, the per-service-call middleware still persists after each model call; only provider loading is skipped. The previous "persist once per run()" wording contradicted the implementation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Clarify that require_per_service_call_history_persistence is a no-op when no HistoryProvider is present (docstrings in _agents.py and _clients.py). - Warn on every service call when the client stores history server-side but returns no conversation_id, so the (uncommon) loss of cross-turn resumability cannot fail silently. - Add tests: storing client + existing conversation_id does not raise and the id propagates; two runs on the same session keep persisting with a stable service_session_id and no provider loading; storing-without-conversation-id warns per call. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 3, 2026 14:40

Copilot started reviewing on behalf of Eduard van Valkenburg (eavanvalkenburg) June 3, 2026 14:40 View session

Evan Mattson (moonbox3) added the python Usage: [Issues, PRs], Target: Python label Jun 3, 2026

Copilot AI reviewed Jun 3, 2026

View reviewed changes

Comment thread python/packages/core/agent_framework/_clients.py Outdated

github-actions Bot reviewed Jun 3, 2026

View reviewed changes

Eduard van Valkenburg (eavanvalkenburg) mentioned this pull request Jun 3, 2026

Python: fix: reject service storage history conflict #5866

Closed

Tao Chen (TaoChenOSU) reviewed Jun 3, 2026

View reviewed changes

Comment thread python/packages/core/agent_framework/_agents.py Outdated

Tao Chen (TaoChenOSU) reviewed Jun 3, 2026

View reviewed changes

Comment thread python/packages/core/agent_framework/_agents.py

Evan Mattson (moonbox3) reviewed Jun 4, 2026

View reviewed changes

Comment thread python/packages/core/agent_framework/_sessions.py

Comment thread python/packages/core/agent_framework/_agents.py

Comment thread python/packages/core/agent_framework/_agents.py

Comment thread python/packages/core/agent_framework/_agents.py

Eduard van Valkenburg (eavanvalkenburg) and others added 3 commits June 8, 2026 11:02

Eduard van Valkenburg (eavanvalkenburg) force-pushed the fix/5798-per-service-call-history-persistence branch from 8e09ec8 to 2827110 Compare June 8, 2026 09:02

Tao Chen (TaoChenOSU) approved these changes Jun 8, 2026

View reviewed changes

Evan Mattson (moonbox3) approved these changes Jun 9, 2026

View reviewed changes

Evan Mattson (moonbox3) added this pull request to the merge queue Jun 9, 2026

Merged via the queue into microsoft:main with commit 7e0767a Jun 9, 2026
37 checks passed

Copilot AI mentioned this pull request Jun 9, 2026

Python: bump package versions for 1.8.1 release #6420

Merged

3 of 4 tasks

Eduard van Valkenburg (eavanvalkenburg) deleted the fix/5798-per-service-call-history-persistence branch June 30, 2026 09:01

This was referenced Jul 18, 2026

Bump the nuget-all group with 21 updates universo-rey/microsoft-agents-governed-lab#22

Closed

Bump the nuget-all group with 21 updates universo-rey/microsoft-agents-governed-lab#24

Closed

This was referenced Jul 26, 2026

Bump the nuget-all group with 6 updates dotnet-presentations/ai-workshop#547

Merged

Bump the nuget-all group with 21 updates universo-rey/microsoft-agents-governed-lab#27

Closed

dependabot Bot mentioned this pull request Aug 8, 2026

Bump the nuget-all group with 21 updates universo-rey/microsoft-agents-governed-lab#29

Closed

naeyn mentioned this pull request Aug 9, 2026

.NET: Python: [Bug]: Streaming create_harness_agent runs duplicate the transcript after tool calls — 400 "insufficient tool messages following tool_calls" #7591

Closed

This was referenced Aug 15, 2026

Bump the nuget-all group with 22 updates universo-rey/microsoft-agents-governed-lab#30

Closed

Bump Microsoft.Agents.AI and 21 others universo-rey/microsoft-agents-governed-lab#32

Merged

This was referenced Aug 26, 2026

Bump the microsoft group with 3 updates JoshuaRowePhantom/Phantom.Workspaces#1361

Closed

Bump Microsoft.Agents.AI and 2 others JoshuaRowePhantom/Phantom.Workspaces#1387

Closed

This was referenced Sep 3, 2026

Bump the microsoft group with 12 updates dignite-projects/vault-extract#601

Closed

Bump the microsoft-dotnet group with 18 updates clawdotnet/SharpClawCode#19

Closed

Python: Fix per-service-call history persistence with server-storing clients by eavanvalkenburg · Pull Request #6310 · microsoft/agent-framework · GitHub

Repository navigation

Python: Fix per-service-call history persistence with server-storing clients - #6310

Python: Fix per-service-call history persistence with server-storing clients#6310
Evan Mattson (moonbox3) merged 3 commits into
microsoft:mainfrom
eavanvalkenburg:fix/5798-per-service-call-history-persistence

Eduard van Valkenburg (eavanvalkenburg) commented Jun 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 3, 2026 •
edited
Loading

Uh oh!

Uh oh!

github-actions Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Python: Fix per-service-call history persistence with server-storing clients by eavanvalkenburg · Pull Request #6310 · microsoft/agent-framework · GitHub

Repository navigation

Python: Fix per-service-call history persistence with server-storing clients - #6310

Conversation

Eduard van Valkenburg (eavanvalkenburg) commented Jun 3, 2026

Motivation and Context

Description

Contribution Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

github-actions Bot commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python Unit Test Overview

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Automated Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions Bot commented Jun 3, 2026 •
edited
Loading