Skip to content

Commit 47086ab

Browse files
committed
Python: add public TypedDict for AgentExecutor checkpoint state (microsoft#8201)
Expose AgentExecutorCheckpointState / AgentSessionCheckpointState, validate restore field types, and cover partial/malformed/forward-compatible payloads.
1 parent 7a82595 commit 47086ab

3 files changed

Lines changed: 177 additions & 14 deletions

File tree

‎python/packages/core/agent_framework/__init__.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -316,7 +316,13 @@
316316
"vectorstoremodel",
317317
),
318318
"._workflows._agent": ("WorkflowAgent",),
319-
"._workflows._agent_executor": ("AgentExecutor", "AgentExecutorRequest", "AgentExecutorResponse"),
319+
"._workflows._agent_executor": (
320+
"AgentExecutor",
321+
"AgentExecutorCheckpointState",
322+
"AgentExecutorRequest",
323+
"AgentExecutorResponse",
324+
"AgentSessionCheckpointState",
325+
),
320326
"._workflows._agent_utils": ("resolve_agent_id",),
321327
"._workflows._checkpoint": (
322328
"CheckpointID",
@@ -423,6 +429,7 @@
423429
"AgentContext",
424430
"AgentEvalConverter",
425431
"AgentExecutor",
432+
"AgentExecutorCheckpointState",
426433
"AgentExecutorRequest",
427434
"AgentExecutorResponse",
428435
"AgentFileStore",
@@ -436,6 +443,7 @@
436443
"AgentResponseUpdate",
437444
"AgentRunInputs",
438445
"AgentSession",
446+
"AgentSessionCheckpointState",
439447
"AggregatingSkillsSource",
440448
"Annotation",
441449
"BackgroundAgentsProvider",

‎python/packages/core/agent_framework/_workflows/_agent_executor.py‎

Lines changed: 96 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,18 @@
33
import inspect
44
import logging
55
import sys
6-
from collections.abc import Awaitable, Callable
6+
from collections.abc import Awaitable, Callable, Mapping
77
from dataclasses import dataclass
88
from typing import Any, Literal, cast
99

10-
from typing_extensions import Never
10+
from typing_extensions import Never, NotRequired, TypedDict
1111

1212
from agent_framework import Content
1313

1414
from .._agents import SupportsAgentRun
1515
from .._sessions import AgentSession
1616
from .._types import AgentResponse, AgentResponseUpdate, Message, ResponseStream
17+
from ..exceptions import WorkflowCheckpointException
1718
from ._agent_utils import prepare_agent_run_args, resolve_agent_id, resolve_executor_kwargs
1819
from ._const import INTERNAL_SOURCE_ID, WORKFLOW_RUN_KWARGS_KEY
1920
from ._executor import Executor, handler
@@ -30,6 +31,79 @@
3031
logger = logging.getLogger(__name__)
3132

3233

34+
class AgentSessionCheckpointState(TypedDict):
35+
"""Serialized :class:`~agent_framework.AgentSession` payload (``AgentSession.to_dict()``).
36+
37+
``state`` holds session-local data. When the session uses service-side storage,
38+
local ``state`` may be incomplete relative to the remote conversation.
39+
"""
40+
41+
type: NotRequired[str]
42+
session_id: str
43+
service_session_id: NotRequired[str | None]
44+
state: NotRequired[dict[str, Any]]
45+
46+
47+
class AgentExecutorCheckpointState(TypedDict, total=False):
48+
"""Public schema for state saved and restored by :class:`AgentExecutor`.
49+
50+
Stored under ``WorkflowCheckpoint.state["_executor_state"][executor_id]``.
51+
52+
``on_checkpoint_save`` always writes every key below. Restore accepts partial
53+
mappings for backward compatibility: missing keys reset to empty defaults.
54+
Unknown keys are ignored so newer writers remain readable by older runtimes.
55+
56+
Compatibility:
57+
- Add fields as ``total=False`` / ``NotRequired`` and treat absence as default.
58+
- Do not rename or change the meaning of existing keys without a migration path.
59+
- Custom executors should define their own TypedDict (or equivalent) and validate
60+
types in ``on_checkpoint_restore``; prefer
61+
:class:`~agent_framework.exceptions.WorkflowCheckpointException` for malformed data.
62+
63+
Keys:
64+
cache: Messages buffered between runs before the next agent invocation.
65+
full_conversation: Prior inputs plus assistant/tool outputs after the last run.
66+
agent_session: Serialized session payload (:class:`AgentSessionCheckpointState`).
67+
pending_agent_requests: In-flight agent-owned user-input requests by request id.
68+
pending_responses_to_agent: Queued content responses waiting to be sent to the agent.
69+
"""
70+
71+
cache: list[Message]
72+
full_conversation: list[Message]
73+
agent_session: AgentSessionCheckpointState
74+
pending_agent_requests: dict[str, Content]
75+
pending_responses_to_agent: list[Content]
76+
77+
78+
def _validate_agent_executor_checkpoint_state(state: Mapping[str, Any]) -> None:
79+
"""Raise :class:`WorkflowCheckpointException` when checkpoint payload types are wrong."""
80+
if not isinstance(state, Mapping):
81+
raise WorkflowCheckpointException(
82+
f"AgentExecutor checkpoint state must be a mapping, got {type(state).__name__}."
83+
)
84+
85+
list_keys = ("cache", "full_conversation", "pending_responses_to_agent")
86+
for key in list_keys:
87+
if key in state and state[key] is not None and not isinstance(state[key], list):
88+
raise WorkflowCheckpointException(
89+
f"AgentExecutor checkpoint field '{key}' must be a list, got {type(state[key]).__name__}."
90+
)
91+
92+
if "pending_agent_requests" in state and state["pending_agent_requests"] is not None:
93+
if not isinstance(state["pending_agent_requests"], dict):
94+
raise WorkflowCheckpointException(
95+
"AgentExecutor checkpoint field 'pending_agent_requests' must be a dict, "
96+
f"got {type(state['pending_agent_requests']).__name__}."
97+
)
98+
99+
if "agent_session" in state and state["agent_session"] is not None:
100+
if not isinstance(state["agent_session"], dict):
101+
raise WorkflowCheckpointException(
102+
"AgentExecutor checkpoint field 'agent_session' must be a dict, "
103+
f"got {type(state['agent_session']).__name__}."
104+
)
105+
106+
33107
def _accepts_runtime_tools(agent: SupportsAgentRun) -> bool:
34108
"""Return whether the agent run surface accepts a tools keyword."""
35109
try:
@@ -347,32 +421,41 @@ async def _cancel_pending_request(
347421
await self._resume_with_pending_responses(ctx)
348422

349423
@override
350-
async def on_checkpoint_save(self) -> dict[str, Any]:
424+
async def on_checkpoint_save(self) -> AgentExecutorCheckpointState:
351425
"""Capture current executor state for checkpointing.
352426
353427
NOTE: if the session uses service-side storage, the full session state
354428
may not be serialized locally.
355429
356430
Returns:
357-
Dict containing serialized cache and session state
431+
:class:`AgentExecutorCheckpointState` with cache, conversation, session,
432+
and pending request/response fields.
358433
"""
359434
serialized_session = self._session.to_dict()
360435

361-
return {
362-
"cache": self._cache,
363-
"full_conversation": self._full_conversation,
364-
"agent_session": serialized_session,
365-
"pending_agent_requests": self._pending_agent_requests,
366-
"pending_responses_to_agent": self._pending_responses_to_agent,
367-
}
436+
return AgentExecutorCheckpointState(
437+
cache=self._cache,
438+
full_conversation=self._full_conversation,
439+
agent_session=serialized_session,
440+
pending_agent_requests=self._pending_agent_requests,
441+
pending_responses_to_agent=self._pending_responses_to_agent,
442+
)
368443

369444
@override
370-
async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
445+
async def on_checkpoint_restore(self, state: AgentExecutorCheckpointState | dict[str, Any]) -> None:
371446
"""Restore executor state from checkpoint.
372447
373448
Args:
374-
state: Checkpoint data dict
449+
state: Checkpoint payload matching :class:`AgentExecutorCheckpointState`
450+
(or a compatible mapping). Missing known keys use empty defaults;
451+
unknown keys are ignored.
452+
453+
Raises:
454+
WorkflowCheckpointException: If ``state`` is not a mapping or a known
455+
field has an incompatible type.
375456
"""
457+
_validate_agent_executor_checkpoint_state(state)
458+
376459
cache_payload = state.get("cache")
377460
self._cache = cache_payload or []
378461

‎python/packages/core/tests/workflow/test_agent_executor.py‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -578,6 +578,78 @@ async def test_checkpoint_restore_works_without_context_mode_in_state() -> None:
578578
assert executor._context_mode == "last_agent" # pyright: ignore[reportPrivateUsage]
579579

580580

581+
async def test_agent_executor_checkpoint_state_public_schema_keys() -> None:
582+
"""Saved AgentExecutor checkpoint state exposes the public TypedDict keys."""
583+
from agent_framework import AgentExecutorCheckpointState, AgentSessionCheckpointState
584+
585+
agent = _CountingAgent(id="schema_agent", name="SchemaAgent")
586+
executor = AgentExecutor(agent)
587+
executor._cache = [Message(role="user", contents=["hello"])] # pyright: ignore[reportPrivateUsage]
588+
589+
state = await executor.on_checkpoint_save()
590+
591+
assert set(state) == {
592+
"cache",
593+
"full_conversation",
594+
"agent_session",
595+
"pending_agent_requests",
596+
"pending_responses_to_agent",
597+
}
598+
assert isinstance(state, dict)
599+
assert len(state["cache"]) == 1
600+
assert "session_id" in state["agent_session"]
601+
# Public types remain importable for static analysis / migrations.
602+
_: type[AgentExecutorCheckpointState] = AgentExecutorCheckpointState
603+
__: type[AgentSessionCheckpointState] = AgentSessionCheckpointState
604+
605+
606+
async def test_agent_executor_checkpoint_restore_missing_optional_fields() -> None:
607+
"""Restore accepts older partial payloads (missing optional TypedDict fields)."""
608+
agent = _CountingAgent(id="partial_agent", name="PartialAgent")
609+
executor = AgentExecutor(agent)
610+
executor._cache = [Message(role="user", contents=["stale"])] # pyright: ignore[reportPrivateUsage]
611+
612+
await executor.on_checkpoint_restore({})
613+
614+
assert executor._cache == [] # pyright: ignore[reportPrivateUsage]
615+
assert executor._full_conversation == [] # pyright: ignore[reportPrivateUsage]
616+
assert executor._pending_agent_requests == {} # pyright: ignore[reportPrivateUsage]
617+
assert executor._pending_responses_to_agent == [] # pyright: ignore[reportPrivateUsage]
618+
619+
620+
async def test_agent_executor_checkpoint_restore_rejects_malformed_fields() -> None:
621+
"""Restore raises WorkflowCheckpointException for wrong field types."""
622+
from agent_framework import WorkflowCheckpointException
623+
624+
agent = _CountingAgent(id="bad_agent", name="BadAgent")
625+
executor = AgentExecutor(agent)
626+
627+
with pytest.raises(WorkflowCheckpointException, match="cache"):
628+
await executor.on_checkpoint_restore({"cache": "not-a-list"}) # type: ignore[typeddict-item]
629+
630+
with pytest.raises(WorkflowCheckpointException, match="agent_session"):
631+
await executor.on_checkpoint_restore({"agent_session": "not-a-dict"}) # type: ignore[typeddict-item]
632+
633+
with pytest.raises(WorkflowCheckpointException, match="pending_agent_requests"):
634+
await executor.on_checkpoint_restore({"pending_agent_requests": []}) # type: ignore[typeddict-item]
635+
636+
637+
async def test_agent_executor_checkpoint_restore_ignores_unknown_keys() -> None:
638+
"""Forward-compatible restore ignores unknown checkpoint keys."""
639+
agent = _CountingAgent(id="fwd_agent", name="FwdAgent")
640+
executor = AgentExecutor(agent)
641+
642+
await executor.on_checkpoint_restore(
643+
{
644+
"cache": [Message(role="user", contents=["ok"])],
645+
"future_field": {"ignored": True},
646+
}
647+
)
648+
649+
assert len(executor._cache) == 1 # pyright: ignore[reportPrivateUsage]
650+
assert executor._cache[0].text == "ok" # pyright: ignore[reportPrivateUsage]
651+
652+
581653
# ---------------------------------------------------------------------------
582654
# Per-executor kwargs resolution tests
583655
# ---------------------------------------------------------------------------

0 commit comments

Comments
 (0)