Python: Ensure agent thread is part of checkpoint

[Eric Zhu (ekzhu)]

Motivation and Context

Resolves #1698 #1684

Description

AgentExecutor currently doesn't snapshot the state of the agent thread, leading to agent "forgetting" previous conversation when restored from checkpoints.

This PR add mechanism to snapshot thread state. Added warning for AzureAIAgent which doesn't work with workflow checkpointing currently.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Mark Wallace (markwallace-microsoft)]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_agent_executor.py	106	26	75%	82, 92–94, 113–114, 129, 163–164, 166–167, 182–183, 208–209, 211, 215, 243–245, 255–257, 259, 263–264
TOTAL	11961	1852	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
1442	98 💤	0 ❌	0 🔥	28.766s ⏱️

[Copilot]

Pull Request Overview

This PR adds checkpoint and restore functionality for AgentExecutor to enable workflow state persistence and recovery. The changes focus on handling both local and server-side agent threads during checkpointing.

Key Changes:

• Made snapshot_state and restore_state methods async in AgentExecutor
• Added thread state serialization/deserialization alongside cache state
• Implemented special handling for server-side threads (with service_thread_id) by converting them to local threads with copied messages during checkpointing
• Added comprehensive test coverage for checkpoint/restore scenarios

Reviewed Changes

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

File	Description
python/packages/core/agent_framework/_workflows/_agent_executor.py	Updated snapshot_state and restore_state methods to be async and added thread state handling with server-side thread conversion logic
python/packages/core/tests/workflow/test_agent_executor.py	Added comprehensive test suite covering checkpoint storage/restoration, direct snapshot/restore, server-side thread handling, and Azure AI integration

[Dineshsuriya D (droideronline)]

Eric Zhu (@ekzhu) , Tao Chen (@TaoChenOSU) , Evan Mattson (@moonbox3) - I understand that after each super step, we now snapshot the full state of all executors — which includes serialized threads and therefore each agent’s conversation history.

Let’s consider a scenario where we’re running 4 agents. After the first agent completes, we take a snapshot and store the state of all agents in the checkpoint. Then the second agent begins execution. If, for any reason, the process is interrupted (for example, if the user presses Ctrl + C), we would still need to persist the current executor’s state so that when we resume, the agent can continue seamlessly with its previous conversation history intact.

Would it be possible to support this behavior as well? I think this would be an essential addition to ensure full resilience and continuity in multi-agent workflows.