Python: Implement annotation-based context compaction by eavanvalkenburg · Pull Request #4469 · microsoft/agent-framework

Eduard van Valkenburg (eavanvalkenburg) · 2026-03-04T16:14:53Z

Summary

implement annotation-based context compaction primitives and built-in strategies in packages/core/agent_framework/_compaction.py
wire compaction through BaseChatClient
add and update core compaction/function-loop tests, plus compaction samples under samples/02-agents/compaction

Mark Wallace (markwallace-microsoft) · 2026-03-04T16:23:53Z

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_agents.py	356	42	88%	447, 451, 513, 918, 954, 970, 1064–1068, 1137, 1264, 1280, 1282, 1295, 1301, 1337, 1339, 1348–1353, 1358, 1360, 1366–1367, 1374, 1376–1377, 1385–1386, 1389–1391, 1399–1400, 1402, 1407, 1409
_clients.py	125	6	95%	321, 373, 521–524
_compaction.py	633	68	89%	104, 150–162, 169–171, 177–178, 193–196, 203–205, 229, 243, 250, 265–266, 320, 327, 343, 393, 417, 447, 491, 497, 499, 518, 562–567, 579, 651, 653, 668, 712, 774, 896, 957, 959, 975, 982, 987, 1002, 1010, 1104, 1107, 1125, 1141, 1237, 1264, 1269
_middleware.py	338	18	94%	61, 64, 69, 770, 786, 788, 790, 913, 916, 943, 945, 970, 1064, 1068, 1216, 1220, 1286, 1360
_sessions.py	175	16	90%	67–69, 71–74, 91–92, 94–98, 583, 599
_skills.py	406	15	96%	183, 912, 914–916, 970, 1009–1010, 1083, 1088, 1137, 1142, 1294–1295, 1543
_tools.py	787	80	89%	169–170, 329, 331, 349–351, 359, 377, 391, 398, 405, 421, 423, 430, 438, 470, 495, 499, 516–518, 565–567, 589, 645, 667, 734–740, 776, 787–798, 817–819, 823, 827, 841–843, 1182, 1202, 1278–1282, 1406, 1410, 1434, 1552, 1582, 1602, 1604, 1657, 1720, 1923–1924, 1975, 2044–2045, 2105, 2110, 2117
_types.py	1032	86	91%	58, 67–68, 122, 127, 146, 148, 152, 156, 158, 160, 162, 180, 184, 210, 232, 237, 242, 246, 276, 684–685, 1193, 1264, 1299, 1317, 1327, 1371, 1503–1505, 1695, 1786–1791, 1816, 1984, 1996, 2247, 2271, 2366, 2597, 2803, 2872, 2883, 2885–2889, 2891, 2894–2902, 2912, 3117–3119, 3122–3124, 3128, 3133, 3137, 3221–3223, 3252, 3306, 3325–3326, 3329–3333, 3339
observability.py	670	31	95%	370–371, 398, 400–402, 405–407, 412–413, 419–420, 426–427, 717, 721–723, 725, 1068–1072, 1262–1263, 1497, 1677, 2061, 2063
packages/core/agent_framework/openai
_responses_client.py	801	128	84%	303–306, 310–311, 314–315, 321–322, 327, 340–346, 367, 375, 398, 494, 496, 593, 648, 652, 654, 656, 658, 726, 740, 820, 830, 835, 878, 957, 974, 987, 1048, 1139, 1144, 1148–1150, 1154–1155, 1198, 1227, 1233, 1243, 1249, 1254, 1260, 1265–1266, 1327, 1349–1350, 1365–1366, 1384–1385, 1426–1429, 1591, 1646, 1648, 1728–1736, 1855, 1910, 1925, 1945–1955, 1968, 1979–1983, 1997, 2007–2018, 2027, 2059–2062, 2070–2071, 2073–2075, 2089–2091, 2101–2102, 2108, 2123
TOTAL	23534	2660	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5125	20 💤	0 ❌	0 🔥	1m 24s ⏱️

Copilot

Pull request overview

Implements Python annotation-based context compaction primitives and strategies, wires in-run compaction through BaseChatClient, and adds tests + samples demonstrating usage.

Changes:

Add new compaction core module with grouping annotations, token counting, built-in strategies, and a CompactionProvider.
Integrate optional compaction into BaseChatClient/Agent and update history provider to optionally skip excluded messages.
Add comprehensive compaction and function-loop tests plus new compaction samples and ADR rollout note.

Reviewed changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
python/uv.lock	Updates locked dependency versions.
python/samples/02-agents/compaction/README.md	Documents new compaction samples and how to run them.
python/samples/02-agents/compaction/basics.py	Demonstrates individual built-in compaction strategies.
python/samples/02-agents/compaction/advanced.py	Demonstrates composed compaction under a token budget.
python/samples/02-agents/compaction/custom.py	Demonstrates a custom strategy implementing the compaction protocol.
python/samples/02-agents/compaction/compaction_provider.py	Demonstrates provider-based compaction in an agent pipeline with history.
python/samples/02-agents/compaction/tiktoken_tokenizer.py	Demonstrates a `TokenizerProtocol` implementation using `tiktoken`.
python/packages/core/tests/openai/test_openai_responses_client.py	Adds regression test for parsing reasoning + function calls into one message.
python/packages/core/tests/core/test_types.py	Adds roundtrip serialization coverage for compaction annotations.
python/packages/core/tests/core/test_function_invocation_logic.py	Adds tests ensuring compaction is applied within function-call loops and under token budgets.
python/packages/core/tests/core/test_compaction.py	Adds extensive tests for grouping, strategies, apply/projection, and provider behavior.
python/packages/core/tests/core/test_clients.py	Adds tests ensuring BaseChatClient applies compaction before inner calls (streaming + non-streaming).
python/packages/core/agent_framework/openai/_responses_client.py	Adjusts OpenAI Responses request shaping for function calls.
python/packages/core/agent_framework/_types.py	Ensures `additional_properties` are normalized to plain dicts for annotation persistence.
python/packages/core/agent_framework/_sessions.py	Adds `skip_excluded` option to `InMemoryHistoryProvider` to omit excluded messages on load.
python/packages/core/agent_framework/_compaction.py	Adds the compaction implementation (annotations, strategies, provider, utilities).
python/packages/core/agent_framework/_clients.py	Wires optional compaction into BaseChatClient and agent factory.
python/packages/core/agent_framework/_agents.py	Plumbs compaction strategy + tokenizer through Agent and into the client.
python/packages/core/agent_framework/init.py	Re-exports compaction APIs from the top-level package.
docs/decisions/0019-python-context-compaction-strategy.md	Adds rollout/phase note for the implementation plan.

Copilot

Pull request overview

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

Co-authored-by: Copilot <[email protected]>

Add ToolResultCompactionStrategy that collapses older tool-call groups into short summary messages (e.g. [Tool calls: get_weather]) while keeping the most recent groups verbatim. This mirrors the .NET ToolResultCompactionStrategy from PR microsoft#4533. Add CompactionProvider as a context-provider that auto-applies compaction before each agent turn and stores compacted history in session state after each turn. Includes tests and samples for both features. Co-authored-by: Copilot <[email protected]>

…p_excluded - ToolResultCompactionStrategy collapses older tool-call groups into [Tool results: func_name: result] summaries with bidirectional tracing (same pattern as SummarizationStrategy). - CompactionProvider as BaseContextProvider with separate before_strategy and after_strategy parameters. before_strategy compacts loaded context; after_strategy compacts stored history via history_source_id. - InMemoryHistoryProvider gains skip_excluded flag to filter out messages marked as excluded by compaction strategies. - Tests, samples, and exports updated. Co-authored-by: Copilot <[email protected]>

… annotations SummarizationStrategy was not calling annotate_message_groups after inserting its summary message, so the summary lacked core group annotations (id, kind, index, has_reasoning, _excluded). Added the missing call. ToolResultCompactionStrategy already had it. Added tests verifying both strategies produce fully annotated summaries. Co-authored-by: Copilot <[email protected]>

Copilot

Pull request overview

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

You can also share your feedback on Copilot code review. Take the survey.

Mark Wallace (markwallace-microsoft) added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python labels Mar 4, 2026

github-actions Bot changed the title ~~Implement annotation-based context compaction~~ Python: Implement annotation-based context compaction Mar 4, 2026

Eduard van Valkenburg (eavanvalkenburg) force-pushed the python_compaction branch 2 times, most recently from 2dbf300 to d46b5fc Compare March 5, 2026 12:24

Copilot AI mentioned this pull request Mar 6, 2026

docs: Alignment analysis of .NET and Python context compaction vs. ADR-0019 #4515

Closed

3 of 4 tasks

Eduard van Valkenburg (eavanvalkenburg) mentioned this pull request Mar 10, 2026

Python: [Bug]: Responses-style continuation bypasses history provider isolation #4577

Closed

Eduard van Valkenburg (eavanvalkenburg) force-pushed the python_compaction branch 2 times, most recently from ebb3f99 to fa5d060 Compare March 11, 2026 07:39

Eduard van Valkenburg (eavanvalkenburg) marked this pull request as ready for review March 11, 2026 08:32

Copilot AI review requested due to automatic review settings March 11, 2026 08:32

Copilot started reviewing on behalf of Eduard van Valkenburg (eavanvalkenburg) March 11, 2026 08:32

View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings March 11, 2026 15:44

Chris (crickman) approved these changes Mar 11, 2026

View reviewed changes

Copilot started reviewing on behalf of Chris (crickman) March 11, 2026 15:45

View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

Comment thread python/packages/core/agent_framework/_compaction.py Resolved

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

Eduard van Valkenburg (eavanvalkenburg) enabled auto-merge March 11, 2026 16:08

Tao Chen (TaoChenOSU) reviewed Mar 11, 2026

View reviewed changes

Dmytro Struk (dmytrostruk) approved these changes Mar 11, 2026

View reviewed changes

Eduard van Valkenburg (eavanvalkenburg) added this pull request to the merge queue Mar 11, 2026

Eduard van Valkenburg (eavanvalkenburg) removed this pull request from the merge queue due to a manual request Mar 11, 2026

Eduard van Valkenburg (eavanvalkenburg) and others added 7 commits March 11, 2026 20:10

Implement annotation-based context compaction

014dfca

Co-authored-by: Copilot <[email protected]>

Handle missing compaction attributes in BaseChatClient

e002dc9

Co-authored-by: Copilot <[email protected]>

Fix CI typing and bandit issues

665a051

Co-authored-by: Copilot <[email protected]>

Optimize incremental compaction annotation pass

7157568

Co-authored-by: Copilot <[email protected]>

refinement

90e297a

refinement and alignment with dotnet PR

af3aedb

Eduard van Valkenburg (eavanvalkenburg) and others added 7 commits March 11, 2026 20:10

updated tool result compaction

673740a

updated tool result compaction

5fe2073

fixed checks

5d78c26

fix mypy

9c14d54

updated propagation

8a3ce72

Eduard van Valkenburg (eavanvalkenburg) force-pushed the python_compaction branch from 0fb9621 to 8a3ce72 Compare March 11, 2026 19:10

Eduard van Valkenburg (eavanvalkenburg) enabled auto-merge March 11, 2026 19:11

fix mypy

cbcbe49

Copilot AI review requested due to automatic review settings March 11, 2026 19:14

Copilot started reviewing on behalf of Eduard van Valkenburg (eavanvalkenburg) March 11, 2026 19:15

View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

Comment thread python/packages/core/agent_framework/_compaction.py Resolved

Comment thread python/packages/core/agent_framework/_compaction.py Resolved

Dmytro Struk (dmytrostruk) approved these changes Mar 11, 2026

View reviewed changes

Eduard van Valkenburg (eavanvalkenburg) added this pull request to the merge queue Mar 11, 2026

Merged via the queue into microsoft:main with commit 3e03a30 Mar 11, 2026
36 checks passed

Eduard van Valkenburg (eavanvalkenburg) deleted the python_compaction branch June 30, 2026 09:02

Anton Sokolovskyi (antsok) mentioned this pull request Sep 13, 2026

Python: [Bug]: Compaction token counter charges encrypted reasoning payloads (protected_data) as prompt text #8348

Closed

Navigation Menu

Repository navigation

Python: Implement annotation-based context compaction - #4469

Python: Implement annotation-based context compaction#4469
Eduard van Valkenburg (eavanvalkenburg) merged 15 commits into
microsoft:mainfrom
eavanvalkenburg:python_compaction

Eduard van Valkenburg (eavanvalkenburg) commented Mar 4, 2026 •

edited

Loading

Uh oh!

Mark Wallace (markwallace-microsoft) commented Mar 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

Eduard van Valkenburg (eavanvalkenburg) commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

Mark Wallace (markwallace-microsoft) commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python Unit Test Overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Eduard van Valkenburg (eavanvalkenburg) commented Mar 4, 2026 •

edited

Loading

Mark Wallace (markwallace-microsoft) commented Mar 4, 2026 •

edited

Loading