Merge branch 'main' into feature/python-foundry-hosted-agent-vnext

python/packages/a2a/pyproject.toml

@@ -4,7 +4,7 @@ description = "A2A integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "a2a-sdk>=0.3.5,<0.3.24",
 ]
 

python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py

@@ -46,6 +46,7 @@ from ._orchestration._tooling import collect_server_tools, merge_tools, register
 from ._run_common import (
     FlowState,
     _build_run_finished_event,  # type: ignore
+    _close_reasoning_block,  # type: ignore
     _emit_content,  # type: ignore
     _extract_resume_payload,  # type: ignore
     _has_only_tool_calls,  # type: ignore
@@ -1058,6 +1059,10 @@ async def run_agent_stream(
                             }
                         )
 
+    # Close any open reasoning block
+    for event in _close_reasoning_block(flow):
+        yield event
+
     # Close any open message
     if flow.message_id:
         logger.debug(f"End of run: closing text message message_id={flow.message_id}")

python/packages/ag-ui/agent_framework_ag_ui/_run_common.py

@@ -128,6 +128,7 @@ class FlowState:
     interrupts: list[dict[str, Any]] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
     reasoning_messages: list[dict[str, Any]] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
     accumulated_reasoning: dict[str, str] = field(default_factory=dict)  # pyright: ignore[reportUnknownVariableType]
+    reasoning_message_id: str | None = None
 
     def get_tool_name(self, call_id: str | None) -> str | None:
         """Get tool name by call ID."""
@@ -462,12 +463,39 @@ def _emit_mcp_tool_result(
     return _emit_tool_result_common(content.call_id, raw_output, flow, predictive_handler)
 
 
+def _close_reasoning_block(flow: FlowState) -> list[BaseEvent]:
+    """Close an open reasoning block, emitting end events.
+
+    Should be called when the reasoning block is complete -- e.g. when
+    non-reasoning content arrives or at end of a run.
+    """
+    if not flow.reasoning_message_id:
+        return []
+    message_id = flow.reasoning_message_id
+    flow.reasoning_message_id = None
+    return [
+        ReasoningMessageEndEvent(message_id=message_id),
+        ReasoningEndEvent(message_id=message_id),
+    ]
+
+
 def _emit_text_reasoning(content: Content, flow: FlowState | None = None) -> list[BaseEvent]:
     """Emit AG-UI reasoning events for text_reasoning content.
 
     Uses the protocol-defined reasoning event types so that AG-UI consumers
     such as CopilotKit can render reasoning natively.
 
+    When *flow* is provided the function follows the streaming pattern: it
+    emits ``ReasoningStartEvent`` / ``ReasoningMessageStartEvent`` only on
+    the first delta for a given ``message_id`` and just
+    ``ReasoningMessageContentEvent`` for subsequent deltas.  The matching
+    ``ReasoningMessageEndEvent`` / ``ReasoningEndEvent`` are deferred until
+    ``_close_reasoning_block`` is called (e.g. when non-reasoning content
+    arrives or at end-of-run).
+
+    Without *flow* (backward-compat) the full Start→Content→End sequence is
+    emitted for every call.
+
     Only ``content.text`` is used for the visible reasoning message. If
     ``content.protected_data`` is present it is emitted as a
     ``ReasoningEncryptedValueEvent`` so that consumers can persist encrypted
@@ -483,26 +511,49 @@ def _emit_text_reasoning(content: Content, flow: FlowState | None = None) -> lis
 
     message_id = content.id or generate_event_id()
 
-    events: list[BaseEvent] = [
-        ReasoningStartEvent(message_id=message_id),
-        ReasoningMessageStartEvent(message_id=message_id, role="assistant"),
-    ]
+    events: list[BaseEvent] = []
 
-    if text:
-        events.append(ReasoningMessageContentEvent(message_id=message_id, delta=text))
+    if flow is not None:
+        # Streaming mode: track open reasoning block in flow state.
+        if flow.reasoning_message_id != message_id:
+            # Close any previously open reasoning block (different message_id).
+            events.extend(_close_reasoning_block(flow))
+            # Open new reasoning block.
+            events.append(ReasoningStartEvent(message_id=message_id))
+            events.append(ReasoningMessageStartEvent(message_id=message_id, role="assistant"))
+            flow.reasoning_message_id = message_id
 
-    events.append(ReasoningMessageEndEvent(message_id=message_id))
+        if text:
+            events.append(ReasoningMessageContentEvent(message_id=message_id, delta=text))
 
-    if content.protected_data is not None:
-        events.append(
-            ReasoningEncryptedValueEvent(
-                subtype="message",
-                entity_id=message_id,
-                encrypted_value=content.protected_data,
+        if content.protected_data is not None:
+            events.append(
+                ReasoningEncryptedValueEvent(
+                    subtype="message",
+                    entity_id=message_id,
+                    encrypted_value=content.protected_data,
+                )
             )
-        )
+    else:
+        # No flow -- backward-compatible full sequence per call.
+        events.append(ReasoningStartEvent(message_id=message_id))
+        events.append(ReasoningMessageStartEvent(message_id=message_id, role="assistant"))
 
-    events.append(ReasoningEndEvent(message_id=message_id))
+        if text:
+            events.append(ReasoningMessageContentEvent(message_id=message_id, delta=text))
+
+        events.append(ReasoningMessageEndEvent(message_id=message_id))
+
+        if content.protected_data is not None:
+            events.append(
+                ReasoningEncryptedValueEvent(
+                    subtype="message",
+                    entity_id=message_id,
+                    encrypted_value=content.protected_data,
+                )
+            )
+
+        events.append(ReasoningEndEvent(message_id=message_id))
 
     # Persist reasoning into flow state for MESSAGES_SNAPSHOT.
     # Accumulate reasoning text per message_id, similar to flow.accumulated_text,
@@ -546,23 +597,30 @@ def _emit_content(
 ) -> list[BaseEvent]:
     """Emit appropriate events for any content type."""
     content_type = getattr(content, "type", None)
+
+    # Close open reasoning block when switching to non-reasoning content.
+    if content_type != "text_reasoning":
+        events = _close_reasoning_block(flow)
+    else:
+        events = []
+
     if content_type == "text":
-        return _emit_text(content, flow, skip_text)
+        return events + _emit_text(content, flow, skip_text)
     if content_type == "function_call":
-        return _emit_tool_call(content, flow, predictive_handler)
+        return events + _emit_tool_call(content, flow, predictive_handler)
     if content_type == "function_result":
-        return _emit_tool_result(content, flow, predictive_handler)
+        return events + _emit_tool_result(content, flow, predictive_handler)
     if content_type == "function_approval_request":
-        return _emit_approval_request(content, flow, predictive_handler, require_confirmation)
+        return events + _emit_approval_request(content, flow, predictive_handler, require_confirmation)
     if content_type == "usage":
-        return _emit_usage(content)
+        return events + _emit_usage(content)
     if content_type == "oauth_consent_request":
-        return _emit_oauth_consent(content)
+        return events + _emit_oauth_consent(content)
     if content_type == "mcp_server_tool_call":
-        return _emit_mcp_tool_call(content, flow)
+        return events + _emit_mcp_tool_call(content, flow)
     if content_type == "mcp_server_tool_result":
-        return _emit_mcp_tool_result(content, flow, predictive_handler)
+        return events + _emit_mcp_tool_result(content, flow, predictive_handler)
     if content_type == "text_reasoning":
         return _emit_text_reasoning(content, flow)
     logger.debug("Skipping unsupported content type in AG-UI emitter: %s", content_type)
-    return []
+    return events

python/packages/ag-ui/agent_framework_ag_ui/_workflow_run.py

@@ -29,6 +29,7 @@ from ._message_adapters import normalize_agui_input_messages
 from ._run_common import (
     FlowState,
     _build_run_finished_event,
+    _close_reasoning_block,
     _emit_content,
     _extract_resume_payload,
     _normalize_resume_interrupts,
@@ -729,6 +730,9 @@ async def run_workflow_stream(
             run_error_emitted = True
         terminal_emitted = True
 
+    for reasoning_evt in _close_reasoning_block(flow):
+        yield reasoning_evt
+
     for end_event in _drain_open_message():
         yield end_event
 

python/packages/ag-ui/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-framework-ag-ui"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 description = "AG-UI protocol integration for Agent Framework"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "ag-ui-protocol==0.1.13",
     "fastapi>=0.115.0,<0.133.1",
     "uvicorn[standard]>=0.30.0,<0.42.0"

python/packages/ag-ui/tests/ag_ui/test_run.py

@@ -11,6 +11,7 @@ from ag_ui.core import (
     ReasoningMessageEndEvent,
     ReasoningMessageStartEvent,
     ReasoningStartEvent,
+    TextMessageContentEvent,
     TextMessageEndEvent,
     TextMessageStartEvent,
     ToolCallArgsEvent,
@@ -29,6 +30,7 @@ from agent_framework_ag_ui._agent_run import (
 from agent_framework_ag_ui._run_common import (
     FlowState,
     _build_run_finished_event,
+    _close_reasoning_block,
     _emit_approval_request,
     _emit_content,
     _emit_mcp_tool_call,
@@ -1344,8 +1346,11 @@ class TestEmitContentMcpRouting:
 
         events = _emit_content(content, flow)
 
-        assert len(events) == 5
+        # Streaming pattern: Start + MessageStart + Content (no End events yet)
+        assert len(events) == 3
         assert isinstance(events[0], ReasoningStartEvent)
+        assert isinstance(events[1], ReasoningMessageStartEvent)
+        assert isinstance(events[2], ReasoningMessageContentEvent)
 
 
 class TestReasoningInSnapshot:
@@ -1501,3 +1506,137 @@ class TestReasoningInSnapshot:
         assert len(flow.reasoning_messages) == 1
         assert flow.reasoning_messages[0]["content"] == "part1 part2"
         assert flow.reasoning_messages[0]["encryptedValue"] == "encrypted-payload"
+
+    def test_reasoning_done_after_deltas_does_not_duplicate(self):
+        """A done-style content arriving after deltas does not duplicate accumulated text.
+
+        The upstream client should skip done events when deltas preceded them,
+        but if one leaks through, the accumulator must not double-append.
+        This test verifies that only the delta-produced text is stored.
+        """
+        flow = FlowState()
+        msg_id = "reason_dedup"
+
+        delta1 = Content.from_text_reasoning(id=msg_id, text="Hello ")
+        delta2 = Content.from_text_reasoning(id=msg_id, text="world")
+
+        _emit_text_reasoning(delta1, flow)
+        _emit_text_reasoning(delta2, flow)
+
+        # Accumulated text should equal the concatenation of deltas only
+        assert len(flow.reasoning_messages) == 1
+        assert flow.reasoning_messages[0]["content"] == "Hello world"
+        assert flow.reasoning_messages[0]["id"] == msg_id
+
+    def test_reasoning_deltas_emit_one_content_event_each(self):
+        """Each reasoning delta emits exactly one ReasoningMessageContentEvent
+        within a single Start/End sequence (streaming pattern)."""
+        flow = FlowState()
+        msg_id = "reason_evt"
+
+        delta1 = Content.from_text_reasoning(id=msg_id, text="Think ")
+        delta2 = Content.from_text_reasoning(id=msg_id, text="hard")
+
+        events1 = _emit_text_reasoning(delta1, flow)
+        events2 = _emit_text_reasoning(delta2, flow)
+        close_events = _close_reasoning_block(flow)
+
+        all_events = events1 + events2 + close_events
+        content_events = [e for e in all_events if isinstance(e, ReasoningMessageContentEvent)]
+
+        assert len(content_events) == 2
+        assert content_events[0].delta == "Think "
+        assert content_events[1].delta == "hard"
+
+        # Streaming pattern: one Start/End sequence wrapping both content events
+        start_events = [e for e in all_events if isinstance(e, ReasoningStartEvent)]
+        end_events = [e for e in all_events if isinstance(e, ReasoningEndEvent)]
+        msg_start_events = [e for e in all_events if isinstance(e, ReasoningMessageStartEvent)]
+        msg_end_events = [e for e in all_events if isinstance(e, ReasoningMessageEndEvent)]
+        assert len(start_events) == 1
+        assert len(end_events) == 1
+        assert len(msg_start_events) == 1
+        assert len(msg_end_events) == 1
+
+    def test_reasoning_streaming_event_order(self):
+        """Streaming reasoning emits Start once, then Content per delta, then End on close."""
+        flow = FlowState()
+        msg_id = "reason_order"
+
+        d1 = Content.from_text_reasoning(id=msg_id, text="A ")
+        d2 = Content.from_text_reasoning(id=msg_id, text="B ")
+        d3 = Content.from_text_reasoning(id=msg_id, text="C")
+
+        events = []
+        events.extend(_emit_text_reasoning(d1, flow))
+        events.extend(_emit_text_reasoning(d2, flow))
+        events.extend(_emit_text_reasoning(d3, flow))
+        events.extend(_close_reasoning_block(flow))
+
+        assert isinstance(events[0], ReasoningStartEvent)
+        assert isinstance(events[1], ReasoningMessageStartEvent)
+        assert isinstance(events[2], ReasoningMessageContentEvent)
+        assert events[2].delta == "A "
+        assert isinstance(events[3], ReasoningMessageContentEvent)
+        assert events[3].delta == "B "
+        assert isinstance(events[4], ReasoningMessageContentEvent)
+        assert events[4].delta == "C"
+        assert isinstance(events[5], ReasoningMessageEndEvent)
+        assert isinstance(events[6], ReasoningEndEvent)
+        assert len(events) == 7
+
+    def test_close_reasoning_block_noop_when_not_open(self):
+        """_close_reasoning_block returns empty list when no reasoning block is open."""
+        flow = FlowState()
+        assert _close_reasoning_block(flow) == []
+
+    def test_close_reasoning_block_resets_state(self):
+        """_close_reasoning_block clears reasoning_message_id."""
+        flow = FlowState()
+        _emit_text_reasoning(Content.from_text_reasoning(id="r1", text="x"), flow)
+        assert flow.reasoning_message_id == "r1"
+
+        _close_reasoning_block(flow)
+        assert flow.reasoning_message_id is None
+
+    def test_emit_content_closes_reasoning_on_text(self):
+        """Switching from reasoning to text content auto-closes reasoning block."""
+        flow = FlowState()
+        reasoning = Content.from_text_reasoning(id="r1", text="thinking")
+        text = Content.from_text("answer")
+
+        r_events = _emit_content(reasoning, flow)
+        t_events = _emit_content(text, flow)
+
+        # reasoning events: Start + MsgStart + Content
+        assert isinstance(r_events[0], ReasoningStartEvent)
+        # text events should start with reasoning End events
+        assert isinstance(t_events[0], ReasoningMessageEndEvent)
+        assert isinstance(t_events[1], ReasoningEndEvent)
+        # then text start
+
+        assert isinstance(t_events[2], TextMessageStartEvent)
+        assert isinstance(t_events[3], TextMessageContentEvent)
+
+    def test_reasoning_distinct_ids_close_previous_block(self):
+        """Emitting reasoning with a new message_id auto-closes the previous block."""
+        flow = FlowState()
+        c1 = Content.from_text_reasoning(id="block1", text="first")
+        c2 = Content.from_text_reasoning(id="block2", text="second")
+
+        events1 = _emit_text_reasoning(c1, flow)
+        events2 = _emit_text_reasoning(c2, flow)
+        close = _close_reasoning_block(flow)
+
+        # events1: Start(block1) + MsgStart(block1) + Content(block1)
+        assert events1[0].message_id == "block1"
+        # events2: MsgEnd(block1) + End(block1) + Start(block2) + MsgStart(block2) + Content(block2)
+        assert isinstance(events2[0], ReasoningMessageEndEvent)
+        assert events2[0].message_id == "block1"
+        assert isinstance(events2[1], ReasoningEndEvent)
+        assert events2[1].message_id == "block1"
+        assert isinstance(events2[2], ReasoningStartEvent)
+        assert events2[2].message_id == "block2"
+        # close: MsgEnd(block2) + End(block2)
+        assert isinstance(close[0], ReasoningMessageEndEvent)
+        assert close[0].message_id == "block2"

python/packages/anthropic/pyproject.toml

@@ -4,7 +4,7 @@ description = "Anthropic integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "anthropic>=0.80.0,<0.80.1",
 ]
 

python/packages/azure-ai-search/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure AI Search integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "azure-search-documents>=11.7.0b2,<11.7.0b3",
 ]
 

python/packages/azure-cosmos/README.md

@@ -14,7 +14,7 @@ The Azure Cosmos DB integration provides `CosmosHistoryProvider` for persistent
 
 ```python
 from azure.identity.aio import DefaultAzureCredential
-from agent_framework.azure import CosmosHistoryProvider
+from agent_framework_azure_cosmos import CosmosHistoryProvider
 
 provider = CosmosHistoryProvider(
     endpoint="https://<account>.documents.azure.com:443/",
@@ -35,13 +35,92 @@ Container naming behavior:
 - Container name is configured on the provider (`container_name` or `AZURE_COSMOS_CONTAINER_NAME`)
 - `session_id` is used as the Cosmos partition key for reads/writes
 
-See the [conversation samples](../../samples/02-agents/conversations/) for runnable examples, including
-[`cosmos_history_provider.py`](../../samples/02-agents/conversations/cosmos_history_provider.py).
+See `samples/02-agents/conversations/cosmos_history_provider.py` for a runnable example.
 
-## Import Paths
+## Cosmos DB Workflow Checkpoint Storage
+
+`CosmosCheckpointStorage` implements the `CheckpointStorage` protocol, enabling
+durable workflow checkpointing backed by Azure Cosmos DB NoSQL. Workflows can be
+paused and resumed across process restarts by persisting checkpoint state in Cosmos DB.
+
+### Basic Usage
+
+#### Managed Identity / RBAC (recommended for production)
 
 ```python
-from agent_framework.azure import CosmosHistoryProvider
-# or directly:
-from agent_framework_azure_cosmos import CosmosHistoryProvider
+from azure.identity.aio import DefaultAzureCredential
+from agent_framework import WorkflowBuilder
+from agent_framework_azure_cosmos import CosmosCheckpointStorage
+
+checkpoint_storage = CosmosCheckpointStorage(
+    endpoint="https://<account>.documents.azure.com:443/",
+    credential=DefaultAzureCredential(),
+    database_name="agent-framework",
+    container_name="workflow-checkpoints",
+)
 ```
+
+#### Account Key
+
+```python
+from agent_framework_azure_cosmos import CosmosCheckpointStorage
+
+checkpoint_storage = CosmosCheckpointStorage(
+    endpoint="https://<account>.documents.azure.com:443/",
+    credential="<your-account-key>",
+    database_name="agent-framework",
+    container_name="workflow-checkpoints",
+)
+```
+
+#### Then use with a workflow
+
+```python
+from agent_framework import WorkflowBuilder
+
+# Build a workflow with checkpointing enabled
+workflow = WorkflowBuilder(
+    start_executor=start,
+    checkpoint_storage=checkpoint_storage,
+).build()
+
+# Run the workflow — checkpoints are automatically saved after each superstep
+result = await workflow.run(message="input data")
+
+# Resume from a checkpoint
+latest = await checkpoint_storage.get_latest(workflow_name=workflow.name)
+if latest:
+    resumed = await workflow.run(checkpoint_id=latest.checkpoint_id)
+```
+
+### Authentication Options
+
+`CosmosCheckpointStorage` supports the same authentication modes as `CosmosHistoryProvider`:
+
+- **Managed identity / RBAC** (recommended): Pass `DefaultAzureCredential()`,
+  `ManagedIdentityCredential()`, or any Azure `TokenCredential`
+- **Account key**: Pass a key string via `credential` parameter
+- **Environment variables**: Set `AZURE_COSMOS_ENDPOINT`, `AZURE_COSMOS_DATABASE_NAME`,
+  `AZURE_COSMOS_CONTAINER_NAME`, and `AZURE_COSMOS_KEY` (key not required when using
+  Azure credentials)
+- **Pre-created client**: Pass an existing `CosmosClient` or `ContainerProxy`
+
+### Database and Container Setup
+
+The database and container are created automatically on first use (via
+`create_database_if_not_exists` and `create_container_if_not_exists`). The container
+uses `/workflow_name` as the partition key. You can also pre-create them in the Azure
+portal with this partition key configuration.
+
+### Environment Variables
+
+| Variable | Description |
+|---|---|
+| `AZURE_COSMOS_ENDPOINT` | Cosmos DB account endpoint |
+| `AZURE_COSMOS_DATABASE_NAME` | Database name |
+| `AZURE_COSMOS_CONTAINER_NAME` | Container name |
+| `AZURE_COSMOS_KEY` | Account key (optional if using Azure credentials) |
+
+See `samples/03-workflows/checkpoint/cosmos_workflow_checkpointing.py` for a standalone example,
+or `samples/03-workflows/checkpoint/cosmos_workflow_checkpointing_foundry.py` for an end-to-end
+example with Azure AI Foundry agents.

python/packages/azure-cosmos/agent_framework_azure_cosmos/__init__.py

@@ -2,6 +2,7 @@
 
 import importlib.metadata
 
+from ._checkpoint_storage import CosmosCheckpointStorage
 from ._history_provider import CosmosHistoryProvider
 
 try:
@@ -10,6 +11,7 @@ except importlib.metadata.PackageNotFoundError:
     __version__ = "0.0.0"  # Fallback for development mode
 
 __all__ = [
+    "CosmosCheckpointStorage",
     "CosmosHistoryProvider",
     "__version__",
 ]

python/packages/azure-cosmos/agent_framework_azure_cosmos/_checkpoint_storage.py

@@ -0,0 +1,426 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Azure Cosmos DB checkpoint storage for workflow checkpointing."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, TypedDict
+
+from agent_framework import AGENT_FRAMEWORK_USER_AGENT
+from agent_framework._settings import SecretString, load_settings
+from agent_framework._workflows._checkpoint import CheckpointID, WorkflowCheckpoint
+from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value, encode_checkpoint_value
+from agent_framework.exceptions import WorkflowCheckpointException
+from azure.core.credentials import TokenCredential
+from azure.core.credentials_async import AsyncTokenCredential
+from azure.cosmos import PartitionKey
+from azure.cosmos.aio import ContainerProxy, CosmosClient
+from azure.cosmos.exceptions import CosmosResourceNotFoundError
+
+AzureCredentialTypes = TokenCredential | AsyncTokenCredential
+
+logger = logging.getLogger(__name__)
+
+
+class AzureCosmosCheckpointSettings(TypedDict, total=False):
+    """Settings for CosmosCheckpointStorage resolved from args and environment."""
+
+    endpoint: str | None
+    database_name: str | None
+    container_name: str | None
+    key: SecretString | None
+
+
+class CosmosCheckpointStorage:
+    """Azure Cosmos DB-backed checkpoint storage for workflow checkpointing.
+
+    Implements the ``CheckpointStorage`` protocol using Azure Cosmos DB NoSQL
+    as the persistent backend. Checkpoints are stored as JSON documents with
+    ``workflow_name`` as the partition key, enabling efficient per-workflow queries.
+
+    This storage uses the same hybrid JSON + pickle encoding as
+    ``FileCheckpointStorage``, allowing full Python object fidelity for
+    complex workflow state while keeping the document structure human-readable.
+
+    SECURITY WARNING: Checkpoints use pickle for data serialization. Only load
+    checkpoints from trusted sources. Loading a malicious checkpoint can execute
+    arbitrary code.
+
+    The database and container are created automatically on first use
+    if they do not already exist. The container uses partition key
+    ``/workflow_name``.
+
+    Example using managed identity / RBAC:
+
+    .. code-block:: python
+
+        from azure.identity.aio import DefaultAzureCredential
+        from agent_framework_azure_cosmos import CosmosCheckpointStorage
+
+        storage = CosmosCheckpointStorage(
+            endpoint="https://my-account.documents.azure.com:443/",
+            credential=DefaultAzureCredential(),
+            database_name="agent-db",
+            container_name="checkpoints",
+        )
+
+    Example using account key:
+
+    .. code-block:: python
+
+        storage = CosmosCheckpointStorage(
+            endpoint="https://my-account.documents.azure.com:443/",
+            credential="my-account-key",
+            database_name="agent-db",
+            container_name="checkpoints",
+        )
+
+    Then use with a workflow builder:
+
+    .. code-block:: python
+
+        workflow = WorkflowBuilder(
+            start_executor=start,
+            checkpoint_storage=storage,
+        ).build()
+    """
+
+    def __init__(
+        self,
+        *,
+        endpoint: str | None = None,
+        database_name: str | None = None,
+        container_name: str | None = None,
+        credential: str | AzureCredentialTypes | None = None,
+        cosmos_client: CosmosClient | None = None,
+        container_client: ContainerProxy | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        """Initialize the Azure Cosmos DB checkpoint storage.
+
+        Supports multiple authentication modes:
+
+        - **Container client** (``container_client``): Use a pre-created
+          Cosmos async container proxy. No client lifecycle is managed.
+        - **Cosmos client** (``cosmos_client``): Use a pre-created Cosmos
+          async client. The caller is responsible for closing it.
+        - **Endpoint + credential**: Create a new Cosmos client. The storage
+          owns the client and closes it on ``close()``.
+        - **Environment variables**: Falls back to ``AZURE_COSMOS_ENDPOINT``,
+          ``AZURE_COSMOS_DATABASE_NAME``, ``AZURE_COSMOS_CONTAINER_NAME``,
+          and ``AZURE_COSMOS_KEY``.
+
+        Args:
+            endpoint: Cosmos DB account endpoint.
+                Can be set via ``AZURE_COSMOS_ENDPOINT``.
+            database_name: Cosmos DB database name.
+                Can be set via ``AZURE_COSMOS_DATABASE_NAME``.
+            container_name: Cosmos DB container name.
+                Can be set via ``AZURE_COSMOS_CONTAINER_NAME``.
+            credential: Credential to authenticate with Cosmos DB.
+                For **managed identity / RBAC**, pass an Azure credential object
+                such as ``DefaultAzureCredential()`` or
+                ``ManagedIdentityCredential()``.
+                For **key-based auth**, pass the account key as a string,
+                or set ``AZURE_COSMOS_KEY`` in the environment.
+            cosmos_client: Pre-created Cosmos async client.
+            container_client: Pre-created Cosmos container client.
+            env_file_path: Path to environment file for loading settings.
+            env_file_encoding: Encoding of the environment file.
+        """
+        self._cosmos_client: CosmosClient | None = cosmos_client
+        self._container_proxy: ContainerProxy | None = container_client
+        self._owns_client = False
+
+        if self._container_proxy is not None:
+            self.database_name: str = database_name or ""
+            self.container_name: str = container_name or ""
+            return
+
+        required_fields: list[str] = ["database_name", "container_name"]
+        if cosmos_client is None:
+            required_fields.append("endpoint")
+            if credential is None:
+                required_fields.append("key")
+
+        settings = load_settings(
+            AzureCosmosCheckpointSettings,
+            env_prefix="AZURE_COSMOS_",
+            required_fields=required_fields,
+            endpoint=endpoint,
+            database_name=database_name,
+            container_name=container_name,
+            key=credential if isinstance(credential, str) else None,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+        )
+        self.database_name = settings["database_name"]  # type: ignore[assignment]
+        self.container_name = settings["container_name"]  # type: ignore[assignment]
+
+        if self._cosmos_client is None:
+            self._cosmos_client = CosmosClient(
+                url=settings["endpoint"],  # type: ignore[arg-type]
+                credential=credential or settings["key"].get_secret_value(),  # type: ignore[arg-type,union-attr]
+                user_agent_suffix=AGENT_FRAMEWORK_USER_AGENT,
+            )
+            self._owns_client = True
+
+    async def save(self, checkpoint: WorkflowCheckpoint) -> CheckpointID:
+        """Save a checkpoint to Cosmos DB and return its ID.
+
+        The checkpoint is encoded to a JSON-compatible form (using pickle for
+        non-JSON-native values) and stored as a Cosmos DB document with the
+        ``workflow_name`` as the partition key.
+
+        The document ``id`` is a composite of ``workflow_name`` and
+        ``checkpoint_id`` to ensure global uniqueness across partitions.
+
+        Args:
+            checkpoint: The WorkflowCheckpoint object to save.
+
+        Returns:
+            The unique ID of the saved checkpoint.
+        """
+        await self._ensure_container_proxy()
+
+        checkpoint_dict = checkpoint.to_dict()
+        encoded = encode_checkpoint_value(checkpoint_dict)
+
+        document: dict[str, Any] = {
+            "id": self._make_document_id(checkpoint.workflow_name, checkpoint.checkpoint_id),
+            "workflow_name": checkpoint.workflow_name,
+            **encoded,
+        }
+
+        await self._container_proxy.upsert_item(body=document)  # type: ignore[union-attr]
+        logger.info("Saved checkpoint %s to Cosmos DB", checkpoint.checkpoint_id)
+        return checkpoint.checkpoint_id
+
+    async def load(self, checkpoint_id: CheckpointID) -> WorkflowCheckpoint:
+        """Load a checkpoint from Cosmos DB by ID.
+
+        Args:
+            checkpoint_id: The unique ID of the checkpoint to load.
+
+        Returns:
+            The WorkflowCheckpoint object corresponding to the given ID.
+
+        Raises:
+            WorkflowCheckpointException: If no checkpoint with the given ID exists,
+                or if multiple checkpoints share the same ID across workflows.
+        """
+        await self._ensure_container_proxy()
+
+        query = "SELECT * FROM c WHERE c.checkpoint_id = @checkpoint_id"
+        parameters: list[dict[str, object]] = [
+            {"name": "@checkpoint_id", "value": checkpoint_id},
+        ]
+
+        items = self._container_proxy.query_items(  # type: ignore[union-attr]
+            query=query,
+            parameters=parameters,
+        )
+
+        results: list[dict[str, Any]] = []
+        async for item in items:
+            results.append(item)
+
+        if not results:
+            raise WorkflowCheckpointException(f"No checkpoint found with ID {checkpoint_id}")
+
+        if len(results) > 1:
+            workflow_names = [r.get("workflow_name", "unknown") for r in results]
+            raise WorkflowCheckpointException(
+                f"Multiple checkpoints found with ID {checkpoint_id} across workflows: "
+                f"{workflow_names}. Use list_checkpoints(workflow_name=...) to query "
+                f"by workflow instead."
+            )
+
+        return self._document_to_checkpoint(results[0])
+
+    async def list_checkpoints(self, *, workflow_name: str) -> list[WorkflowCheckpoint]:
+        """List checkpoint objects for a given workflow name.
+
+        Args:
+            workflow_name: The name of the workflow to list checkpoints for.
+
+        Returns:
+            A list of WorkflowCheckpoint objects for the specified workflow name.
+        """
+        await self._ensure_container_proxy()
+
+        query = "SELECT * FROM c WHERE c.workflow_name = @workflow_name ORDER BY c.timestamp ASC"
+        parameters: list[dict[str, object]] = [
+            {"name": "@workflow_name", "value": workflow_name},
+        ]
+
+        items = self._container_proxy.query_items(  # type: ignore[union-attr]
+            query=query,
+            parameters=parameters,
+            partition_key=workflow_name,
+        )
+
+        checkpoints: list[WorkflowCheckpoint] = []
+        async for item in items:
+            try:
+                checkpoints.append(self._document_to_checkpoint(item))
+            except Exception as e:
+                logger.warning("Failed to decode checkpoint document: %s", e)
+        return checkpoints
+
+    async def delete(self, checkpoint_id: CheckpointID) -> bool:
+        """Delete a checkpoint from Cosmos DB by ID.
+
+        Args:
+            checkpoint_id: The unique ID of the checkpoint to delete.
+
+        Returns:
+            True if the checkpoint was successfully deleted, False if not found.
+        """
+        await self._ensure_container_proxy()
+
+        query = "SELECT c.id, c.workflow_name FROM c WHERE c.checkpoint_id = @checkpoint_id"
+        parameters: list[dict[str, object]] = [
+            {"name": "@checkpoint_id", "value": checkpoint_id},
+        ]
+
+        items = self._container_proxy.query_items(  # type: ignore[union-attr]
+            query=query,
+            parameters=parameters,
+        )
+
+        async for item in items:
+            try:
+                await self._container_proxy.delete_item(  # type: ignore[union-attr]
+                    item=item["id"],
+                    partition_key=item["workflow_name"],
+                )
+                logger.info("Deleted checkpoint %s from Cosmos DB", checkpoint_id)
+                return True
+            except CosmosResourceNotFoundError:
+                return False
+
+        return False
+
+    async def get_latest(self, *, workflow_name: str) -> WorkflowCheckpoint | None:
+        """Get the latest checkpoint for a given workflow name.
+
+        Args:
+            workflow_name: The name of the workflow to get the latest checkpoint for.
+
+        Returns:
+            The latest WorkflowCheckpoint, or None if no checkpoints exist.
+        """
+        await self._ensure_container_proxy()
+
+        query = "SELECT * FROM c WHERE c.workflow_name = @workflow_name ORDER BY c.timestamp DESC OFFSET 0 LIMIT 1"
+        parameters: list[dict[str, object]] = [
+            {"name": "@workflow_name", "value": workflow_name},
+        ]
+
+        items = self._container_proxy.query_items(  # type: ignore[union-attr]
+            query=query,
+            parameters=parameters,
+            partition_key=workflow_name,
+        )
+
+        async for item in items:
+            checkpoint = self._document_to_checkpoint(item)
+            logger.debug(
+                "Latest checkpoint for workflow %s is %s",
+                workflow_name,
+                checkpoint.checkpoint_id,
+            )
+            return checkpoint
+
+        return None
+
+    async def list_checkpoint_ids(self, *, workflow_name: str) -> list[CheckpointID]:
+        """List checkpoint IDs for a given workflow name.
+
+        Args:
+            workflow_name: The name of the workflow to list checkpoint IDs for.
+
+        Returns:
+            A list of checkpoint IDs for the specified workflow name.
+        """
+        await self._ensure_container_proxy()
+
+        query = "SELECT c.checkpoint_id FROM c WHERE c.workflow_name = @workflow_name ORDER BY c.timestamp ASC"
+        parameters: list[dict[str, object]] = [
+            {"name": "@workflow_name", "value": workflow_name},
+        ]
+
+        items = self._container_proxy.query_items(  # type: ignore[union-attr]
+            query=query,
+            parameters=parameters,
+            partition_key=workflow_name,
+        )
+
+        checkpoint_ids: list[CheckpointID] = []
+        async for item in items:
+            cid = item.get("checkpoint_id")
+            if isinstance(cid, str):
+                checkpoint_ids.append(cid)
+        return checkpoint_ids
+
+    async def close(self) -> None:
+        """Close the underlying Cosmos client when this storage owns it."""
+        if self._owns_client and self._cosmos_client is not None:
+            await self._cosmos_client.close()
+
+    async def __aenter__(self) -> CosmosCheckpointStorage:
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Async context manager exit."""
+        try:
+            await self.close()
+        except Exception:
+            if exc_type is None:
+                raise
+
+    async def _ensure_container_proxy(self) -> None:
+        """Get or create the Cosmos DB database and container for storing checkpoints."""
+        if self._container_proxy is not None:
+            return
+        if self._cosmos_client is None:
+            raise RuntimeError("Cosmos client is not initialized.")
+
+        database = await self._cosmos_client.create_database_if_not_exists(id=self.database_name)
+        self._container_proxy = await database.create_container_if_not_exists(
+            id=self.container_name,
+            partition_key=PartitionKey(path="/workflow_name"),
+        )
+
+    @staticmethod
+    def _document_to_checkpoint(document: dict[str, Any]) -> WorkflowCheckpoint:
+        """Convert a Cosmos DB document back to a WorkflowCheckpoint.
+
+        Strips Cosmos DB system properties (``_rid``, ``_self``, ``_etag``,
+        ``_attachments``, ``_ts``) before decoding.
+        """
+        # Remove Cosmos DB system properties and the composite 'id' field
+        # (checkpoints use 'checkpoint_id', not 'id')
+        cosmos_keys = {"id", "_rid", "_self", "_etag", "_attachments", "_ts"}
+        cleaned = {k: v for k, v in document.items() if k not in cosmos_keys}
+
+        decoded = decode_checkpoint_value(cleaned)
+        return WorkflowCheckpoint.from_dict(decoded)
+
+    @staticmethod
+    def _make_document_id(workflow_name: str, checkpoint_id: str) -> str:
+        """Create a composite Cosmos DB document ID.
+
+        Combines ``workflow_name`` and ``checkpoint_id`` to ensure global
+        uniqueness across partitions.
+        """
+        return f"{workflow_name}_{checkpoint_id}"

python/packages/azure-cosmos/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Cosmos DB history provider integration for Microsoft Agent
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "azure-cosmos>=4.3.0,<5",
 ]
 

python/packages/azure-cosmos/tests/test_cosmos_checkpoint_storage.py

@@ -0,0 +1,597 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+import os
+import uuid
+from collections.abc import AsyncIterator
+from contextlib import suppress
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from agent_framework._workflows._checkpoint import WorkflowCheckpoint
+from agent_framework._workflows._checkpoint_encoding import encode_checkpoint_value
+from agent_framework.exceptions import SettingNotFoundError, WorkflowCheckpointException
+from azure.cosmos.aio import CosmosClient
+from azure.cosmos.exceptions import CosmosResourceNotFoundError
+
+import agent_framework_azure_cosmos._checkpoint_storage as checkpoint_storage_module
+from agent_framework_azure_cosmos._checkpoint_storage import CosmosCheckpointStorage
+
+skip_if_cosmos_integration_tests_disabled = pytest.mark.skipif(
+    any(
+        os.getenv(name, "") == ""
+        for name in (
+            "AZURE_COSMOS_ENDPOINT",
+            "AZURE_COSMOS_KEY",
+            "AZURE_COSMOS_DATABASE_NAME",
+            "AZURE_COSMOS_CONTAINER_NAME",
+        )
+    ),
+    reason=(
+        "AZURE_COSMOS_ENDPOINT, AZURE_COSMOS_KEY, AZURE_COSMOS_DATABASE_NAME, and "
+        "AZURE_COSMOS_CONTAINER_NAME are required for Cosmos integration tests."
+    ),
+)
+
+
+def _to_async_iter(items: list[Any]) -> AsyncIterator[Any]:
+    async def _iterator() -> AsyncIterator[Any]:
+        for item in items:
+            yield item
+
+    return _iterator()
+
+
+def _make_checkpoint(
+    workflow_name: str = "test-workflow",
+    checkpoint_id: str | None = None,
+    previous_checkpoint_id: str | None = None,
+    timestamp: str | None = None,
+) -> WorkflowCheckpoint:
+    """Create a minimal WorkflowCheckpoint for testing."""
+    return WorkflowCheckpoint(
+        workflow_name=workflow_name,
+        graph_signature_hash="abc123",
+        checkpoint_id=checkpoint_id or str(uuid.uuid4()),
+        previous_checkpoint_id=previous_checkpoint_id,
+        timestamp=timestamp or "2025-01-01T00:00:00+00:00",
+        state={"counter": 42},
+        iteration_count=1,
+    )
+
+
+def _checkpoint_to_cosmos_document(checkpoint: WorkflowCheckpoint) -> dict[str, Any]:
+    """Simulate what a Cosmos DB document looks like after save."""
+    encoded = encode_checkpoint_value(checkpoint.to_dict())
+    doc: dict[str, Any] = {
+        "id": f"{checkpoint.workflow_name}_{checkpoint.checkpoint_id}",
+        "workflow_name": checkpoint.workflow_name,
+        **encoded,
+        # Cosmos system properties
+        "_rid": "abc",
+        "_self": "dbs/abc/colls/def/docs/ghi",
+        "_etag": '"00000000-0000-0000-0000-000000000000"',
+        "_attachments": "attachments/",
+        "_ts": 1700000000,
+    }
+    return doc
+
+
+@pytest.fixture
+def mock_container() -> MagicMock:
+    container = MagicMock()
+    container.query_items = MagicMock(return_value=_to_async_iter([]))
+    container.upsert_item = AsyncMock(return_value={})
+    container.delete_item = AsyncMock(return_value={})
+    return container
+
+
+@pytest.fixture
+def mock_cosmos_client(mock_container: MagicMock) -> MagicMock:
+    database_client = MagicMock()
+    database_client.create_container_if_not_exists = AsyncMock(return_value=mock_container)
+
+    client = MagicMock()
+    client.create_database_if_not_exists = AsyncMock(return_value=database_client)
+    client.close = AsyncMock()
+    return client
+
+
+# --- Tests for initialization ---
+
+
+async def test_init_uses_provided_container_client(mock_container: MagicMock) -> None:
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    assert storage.database_name == ""
+    assert storage.container_name == ""
+
+
+async def test_init_uses_provided_cosmos_client(mock_cosmos_client: MagicMock) -> None:
+    storage = CosmosCheckpointStorage(
+        cosmos_client=mock_cosmos_client,
+        database_name="db1",
+        container_name="checkpoints",
+    )
+    assert storage.database_name == "db1"
+    assert storage.container_name == "checkpoints"
+
+
+async def test_init_missing_required_settings_raises(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("AZURE_COSMOS_ENDPOINT", raising=False)
+    monkeypatch.delenv("AZURE_COSMOS_DATABASE_NAME", raising=False)
+    monkeypatch.delenv("AZURE_COSMOS_CONTAINER_NAME", raising=False)
+    monkeypatch.delenv("AZURE_COSMOS_KEY", raising=False)
+
+    with pytest.raises(SettingNotFoundError, match="database_name"):
+        CosmosCheckpointStorage()
+
+
+async def test_init_constructs_client_with_credential(
+    monkeypatch: pytest.MonkeyPatch, mock_cosmos_client: MagicMock
+) -> None:
+    """Uses key-based auth when a key string is provided, otherwise falls back to Azure credential (RBAC)."""
+    mock_factory = MagicMock(return_value=mock_cosmos_client)
+    monkeypatch.setattr(checkpoint_storage_module, "CosmosClient", mock_factory)
+    monkeypatch.delenv("AZURE_COSMOS_KEY", raising=False)
+
+    # Simulate real-world pattern: use key if available, else RBAC credential
+    cosmos_key = os.getenv("AZURE_COSMOS_KEY")
+    credential: Any = cosmos_key if cosmos_key else MagicMock()  # MagicMock simulates DefaultAzureCredential()
+
+    CosmosCheckpointStorage(
+        endpoint="https://account.documents.azure.com:443/",
+        credential=credential,
+        database_name="db1",
+        container_name="checkpoints",
+    )
+
+    mock_factory.assert_called_once()
+    kwargs = mock_factory.call_args.kwargs
+    assert kwargs["url"] == "https://account.documents.azure.com:443/"
+    assert kwargs["credential"] is credential
+
+
+async def test_init_creates_database_and_container(mock_cosmos_client: MagicMock) -> None:
+    storage = CosmosCheckpointStorage(
+        cosmos_client=mock_cosmos_client,
+        database_name="db1",
+        container_name="custom-checkpoints",
+    )
+
+    await storage.list_checkpoint_ids(workflow_name="wf")
+
+    mock_cosmos_client.create_database_if_not_exists.assert_awaited_once_with(id="db1")
+    database_client = mock_cosmos_client.create_database_if_not_exists.return_value
+    assert database_client.create_container_if_not_exists.await_count == 1
+    kwargs = database_client.create_container_if_not_exists.await_args.kwargs
+    assert kwargs["id"] == "custom-checkpoints"
+
+
+# --- Tests for save ---
+
+
+async def test_save_upserts_document(mock_container: MagicMock) -> None:
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    checkpoint = _make_checkpoint()
+
+    result = await storage.save(checkpoint)
+
+    assert result == checkpoint.checkpoint_id
+    mock_container.upsert_item.assert_awaited_once()
+    document = mock_container.upsert_item.await_args.kwargs["body"]
+    assert document["id"] == f"test-workflow_{checkpoint.checkpoint_id}"
+    assert document["workflow_name"] == "test-workflow"
+    assert document["graph_signature_hash"] == "abc123"
+    assert document["state"]["counter"] == 42
+
+
+async def test_save_returns_checkpoint_id(mock_container: MagicMock) -> None:
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    checkpoint = _make_checkpoint(checkpoint_id="cp-123")
+
+    result = await storage.save(checkpoint)
+
+    assert result == "cp-123"
+
+
+# --- Tests for load ---
+
+
+async def test_load_returns_checkpoint(mock_container: MagicMock) -> None:
+    checkpoint = _make_checkpoint(checkpoint_id="cp-load")
+    doc = _checkpoint_to_cosmos_document(checkpoint)
+    mock_container.query_items.return_value = _to_async_iter([doc])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    loaded = await storage.load("cp-load")
+
+    assert loaded.checkpoint_id == "cp-load"
+    assert loaded.workflow_name == "test-workflow"
+    assert loaded.graph_signature_hash == "abc123"
+    assert loaded.state["counter"] == 42
+
+
+async def test_load_nonexistent_raises(mock_container: MagicMock) -> None:
+    mock_container.query_items.return_value = _to_async_iter([])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+
+    with pytest.raises(WorkflowCheckpointException, match="No checkpoint found"):
+        await storage.load("nonexistent-id")
+
+
+async def test_load_queries_without_partition_key(mock_container: MagicMock) -> None:
+    mock_container.query_items.return_value = _to_async_iter([])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    with suppress(WorkflowCheckpointException):
+        await storage.load("cp-id")
+
+    kwargs = mock_container.query_items.call_args.kwargs
+    assert "partition_key" not in kwargs
+
+
+async def test_load_multiple_workflows_same_checkpoint_id_raises(mock_container: MagicMock) -> None:
+    cp1 = _make_checkpoint(checkpoint_id="shared-id", workflow_name="workflow-a")
+    cp2 = _make_checkpoint(checkpoint_id="shared-id", workflow_name="workflow-b")
+    mock_container.query_items.return_value = _to_async_iter([
+        _checkpoint_to_cosmos_document(cp1),
+        _checkpoint_to_cosmos_document(cp2),
+    ])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+
+    with pytest.raises(WorkflowCheckpointException, match="Multiple checkpoints found"):
+        await storage.load("shared-id")
+
+
+# --- Tests for list_checkpoints ---
+
+
+async def test_list_checkpoints_returns_checkpoints_for_workflow(mock_container: MagicMock) -> None:
+    cp1 = _make_checkpoint(checkpoint_id="cp-1", timestamp="2025-01-01T00:00:00+00:00")
+    cp2 = _make_checkpoint(checkpoint_id="cp-2", timestamp="2025-01-02T00:00:00+00:00")
+    mock_container.query_items.return_value = _to_async_iter([
+        _checkpoint_to_cosmos_document(cp1),
+        _checkpoint_to_cosmos_document(cp2),
+    ])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    results = await storage.list_checkpoints(workflow_name="test-workflow")
+
+    assert len(results) == 2
+    assert results[0].checkpoint_id == "cp-1"
+    assert results[1].checkpoint_id == "cp-2"
+
+
+async def test_list_checkpoints_uses_partition_key(mock_container: MagicMock) -> None:
+    mock_container.query_items.return_value = _to_async_iter([])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    await storage.list_checkpoints(workflow_name="my-workflow")
+
+    kwargs = mock_container.query_items.call_args.kwargs
+    assert kwargs["partition_key"] == "my-workflow"
+
+
+async def test_list_checkpoints_empty_returns_empty(mock_container: MagicMock) -> None:
+    mock_container.query_items.return_value = _to_async_iter([])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    results = await storage.list_checkpoints(workflow_name="test-workflow")
+
+    assert results == []
+
+
+async def test_list_checkpoints_skips_malformed_documents(mock_container: MagicMock) -> None:
+    valid_cp = _make_checkpoint(checkpoint_id="cp-valid")
+    mock_container.query_items.return_value = _to_async_iter([
+        {"id": "bad_doc", "workflow_name": "test-workflow", "not_a_checkpoint": True},
+        _checkpoint_to_cosmos_document(valid_cp),
+    ])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    results = await storage.list_checkpoints(workflow_name="test-workflow")
+
+    assert len(results) == 1
+    assert results[0].checkpoint_id == "cp-valid"
+
+
+# --- Tests for delete ---
+
+
+async def test_delete_existing_returns_true(mock_container: MagicMock) -> None:
+    mock_container.query_items.return_value = _to_async_iter([
+        {"id": "test-workflow_cp-del", "workflow_name": "test-workflow"},
+    ])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    result = await storage.delete("cp-del")
+
+    assert result is True
+    mock_container.delete_item.assert_awaited_once_with(
+        item="test-workflow_cp-del",
+        partition_key="test-workflow",
+    )
+
+
+async def test_delete_nonexistent_returns_false(mock_container: MagicMock) -> None:
+    mock_container.query_items.return_value = _to_async_iter([])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    result = await storage.delete("nonexistent")
+
+    assert result is False
+    mock_container.delete_item.assert_not_awaited()
+
+
+async def test_delete_cosmos_not_found_returns_false(mock_container: MagicMock) -> None:
+    mock_container.query_items.return_value = _to_async_iter([
+        {"id": "test-workflow_cp-del", "workflow_name": "test-workflow"},
+    ])
+    mock_container.delete_item = AsyncMock(side_effect=CosmosResourceNotFoundError)
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    result = await storage.delete("cp-del")
+
+    assert result is False
+
+
+# --- Tests for get_latest ---
+
+
+async def test_get_latest_returns_latest_checkpoint(mock_container: MagicMock) -> None:
+    cp = _make_checkpoint(checkpoint_id="cp-latest", timestamp="2025-06-01T00:00:00+00:00")
+    mock_container.query_items.return_value = _to_async_iter([
+        _checkpoint_to_cosmos_document(cp),
+    ])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    result = await storage.get_latest(workflow_name="test-workflow")
+
+    assert result is not None
+    assert result.checkpoint_id == "cp-latest"
+
+
+async def test_get_latest_returns_none_when_empty(mock_container: MagicMock) -> None:
+    mock_container.query_items.return_value = _to_async_iter([])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    result = await storage.get_latest(workflow_name="test-workflow")
+
+    assert result is None
+
+
+async def test_get_latest_uses_order_by_desc_with_limit(mock_container: MagicMock) -> None:
+    mock_container.query_items.return_value = _to_async_iter([])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    await storage.get_latest(workflow_name="test-workflow")
+
+    kwargs = mock_container.query_items.call_args.kwargs
+    assert "ORDER BY c.timestamp DESC" in kwargs["query"]
+    assert "OFFSET 0 LIMIT 1" in kwargs["query"]
+
+
+# --- Tests for list_checkpoint_ids ---
+
+
+async def test_list_checkpoint_ids_returns_ids(mock_container: MagicMock) -> None:
+    mock_container.query_items.return_value = _to_async_iter([
+        {"checkpoint_id": "cp-1"},
+        {"checkpoint_id": "cp-2"},
+    ])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    ids = await storage.list_checkpoint_ids(workflow_name="test-workflow")
+
+    assert ids == ["cp-1", "cp-2"]
+
+
+async def test_list_checkpoint_ids_empty_returns_empty(mock_container: MagicMock) -> None:
+    mock_container.query_items.return_value = _to_async_iter([])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    ids = await storage.list_checkpoint_ids(workflow_name="test-workflow")
+
+    assert ids == []
+
+
+# --- Tests for close and context manager ---
+
+
+async def test_close_closes_owned_client(monkeypatch: pytest.MonkeyPatch, mock_cosmos_client: MagicMock) -> None:
+    mock_factory = MagicMock(return_value=mock_cosmos_client)
+    monkeypatch.setattr(checkpoint_storage_module, "CosmosClient", mock_factory)
+
+    storage = CosmosCheckpointStorage(
+        endpoint="https://account.documents.azure.com:443/",
+        credential="key-123",
+        database_name="db1",
+        container_name="checkpoints",
+    )
+
+    await storage.close()
+
+    mock_cosmos_client.close.assert_awaited_once()
+
+
+async def test_close_does_not_close_external_client(mock_cosmos_client: MagicMock) -> None:
+    storage = CosmosCheckpointStorage(
+        cosmos_client=mock_cosmos_client,
+        database_name="db1",
+        container_name="checkpoints",
+    )
+
+    await storage.close()
+
+    mock_cosmos_client.close.assert_not_awaited()
+
+
+async def test_context_manager_closes_owned_client(
+    monkeypatch: pytest.MonkeyPatch, mock_cosmos_client: MagicMock
+) -> None:
+    mock_factory = MagicMock(return_value=mock_cosmos_client)
+    monkeypatch.setattr(checkpoint_storage_module, "CosmosClient", mock_factory)
+
+    async with CosmosCheckpointStorage(
+        endpoint="https://account.documents.azure.com:443/",
+        credential="key-123",
+        database_name="db1",
+        container_name="checkpoints",
+    ) as storage:
+        assert storage is not None
+
+    mock_cosmos_client.close.assert_awaited_once()
+
+
+async def test_context_manager_preserves_original_exception(mock_container: MagicMock) -> None:
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+
+    with (
+        patch.object(storage, "close", AsyncMock(side_effect=RuntimeError("close failed"))),
+        pytest.raises(ValueError, match="inner error"),
+    ):
+        async with storage:
+            raise ValueError("inner error")
+
+
+async def test_context_manager_reraises_close_error(mock_container: MagicMock) -> None:
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+
+    with (
+        patch.object(storage, "close", AsyncMock(side_effect=RuntimeError("close failed"))),
+        pytest.raises(RuntimeError, match="close failed"),
+    ):
+        async with storage:
+            pass  # no inner exception — close error should propagate
+
+
+# --- Tests for save/load round-trip ---
+
+
+async def test_round_trip_preserves_data(mock_container: MagicMock) -> None:
+    checkpoint = _make_checkpoint(
+        checkpoint_id="cp-roundtrip",
+        previous_checkpoint_id="cp-parent",
+    )
+    checkpoint.state = {"key": "value", "nested": {"a": 1}}
+    checkpoint.metadata = {"superstep": 3}
+    checkpoint.iteration_count = 5
+
+    saved_doc: dict[str, Any] = {}
+
+    async def capture_upsert(body: dict[str, Any]) -> dict[str, Any]:
+        saved_doc.update(body)
+        return body
+
+    mock_container.upsert_item = AsyncMock(side_effect=capture_upsert)
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    await storage.save(checkpoint)
+
+    returned_doc = {
+        **saved_doc,
+        "_rid": "abc",
+        "_self": "dbs/abc/colls/def/docs/ghi",
+        "_etag": '"etag"',
+        "_attachments": "attachments/",
+        "_ts": 1700000000,
+    }
+    mock_container.query_items.return_value = _to_async_iter([returned_doc])
+
+    loaded = await storage.load("cp-roundtrip")
+
+    assert loaded.checkpoint_id == checkpoint.checkpoint_id
+    assert loaded.workflow_name == checkpoint.workflow_name
+    assert loaded.graph_signature_hash == checkpoint.graph_signature_hash
+    assert loaded.previous_checkpoint_id == "cp-parent"
+    assert loaded.state == {"key": "value", "nested": {"a": 1}}
+    assert loaded.metadata == {"superstep": 3}
+    assert loaded.iteration_count == 5
+    assert loaded.version == "1.0"
+
+
+# --- Integration test ---
+
+
+@pytest.mark.integration
+@skip_if_cosmos_integration_tests_disabled
+async def test_cosmos_checkpoint_storage_roundtrip_with_emulator() -> None:
+    endpoint = os.getenv("AZURE_COSMOS_ENDPOINT", "")
+    key = os.getenv("AZURE_COSMOS_KEY", "")
+    database_prefix = os.getenv("AZURE_COSMOS_DATABASE_NAME", "")
+    container_prefix = os.getenv("AZURE_COSMOS_CONTAINER_NAME", "")
+    unique = uuid.uuid4().hex[:8]
+    database_name = f"{database_prefix}-cp-{unique}"
+    container_name = f"{container_prefix}-cp-{unique}"
+
+    async with CosmosClient(url=endpoint, credential=key) as cosmos_client:
+        await cosmos_client.create_database_if_not_exists(id=database_name)
+
+        storage = CosmosCheckpointStorage(
+            cosmos_client=cosmos_client,
+            database_name=database_name,
+            container_name=container_name,
+        )
+
+        try:
+            # Save two checkpoints for the same workflow
+            cp1 = _make_checkpoint(
+                checkpoint_id="cp-int-1",
+                workflow_name="integration-wf",
+                timestamp="2025-01-01T00:00:00+00:00",
+            )
+            cp2 = _make_checkpoint(
+                checkpoint_id="cp-int-2",
+                workflow_name="integration-wf",
+                previous_checkpoint_id="cp-int-1",
+                timestamp="2025-01-02T00:00:00+00:00",
+            )
+            cp2.state = {"step": 2}
+
+            await storage.save(cp1)
+            await storage.save(cp2)
+
+            # Load by ID
+            loaded = await storage.load("cp-int-1")
+            assert loaded.checkpoint_id == "cp-int-1"
+            assert loaded.workflow_name == "integration-wf"
+
+            # List all checkpoints for workflow
+            all_cps = await storage.list_checkpoints(workflow_name="integration-wf")
+            assert len(all_cps) == 2
+
+            # List checkpoint IDs
+            ids = await storage.list_checkpoint_ids(workflow_name="integration-wf")
+            assert "cp-int-1" in ids
+            assert "cp-int-2" in ids
+
+            # Get latest
+            latest = await storage.get_latest(workflow_name="integration-wf")
+            assert latest is not None
+            assert latest.checkpoint_id == "cp-int-2"
+            assert latest.state == {"step": 2}
+
+            # Delete
+            assert await storage.delete("cp-int-1") is True
+            assert await storage.delete("cp-int-1") is False
+
+            remaining = await storage.list_checkpoint_ids(workflow_name="integration-wf")
+            assert remaining == ["cp-int-2"]
+
+            # Cross-workflow isolation
+            other_cp = _make_checkpoint(
+                checkpoint_id="cp-other",
+                workflow_name="other-wf",
+            )
+            await storage.save(other_cp)
+            wf_cps = await storage.list_checkpoints(workflow_name="integration-wf")
+            assert len(wf_cps) == 1
+            assert wf_cps[0].checkpoint_id == "cp-int-2"
+
+        finally:
+            with suppress(Exception):
+                await cosmos_client.delete_database(database_name)

python/packages/azurefunctions/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Functions integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "agent-framework-durabletask",
     "azure-functions>=1.24.0,<2",
     "azure-functions-durable>=1.3.1,<2",

python/packages/bedrock/pyproject.toml

@@ -4,7 +4,7 @@ description = "Amazon Bedrock integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "boto3>=1.35.0,<2.0.0",
     "botocore>=1.35.0,<2.0.0",
 ]

python/packages/chatkit/pyproject.toml

@@ -4,7 +4,7 @@ description = "OpenAI ChatKit integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "openai-chatkit>=1.4.1,<2.0.0",
 ]
 

python/packages/claude/pyproject.toml

@@ -4,7 +4,7 @@ description = "Claude Agent SDK integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "claude-agent-sdk>=0.1.36,<0.1.49",
 ]
 

python/packages/copilotstudio/pyproject.toml

@@ -4,7 +4,7 @@ description = "Copilot Studio integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "microsoft-agents-copilotstudio-client>=0.3.1,<0.3.2",
 ]
 

python/packages/core/agent_framework/_workflows/_checkpoint.py

@@ -244,14 +244,39 @@ class FileCheckpointStorage:
     is serialized using pickle and embedded as base64-encoded strings within the JSON. This allows
     for human-readable checkpoint files while preserving the ability to store complex Python objects.
 
-    SECURITY WARNING: Checkpoints use pickle for data serialization. Only load checkpoints
-    from trusted sources. Loading a malicious checkpoint file can execute arbitrary code.
+    By default, checkpoint deserialization is restricted to a built-in set of safe
+    Python types (primitives, datetime, uuid, ...) and all ``agent_framework``
+    internal types.  To allow additional application-specific types, pass them via
+    the ``allowed_checkpoint_types`` parameter using ``"module:qualname"`` format.
+
+    Example::
+
+        storage = FileCheckpointStorage(
+            "/tmp/checkpoints",
+            allowed_checkpoint_types=[
+                "my_app.models:MyState",
+            ],
+        )
     """
 
-    def __init__(self, storage_path: str | Path):
-        """Initialize the file storage."""
+    def __init__(
+        self,
+        storage_path: str | Path,
+        *,
+        allowed_checkpoint_types: list[str] | None = None,
+    ) -> None:
+        """Initialize the file storage.
+
+        Args:
+            storage_path: Directory path where checkpoint files will be stored.
+            allowed_checkpoint_types: Additional types (beyond the built-in safe set
+                and framework types) that are permitted during checkpoint
+                deserialization.  Each entry should be a ``"module:qualname"``
+                string (e.g., ``"my_app.models:MyState"``).
+        """
         self.storage_path = Path(storage_path)
         self.storage_path.mkdir(parents=True, exist_ok=True)
+        self._allowed_types: frozenset[str] = frozenset(allowed_checkpoint_types or [])
         logger.info(f"Initialized file checkpoint storage at {self.storage_path}")
 
     def _validate_file_path(self, checkpoint_id: CheckpointID) -> Path:
@@ -327,7 +352,7 @@ class FileCheckpointStorage:
         from ._checkpoint_encoding import decode_checkpoint_value
 
         try:
-            decoded_checkpoint_dict = decode_checkpoint_value(encoded_checkpoint)
+            decoded_checkpoint_dict = decode_checkpoint_value(encoded_checkpoint, allowed_types=self._allowed_types)
         except WorkflowCheckpointException:
             raise
         checkpoint = WorkflowCheckpoint.from_dict(decoded_checkpoint_dict)
@@ -352,7 +377,9 @@ class FileCheckpointStorage:
                         encoded_checkpoint = json.load(f)
                         from ._checkpoint_encoding import decode_checkpoint_value
 
-                        decoded_checkpoint_dict = decode_checkpoint_value(encoded_checkpoint)
+                        decoded_checkpoint_dict = decode_checkpoint_value(
+                            encoded_checkpoint, allowed_types=self._allowed_types
+                        )
                         checkpoint = WorkflowCheckpoint.from_dict(decoded_checkpoint_dict)
                     if checkpoint.workflow_name == workflow_name:
                         checkpoints.append(checkpoint)

python/packages/core/agent_framework/_workflows/_checkpoint_encoding.py

@@ -1,14 +1,5 @@
 # Copyright (c) Microsoft. All rights reserved.
 
-from __future__ import annotations
-
-import base64
-import logging
-import pickle  # nosec  # noqa: S403
-from typing import Any
-
-from ..exceptions import WorkflowCheckpointException
-
 """Checkpoint encoding using JSON structure with pickle+base64 for arbitrary data.
 
 This hybrid approach provides:
@@ -16,10 +7,23 @@ This hybrid approach provides:
 - Full Python object fidelity via pickle for data values (non-JSON-native types)
 - Base64 encoding to embed binary pickle data in JSON strings
 
-SECURITY WARNING: Checkpoints use pickle for data serialization. Only load checkpoints
-from trusted sources. Loading a malicious checkpoint file can execute arbitrary code.
+When ``allowed_types`` is supplied to :func:`decode_checkpoint_value`, a
+``RestrictedUnpickler`` is used that limits which classes may be instantiated
+during deserialization.  The default built-in safe set covers common Python
+value types (primitives, datetime, uuid, ...) and all ``agent_framework``
+internal types.  Callers can extend the set by passing additional
+``"module:qualname"`` strings.
 """
 
+from __future__ import annotations
+
+import base64
+import io
+import logging
+import pickle  # nosec  # noqa: S403
+from typing import Any
+
+from ..exceptions import WorkflowCheckpointException
 
 logger = logging.getLogger("agent_framework")
 
@@ -30,6 +34,82 @@ _TYPE_MARKER = "__type__"
 # Types that are natively JSON-serializable and don't need pickling
 _JSON_NATIVE_TYPES = (str, int, float, bool, type(None))
 
+# Module prefix for framework-internal types that are always allowed
+_FRAMEWORK_MODULE_PREFIX = "agent_framework."
+
+# Built-in types considered safe for checkpoint deserialization.
+# Each entry is a ``module:qualname`` string matching the format produced by
+# :func:`_type_to_key`.  These are the classes for which pickle's
+# ``find_class`` will be called when unpickling common Python value types.
+_BUILTIN_ALLOWED_TYPE_KEYS: frozenset[str] = frozenset({
+    # builtins
+    "builtins:object",
+    "builtins:complex",
+    "builtins:range",
+    "builtins:slice",
+    "builtins:int",
+    "builtins:float",
+    "builtins:str",
+    "builtins:bytes",
+    "builtins:bytearray",
+    "builtins:bool",
+    "builtins:set",
+    "builtins:frozenset",
+    "builtins:list",
+    "builtins:dict",
+    "builtins:tuple",
+    "builtins:type",
+    # getattr is used by pickle to reconstruct enum members
+    "builtins:getattr",
+    # copyreg helpers used by pickle for object reconstruction
+    "copyreg:_reconstructor",
+    # datetime
+    "datetime:datetime",
+    "datetime:date",
+    "datetime:time",
+    "datetime:timedelta",
+    "datetime:timezone",
+    # uuid
+    "uuid:UUID",
+    # decimal
+    "decimal:Decimal",
+    # collections
+    "collections:OrderedDict",
+    "collections:defaultdict",
+    "collections:deque",
+})
+
+
+class _RestrictedUnpickler(pickle.Unpickler):  # noqa: S301
+    """Unpickler that restricts which classes may be instantiated.
+
+    Only classes whose ``module:qualname`` key appears in the combined allow
+    set (built-in safe types + framework types + caller-specified extras) are
+    permitted.  All other classes raise :class:`pickle.UnpicklingError`.
+    """
+
+    def __init__(self, data: bytes, allowed_types: frozenset[str]) -> None:
+        super().__init__(io.BytesIO(data))
+        self._allowed_types = allowed_types
+
+    def find_class(self, module: str, name: str) -> type:
+        type_key = f"{module}:{name}"
+
+        if (
+            type_key in _BUILTIN_ALLOWED_TYPE_KEYS
+            or type_key in self._allowed_types
+            or module.startswith(_FRAMEWORK_MODULE_PREFIX)
+        ):
+            return super().find_class(module, name)  # type: ignore[no-any-return]  # nosec
+
+        raise pickle.UnpicklingError(
+            f"Checkpoint deserialization blocked for type '{type_key}'. "
+            f"To allow this type, either include its 'module:qualname' key in the "
+            f"'allowed_types' set passed to 'decode_checkpoint_value', or add it to "
+            f"'allowed_checkpoint_types' on your checkpoint storage "
+            f"(for example, 'FileCheckpointStorage.allowed_checkpoint_types')."
+        )
+
 
 def encode_checkpoint_value(value: Any) -> Any:
     """Encode a Python value for checkpoint storage.
@@ -48,29 +128,51 @@ def encode_checkpoint_value(value: Any) -> Any:
     return _encode(value)
 
 
-def decode_checkpoint_value(value: Any) -> Any:
+def decode_checkpoint_value(value: Any, *, allowed_types: frozenset[str] | None = None) -> Any:
     """Decode a value from checkpoint storage.
 
     Reverses the encoding performed by encode_checkpoint_value.
     Pickled values (identified by _PICKLE_MARKER) are decoded and unpickled.
 
-    WARNING: Only call this with trusted data. Pickle can execute
-    arbitrary code during deserialization. The post-unpickle type verification
-    detects accidental corruption or type mismatches, but cannot prevent
-    arbitrary code execution from malicious pickle payloads.
-
     Args:
         value: A JSON-deserialized value from checkpoint storage.
+        allowed_types: If not ``None``, restrict pickle deserialization to the
+            built-in safe set, framework types, and the types listed here.
+            Each entry should use ``"module:qualname"`` format — that is, the
+            dotted module path followed by a colon and the class
+            ``__qualname__``.  For example, given a user-defined class::
+
+                # my_app/models.py
+                class MyState: ...
+
+            the corresponding entry would be ``"my_app.models:MyState"``::
+
+                decode_checkpoint_value(
+                    data,
+                    allowed_types=frozenset({"my_app.models:MyState"}),
+                )
+
+            When using :class:`FileCheckpointStorage`, pass the same strings
+            via ``allowed_checkpoint_types``::
+
+                storage = FileCheckpointStorage(
+                    "/tmp/checkpoints",
+                    allowed_checkpoint_types=["my_app.models:MyState"],
+                )
+
+            If ``None``, no restriction is applied (backward-compatible
+            behavior).
 
     Returns:
         The original Python value.
 
     Raises:
         WorkflowCheckpointException: If the unpickled object's type doesn't match
-            the recorded type, indicating corruption, or if the base64/pickle
-            data is malformed.
+            the recorded type, indicating corruption, if the base64/pickle
+            data is malformed, or if a disallowed type is encountered during
+            restricted deserialization.
     """
-    return _decode(value)
+    return _decode(value, allowed_types=allowed_types)
 
 
 def _encode(value: Any) -> Any:
@@ -94,7 +196,7 @@ def _encode(value: Any) -> Any:
     }
 
 
-def _decode(value: Any) -> Any:
+def _decode(value: Any, *, allowed_types: frozenset[str] | None = None) -> Any:
     """Recursively decode a value from JSON storage."""
     # JSON-native types pass through
     if isinstance(value, _JSON_NATIVE_TYPES):
@@ -104,16 +206,16 @@ def _decode(value: Any) -> Any:
     if isinstance(value, dict):
         # Pickled value: decode, unpickle, and verify type
         if _PICKLE_MARKER in value and _TYPE_MARKER in value:
-            obj = _base64_to_unpickle(value[_PICKLE_MARKER])  # type: ignore
+            obj = _base64_to_unpickle(value[_PICKLE_MARKER], allowed_types=allowed_types)  # type: ignore
             _verify_type(obj, value.get(_TYPE_MARKER))  # type: ignore
             return obj
 
         # Regular dict: decode values recursively
-        return {k: _decode(v) for k, v in value.items()}  # type: ignore
+        return {k: _decode(v, allowed_types=allowed_types) for k, v in value.items()}  # type: ignore
 
     # Handle encoded lists
     if isinstance(value, list):
-        return [_decode(item) for item in value]  # type: ignore
+        return [_decode(item, allowed_types=allowed_types) for item in value]  # type: ignore
 
     return value
 
@@ -148,15 +250,23 @@ def _pickle_to_base64(value: Any) -> str:
     return base64.b64encode(pickled).decode("ascii")
 
 
-def _base64_to_unpickle(encoded: str) -> Any:
+def _base64_to_unpickle(encoded: str, *, allowed_types: frozenset[str] | None = None) -> Any:
     """Decode base64 string and unpickle.
 
+    Args:
+        encoded: Base64-encoded pickle data.
+        allowed_types: If not ``None``, use restricted unpickling that only
+            permits built-in safe types, framework types, and the specified
+            extra types.
+
     Raises:
-        WorkflowCheckpointException: If the base64 data is corrupted or the pickle
-            format is incompatible.
+        WorkflowCheckpointException: If the base64 data is corrupted, the pickle
+            format is incompatible, or a disallowed type is encountered.
     """
     try:
         pickled = base64.b64decode(encoded.encode("ascii"))
+        if allowed_types is not None:
+            return _RestrictedUnpickler(pickled, allowed_types).load()
         return pickle.loads(pickled)  # nosec  # noqa: S301
     except Exception as exc:
         raise WorkflowCheckpointException(f"Failed to decode pickled checkpoint data: {exc}") from exc

python/packages/core/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Agent Framework for building AI Agents with Python. Thi
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0"
+version = "1.0.1"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/core/tests/workflow/test_checkpoint.py

@@ -1048,7 +1048,10 @@ async def test_file_checkpoint_storage_roundtrip_datetime():
 async def test_file_checkpoint_storage_roundtrip_dataclass():
     """Test that dataclass objects roundtrip correctly via pickle encoding."""
     with tempfile.TemporaryDirectory() as temp_dir:
-        storage = FileCheckpointStorage(temp_dir)
+        storage = FileCheckpointStorage(
+            temp_dir,
+            allowed_checkpoint_types=["tests.workflow.test_checkpoint:_TestCustomData"],
+        )
 
         custom_obj = _TestCustomData(name="test", value=42, tags=["a", "b", "c"])
 
@@ -1238,7 +1241,10 @@ async def test_file_checkpoint_storage_roundtrip_messages_with_complex_data():
 async def test_file_checkpoint_storage_roundtrip_pending_request_info_events():
     """Test that pending_request_info_events with WorkflowEvent objects roundtrip correctly."""
     with tempfile.TemporaryDirectory() as temp_dir:
-        storage = FileCheckpointStorage(temp_dir)
+        storage = FileCheckpointStorage(
+            temp_dir,
+            allowed_checkpoint_types=["tests.workflow.test_checkpoint:_TestToolApprovalRequest"],
+        )
 
         # Create request_info events using the proper WorkflowEvent factory
         event1 = WorkflowEvent.request_info(
@@ -1300,7 +1306,13 @@ async def test_file_checkpoint_storage_roundtrip_pending_request_info_events():
 async def test_file_checkpoint_storage_roundtrip_full_checkpoint():
     """Test complete WorkflowCheckpoint roundtrip with all fields populated using proper types."""
     with tempfile.TemporaryDirectory() as temp_dir:
-        storage = FileCheckpointStorage(temp_dir)
+        storage = FileCheckpointStorage(
+            temp_dir,
+            allowed_checkpoint_types=[
+                "tests.workflow.test_checkpoint:_TestApprovalRequest",
+                "tests.workflow.test_checkpoint:_TestExecutorState",
+            ],
+        )
 
         # Create proper WorkflowMessage objects
         msg1 = WorkflowMessage(data="msg1", source_id="s", target_id="t")

python/packages/core/tests/workflow/test_checkpoint_unrestricted_pickle.py

@@ -0,0 +1,218 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for restricted checkpoint deserialization.
+
+These tests verify that persisted checkpoint loading uses a restricted
+unpickler by default:
+- Arbitrary callables are blocked during deserialization
+- __reduce__ payloads cannot execute code during deserialization
+- FileCheckpointStorage accepts allowed_checkpoint_types for extension
+- User-defined types are blocked unless explicitly allowed
+- Built-in safe types and framework types are always allowed
+"""
+
+import base64
+import os
+import pickle
+import tempfile
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+import pytest
+
+from agent_framework import WorkflowCheckpointException
+from agent_framework._workflows._checkpoint import FileCheckpointStorage
+from agent_framework._workflows._checkpoint_encoding import (
+    _PICKLE_MARKER,
+    _TYPE_MARKER,
+    decode_checkpoint_value,
+    encode_checkpoint_value,
+)
+
+
+class MaliciousPayload:
+    """A class whose __reduce__ executes code during unpickling."""
+
+    def __reduce__(self):
+        return (os.getpid, ())
+
+
+def test_restricted_decode_blocks_arbitrary_callable():
+    """Restricted decoding blocks arbitrary module-level callables."""
+    pickled = pickle.dumps(os.getpid, protocol=pickle.HIGHEST_PROTOCOL)
+    encoded_b64 = base64.b64encode(pickled).decode("ascii")
+
+    checkpoint_value = {
+        _PICKLE_MARKER: encoded_b64,
+        _TYPE_MARKER: "builtins:builtin_function_or_method",
+    }
+
+    with pytest.raises(WorkflowCheckpointException, match="deserialization blocked"):
+        decode_checkpoint_value(checkpoint_value, allowed_types=frozenset())
+
+
+def test_restricted_decode_blocks_reduce_payload():
+    """__reduce__-based payloads are blocked before code can execute."""
+    payload = MaliciousPayload()
+    pickled = pickle.dumps(payload, protocol=pickle.HIGHEST_PROTOCOL)
+    encoded_b64 = base64.b64encode(pickled).decode("ascii")
+
+    checkpoint_value = {
+        _PICKLE_MARKER: encoded_b64,
+        _TYPE_MARKER: f"{MaliciousPayload.__module__}:{MaliciousPayload.__qualname__}",
+    }
+
+    with pytest.raises(WorkflowCheckpointException, match="deserialization blocked"):
+        decode_checkpoint_value(checkpoint_value, allowed_types=frozenset())
+
+
+def test_restricted_decode_prevents_code_execution():
+    """Restricted deserialization prevents __reduce__ code from running."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        marker_file = os.path.join(tmpdir, "checkpoint_test_marker")
+
+        payload_bytes = pickle.dumps(
+            type(
+                "Exploit",
+                (),
+                {
+                    "__reduce__": lambda self: (
+                        eval,
+                        (f"open({marker_file!r}, 'w').write('pwned')",),
+                    )
+                },
+            )(),
+            protocol=pickle.HIGHEST_PROTOCOL,
+        )
+        encoded_b64 = base64.b64encode(payload_bytes).decode("ascii")
+
+        checkpoint_value = {
+            _PICKLE_MARKER: encoded_b64,
+            _TYPE_MARKER: "builtins:int",
+        }
+        with pytest.raises(WorkflowCheckpointException, match="deserialization blocked"):
+            decode_checkpoint_value(checkpoint_value, allowed_types=frozenset())
+
+        assert not os.path.exists(marker_file), (
+            "Restricted unpickler should have prevented code execution, but the marker file was created."
+        )
+
+
+def test_file_checkpoint_storage_accepts_allowed_types():
+    """FileCheckpointStorage.__init__ accepts allowed_checkpoint_types."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        storage = FileCheckpointStorage(
+            tmpdir,
+            allowed_checkpoint_types=["some.module:SomeType"],
+        )
+        assert storage is not None
+
+
+@dataclass
+class _AllowedTestState:
+    """Test dataclass that will be explicitly allowed."""
+
+    name: str
+    value: int
+
+
+def test_restricted_decode_blocks_unlisted_user_type():
+    """User-defined types are blocked when not in allowed_checkpoint_types."""
+    original = _AllowedTestState(name="test", value=42)
+    encoded = encode_checkpoint_value(original)
+
+    with pytest.raises(WorkflowCheckpointException, match="deserialization blocked"):
+        decode_checkpoint_value(encoded, allowed_types=frozenset())
+
+
+def test_restricted_decode_allows_listed_user_type():
+    """User-defined types are allowed when listed in allowed_types."""
+    original = _AllowedTestState(name="test", value=42)
+    encoded = encode_checkpoint_value(original)
+
+    type_key = f"{_AllowedTestState.__module__}:{_AllowedTestState.__qualname__}"
+    decoded = decode_checkpoint_value(encoded, allowed_types=frozenset({type_key}))
+
+    assert isinstance(decoded, _AllowedTestState)
+    assert decoded.name == "test"
+    assert decoded.value == 42
+
+
+def test_restricted_decode_allows_builtin_safe_types():
+    """Built-in safe types (datetime, set, etc.) are always allowed."""
+    test_values = [
+        datetime(2025, 1, 1, tzinfo=timezone.utc),
+        {1, 2, 3},
+        frozenset({4, 5, 6}),
+        (1, "two", 3.0),
+        complex(1, 2),
+    ]
+    for original in test_values:
+        encoded = encode_checkpoint_value(original)
+        decoded = decode_checkpoint_value(encoded, allowed_types=frozenset())
+        assert decoded == original
+
+
+def test_unrestricted_decode_allows_arbitrary_types():
+    """Without allowed_types, decode_checkpoint_value remains unrestricted."""
+    original = _AllowedTestState(name="test", value=42)
+    encoded = encode_checkpoint_value(original)
+
+    decoded = decode_checkpoint_value(encoded)
+
+    assert isinstance(decoded, _AllowedTestState)
+    assert decoded.name == "test"
+
+
+async def test_file_storage_blocks_unlisted_user_type():
+    """FileCheckpointStorage blocks user types not in allowed_checkpoint_types."""
+    from agent_framework import WorkflowCheckpoint
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        # Save with a storage that allows the type
+        type_key = f"{_AllowedTestState.__module__}:{_AllowedTestState.__qualname__}"
+        save_storage = FileCheckpointStorage(tmpdir, allowed_checkpoint_types=[type_key])
+
+        checkpoint = WorkflowCheckpoint(
+            workflow_name="test",
+            graph_signature_hash="hash",
+            state={"data": _AllowedTestState(name="test", value=1)},
+        )
+        await save_storage.save(checkpoint)
+
+        # Load with a storage that does NOT allow the type
+        load_storage = FileCheckpointStorage(tmpdir)
+        with pytest.raises(WorkflowCheckpointException, match="deserialization blocked"):
+            await load_storage.load(checkpoint.checkpoint_id)
+
+
+async def test_file_storage_allows_listed_user_type():
+    """FileCheckpointStorage allows user types listed in allowed_checkpoint_types."""
+    from agent_framework import WorkflowCheckpoint
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        type_key = f"{_AllowedTestState.__module__}:{_AllowedTestState.__qualname__}"
+        storage = FileCheckpointStorage(tmpdir, allowed_checkpoint_types=[type_key])
+
+        checkpoint = WorkflowCheckpoint(
+            workflow_name="test",
+            graph_signature_hash="hash",
+            state={"data": _AllowedTestState(name="allowed", value=99)},
+        )
+        await storage.save(checkpoint)
+        loaded = await storage.load(checkpoint.checkpoint_id)
+
+        assert isinstance(loaded.state["data"], _AllowedTestState)
+        assert loaded.state["data"].name == "allowed"
+        assert loaded.state["data"].value == 99
+
+
+def test_restricted_unpickler_raises_pickle_error():
+    """_RestrictedUnpickler.find_class raises pickle.UnpicklingError, not a framework exception."""
+    from agent_framework._workflows._checkpoint_encoding import _RestrictedUnpickler
+
+    pickled = pickle.dumps(os.getpid, protocol=pickle.HIGHEST_PROTOCOL)
+
+    unpickler = _RestrictedUnpickler(pickled, frozenset())
+    with pytest.raises(pickle.UnpicklingError, match="deserialization blocked"):
+        unpickler.load()

python/packages/core/tests/workflow/test_request_info_event_rehydrate.py

@@ -130,7 +130,17 @@ async def test_checkpoint_with_pending_request_info_events():
 
     with tempfile.TemporaryDirectory() as temp_dir:
         # Use file-based storage to test full serialization
-        storage = FileCheckpointStorage(temp_dir)
+        storage = FileCheckpointStorage(
+            temp_dir,
+            allowed_checkpoint_types=[
+                "tests.workflow.test_request_info_and_response:UserApprovalRequest",
+                "tests.workflow.test_request_info_and_response:CalculationRequest",
+                "tests.workflow.test_request_info_event_rehydrate:MockRequest",
+                "tests.workflow.test_request_info_event_rehydrate:SimpleApproval",
+                "tests.workflow.test_request_info_event_rehydrate:SlottedApproval",
+                "tests.workflow.test_request_info_event_rehydrate:TimedApproval",
+            ],
+        )
 
         # Create workflow with checkpointing enabled
         executor = ApprovalRequiredExecutor(id="approval_executor")
@@ -225,7 +235,17 @@ async def test_checkpoint_restore_with_responses_does_not_reemit_handled_request
 
     with tempfile.TemporaryDirectory() as temp_dir:
         # Use file-based storage to test full serialization
-        storage = FileCheckpointStorage(temp_dir)
+        storage = FileCheckpointStorage(
+            temp_dir,
+            allowed_checkpoint_types=[
+                "tests.workflow.test_request_info_and_response:UserApprovalRequest",
+                "tests.workflow.test_request_info_and_response:CalculationRequest",
+                "tests.workflow.test_request_info_event_rehydrate:MockRequest",
+                "tests.workflow.test_request_info_event_rehydrate:SimpleApproval",
+                "tests.workflow.test_request_info_event_rehydrate:SlottedApproval",
+                "tests.workflow.test_request_info_event_rehydrate:TimedApproval",
+            ],
+        )
 
         # Create workflow with checkpointing enabled
         executor = ApprovalRequiredExecutor(id="approval_executor")
@@ -288,7 +308,17 @@ async def test_checkpoint_restore_with_partial_responses_reemits_unhandled_reque
     import tempfile
 
     with tempfile.TemporaryDirectory() as temp_dir:
-        storage = FileCheckpointStorage(temp_dir)
+        storage = FileCheckpointStorage(
+            temp_dir,
+            allowed_checkpoint_types=[
+                "tests.workflow.test_request_info_and_response:UserApprovalRequest",
+                "tests.workflow.test_request_info_and_response:CalculationRequest",
+                "tests.workflow.test_request_info_event_rehydrate:MockRequest",
+                "tests.workflow.test_request_info_event_rehydrate:SimpleApproval",
+                "tests.workflow.test_request_info_event_rehydrate:SlottedApproval",
+                "tests.workflow.test_request_info_event_rehydrate:TimedApproval",
+            ],
+        )
 
         # Create workflow with multiple requests
         executor = MultiRequestExecutor(id="multi_executor")

python/packages/declarative/pyproject.toml

@@ -4,7 +4,7 @@ description = "Declarative specification support for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "powerfx>=0.0.32,<0.0.35; python_version < '3.14'",
     "pyyaml>=6.0,<7.0",
 ]

python/packages/devui/frontend/README.md

@@ -51,7 +51,7 @@ export default tseslint.config([
 ])
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/plugins/eslint-plugin-react-dom) for React-specific lint rules:
 
 ```js
 // eslint.config.js

python/packages/devui/pyproject.toml

@@ -4,7 +4,7 @@ description = "Debug UI for Microsoft Agent Framework with OpenAI-compatible API
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://github.com/microsoft/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
  dependencies = [
-     "agent-framework-core>=1.0.0,<2",
+     "agent-framework-core>=1.0.1,<2",
      "openai>=1.99.0,<3",
      "opentelemetry-sdk>=1.39.0,<2",
      "fastapi>=0.115.0,<0.133.1",

python/packages/durabletask/pyproject.toml

@@ -4,7 +4,7 @@ description = "Durable Task integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "durabletask>=1.3.0,<2",
     "durabletask-azuremanaged>=1.3.0,<2",
     "python-dateutil>=2.8.0,<3",

python/packages/durabletask/tests/test_executors.py

@@ -50,6 +50,7 @@ def mock_orchestration_context(mock_entity_task: Mock) -> Mock:
     """Provide a mock orchestration context with call_entity configured."""
     context = Mock()
     context.call_entity = Mock(return_value=mock_entity_task)
+    context.new_uuid = Mock(return_value="test-uuid-1234")
     return context
 
 

python/packages/foundry/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Foundry integrations for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0"
+version = "1.0.1"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,8 +23,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
-    "agent-framework-openai>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
+    "agent-framework-openai>=1.0.1,<2",
     "azure-ai-inference>=1.0.0b9,<1.0.0b10",
     "azure-ai-projects>=2.0.0,<3.0",
 ]

python/packages/foundry_local/pyproject.toml

@@ -4,7 +4,7 @@ description = "Foundry Local integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,8 +23,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
-    "agent-framework-openai>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
+    "agent-framework-openai>=1.0.1,<2",
     "foundry-local-sdk>=0.5.1,<0.5.2",
 ]
 

python/packages/github_copilot/agent_framework_github_copilot/_agent.py

@@ -7,7 +7,7 @@ import contextlib
 import logging
 import sys
 from collections.abc import AsyncIterable, Awaitable, Callable, MutableMapping, Sequence
-from typing import Any, ClassVar, Generic, Literal, TypedDict, cast, overload
+from typing import Any, ClassVar, Generic, Literal, TypedDict, overload
 
 from agent_framework import (
     AgentMiddlewareTypes,
@@ -29,20 +29,11 @@ from agent_framework._types import AgentRunInputs, normalize_tools
 from agent_framework.exceptions import AgentException
 
 try:
-    from copilot import CopilotClient, CopilotSession
+    from copilot import CopilotClient, CopilotSession, SubprocessConfig
     from copilot.generated.session_events import PermissionRequest, SessionEvent, SessionEventType
-    from copilot.types import (
-        CopilotClientOptions,
-        MCPServerConfig,
-        MessageOptions,
-        PermissionRequestResult,
-        ResumeSessionConfig,
-        SessionConfig,
-        SystemMessageConfig,
-        ToolInvocation,
-        ToolResult,
-    )
-    from copilot.types import Tool as CopilotTool
+    from copilot.session import MCPServerConfig, PermissionRequestResult, SystemMessageConfig
+    from copilot.tools import Tool as CopilotTool
+    from copilot.tools import ToolInvocation, ToolResult
 except ImportError as _copilot_import_error:
     raise ImportError(
         "GitHubCopilotAgent requires the 'github-copilot-sdk' package, which is only available on Python 3.11+. "
@@ -64,6 +55,14 @@ PermissionHandlerType = Callable[[PermissionRequest, dict[str, str]], Permission
 logger = logging.getLogger("agent_framework.github_copilot")
 
 
+def _deny_all_permissions(
+    _request: PermissionRequest,
+    _invocation: dict[str, str],
+) -> PermissionRequestResult:
+    """Default permission handler that denies all requests."""
+    return PermissionRequestResult()
+
+
 class GitHubCopilotSettings(TypedDict, total=False):
     """GitHub Copilot model settings.
 
@@ -274,16 +273,13 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
             return
 
         if self._client is None:
-            client_options: CopilotClientOptions = {}
-            cli_path = self._settings.get("cli_path")
-            if cli_path:
-                client_options["cli_path"] = cli_path
+            cli_path = self._settings.get("cli_path") or None
+            log_level = self._settings.get("log_level") or None
 
-            log_level = self._settings.get("log_level")
+            subprocess_kwargs: dict[str, Any] = {"cli_path": cli_path}
             if log_level:
-                client_options["log_level"] = log_level  # type: ignore[typeddict-item]
-
-            self._client = CopilotClient(client_options if client_options else None)
+                subprocess_kwargs["log_level"] = log_level
+            self._client = CopilotClient(SubprocessConfig(**subprocess_kwargs))
 
         try:
             await self._client.start()
@@ -407,10 +403,9 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         prompt = "\n".join([message.text for message in context_messages])
         if session_context.instructions:
             prompt = "\n".join(session_context.instructions) + "\n" + prompt
-        message_options = cast(MessageOptions, {"prompt": prompt})
 
         try:
-            response_event = await copilot_session.send_and_wait(message_options, timeout=timeout)
+            response_event = await copilot_session.send_and_wait(prompt, timeout=timeout)
         except Exception as ex:
             raise AgentException(f"GitHub Copilot request failed: {ex}") from ex
 
@@ -489,7 +484,6 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         prompt = "\n".join([message.text for message in context_messages])
         if session_context.instructions:
             prompt = "\n".join(session_context.instructions) + "\n" + prompt
-        message_options = cast(MessageOptions, {"prompt": prompt})
 
         queue: asyncio.Queue[AgentResponseUpdate | Exception | None] = asyncio.Queue()
 
@@ -550,7 +544,7 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         unsubscribe = copilot_session.on(event_handler)
 
         try:
-            await copilot_session.send(message_options)
+            await copilot_session.send(prompt)
 
             while (item := await queue.get()) is not None:
                 if isinstance(item, Exception):
@@ -730,43 +724,35 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
             raise RuntimeError("GitHub Copilot client not initialized. Call start() first.")
 
         opts = runtime_options or {}
-        config: SessionConfig = {"streaming": streaming}
+        model = opts.get("model") or self._settings.get("model") or None
+        system_message = opts.get("system_message") or self._default_options.get("system_message") or None
+        permission_handler: PermissionHandlerType = (
+            opts.get("on_permission_request") or self._permission_handler or _deny_all_permissions
+        )
+        mcp_servers = opts.get("mcp_servers") or self._mcp_servers or None
+        tools = self._prepare_tools(self._tools) if self._tools else None
 
-        model = opts.get("model") or self._settings.get("model")
-        if model:
-            config["model"] = model  # type: ignore[typeddict-item]
-
-        system_message = opts.get("system_message") or self._default_options.get("system_message")
-        if system_message:
-            config["system_message"] = system_message
-
-        if self._tools:
-            config["tools"] = self._prepare_tools(self._tools)
-
-        permission_handler = opts.get("on_permission_request") or self._permission_handler
-        if permission_handler:
-            config["on_permission_request"] = permission_handler
-
-        mcp_servers = opts.get("mcp_servers") or self._mcp_servers
-        if mcp_servers:
-            config["mcp_servers"] = mcp_servers
-
-        return await self._client.create_session(config)
+        return await self._client.create_session(
+            on_permission_request=permission_handler,
+            streaming=streaming,
+            model=model or None,
+            system_message=system_message or None,
+            tools=tools or None,
+            mcp_servers=mcp_servers or None,
+        )
 
     async def _resume_session(self, session_id: str, streaming: bool) -> CopilotSession:
         """Resume an existing Copilot session by ID."""
         if not self._client:
             raise RuntimeError("GitHub Copilot client not initialized. Call start() first.")
 
-        config: ResumeSessionConfig = {"streaming": streaming}
+        permission_handler: PermissionHandlerType = self._permission_handler or _deny_all_permissions
+        tools = self._prepare_tools(self._tools) if self._tools else None
 
-        if self._tools:
-            config["tools"] = self._prepare_tools(self._tools)
-
-        if self._permission_handler:
-            config["on_permission_request"] = self._permission_handler
-
-        if self._mcp_servers:
-            config["mcp_servers"] = self._mcp_servers
-
-        return await self._client.resume_session(session_id, config)
+        return await self._client.resume_session(
+            session_id,
+            on_permission_request=permission_handler,
+            streaming=streaming,
+            tools=tools or None,
+            mcp_servers=self._mcp_servers or None,
+        )

python/packages/github_copilot/pyproject.toml

@@ -4,7 +4,7 @@ description = "GitHub Copilot integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,8 +23,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
-    "github-copilot-sdk>=0.1.31,<0.1.33; python_version >= '3.11'",
+    "agent-framework-core>=1.0.1,<2",
+    "github-copilot-sdk>=0.2.1,<=0.2.1; python_version >= '3.11'",
 ]
 
 [tool.uv]
@@ -102,3 +102,4 @@ interpreter = "posix"
 [build-system]
 requires = ["flit-core >= 3.11,<4.0"]
 build-backend = "flit_core.buildapi"
+

python/packages/github_copilot/tests/test_github_copilot_agent.py

@@ -23,7 +23,7 @@ from agent_framework import (
 )
 from agent_framework.exceptions import AgentException
 from copilot.generated.session_events import Data, ErrorClass, Result, SessionEvent, SessionEventType
-from copilot.types import ToolInvocation, ToolResult
+from copilot.tools import ToolInvocation, ToolResult
 
 from agent_framework_github_copilot import GitHubCopilotAgent, GitHubCopilotOptions
 
@@ -268,8 +268,8 @@ class TestGitHubCopilotAgentLifecycle:
             await agent.start()
 
             call_args = MockClient.call_args[0][0]
-            assert call_args["cli_path"] == "/custom/path"
-            assert call_args["log_level"] == "debug"
+            assert call_args.cli_path == "/custom/path"
+            assert call_args.log_level == "debug"
 
 
 class TestGitHubCopilotAgentRun:
@@ -855,7 +855,13 @@ class TestGitHubCopilotAgentSessionManagement:
         await agent.run("World", session=session)
 
         mock_client.create_session.assert_called_once()
-        mock_client.resume_session.assert_called_once_with(mock_session.session_id, unittest.mock.ANY)
+        mock_client.resume_session.assert_called_once_with(
+            mock_session.session_id,
+            on_permission_request=unittest.mock.ANY,
+            streaming=unittest.mock.ANY,
+            tools=unittest.mock.ANY,
+            mcp_servers=unittest.mock.ANY,
+        )
 
     async def test_session_config_includes_model(
         self,
@@ -871,7 +877,7 @@ class TestGitHubCopilotAgentSessionManagement:
         await agent._get_or_create_session(AgentSession())  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
+        config = call_args.kwargs
         assert config["model"] == "claude-sonnet-4"
 
     async def test_session_config_includes_instructions(
@@ -889,7 +895,7 @@ class TestGitHubCopilotAgentSessionManagement:
         await agent._get_or_create_session(AgentSession())  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
+        config = call_args.kwargs
         assert config["system_message"]["mode"] == "append"
         assert config["system_message"]["content"] == "You are a helpful assistant."
 
@@ -914,7 +920,7 @@ class TestGitHubCopilotAgentSessionManagement:
         )
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
+        config = call_args.kwargs
         assert config["system_message"]["mode"] == "replace"
         assert config["system_message"]["content"] == "Runtime instructions"
 
@@ -930,7 +936,7 @@ class TestGitHubCopilotAgentSessionManagement:
         await agent._get_or_create_session(AgentSession(), streaming=True)  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
+        config = call_args.kwargs
         assert config["streaming"] is True
 
     async def test_resume_session_with_existing_service_session_id(
@@ -958,7 +964,8 @@ class TestGitHubCopilotAgentSessionManagement:
         mock_session: MagicMock,
     ) -> None:
         """Test that resumed session config includes tools and permission handler."""
-        from copilot.types import PermissionRequest, PermissionRequestResult
+        from copilot.generated.session_events import PermissionRequest
+        from copilot.session import PermissionRequestResult
 
         def my_handler(request: PermissionRequest, context: dict[str, str]) -> PermissionRequestResult:
             return PermissionRequestResult(kind="approved")
@@ -981,7 +988,7 @@ class TestGitHubCopilotAgentSessionManagement:
 
         mock_client.resume_session.assert_called_once()
         call_args = mock_client.resume_session.call_args
-        config = call_args[0][1]
+        config = call_args.kwargs
         assert "tools" in config
         assert "on_permission_request" in config
 
@@ -995,7 +1002,7 @@ class TestGitHubCopilotAgentMCPServers:
         mock_session: MagicMock,
     ) -> None:
         """Test that mcp_servers are passed through to create_session config."""
-        from copilot.types import MCPServerConfig
+        from copilot.session import MCPServerConfig
 
         mcp_servers: dict[str, MCPServerConfig] = {
             "filesystem": {
@@ -1020,7 +1027,7 @@ class TestGitHubCopilotAgentMCPServers:
         await agent._get_or_create_session(AgentSession())  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
+        config = call_args.kwargs
         assert "mcp_servers" in config
         assert "filesystem" in config["mcp_servers"]
         assert "remote" in config["mcp_servers"]
@@ -1033,7 +1040,7 @@ class TestGitHubCopilotAgentMCPServers:
         mock_session: MagicMock,
     ) -> None:
         """Test that mcp_servers are passed through to resume_session config."""
-        from copilot.types import MCPServerConfig
+        from copilot.session import MCPServerConfig
 
         mcp_servers: dict[str, MCPServerConfig] = {
             "test-server": {
@@ -1057,7 +1064,7 @@ class TestGitHubCopilotAgentMCPServers:
 
         mock_client.resume_session.assert_called_once()
         call_args = mock_client.resume_session.call_args
-        config = call_args[0][1]
+        config = call_args.kwargs
         assert "mcp_servers" in config
         assert "test-server" in config["mcp_servers"]
 
@@ -1073,8 +1080,8 @@ class TestGitHubCopilotAgentMCPServers:
         await agent._get_or_create_session(AgentSession())  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
-        assert "mcp_servers" not in config
+        config = call_args.kwargs
+        assert config["mcp_servers"] is None
 
 
 class TestGitHubCopilotAgentToolConversion:
@@ -1097,7 +1104,7 @@ class TestGitHubCopilotAgentToolConversion:
         await agent._get_or_create_session(AgentSession())  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
+        config = call_args.kwargs
         assert "tools" in config
         assert len(config["tools"]) == 1
         assert config["tools"][0].name == "my_tool"
@@ -1120,7 +1127,7 @@ class TestGitHubCopilotAgentToolConversion:
         await agent._get_or_create_session(AgentSession())  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
+        config = call_args.kwargs
         copilot_tool = config["tools"][0]
 
         result = await copilot_tool.handler(ToolInvocation(arguments={"arg": "test"}))
@@ -1146,7 +1153,7 @@ class TestGitHubCopilotAgentToolConversion:
         await agent._get_or_create_session(AgentSession())  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
+        config = call_args.kwargs
         copilot_tool = config["tools"][0]
 
         result = await copilot_tool.handler(ToolInvocation(arguments={"arg": "test"}))
@@ -1173,7 +1180,7 @@ class TestGitHubCopilotAgentToolConversion:
         await agent._get_or_create_session(AgentSession())  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
+        config = call_args.kwargs
         copilot_tool = config["tools"][0]
 
         with pytest.raises((TypeError, AttributeError)):
@@ -1196,7 +1203,7 @@ class TestGitHubCopilotAgentToolConversion:
         await agent._get_or_create_session(AgentSession())  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
+        config = call_args.kwargs
         copilot_tool = config["tools"][0]
 
         result = await copilot_tool.handler(ToolInvocation(arguments={}))
@@ -1210,7 +1217,7 @@ class TestGitHubCopilotAgentToolConversion:
         mock_client: MagicMock,
     ) -> None:
         """Test that CopilotTool instances are passed through as-is."""
-        from copilot.types import Tool as CopilotTool
+        from copilot.tools import Tool as CopilotTool
 
         async def tool_handler(invocation: Any) -> Any:
             return {"text_result_for_llm": "result", "result_type": "success"}
@@ -1234,7 +1241,7 @@ class TestGitHubCopilotAgentToolConversion:
     ) -> None:
         """Test that mixed tool types are handled correctly."""
         from agent_framework import tool
-        from copilot.types import Tool as CopilotTool
+        from copilot.tools import Tool as CopilotTool
 
         @tool(approval_mode="never_require")
         def my_function(arg: str) -> str:
@@ -1317,10 +1324,11 @@ class TestGitHubCopilotAgentPermissions:
 
     def test_permission_handler_set_when_provided(self) -> None:
         """Test that a handler is set when on_permission_request is provided."""
-        from copilot.types import PermissionRequest, PermissionRequestResult
+        from copilot.generated.session_events import PermissionRequest
+        from copilot.session import PermissionRequestResult
 
         def approve_shell(request: PermissionRequest, context: dict[str, str]) -> PermissionRequestResult:
-            if request.get("kind") == "shell":
+            if request.kind == "shell":
                 return PermissionRequestResult(kind="approved")
             return PermissionRequestResult(kind="denied-interactively-by-user")
 
@@ -1335,10 +1343,11 @@ class TestGitHubCopilotAgentPermissions:
         mock_session: MagicMock,
     ) -> None:
         """Test that session config includes permission handler when provided."""
-        from copilot.types import PermissionRequest, PermissionRequestResult
+        from copilot.generated.session_events import PermissionRequest
+        from copilot.session import PermissionRequestResult
 
         def approve_shell_read(request: PermissionRequest, context: dict[str, str]) -> PermissionRequestResult:
-            if request.get("kind") in ("shell", "read"):
+            if request.kind in ("shell", "read"):
                 return PermissionRequestResult(kind="approved")
             return PermissionRequestResult(kind="denied-interactively-by-user")
 
@@ -1351,24 +1360,29 @@ class TestGitHubCopilotAgentPermissions:
         await agent._get_or_create_session(AgentSession())  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
+        config = call_args.kwargs
         assert "on_permission_request" in config
         assert config["on_permission_request"] is not None
 
-    async def test_session_config_excludes_permission_handler_when_not_set(
+    async def test_session_config_uses_deny_all_when_no_permission_handler_set(
         self,
         mock_client: MagicMock,
         mock_session: MagicMock,
     ) -> None:
-        """Test that session config does not include permission handler when not set."""
+        """Test that session config uses deny-all handler when no permission handler is set.
+
+        In SDK 0.2.x, on_permission_request is required by create_session, so the agent
+        always falls back to _deny_all_permissions when no handler is provided.
+        """
         agent = GitHubCopilotAgent(client=mock_client)
         await agent.start()
 
         await agent._get_or_create_session(AgentSession())  # type: ignore
 
         call_args = mock_client.create_session.call_args
-        config = call_args[0][0]
-        assert "on_permission_request" not in config
+        config = call_args.kwargs
+        assert "on_permission_request" in config
+        assert config["on_permission_request"] is not None
 
 
 class SpyContextProvider(ContextProvider):
@@ -1454,7 +1468,7 @@ class TestGitHubCopilotAgentContextProviders:
         session = agent.create_session()
         await agent.run("Hello", session=session)
 
-        sent_prompt = mock_session.send_and_wait.call_args[0][0]["prompt"]
+        sent_prompt = mock_session.send_and_wait.call_args[0][0]
         assert "Injected by spy provider" in sent_prompt
 
     async def test_after_run_receives_response(
@@ -1547,7 +1561,7 @@ class TestGitHubCopilotAgentContextProviders:
         async for _ in agent.run("Hello", stream=True, session=session):
             pass
 
-        sent_prompt = mock_session.send.call_args[0][0]["prompt"]
+        sent_prompt = mock_session.send.call_args[0][0]
         assert "Injected by spy provider" in sent_prompt
 
     async def test_context_preserved_across_runs(
@@ -1608,7 +1622,7 @@ class TestGitHubCopilotAgentContextProviders:
         session = agent.create_session()
         await agent.run("Hello", session=session)
 
-        sent_prompt = mock_session.send_and_wait.call_args[0][0]["prompt"]
+        sent_prompt = mock_session.send_and_wait.call_args[0][0]
         assert "History message" in sent_prompt
         assert "Hello" in sent_prompt
 
@@ -1659,7 +1673,7 @@ class TestGitHubCopilotAgentContextProviders:
         async for _ in agent.run("Hello", stream=True, session=session):
             pass
 
-        sent_prompt = mock_session.send.call_args[0][0]["prompt"]
+        sent_prompt = mock_session.send.call_args[0][0]
         assert "History message" in sent_prompt
         assert "Hello" in sent_prompt
 

python/packages/lab/pyproject.toml

@@ -4,7 +4,7 @@ description = "Experimental modules for Microsoft Agent Framework"
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "agent-framework-core>=1.0.0,<2",
+  "agent-framework-core>=1.0.1,<2",
 ]
 
 [project.optional-dependencies]

python/packages/mem0/pyproject.toml

@@ -4,7 +4,7 @@ description = "Mem0 integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "mem0ai>=1.0.0,<2",
 ]
 

python/packages/ollama/pyproject.toml

@@ -4,7 +4,7 @@ description = "Ollama integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://learn.microsoft.com/en-us/agent-framework/"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "ollama>=0.5.3,<0.5.4",
 ]
 

python/packages/openai/agent_framework_openai/_chat_client.py

@@ -512,6 +512,7 @@ class RawOpenAIChatClient(  # type: ignore[misc]
 
         if stream:
             function_call_ids: dict[int, tuple[str, str]] = {}
+            seen_reasoning_delta_item_ids: set[str] = set()
             validated_options: dict[str, Any] | None = None
 
             async def _stream() -> AsyncIterable[ChatResponseUpdate]:
@@ -530,6 +531,7 @@ class RawOpenAIChatClient(  # type: ignore[misc]
                                 chunk,
                                 options=validated_options,
                                 function_call_ids=function_call_ids,
+                                seen_reasoning_delta_item_ids=seen_reasoning_delta_item_ids,
                             )
                     except Exception as ex:
                         self._handle_request_error(ex)
@@ -1930,6 +1932,7 @@ class RawOpenAIChatClient(  # type: ignore[misc]
         event: OpenAIResponseStreamEvent,
         options: dict[str, Any],
         function_call_ids: dict[int, tuple[str, str]],
+        seen_reasoning_delta_item_ids: set[str] | None = None,
     ) -> ChatResponseUpdate:
         """Parse an OpenAI Responses API streaming event into a ChatResponseUpdate."""
         metadata: dict[str, Any] = {}
@@ -2008,6 +2011,8 @@ class RawOpenAIChatClient(  # type: ignore[misc]
                 contents.append(Content.from_text(text=event.delta, raw_representation=event))
                 metadata.update(self._get_metadata_from_response(event))
             case "response.reasoning_text.delta":
+                if seen_reasoning_delta_item_ids is not None:
+                    seen_reasoning_delta_item_ids.add(event.item_id)
                 contents.append(
                     Content.from_text_reasoning(
                         id=event.item_id,
@@ -2017,15 +2022,21 @@ class RawOpenAIChatClient(  # type: ignore[misc]
                 )
                 metadata.update(self._get_metadata_from_response(event))
             case "response.reasoning_text.done":
-                contents.append(
-                    Content.from_text_reasoning(
-                        id=event.item_id,
-                        text=event.text,
-                        raw_representation=event,
+                # Done event carries the full accumulated text. Emit it only as a
+                # fallback when no delta was already received for this item_id, to
+                # avoid duplicating content in downstream accumulators (e.g. ag-ui).
+                if seen_reasoning_delta_item_ids is None or event.item_id not in seen_reasoning_delta_item_ids:
+                    contents.append(
+                        Content.from_text_reasoning(
+                            id=event.item_id,
+                            text=event.text,
+                            raw_representation=event,
+                        )
                     )
-                )
                 metadata.update(self._get_metadata_from_response(event))
             case "response.reasoning_summary_text.delta":
+                if seen_reasoning_delta_item_ids is not None:
+                    seen_reasoning_delta_item_ids.add(event.item_id)
                 contents.append(
                     Content.from_text_reasoning(
                         id=event.item_id,
@@ -2035,13 +2046,17 @@ class RawOpenAIChatClient(  # type: ignore[misc]
                 )
                 metadata.update(self._get_metadata_from_response(event))
             case "response.reasoning_summary_text.done":
-                contents.append(
-                    Content.from_text_reasoning(
-                        id=event.item_id,
-                        text=event.text,
-                        raw_representation=event,
+                # Done event carries the full accumulated text. Emit it only as a
+                # fallback when no delta was already received for this item_id, to
+                # avoid duplicating content in downstream accumulators (e.g. ag-ui).
+                if seen_reasoning_delta_item_ids is None or event.item_id not in seen_reasoning_delta_item_ids:
+                    contents.append(
+                        Content.from_text_reasoning(
+                            id=event.item_id,
+                            text=event.text,
+                            raw_representation=event,
+                        )
                     )
-                )
                 metadata.update(self._get_metadata_from_response(event))
             case "response.code_interpreter_call_code.delta":
                 call_id = getattr(event, "call_id", None) or getattr(event, "id", None) or event.item_id
@@ -2065,6 +2080,9 @@ class RawOpenAIChatClient(  # type: ignore[misc]
                     )
                 )
                 metadata.update(self._get_metadata_from_response(event))
+                # NOTE: Unlike reasoning done events, code_interpreter done events always
+                # emit content because downstream consumers do not accumulate
+                # code_interpreter deltas the same way.
             case "response.code_interpreter_call_code.done":
                 call_id = getattr(event, "call_id", None) or getattr(event, "id", None) or event.item_id
                 ci_additional_properties = {

python/packages/openai/pyproject.toml

@@ -4,7 +4,7 @@ description = "OpenAI integrations for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0"
+version = "1.0.1"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "openai>=1.99.0,<3",
 ]
 

python/packages/openai/tests/openai/test_openai_chat_client.py

@@ -2808,11 +2808,12 @@ def test_streaming_reasoning_text_delta_event() -> None:
         mock_metadata.assert_called_once_with(event)
 
 
-def test_streaming_reasoning_text_done_event() -> None:
-    """Test reasoning text done event creates TextReasoningContent with complete text."""
+def test_streaming_reasoning_text_done_event_skipped_after_deltas() -> None:
+    """Test reasoning text done event does not emit content when deltas were already received."""
     client = OpenAIChatClient(model="test-model", api_key="test-key")
     chat_options = ChatOptions()
     function_call_ids: dict[int, tuple[str, str]] = {}
+    seen_reasoning_delta_item_ids: set[str] = {"reasoning_456"}
 
     event = ResponseReasoningTextDoneEvent(
         type="response.reasoning_text.done",
@@ -2824,12 +2825,40 @@ def test_streaming_reasoning_text_done_event() -> None:
     )
 
     with patch.object(client, "_get_metadata_from_response", return_value={"test": "data"}) as mock_metadata:
-        response = client._parse_chunk_from_openai(event, chat_options, function_call_ids)  # type: ignore
+        response = client._parse_chunk_from_openai(
+            event, chat_options, function_call_ids, seen_reasoning_delta_item_ids
+        )  # type: ignore
+
+        assert len(response.contents) == 0
+        mock_metadata.assert_called_once_with(event)
+        assert response.additional_properties == {"test": "data"}
+
+
+def test_streaming_reasoning_text_done_event_fallback_without_deltas() -> None:
+    """Test reasoning text done event emits content when no deltas were received for this item_id."""
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+    chat_options = ChatOptions()
+    function_call_ids: dict[int, tuple[str, str]] = {}
+    seen_reasoning_delta_item_ids: set[str] = set()
+
+    event = ResponseReasoningTextDoneEvent(
+        type="response.reasoning_text.done",
+        content_index=0,
+        item_id="reasoning_456",
+        output_index=0,
+        sequence_number=2,
+        text="complete reasoning",
+    )
+
+    with patch.object(client, "_get_metadata_from_response", return_value={"test": "data"}) as mock_metadata:
+        response = client._parse_chunk_from_openai(
+            event, chat_options, function_call_ids, seen_reasoning_delta_item_ids
+        )  # type: ignore
 
         assert len(response.contents) == 1
         assert response.contents[0].type == "text_reasoning"
+        assert response.contents[0].id == "reasoning_456"
         assert response.contents[0].text == "complete reasoning"
-        assert response.contents[0].raw_representation == event
         mock_metadata.assert_called_once_with(event)
         assert response.additional_properties == {"test": "data"}
 
@@ -2859,11 +2888,12 @@ def test_streaming_reasoning_summary_text_delta_event() -> None:
         mock_metadata.assert_called_once_with(event)
 
 
-def test_streaming_reasoning_summary_text_done_event() -> None:
-    """Test reasoning summary text done event creates TextReasoningContent with complete text."""
+def test_streaming_reasoning_summary_text_done_event_skipped_after_deltas() -> None:
+    """Test reasoning summary text done event does not emit content when deltas were already received."""
     client = OpenAIChatClient(model="test-model", api_key="test-key")
     chat_options = ChatOptions()
     function_call_ids: dict[int, tuple[str, str]] = {}
+    seen_reasoning_delta_item_ids: set[str] = {"summary_012"}
 
     event = ResponseReasoningSummaryTextDoneEvent(
         type="response.reasoning_summary_text.done",
@@ -2875,16 +2905,94 @@ def test_streaming_reasoning_summary_text_done_event() -> None:
     )
 
     with patch.object(client, "_get_metadata_from_response", return_value={"custom": "meta"}) as mock_metadata:
-        response = client._parse_chunk_from_openai(event, chat_options, function_call_ids)  # type: ignore
+        response = client._parse_chunk_from_openai(
+            event, chat_options, function_call_ids, seen_reasoning_delta_item_ids
+        )  # type: ignore
+
+        assert len(response.contents) == 0
+        mock_metadata.assert_called_once_with(event)
+        assert response.additional_properties == {"custom": "meta"}
+
+
+def test_streaming_reasoning_summary_text_done_event_fallback_without_deltas() -> None:
+    """Test reasoning summary text done event emits content when no deltas were received for this item_id."""
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+    chat_options = ChatOptions()
+    function_call_ids: dict[int, tuple[str, str]] = {}
+    seen_reasoning_delta_item_ids: set[str] = set()
+
+    event = ResponseReasoningSummaryTextDoneEvent(
+        type="response.reasoning_summary_text.done",
+        item_id="summary_012",
+        output_index=0,
+        sequence_number=4,
+        summary_index=0,
+        text="complete summary",
+    )
+
+    with patch.object(client, "_get_metadata_from_response", return_value={"custom": "meta"}) as mock_metadata:
+        response = client._parse_chunk_from_openai(
+            event, chat_options, function_call_ids, seen_reasoning_delta_item_ids
+        )  # type: ignore
 
         assert len(response.contents) == 1
         assert response.contents[0].type == "text_reasoning"
+        assert response.contents[0].id == "summary_012"
         assert response.contents[0].text == "complete summary"
-        assert response.contents[0].raw_representation == event
         mock_metadata.assert_called_once_with(event)
         assert response.additional_properties == {"custom": "meta"}
 
 
+def test_streaming_reasoning_deltas_then_done_no_duplication() -> None:
+    """Sending delta events followed by a done event produces content only from deltas."""
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+    chat_options = ChatOptions()
+    function_call_ids: dict[int, tuple[str, str]] = {}
+    seen_reasoning_delta_item_ids: set[str] = set()
+    item_id = "reasoning_seq"
+
+    delta1 = ResponseReasoningTextDeltaEvent(
+        type="response.reasoning_text.delta",
+        content_index=0,
+        item_id=item_id,
+        output_index=0,
+        sequence_number=1,
+        delta="Hello ",
+    )
+    delta2 = ResponseReasoningTextDeltaEvent(
+        type="response.reasoning_text.delta",
+        content_index=0,
+        item_id=item_id,
+        output_index=0,
+        sequence_number=2,
+        delta="world",
+    )
+    done = ResponseReasoningTextDoneEvent(
+        type="response.reasoning_text.done",
+        content_index=0,
+        item_id=item_id,
+        output_index=0,
+        sequence_number=3,
+        text="Hello world",
+    )
+
+    all_contents = []
+    with patch.object(client, "_get_metadata_from_response", return_value={}):
+        for event in [delta1, delta2, done]:
+            response = client._parse_chunk_from_openai(
+                event,
+                chat_options,
+                function_call_ids,
+                seen_reasoning_delta_item_ids,  # type: ignore
+            )
+            all_contents.extend(response.contents)
+
+    assert len(all_contents) == 2
+    assert all_contents[0].text == "Hello "
+    assert all_contents[1].text == "world"
+    assert "".join(c.text for c in all_contents) == "Hello world"
+
+
 def test_streaming_reasoning_events_preserve_metadata() -> None:
     """Test that reasoning events preserve metadata like regular text events."""
     client = OpenAIChatClient(model="test-model", api_key="test-key")

python/packages/orchestrations/pyproject.toml

@@ -4,7 +4,7 @@ description = "Orchestration patterns for Microsoft Agent Framework. Includes Se
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
 ]
 
 [tool.uv]

python/packages/purview/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Purview (Graph dataSecurityAndGovernance) integration f
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://github.com/microsoft/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -24,7 +24,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "azure-core>=1.30.0,<2",
     "httpx>=0.27.0,<0.29",
 ]

python/packages/redis/pyproject.toml

@@ -4,7 +4,7 @@ description = "Redis integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260402"
+version = "1.0.0b260409"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0,<2",
+    "agent-framework-core>=1.0.1,<2",
     "redis>=6.4.0,<7.2.1",
     "redisvl>=0.11.0,<0.16",
     "numpy>=2.2.6,<3"