Skip to content

Python: [Bug]: A registered Pydantic state type with a validation alias cannot be restored from a session snapshot #10287

Description

@DZH166

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.

Activity

  1. added
    pythonUsage: [Issues, PRs], Target: Python
    triageUsage: [Issues], Target: All issues that still need to be triaged
    on Nov 12, 2026
  2. github-actions commented on Nov 12, 2026

    @github-actions
    Contributor

    Reproduced on main (22b5e75) with an independently written test: a registered Pydantic state type with either validation_alias=AliasChoices(...) or alias= fails AgentSession.from_dict(session.to_dict()) with ValueError: Failed to deserialize registered state type .... The decoder lives in python/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

    Generated by Issue Routing for #10287 · copilot · auto · ~25 AIC · ⌖ ~1 AIC · ⊞ 5.2K · ◷

  3. added
    agentsUsage: [Issues, PRs], Target: Single agent
    reproducedUsage: [Issues], Target: all issues that can be reproduced by the triage workflow
    on Nov 12, 2026
  4. eavanvalkenburg commented on Nov 12, 2026

    @eavanvalkenburg
    Member

    I'm a bit unsure of the scenario here. Session snapshots are serialized with the model's field names, while Pydantic validation_alias controls which input names are accepted during validation. If the state type needs to accept both the alias and the serialized field name, could it enable populate_by_name=True / validate_by_name=True, for example:

    class State(BaseModel):
        model_config = ConfigDict(populate_by_name=True)
        record_id: str = Field(validation_alias=AliasChoices("document_id"))

    Would that cover the restore scenario, or is there a case where Agent Framework must synthesize an AliasChoices or AliasPath input rather than restoring the field names it serialized?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

agentsUsage: [Issues, PRs], Target: Single agentpythonUsage: [Issues, PRs], Target: PythonreproducedUsage: [Issues], Target: all issues that can be reproduced by the triage workflowtriageUsage: [Issues], Target: All issues that still need to be triaged

Type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions