Python: Built-in group chat message types are rejected during checkpoint restore

[droideronline]

Description

When a workflow uses GroupChatBuilder with checkpoint persistence, checkpoint restore can fail because built-in group-chat envelope types are not included in the default checkpoint deserialization allowlist.

The affected types include:

• agent_framework_orchestrations._base_group_chat_orchestrator:GroupChatRequestMessage
• agent_framework_orchestrations._base_group_chat_orchestrator:GroupChatParticipantMessage
• agent_framework_orchestrations._base_group_chat_orchestrator:GroupChatResponseMessage

These are framework-owned types emitted and routed by the group-chat orchestration implementation, but users currently need to manually add them to FileCheckpointStorage(allowed_checkpoint_types=...).

Error

Failed to decode pickled checkpoint data: Checkpoint deserialization blocked for type 'agent_framework_orchestrations._base_group_chat_orchestrator:GroupChatParticipantMessage'. To allow this type, either include its 'module:qualname' key in the 'allowed_types' set passed to 'decode_checkpoint_value', or add it to 'allowed_checkpoint_types' on your checkpoint storage.

Reproduction

from agent_framework._workflows._checkpoint import FileCheckpointStorage
from agent_framework_orchestrations import GroupChatBuilder

storage = FileCheckpointStorage("./checkpoints")

workflow = GroupChatBuilder(
    participants=[...],
    orchestrator_agent=...,
    checkpoint_storage=storage,
).build()

# Run until a checkpoint contains a group-chat envelope, then restore it.

Expected behavior

Framework-owned orchestration message types should be included in the framework's trusted checkpoint type registry by default, or the orchestration package should provide a documented helper that registers all of its checkpoint-safe types.

Users should not need to maintain an internal module-path allowlist for built-in MAF orchestration envelopes.

Workaround

storage = FileCheckpointStorage(
    "./checkpoints",
    allowed_checkpoint_types=[
        "agent_framework_orchestrations._base_group_chat_orchestrator:GroupChatRequestMessage",
        "agent_framework_orchestrations._base_group_chat_orchestrator:GroupChatParticipantMessage",
        "agent_framework_orchestrations._base_group_chat_orchestrator:GroupChatResponseMessage",
    ],
)

Additional context

The same consideration may apply to other framework-owned orchestration payloads, such as handoff and Magentic orchestration event/request types. It would be useful to audit all built-in types that can cross a checkpoint boundary and ensure they are registered consistently.

[z2Ace0107]

I can investigate this issue and prepare a focused regression fix, subject to maintainer guidance on the registration boundary.

From the current main branch, FileCheckpointStorage passes an allowlist to the restricted checkpoint decoder, while the GroupChat envelope types live under the agent_framework_orchestrations.* namespace. The decoder currently auto-allows agent_framework.* types, which appears to explain why these framework-owned messages are rejected during restore.

My initial plan would be:

• Add a deterministic file-checkpoint save/load regression test for the three GroupChat envelope types.
• Keep user-provided allowed_checkpoint_types behavior unchanged.
• If appropriate, register the framework-owned GroupChat checkpoint types through the existing register_checkpoint_type mechanism when the orchestration package is loaded.

Before I start, could you confirm whether the orchestration package should register these checkpoint-safe types, or whether you prefer another mechanism? Should Handoff and Magentic checkpoint payloads be handled separately?

I’m happy to take this issue if that direction is acceptable.

[atty57]

Confirmed on main and opened a draft PR for this: #7791. Ace (@z2Ace0107) — apologies, I had this branched before your comment landed; happy to close mine if you'd rather take it, and either way the notes below should be useful.

The cause is the module-prefix rule in the restricted checkpoint unpickler. _checkpoint_encoding.py auto-allows anything under _FRAMEWORK_MODULE_PREFIX = "agent_framework." (with the trailing dot), so agent_framework_orchestrations — a sibling distribution, not a submodule — falls through to the generic "blocked type" branch, which is why these read as user types.

Minimal repro without a workflow or storage backend:

from agent_framework import Message
from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value, encode_checkpoint_value
from agent_framework_orchestrations._base_group_chat_orchestrator import GroupChatParticipantMessage

msg = GroupChatParticipantMessage(messages=[Message(role="user", contents=[])])
decode_checkpoint_value(encode_checkpoint_value(msg), allowed_types=frozenset())

On the audit point: alongside the three group chat envelopes, the other orchestration types that cross a checkpoint boundary are the request_info payloads and responses — HandoffAgentUserRequest (_handoff.py:439), AgentRequestInfoResponse (_orchestration_request_info.py:101), MagenticPlanReviewRequest/MagenticPlanReviewResponse (_magentic.py:1048) along with the ledger types nested in the request, and MagenticResetSignal (_magentic.py:1271). GroupChatState, OrchestrationState, and MagenticContext are not affected — they persist through to_dict/from_dict rather than pickle.

The PR registers that set via the existing register_checkpoint_type API at package import, so nothing in core's prefix rule changes and no other package becomes trusted. The alternative — broadening the core prefix to cover the whole agent_framework_* family — would fix every first-party package at once but also auto-trusts any installed distribution using that module name, so it seemed like a maintainer call rather than something to fold into this fix.

[github-actions]

🤖 Automated triage reproduction notes (agent-authored — trust but verify)

Agent analysis

Repro: restricted restore fails in python/packages/core/agent_framework/_workflows/_checkpoint_encoding.py::_RestrictedUnpickler.find_class for the three envelope classes defined in python/packages/orchestrations/agent_framework_orchestrations/_base_group_chat_orchestrator.py. Minimal repro: encode each group-chat envelope and call decode_checkpoint_value(encoded, allowed_types=frozenset()); all three raise WorkflowCheckpointException because their agent_framework_orchestrations.* types are blocked.

• Failing test: python/packages/orchestrations/tests/test_group_chat_checkpoint_restore.py
• Files examined: python/packages/core/agent_framework/_workflows/_checkpoint_encoding.py, python/packages/orchestrations/agent_framework_orchestrations/_base_group_chat_orchestrator.py, python/packages/orchestrations/agent_framework_orchestrations/init.py, python/packages/core/tests/workflow/test_checkpoint_unrestricted_pickle.py, python/packages/orchestrations/pyproject.toml
• Tests run: python/packages/orchestrations/tests/test_group_chat_checkpoint_restore.py
• Current version: 1.1.0