Repository navigation
Description
Describe the bug
A registered Pydantic state type cannot be restored from a session snapshot when one of its fields is populated through a validation alias (alias= / validation_alias=AliasChoices(...)).
_default_state_decoder.decode_pydantic hands the dumped field names straight back to Pydantic:
return cls.model_validate({k: v for k, v in value.items() if k != "type"})model_dump() emits the field name, but a field that declares only an alias rejects that name on validation (Pydantic's validate_by_name is off by default, and validate_by_alias wins when an alias exists). The snapshot is written successfully and then cannot be read back, so the persisted state value is lost.
To Reproduce
from pydantic import AliasChoices, BaseModel, Field
from agent_framework import AgentSession, register_state_type
class AliasedState(BaseModel):
note: str = Field(validation_alias=AliasChoices("note_text", "memo"))
register_state_type(AliasedState, type_id="repro:AliasedState")
session = AgentSession(session_id="demo")
session.state["entry"] = AliasedState.model_validate({"note_text": "hello"})
snapshot = session.to_dict()
print(snapshot)
# {'demo': {'entry': {'note': 'hello', 'type': 'repro:AliasedState'}}}
AgentSession.from_dict(snapshot)
# ValueError: Failed to deserialize registered state type 'repro:AliasedState' at state.demo.entry.A plain alias="note_text" field fails the same way.
Expected behavior
AgentSession.from_dict(AgentSession.to_dict()) restores the state value, exactly as it does for fields without aliases.
Actual behavior
ValueError: Failed to deserialize registered state type '...' at state.... — the round trip is broken, and any session persisted with an aliased state type cannot be resumed.
Environment
agent-framework-core: main @ 2026-11-11
Python: 3.11 / 3.13
OS: Windows 11 and Linux (same behaviour)
Installation: uv sync from source
Additional context
Fix direction: before validating, map each dumped field name back to the first declared validation alias (AliasChoices first string choice, AliasPath, or a string alias), falling back to the field name. Covered by python/packages/core/tests/core/test_sessions.py.
Metadata
Metadata
Labels
Type
Projects
- StatusShow more project fieldsNo status
Activity
github-actions commentedon Nov 12, 2026
Reproduced on
main(22b5e75) with an independently written test: a registered Pydantic state type with eithervalidation_alias=AliasChoices(...)oralias=failsAgentSession.from_dict(session.to_dict())withValueError: Failed to deserialize registered state type .... The decoder lives inpython/packages/core/agent_framework/_sessions.py. Related open PR: #10247.Support boundary: unclear. I found no maintained spec stating whether aliased state types must round-trip, so scope is a maintainer decision. Routed to the core package owner; priority and acceptance are left to maintainers.
Run: https://github.com/microsoft/agent-framework/actions/runs/43149393987
eavanvalkenburg commentedon Nov 12, 2026
I'm a bit unsure of the scenario here. Session snapshots are serialized with the model's field names, while Pydantic
validation_aliascontrols which input names are accepted during validation. If the state type needs to accept both the alias and the serialized field name, could it enablepopulate_by_name=True/validate_by_name=True, for example:Would that cover the restore scenario, or is there a case where Agent Framework must synthesize an
AliasChoicesorAliasPathinput rather than restoring the field names it serialized?