Python: Register built-in orchestration types for checkpoint restore

[Atharva Vichare (atty57)]

Motivation & Context

GroupChatBuilder, HandoffBuilder, and MagenticBuilder route framework-owned dataclasses as executor-to-executor messages and as request_info payloads/responses. Those types live in agent_framework_orchestrations, which is outside the agent_framework. module prefix that the restricted checkpoint unpickler auto-allows.

The result is that restoring a checkpoint from a built-in orchestration fails unless the user hand-maintains an allowlist of internal framework module paths:

Failed to decode pickled checkpoint data: Checkpoint deserialization blocked for type
'agent_framework_orchestrations._base_group_chat_orchestrator:GroupChatParticipantMessage'.

Users should not have to track framework-internal module paths to restore a framework-provided orchestration.

Description & Review Guide

• What are the major changes?

  • agent_framework_orchestrations/__init__.py registers the package's checkpoint-crossing types through the existing public register_checkpoint_type API at import time.
  • The registered set covers the three group chat envelopes from the issue plus the wider audit it asks for: HandoffAgentUserRequest, AgentRequestInfoResponse, MagenticResetSignal, MagenticPlanReviewRequest/MagenticPlanReviewResponse, and the ledger types nested inside the plan review request.
  • New tests/test_checkpoint_types.py round-trips the envelopes through encode_checkpoint_value/decode_checkpoint_value under a restricted allowlist (allowed_types=frozenset()), and asserts the request_info payload/response types are registered.

• What is the impact of these changes?

  • Built-in orchestrations restore from checkpoints without any allowed_checkpoint_types configuration. The previously documented workaround keeps working; it is now redundant.
  • No change to the allowlist mechanism itself, and no widening of the module-prefix rule in core — only these named types become trusted.

• What do you want reviewers to focus on?

  • Whether the registered set is complete. GroupChatState, OrchestrationState, and MagenticContext are deliberately excluded because they persist through to_dict/from_dict rather than pickle.
  • Whether package-import-time registration is the right hook, versus a documented explicit helper that callers invoke.

Related Issue

Fixes #7789

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 is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• 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.

[Copilot]

Pull request overview

Registers built-in orchestration payloads for restricted checkpoint restoration.

Changes:

• Registers group-chat, handoff, and Magentic checkpoint types at package import.
• Adds restricted allowlist restoration tests.

Reviewed changes

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

File	Description
agent_framework_orchestrations/__init__.py	Registers orchestration checkpoint types.
tests/test_checkpoint_types.py	Tests registration and envelope restoration.

---

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

[Evan Mattson (moonbox3)]

Why is this still a draft? Please re-open when all comments are addressed and you're ready to move forward.