Skip to content

Python: fix(core): deep-restore nested registered values in the default Pydantic state decoder - #9250

Open
Yufeng He (he-yufeng) wants to merge 16 commits into
microsoft:mainfrom
he-yufeng:fix/state-codec-nested-message
Open

Yufeng He (he-yufeng) wants to merge 16 commits into
microsoft:mainfrom
he-yufeng:fix/state-codec-nested-message

Conversation

@he-yufeng

@he-yufeng Yufeng He (he-yufeng) commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Motivation & Context

Registered Pydantic application state can persist a nested Message successfully but fail to restore it because validation receives the tagged dictionary instead of the registered value. Error locations must be followed through the actual schema, including aliases and multiple container levels, without interpreting unrelated application dictionaries as codecs.

Description & Review Guide

  • What are the major changes? The default decoder validates raw input first and restores only values blamed by validation errors. Location traversal resolves model aliases and independently validates union candidates. Each container keeps its full annotation until its own key or index consumes that level, so mapping values and tuple elements remain aligned with the serialized payload.
  • What is the impact of these changes? Nested registered values round-trip through JSON and MessagePack while valid tag-shaped application dictionaries remain raw. Custom codecs retain their raw-payload contract, union candidates do not share repairs, and unknown type tags retain their compatibility behavior.
  • What do you want reviewers to focus on? Schema alignment across nested mappings, lists and tuples, the raw-first retry boundary, and preservation of siblings beside a restored value. The new mixed-container regressions cover the three reported alias shapes and a deeper mapping/tuple/list composition through fresh file stores.

The reported nested shapes failed in six JSON/MessagePack cases before the fix, with two deeper-composition controls already passing. The final session file has 238 passed with three existing framework warnings. Scoped strict Pyright, scoped zuban, Ruff and formatting pass. The all-core strict Pyright attempt timed out after 120 seconds; the earlier full-core counts in this PR's history have not been rerun on this head. Hosted checks remain required.

Related Issue

Fixes #9246

AI Assistance

  • No material AI assistance was used.
  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance covered implementation, regression tests and this description. The current verification was executed locally by the agent against the reported source checkout and existing project environment; scoped results are not presented as a full workspace check.

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
  • This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix). A workflow keeps the label and title prefix in sync automatically.

…lt Pydantic state decoder

The default encoder hands nested values to _serialize_value, which tags
them for the registry, but the default Pydantic decoder validated the raw
payload, so a nested Message arrived as a tagged dict and restoration of
a registered state model failed on AgentSession.from_dict and on a fresh
FileSessionStore read.

Fixes microsoft#9246
Copilot AI balanced review requested due to automatic review settings October 10, 2026 13:35
@agent-framework-automation agent-framework-automation Bot added the python Usage: [Issues, PRs], Target: Python label Oct 10, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The focused decoder change preserves existing codec contracts and is adequately covered by regression tests.

0 open findings

What changed in this PR

Fixes nested registered-value restoration in default Pydantic session-state decoding.

Changes:

  • Deep-deserializes Pydantic payload fields before validation.
  • Adds direct and file-backed regression coverage.
File Description
python/​packages/​core/​agent_framework/​_sessions.py Restores nested registered values before Pydantic validation.
python/​packages/​core/​tests/​core/​test_sessions.py Tests nested Message round trips.

🧠 Review effort: Balanced


💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

@eavanvalkenburg

Copy link
Copy Markdown
Member

Yufeng He (@he-yufeng) Please update the PR body to use the repository's current PR template at .github/pull_request_template.md, including its required headings and fields.

…lues

Deep-restoring every payload field up front hijacks a plain dict field
whose "type" happens to name a registered state type: the tagged shape
is converted before model_validate and then rejected. Validate the raw
payload first and only retry with restored values when that fails, and
cover a tag-shaped dict field staying raw. Also formats the two earlier
nested-message cases that missed ruff format.
@he-yufeng

Copy link
Copy Markdown
Contributor Author

Eduard van Valkenburg (@eavanvalkenburg) done, the body now follows the current template including the AI Assistance section with the assisted areas identified.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yufeng He (@he-yufeng) Please address the inline alias-restoration finding before merge.

…lt Pydantic state decoder

The retry keyed on the first segment of the validation-error location, so a failure pydantic reported at `child.message` restored the whole `child`. `_deserialize_value` then walked the siblings too, and a sibling that legitimately holds a tag-shaped dict, an ordinary `dict[str, Any]` whose `type` merely happens to name a registered type, was handed to that type's codec. It either came back as a framework object or raised `Failed to deserialize registered state type`, which failed the whole restore because of one broken field.

The complete error location is now walked instead. Each segment is resolved onto the raw payload through the field name and its aliases and through container indexes, so a failure two levels down behind `Field(alias=...)` inside a list or a keyed mapping repairs exactly that value and leaves its siblings byte-identical. The class governing each level comes from the annotations: a nested model's own fields resolve the keys beneath it, while `dict[str, Item]` and `list[Item]` treat their keys or positions as application data and hand the item class down to the values.

Where a location would reach inside a payload owned by a registered codec, that codec still restores the value as a whole, since only it knows the shape. A deeper location supersedes a shallower one on the same path, so blaming both `child` and `child.message` repairs `child.message` alone.

Three regressions pin it, each pairing a `Message` field with raw tag-shaped application data: a nested model, an aliased field behind a list index, and an aliased field behind a keyed container. All three fail without the fix, on `Failed to deserialize registered state type 'message' at ...data`, which is the sibling being swept up.

200 tests pass in packages/core/tests/core/test_sessions.py and 8983 in packages/core/tests. `poe pyright` reports the same errors as the base on the file changed, and ruff check and format are clean.
@eavanvalkenburg

Copy link
Copy Markdown
Member

Yufeng He (@he-yufeng) The deep-restoration walker still misses two supported nested shapes. First, Pydantic can include synthetic union-branch labels in error locations—for example child.Item.message—and the walker treats Item as a serialized dictionary key, so restoration is skipped. Second, the generic-argument loop uses the first argument for every container, which selects int instead of Item for dict[int, Item] and for the Item position in tuple[int, Item]; aliased nested Message values then remain plain dictionaries. Please normalize union-branch segments, select mapping value annotations and tuple annotations by index, and add JSON and MessagePack round-trip regressions for these cases.

@eavanvalkenburg

Copy link
Copy Markdown
Member

Yufeng He (@he-yufeng), I found two material union-restore gaps on the current head:

  • python/packages/core/agent_framework/_sessions.py:375: Pydantic can label union branches as is-instance[Message] or by discriminator values rather than the class name. Those branches are skipped, so tagged dictionaries remain unrestored. Please support schema-defined branch labels and add arbitrary-type/discriminated-union coverage.
  • python/packages/core/agent_framework/_sessions.py:380: if an unsuccessful union candidate's codec raises before validation, restoration aborts instead of trying the next valid branch. Please isolate codec failures per candidate and add JSON and MessagePack regressions.

@he-yufeng

Copy link
Copy Markdown
Contributor Author

Eduard van Valkenburg (@eavanvalkenburg) Implemented both follow-ups in 13ddfbc3c and merged current main in f70d63879.

Union recovery no longer depends only on class-name labels. For is-instance[Message], discriminator values, and other schema-defined labels, each candidate restores from the original value and must validate independently before supplying repairs. Candidate validation preserves arbitrary-type support without applying a model config to BaseModel branches. Codec failures are scoped to the candidate that raised, so a later valid branch still gets its chance.

Added JSON and MessagePack round trips for an arbitrary-type union, an aliased nested Message in a discriminated union, and a failing first-candidate codec beside a valid fallback with raw application data. All six regressions fail on the previous head and pass now. The container fixture redeclaration that broke the four typing checkers is also removed.

On the merged head, the complete core suite passes with 9471 passed, 22 skipped, and 2 xfailed. Ruff, formatting, Pyright, mypy, pyrefly, ty, and zuban all pass for core.

@he-yufeng

Copy link
Copy Markdown
Contributor Author

Eduard van Valkenburg (@eavanvalkenburg) Current main is merged in c7dbb1089; the diff remains limited to _sessions.py and test_sessions.py, and all review threads are resolved.

On this merged head, the complete core suite is 9546 passed, 21 skipped, and 2 xfailed. Test Pyright and the pre-commit hooks pass. Could you take another look at the union-restoration follow-ups from 13ddfbc3c?

@BlueRaddish BlueRaddish left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The union retry still selects the wrong branch when two distinct Pydantic model classes share the same class name. This can occur when application state combines result types from two libraries that both call their model Result.

At c7dbb108910a7288ccf226339caef692032ad81b, I reproduced it through the public register_state_type and AgentSession.to_dict / AgentSession.from_dict APIs, with a real JSON serialization step between them:

provider_a.Result: kind = Literal["a"], item = registered opaque Item
provider_b.Result: kind = Literal["b"], item = registered opaque Item
Outer.choice: provider_a.Result | provider_b.Result

original choice = provider_b.Result(kind="b", item=Item("saved-value"))
AgentSession.from_dict(JSON-round-tripped session.to_dict())
→ ValueError: Failed to deserialize registered state type ... at state.value

Pydantic reports both branches using the same Result segment, including duplicate ("choice", "Result", "item") locations. _restore_union resolves that segment with next(arg for arg ... if _union_branch_label(arg) == segment), which selects only provider_a.Result. Its kind="a" validation correctly rejects the stored kind="b", but the second matching class never gets a restoration attempt. The fallback over every candidate only runs when no name matches, so it does not cover a non-unique matching label.

Could a label that matches multiple branches try each matching candidate independently, instead of committing to the first class name? Please add a regression where the saved value belongs to the second same-named branch. Two controls confirm the distinction: the first Result branch round-trips successfully, and the second branch round-trips successfully when the class names are distinct. Both controls preserve the expected branch class and restore the nested registered Item object.

Verification used Python 3.11.17 and Pydantic 2.14.1. It executed the unchanged complete current registry, serializer, decoder and restoration definitions plus the complete public AgentSession class, isolated from unrelated SDK imports. The fixture creates two distinct real Pydantic classes named Result with different provider-module names, and uses an ordinary registered opaque class implementing to_dict / from_dict. A dataclass version also round-tripped successfully because Pydantic could validate its raw dictionary directly; it did not exercise this repair path. No full SDK import, FileSessionStore, MessagePack, repository owner suite, external provider or live model execution is claimed. Analysis, reproduction preparation and this review were AI-assisted.

continue
config = (
None
if isinstance(candidate, type) and issubclass(candidate, BaseModel)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yufeng He (@he-yufeng) This guard recognizes only bare BaseModel classes. Annotated[...] model branches, dataclasses, and TypedDict branches fall through to ConfigDict(arbitrary_types_allowed=True), but Pydantic rejects adapter configuration for those types. A valid tagged union can therefore serialize successfully and then fail during restoration. Please unwrap Annotated and avoid passing adapter config to types that own their validation configuration, with regressions for tagged model, dataclass, and TypedDict union branches.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implemented in caa8b5312. Annotated is unwrapped for the configuration decision, and BaseModel, dataclass, and TypedDict candidates now use their own validation configuration instead of receiving an adapter override.

All three tagged-union shapes have JSON and MessagePack round-trip regressions. The complete core run collected 9,581 tests with 0 failures, 0 errors, and 27 skipped. Source Pyright reports 0 errors, all five test-typing tasks pass, and Ruff check/format pass. Pytest also emitted post-test OpenTelemetry export I/O messages on this machine after completing successfully; those are not being omitted from the local evidence.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I rechecked the current head fb9f20cb29c77257e003c085f5a889cdb0a7987b. The union decoder unwraps Annotated before classification and leaves adapter configuration to types that own their validation config, including BaseModel, dataclasses and TypedDict. The same-named union control is also covered. The four focused session regressions are present, and all 50 current-head checks are green. Could you take another look at this thread and the older change request when you have a chance?

@he-yufeng

Copy link
Copy Markdown
Contributor Author

BlueRaddish caa8b5312 now tries every branch matching a synthetic union label instead of committing to the first class name. Each candidate starts from the original value and must validate independently.

The regression covers your second same-named Result branch, plus the first-branch and distinct-name controls. All three preserve the expected branch class and nested Message through both JSON and MessagePack file-store round trips. The latest Annotated / dataclass / TypedDict adapter-configuration finding is addressed in the same commit.

@he-yufeng

Copy link
Copy Markdown
Contributor Author

Eduard van Valkenburg (@eavanvalkenburg) Current head caa8b5312 includes the Annotated / dataclass / TypedDict adapter-configuration fix and the independent same-named-union retry. All current checks are green.

The JSON and MessagePack round trips cover both new cases. The complete core run is 9,581 collected with 0 failures, 0 errors, and 27 skipped; source Pyright and all five test-typing tasks pass. Could you take another look at the latest follow-up?

@he-yufeng

Copy link
Copy Markdown
Contributor Author

The pre-commit failure is addressed in 6c4339e8e.

Pyupgrade moved is_typeddict from typing_extensions to typing. On this Python 3.14 environment, the stdlib predicate does not recognize typing_extensions._TypedDictMeta, which made both TypedDict union round trips fail. The module-qualified typing_extensions.is_typeddict keeps the intended runtime behavior while satisfying pyupgrade.

The full test_sessions.py file now exits successfully, and the complete scoped pre-commit run passes, including pyupgrade, Poe checks, and Bandit.

@he-yufeng

Copy link
Copy Markdown
Contributor Author

Re-verified the current head fb9f20cb29c77257e003c085f5a889cdb0a7987b against the annotation-tracking finding.

The one-level shift is gone. _restore_mapping now computes value_annotation from the current item_annotation and passes _descend_classes(field.annotation or value_annotation) per key; _restore_list does the same through _list_item_annotation(item_annotation, segment) per index. Each location consumes its own key or index before the next descent, so a list's tuple element is no longer mistaken for the list itself.

The regression covers all three reported shapes plus a deeper composition, in both serialization formats:

container_kind = mapping_list | mapping_mapping | sequence_tuple | mapping_tuple_list
serialization_format = json | msgpack

→ 8 passed, 230 deselected. The full tests/core/test_sessions.py on this head → 238 passed. Python 3.13.11, agent_framework resolving to this checkout. All 51 hosted checks are green (34 success, 17 skipped).

The earlier Annotated / dataclass / TypedDict union-configuration finding is also still satisfied on this tip: the decoder unwraps Annotated before classification and leaves adapter configuration to the types that own their validation config.

Nothing further is pending on my side. The formal CHANGES_REQUESTED stands until you re-ack.

This branch was successfully deployed

1 active deployment
github-app-auth — fb9f20cb Deployed Nov 11, 2026 by he-yufeng via add_label #27619
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Python: [Bug]: Default registered Pydantic state cannot restore a Message field

4 participants