Fix WorkflowAgent to include thread convo history. Enable checkpointing. (#2774)

python/samples/getting_started/workflows/README.md

@@ -44,6 +44,7 @@ Once comfortable with these, explore the rest of the samples below.
 | Magentic Workflow as Agent | [agents/magentic_workflow_as_agent.py](./agents/magentic_workflow_as_agent.py) | Configure Magentic orchestration with callbacks, then expose the workflow as an agent |
 | Workflow as Agent (Reflection Pattern) | [agents/workflow_as_agent_reflection_pattern.py](./agents/workflow_as_agent_reflection_pattern.py) | Wrap a workflow so it can behave like an agent (reflection pattern) |
 | Workflow as Agent + HITL | [agents/workflow_as_agent_human_in_the_loop.py](./agents/workflow_as_agent_human_in_the_loop.py) | Extend workflow-as-agent with human-in-the-loop capability |
+| Workflow as Agent with Thread | [agents/workflow_as_agent_with_thread.py](./agents/workflow_as_agent_with_thread.py) | Use AgentThread to maintain conversation history across workflow-as-agent invocations |
 | Handoff Workflow as Agent | [agents/handoff_workflow_as_agent.py](./agents/handoff_workflow_as_agent.py) | Use a HandoffBuilder workflow as an agent with HITL via FunctionCallContent/FunctionResultContent |
 
 ### checkpoint
@@ -54,6 +55,7 @@ Once comfortable with these, explore the rest of the samples below.
 | Checkpoint & HITL Resume | [checkpoint/checkpoint_with_human_in_the_loop.py](./checkpoint/checkpoint_with_human_in_the_loop.py) | Combine checkpointing with human approvals and resume pending HITL requests |
 | Checkpointed Sub-Workflow | [checkpoint/sub_workflow_checkpoint.py](./checkpoint/sub_workflow_checkpoint.py) | Save and resume a sub-workflow that pauses for human approval |
 | Handoff + Tool Approval Resume | [checkpoint/handoff_with_tool_approval_checkpoint_resume.py](./checkpoint/handoff_with_tool_approval_checkpoint_resume.py) | Handoff workflow that captures tool-call approvals in checkpoints and resumes with human decisions |
+| Workflow as Agent Checkpoint | [checkpoint/workflow_as_agent_checkpoint.py](./checkpoint/workflow_as_agent_checkpoint.py) | Enable checkpointing when using workflow.as_agent() with checkpoint_storage parameter |
 
 ### composition
 

python/samples/getting_started/workflows/agents/workflow_as_agent_with_thread.py

@@ -0,0 +1,167 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import AgentThread, ChatAgent, ChatMessageStore, SequentialBuilder
+from agent_framework.openai import OpenAIChatClient
+
+"""
+Sample: Workflow as Agent with Thread Conversation History and Checkpointing
+
+This sample demonstrates how to use AgentThread with a workflow wrapped as an agent
+to maintain conversation history across multiple invocations. When using as_agent(),
+the thread's message store history is included in each workflow run, enabling
+the workflow participants to reference prior conversation context.
+
+It also demonstrates how to enable checkpointing for workflow execution state
+persistence, allowing workflows to be paused and resumed.
+
+Key concepts:
+- Workflows can be wrapped as agents using workflow.as_agent()
+- AgentThread with ChatMessageStore preserves conversation history
+- Each call to agent.run() includes thread history + new message
+- Participants in the workflow see the full conversation context
+- checkpoint_storage parameter enables workflow state persistence
+
+Use cases:
+- Multi-turn conversations with workflow-based orchestrations
+- Stateful workflows that need context from previous interactions
+- Building conversational agents that leverage workflow patterns
+- Long-running workflows that need pause/resume capability
+
+Prerequisites:
+- OpenAI environment variables configured for OpenAIChatClient
+"""
+
+
+async def main() -> None:
+    # Create a chat client
+    chat_client = OpenAIChatClient()
+
+    # Define factory functions for workflow participants
+    def create_assistant() -> ChatAgent:
+        return chat_client.create_agent(
+            name="assistant",
+            instructions=(
+                "You are a helpful assistant. Answer questions based on the conversation "
+                "history. If the user asks about something mentioned earlier, reference it."
+            ),
+        )
+
+    def create_summarizer() -> ChatAgent:
+        return chat_client.create_agent(
+            name="summarizer",
+            instructions=(
+                "You are a summarizer. After the assistant responds, provide a brief "
+                "one-sentence summary of the key point from the conversation so far."
+            ),
+        )
+
+    # Build a sequential workflow: assistant -> summarizer
+    workflow = SequentialBuilder().register_participants([create_assistant, create_summarizer]).build()
+
+    # Wrap the workflow as an agent
+    agent = workflow.as_agent(name="ConversationalWorkflowAgent")
+
+    # Create a thread with a ChatMessageStore to maintain history
+    message_store = ChatMessageStore()
+    thread = AgentThread(message_store=message_store)
+
+    print("=" * 60)
+    print("Workflow as Agent with Thread - Multi-turn Conversation")
+    print("=" * 60)
+
+    # First turn: Introduce a topic
+    query1 = "My name is Alex and I'm learning about machine learning."
+    print(f"\n[Turn 1] User: {query1}")
+
+    response1 = await agent.run(query1, thread=thread)
+    if response1.messages:
+        for msg in response1.messages:
+            speaker = msg.author_name or msg.role.value
+            print(f"[{speaker}]: {msg.text}")
+
+    # Second turn: Reference the previous topic
+    query2 = "What was my name again, and what am I learning about?"
+    print(f"\n[Turn 2] User: {query2}")
+
+    response2 = await agent.run(query2, thread=thread)
+    if response2.messages:
+        for msg in response2.messages:
+            speaker = msg.author_name or msg.role.value
+            print(f"[{speaker}]: {msg.text}")
+
+    # Third turn: Ask a follow-up question
+    query3 = "Can you suggest a good first project for me to try?"
+    print(f"\n[Turn 3] User: {query3}")
+
+    response3 = await agent.run(query3, thread=thread)
+    if response3.messages:
+        for msg in response3.messages:
+            speaker = msg.author_name or msg.role.value
+            print(f"[{speaker}]: {msg.text}")
+
+    # Show the accumulated conversation history
+    print("\n" + "=" * 60)
+    print("Full Thread History")
+    print("=" * 60)
+    if thread.message_store:
+        history = await thread.message_store.list_messages()
+        for i, msg in enumerate(history, start=1):
+            role = msg.role.value if hasattr(msg.role, "value") else str(msg.role)
+            speaker = msg.author_name or role
+            text_preview = msg.text[:80] + "..." if len(msg.text) > 80 else msg.text
+            print(f"{i:02d}. [{speaker}]: {text_preview}")
+
+
+async def demonstrate_thread_serialization() -> None:
+    """
+    Demonstrates serializing and resuming a thread with a workflow agent.
+
+    This shows how conversation history can be persisted and restored,
+    enabling long-running conversational workflows.
+    """
+    chat_client = OpenAIChatClient()
+
+    def create_assistant() -> ChatAgent:
+        return chat_client.create_agent(
+            name="memory_assistant",
+            instructions="You are a helpful assistant with good memory. Remember details from our conversation.",
+        )
+
+    workflow = SequentialBuilder().register_participants([create_assistant]).build()
+    agent = workflow.as_agent(name="MemoryWorkflowAgent")
+
+    # Create initial thread and have a conversation
+    thread = AgentThread(message_store=ChatMessageStore())
+
+    print("\n" + "=" * 60)
+    print("Thread Serialization Demo")
+    print("=" * 60)
+
+    # First interaction
+    query = "Remember this: the secret code is ALPHA-7."
+    print(f"\n[Session 1] User: {query}")
+    response = await agent.run(query, thread=thread)
+    if response.messages:
+        print(f"[assistant]: {response.messages[0].text}")
+
+    # Serialize thread state (could be saved to database/file)
+    serialized_state = await thread.serialize()
+    print("\n[Serialized thread state for persistence]")
+
+    # Simulate a new session by creating a new thread from serialized state
+    restored_thread = AgentThread(message_store=ChatMessageStore())
+    await restored_thread.update_from_thread_state(serialized_state)
+
+    # Continue conversation with restored thread
+    query = "What was the secret code I told you?"
+    print(f"\n[Session 2 - Restored] User: {query}")
+    response = await agent.run(query, thread=restored_thread)
+    if response.messages:
+        print(f"[assistant]: {response.messages[0].text}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+    asyncio.run(demonstrate_thread_serialization())

python/samples/getting_started/workflows/checkpoint/workflow_as_agent_checkpoint.py

@@ -0,0 +1,163 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Sample: Workflow as Agent with Checkpointing
+
+Purpose:
+This sample demonstrates how to use checkpointing with a workflow wrapped as an agent.
+It shows how to enable checkpoint storage when calling agent.run() or agent.run_stream(),
+allowing workflow execution state to be persisted and potentially resumed.
+
+What you learn:
+- How to pass checkpoint_storage to WorkflowAgent.run() and run_stream()
+- How checkpoints are created during workflow-as-agent execution
+- How to combine thread conversation history with workflow checkpointing
+- How to resume a workflow-as-agent from a checkpoint
+
+Key concepts:
+- Thread (AgentThread): Maintains conversation history across agent invocations
+- Checkpoint: Persists workflow execution state for pause/resume capability
+- These are complementary: threads track conversation, checkpoints track workflow state
+
+Prerequisites:
+- OpenAI environment variables configured for OpenAIChatClient
+"""
+
+import asyncio
+
+from agent_framework import (
+    AgentThread,
+    ChatAgent,
+    ChatMessageStore,
+    InMemoryCheckpointStorage,
+    SequentialBuilder,
+)
+from agent_framework.openai import OpenAIChatClient
+
+
+async def basic_checkpointing() -> None:
+    """Demonstrate basic checkpoint storage with workflow-as-agent."""
+    print("=" * 60)
+    print("Basic Checkpointing with Workflow as Agent")
+    print("=" * 60)
+
+    chat_client = OpenAIChatClient()
+
+    def create_assistant() -> ChatAgent:
+        return chat_client.create_agent(
+            name="assistant",
+            instructions="You are a helpful assistant. Keep responses brief.",
+        )
+
+    def create_reviewer() -> ChatAgent:
+        return chat_client.create_agent(
+            name="reviewer",
+            instructions="You are a reviewer. Provide a one-sentence summary of the assistant's response.",
+        )
+
+    # Build sequential workflow with participant factories
+    workflow = SequentialBuilder().register_participants([create_assistant, create_reviewer]).build()
+    agent = workflow.as_agent(name="CheckpointedAgent")
+
+    # Create checkpoint storage
+    checkpoint_storage = InMemoryCheckpointStorage()
+
+    # Run with checkpointing enabled
+    query = "What are the benefits of renewable energy?"
+    print(f"\nUser: {query}")
+
+    response = await agent.run(query, checkpoint_storage=checkpoint_storage)
+
+    for msg in response.messages:
+        speaker = msg.author_name or msg.role.value
+        print(f"[{speaker}]: {msg.text}")
+
+    # Show checkpoints that were created
+    checkpoints = await checkpoint_storage.list_checkpoints(workflow.id)
+    print(f"\nCheckpoints created: {len(checkpoints)}")
+    for i, cp in enumerate(checkpoints[:5], 1):
+        print(f"  {i}. {cp.checkpoint_id}")
+
+
+async def checkpointing_with_thread() -> None:
+    """Demonstrate combining thread history with checkpointing."""
+    print("\n" + "=" * 60)
+    print("Checkpointing with Thread Conversation History")
+    print("=" * 60)
+
+    chat_client = OpenAIChatClient()
+
+    def create_assistant() -> ChatAgent:
+        return chat_client.create_agent(
+            name="memory_assistant",
+            instructions="You are a helpful assistant with good memory. Reference previous conversation when relevant.",
+        )
+
+    workflow = SequentialBuilder().register_participants([create_assistant]).build()
+    agent = workflow.as_agent(name="MemoryAgent")
+
+    # Create both thread (for conversation) and checkpoint storage (for workflow state)
+    thread = AgentThread(message_store=ChatMessageStore())
+    checkpoint_storage = InMemoryCheckpointStorage()
+
+    # First turn
+    query1 = "My favorite color is blue. Remember that."
+    print(f"\n[Turn 1] User: {query1}")
+    response1 = await agent.run(query1, thread=thread, checkpoint_storage=checkpoint_storage)
+    if response1.messages:
+        print(f"[assistant]: {response1.messages[0].text}")
+
+    # Second turn - agent should remember from thread history
+    query2 = "What's my favorite color?"
+    print(f"\n[Turn 2] User: {query2}")
+    response2 = await agent.run(query2, thread=thread, checkpoint_storage=checkpoint_storage)
+    if response2.messages:
+        print(f"[assistant]: {response2.messages[0].text}")
+
+    # Show accumulated state
+    checkpoints = await checkpoint_storage.list_checkpoints(workflow.id)
+    print(f"\nTotal checkpoints across both turns: {len(checkpoints)}")
+
+    if thread.message_store:
+        history = await thread.message_store.list_messages()
+        print(f"Messages in thread history: {len(history)}")
+
+
+async def streaming_with_checkpoints() -> None:
+    """Demonstrate streaming with checkpoint storage."""
+    print("\n" + "=" * 60)
+    print("Streaming with Checkpointing")
+    print("=" * 60)
+
+    chat_client = OpenAIChatClient()
+
+    def create_assistant() -> ChatAgent:
+        return chat_client.create_agent(
+            name="streaming_assistant",
+            instructions="You are a helpful assistant.",
+        )
+
+    workflow = SequentialBuilder().register_participants([create_assistant]).build()
+    agent = workflow.as_agent(name="StreamingCheckpointAgent")
+
+    checkpoint_storage = InMemoryCheckpointStorage()
+
+    query = "List three interesting facts about the ocean."
+    print(f"\nUser: {query}")
+    print("[assistant]: ", end="", flush=True)
+
+    # Stream with checkpointing
+    async for update in agent.run_stream(query, checkpoint_storage=checkpoint_storage):
+        if update.text:
+            print(update.text, end="", flush=True)
+
+    print()  # Newline after streaming
+
+    checkpoints = await checkpoint_storage.list_checkpoints(workflow.id)
+    print(f"\nCheckpoints created during stream: {len(checkpoints)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(basic_checkpointing())
+    asyncio.run(checkpointing_with_thread())
+    asyncio.run(streaming_with_checkpoints())