Merge branch 'main' into crickman/workflows-declarative-nocodegen

dotnet/agent-framework-dotnet.slnx

@@ -57,6 +57,7 @@
     <Project Path="samples/02-agents/Agents/Agent_Step16_Declarative/Agent_Step16_Declarative.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step17_AdditionalAIContext/Agent_Step17_AdditionalAIContext.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step18_CompactionPipeline/Agent_Step18_CompactionPipeline.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Agent_Step19_InFunctionLoopCheckpointing.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/DeclarativeAgents/">
     <Project Path="samples/02-agents/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
@@ -76,6 +77,8 @@
     <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/01_SequentialWorkflow/01_SequentialWorkflow.csproj" />
     <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/02_ConcurrentWorkflow/02_ConcurrentWorkflow.csproj" />
     <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/03_WorkflowHITL/03_WorkflowHITL.csproj" />
+    <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/04_WorkflowMcpTool.csproj" />
+    <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/05_WorkflowAndAgents.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/">
     <File Path="samples/GettingStarted/README.md" />

dotnet/samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Agent_Step19_InFunctionLoopCheckpointing.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Program.cs

@@ -0,0 +1,226 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how the ChatClientAgent persists chat history after each individual
+// call to the AI service.
+// When an agent uses tools, FunctionInvokingChatClient may loop multiple times
+// (service call → tool execution → service call), and intermediate messages (tool calls and
+// results) are persisted after each service call. This allows you to inspect or recover them
+// even if the process is interrupted mid-loop, but may also result in chat history that is not
+// yet finalized (e.g., tool calls without results) being persisted, which may be undesirable in some cases.
+//
+// To opt into end-of-run persistence instead (atomic run semantics), set
+// PersistChatHistoryAtEndOfRun = true on ChatClientAgentOptions.
+//
+// The sample runs two multi-turn conversations: one using non-streaming (RunAsync) and one
+// using streaming (RunStreamingAsync), to demonstrate correct behavior in both modes.
+
+using System.ComponentModel;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI.Responses;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+var store = Environment.GetEnvironmentVariable("AZURE_OPENAI_RESPONSES_STORE") ?? "false";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AzureOpenAIClient openAIClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+// Define multiple tools so the model makes several tool calls in a single run.
+[Description("Get the current weather for a city.")]
+static string GetWeather([Description("The city name.")] string city) =>
+    city.ToUpperInvariant() switch
+    {
+        "SEATTLE" => "Seattle: 55°F, cloudy with light rain.",
+        "NEW YORK" => "New York: 72°F, sunny and warm.",
+        "LONDON" => "London: 48°F, overcast with fog.",
+        "DUBLIN" => "Dublin: 43°F, overcast with fog.",
+        _ => $"{city}: weather data not available."
+    };
+
+[Description("Get the current time in a city.")]
+static string GetTime([Description("The city name.")] string city) =>
+    city.ToUpperInvariant() switch
+    {
+        "SEATTLE" => "Seattle: 9:00 AM PST",
+        "NEW YORK" => "New York: 12:00 PM EST",
+        "LONDON" => "London: 5:00 PM GMT",
+        "DUBLIN" => "Dublin: 5:00 PM GMT",
+        _ => $"{city}: time data not available."
+    };
+
+// Create the agent — per-service-call persistence is the default behavior.
+// The in-memory ChatHistoryProvider is used by default when the service does not require service stored chat
+// history, so for those cases, we can inspect the chat history via session.TryGetInMemoryChatHistory().
+IChatClient chatClient = string.Equals(store, "TRUE", StringComparison.OrdinalIgnoreCase) ?
+    openAIClient.GetResponsesClient().AsIChatClient(deploymentName) :
+    openAIClient.GetResponsesClient().AsIChatClientWithStoredOutputDisabled(deploymentName);
+AIAgent agent = chatClient.AsAIAgent(
+    new ChatClientAgentOptions
+    {
+        Name = "WeatherAssistant",
+        ChatOptions = new()
+        {
+            Instructions = "You are a helpful assistant. When asked about multiple cities, call the appropriate tool for each city.",
+            Tools = [AIFunctionFactory.Create(GetWeather), AIFunctionFactory.Create(GetTime)]
+        },
+    });
+
+await RunNonStreamingAsync();
+await RunStreamingAsync();
+
+async Task RunNonStreamingAsync()
+{
+    int lastChatHistorySize = 0;
+    string lastConversationId = string.Empty;
+
+    Console.ForegroundColor = ConsoleColor.Yellow;
+    Console.WriteLine("\n=== Non-Streaming Mode ===");
+    Console.ResetColor();
+
+    AgentSession session = await agent.CreateSessionAsync();
+
+    // First turn — ask about multiple cities so the model calls tools.
+    const string Prompt = "What's the weather and time in Seattle, New York, and London?";
+    PrintUserMessage(Prompt);
+
+    var response = await agent.RunAsync(Prompt, session);
+    PrintAgentResponse(response.Text);
+    PrintChatHistory(session, "After run", ref lastChatHistorySize, ref lastConversationId);
+
+    // Second turn — follow-up to verify chat history is correct.
+    const string FollowUp1 = "And Dublin?";
+    PrintUserMessage(FollowUp1);
+
+    response = await agent.RunAsync(FollowUp1, session);
+    PrintAgentResponse(response.Text);
+    PrintChatHistory(session, "After second run", ref lastChatHistorySize, ref lastConversationId);
+
+    // Third turn — follow-up to verify chat history is correct.
+    const string FollowUp2 = "Which city is the warmest?";
+    PrintUserMessage(FollowUp2);
+
+    response = await agent.RunAsync(FollowUp2, session);
+    PrintAgentResponse(response.Text);
+    PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
+}
+
+async Task RunStreamingAsync()
+{
+    int lastChatHistorySize = 0;
+    string lastConversationId = string.Empty;
+
+    Console.ForegroundColor = ConsoleColor.Yellow;
+    Console.WriteLine("\n=== Streaming Mode ===");
+    Console.ResetColor();
+
+    AgentSession session = await agent.CreateSessionAsync();
+
+    // First turn — ask about multiple cities so the model calls tools.
+    const string Prompt = "What's the weather and time in Seattle, New York, and London?";
+    PrintUserMessage(Prompt);
+
+    Console.ForegroundColor = ConsoleColor.Cyan;
+    Console.Write("\n[Agent] ");
+    Console.ResetColor();
+
+    await foreach (var update in agent.RunStreamingAsync(Prompt, session))
+    {
+        Console.Write(update);
+
+        // During streaming we should be able to see updates to the chat history
+        // before the full run completes, as each service call is made and persisted.
+        PrintChatHistory(session, "During run", ref lastChatHistorySize, ref lastConversationId);
+    }
+
+    Console.WriteLine();
+    PrintChatHistory(session, "After run", ref lastChatHistorySize, ref lastConversationId);
+
+    // Second turn — follow-up to verify chat history is correct.
+    const string FollowUp1 = "And Dublin?";
+    PrintUserMessage(FollowUp1);
+
+    Console.ForegroundColor = ConsoleColor.Cyan;
+    Console.Write("\n[Agent] ");
+    Console.ResetColor();
+
+    await foreach (var update in agent.RunStreamingAsync(FollowUp1, session))
+    {
+        Console.Write(update);
+
+        // During streaming we should be able to see updates to the chat history
+        // before the full run completes, as each service call is made and persisted.
+        PrintChatHistory(session, "During second run", ref lastChatHistorySize, ref lastConversationId);
+    }
+
+    Console.WriteLine();
+    PrintChatHistory(session, "After second run", ref lastChatHistorySize, ref lastConversationId);
+
+    // Third turn — follow-up to verify chat history is correct.
+    const string FollowUp2 = "Which city is the warmest?";
+    PrintUserMessage(FollowUp2);
+
+    Console.ForegroundColor = ConsoleColor.Cyan;
+    Console.Write("\n[Agent] ");
+    Console.ResetColor();
+
+    await foreach (var update in agent.RunStreamingAsync(FollowUp2, session))
+    {
+        Console.Write(update);
+
+        // During streaming we should be able to see updates to the chat history
+        // before the full run completes, as each service call is made and persisted.
+        PrintChatHistory(session, "During third run", ref lastChatHistorySize, ref lastConversationId);
+    }
+
+    Console.WriteLine();
+    PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
+}
+
+void PrintUserMessage(string message)
+{
+    Console.ForegroundColor = ConsoleColor.Cyan;
+    Console.Write("\n[User] ");
+    Console.ResetColor();
+    Console.WriteLine(message);
+}
+
+void PrintAgentResponse(string? text)
+{
+    Console.ForegroundColor = ConsoleColor.Cyan;
+    Console.Write("\n[Agent] ");
+    Console.ResetColor();
+    Console.WriteLine(text);
+}
+
+// Helper to print the current chat history from the session.
+void PrintChatHistory(AgentSession session, string label, ref int lastChatHistorySize, ref string lastConversationId)
+{
+    if (session.TryGetInMemoryChatHistory(out var history) && history.Count != lastChatHistorySize)
+    {
+        Console.ForegroundColor = ConsoleColor.DarkGray;
+        Console.WriteLine($"\n  [{label} — Chat history: {history.Count} message(s)]");
+        foreach (var msg in history)
+        {
+            var preview = msg.Text?.Length > 80 ? msg.Text[..80] + "…" : msg.Text;
+            var contentTypes = string.Join(", ", msg.Contents.Select(c => c.GetType().Name));
+            Console.WriteLine($"    {msg.Role,-12} | {(string.IsNullOrWhiteSpace(preview) ? $"[{contentTypes}]" : preview)}");
+        }
+
+        Console.ResetColor();
+
+        lastChatHistorySize = history.Count;
+    }
+
+    if (session is ChatClientAgentSession ccaSession && ccaSession.ConversationId is not null && ccaSession.ConversationId != lastConversationId)
+    {
+        Console.ForegroundColor = ConsoleColor.DarkGray;
+        Console.WriteLine($"  [{label} — Conversation ID: {ccaSession.ConversationId}]");
+        Console.ResetColor();
+        lastConversationId = ccaSession.ConversationId;
+    }
+}

dotnet/samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/README.md

@@ -0,0 +1,63 @@
+# In-Function-Loop Checkpointing
+
+This sample demonstrates how `ChatClientAgent` persists chat history after each individual call to the AI service by default. This per-service-call persistence ensures intermediate progress is saved during the function invocation loop.
+
+## What This Sample Shows
+
+When an agent uses tools, the `FunctionInvokingChatClient` loops multiple times (service call → tool execution → service call → …). By default, chat history is persisted after each service call via the `ChatHistoryPersistingChatClient` decorator:
+
+- A `ChatHistoryPersistingChatClient` decorator is automatically inserted into the chat client pipeline
+- After each service call, the decorator notifies the `ChatHistoryProvider` (and any `AIContextProvider` instances) with the new messages
+- Only **new** messages are sent to providers on each notification — messages that were already persisted in an earlier call within the same run are deduplicated automatically
+
+To opt into end-of-run persistence instead (atomic run semantics), set `PersistChatHistoryAtEndOfRun = true` on `ChatClientAgentOptions`. In that mode, the decorator marks messages with metadata rather than persisting them immediately, and `ChatClientAgent` persists only the marked messages at the end of the run.
+
+Per-service-call persistence is useful for:
+- **Crash recovery** — if the process is interrupted mid-loop, the intermediate tool calls and results are already persisted
+- **Observability** — you can inspect the chat history while the agent is still running (e.g., during streaming)
+- **Long-running tool loops** — agents with many sequential tool calls benefit from incremental persistence
+
+## How It Works
+
+The sample asks the agent about the weather and time in three cities. The model calls the `GetWeather` and `GetTime` tools for each city, resulting in multiple service calls within a single `RunStreamingAsync` invocation. After the run completes, the sample prints the full chat history to show all the intermediate messages that were persisted along the way.
+
+### Pipeline Architecture
+
+```
+ChatClientAgent
+  └─ FunctionInvokingChatClient    (handles tool call loop)
+       └─ ChatHistoryPersistingChatClient  (persists after each service call)
+            └─ Leaf IChatClient            (Azure OpenAI)
+```
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Azure OpenAI service endpoint and model deployment
+- Azure CLI installed and authenticated
+
+**Note**: This sample uses `DefaultAzureCredential`. Sign in with `az login` before running. For production, prefer a specific credential such as `ManagedIdentityCredential`. For more information, see the [Azure CLI authentication documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+
+## Environment Variables
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"  # Required
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"                       # Optional, defaults to gpt-4o-mini
+```
+
+## Running the Sample
+
+```powershell
+cd dotnet/samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing
+dotnet run
+```
+
+## Expected Behavior
+
+The sample runs two conversation turns:
+
+1. **First turn** — asks about weather and time in three cities. The model calls `GetWeather` and `GetTime` tools (potentially in parallel or sequentially), then provides a summary. The chat history dump after the run shows all the intermediate tool call and result messages.
+
+2. **Second turn** — asks a follow-up question ("Which city is the warmest?") that uses the persisted conversation context. The chat history dump shows the full accumulated conversation.
+
+The chat history printout uses `session.TryGetInMemoryChatHistory()` to inspect the in-memory storage.

dotnet/samples/02-agents/Agents/README.md

@@ -45,6 +45,7 @@ Before you begin, ensure you have the following prerequisites:
 |[Declarative agent](./Agent_Step16_Declarative/)|This sample demonstrates how to declaratively define an agent.|
 |[Providing additional AI Context to an agent using multiple AIContextProviders](./Agent_Step17_AdditionalAIContext/)|This sample demonstrates how to inject additional AI context into a ChatClientAgent using multiple custom AIContextProvider components that are attached to the agent.|
 |[Using compaction pipeline with an agent](./Agent_Step18_CompactionPipeline/)|This sample demonstrates how to use a compaction pipeline to efficiently limit the size of the conversation history for an agent.|
+|[In-function-loop checkpointing](./Agent_Step19_InFunctionLoopCheckpointing/)|This sample demonstrates how to persist chat history after each service call during a tool-calling loop, enabling crash recovery and mid-run observability.|
 
 ## Running the samples from the console
 

dotnet/samples/03-workflows/Agents/WorkflowAsAnAgent/Program.cs

@@ -9,7 +9,7 @@ using Microsoft.Extensions.AI;
 namespace WorkflowAsAnAgentSample;
 
 /// <summary>
-/// This sample introduces the concepts workflows as agents, where a workflow can be
+/// This sample introduces the concept of workflows as agents, where a workflow can be
 /// treated as an <see cref="AIAgent"/>. This allows you to interact with a workflow
 /// as if it were a single agent.
 ///
@@ -18,6 +18,14 @@ namespace WorkflowAsAnAgentSample;
 ///
 /// You will interact with the workflow in an interactive loop, sending messages and receiving
 /// streaming responses from the workflow as if it were an agent who responds in both languages.
+///
+/// This sample also demonstrates <see cref="IResettableExecutor"/>, which is required
+/// for stateful executors that are shared across multiple workflow runs. Each iteration
+/// of the interactive loop triggers a new workflow run against the same workflow instance.
+/// Between runs, the framework automatically calls <see cref="IResettableExecutor.ResetAsync"/>
+/// on shared executors so that accumulated state (e.g., collected messages) is cleared
+/// before the next run begins. See <c>WorkflowFactory.ConcurrentAggregationExecutor</c>
+/// for the implementation.
 /// </summary>
 /// <remarks>
 /// Pre-requisites:
@@ -39,7 +47,10 @@ public static class Program
         var agent = workflow.AsAIAgent("workflow-agent", "Workflow Agent");
         var session = await agent.CreateSessionAsync();
 
-        // Start an interactive loop to interact with the workflow as if it were an agent
+        // Start an interactive loop to interact with the workflow as if it were an agent.
+        // Each iteration runs the workflow again on the same workflow instance. Between runs,
+        // the framework calls IResettableExecutor.ResetAsync() on shared stateful executors
+        // (like ConcurrentAggregationExecutor) to clear accumulated state from the previous run.
         while (true)
         {
             Console.WriteLine();

dotnet/samples/03-workflows/Agents/WorkflowAsAnAgent/WorkflowFactory.cs

@@ -10,6 +10,14 @@ internal static class WorkflowFactory
 {
     /// <summary>
     /// Creates a workflow that uses two language agents to process input concurrently.
+    ///
+    /// In this workflow, the <c>Start</c> <see cref="ChatForwardingExecutor"/> and the
+    /// <see cref="ConcurrentAggregationExecutor"/> are provided as shared instances, meaning
+    /// the same executor objects are reused across multiple workflow runs. The language agents
+    /// (French and English) are created via a factory and instantiated per workflow run.
+    /// Stateful shared executors must implement <see cref="IResettableExecutor"/> so the
+    /// framework can clear their state between runs. Framework-provided executors like
+    /// <see cref="ChatForwardingExecutor"/> already implement this interface.
     /// </summary>
     /// <param name="chatClient">The chat client to use for the agents</param>
     /// <returns>A workflow that processes input using two language agents</returns>
@@ -40,6 +48,16 @@ internal static class WorkflowFactory
 
     /// <summary>
     /// Executor that aggregates the results from the concurrent agents.
+    ///
+    /// This executor is stateful — it accumulates messages in <see cref="_messages"/>
+    /// as they arrive from each agent. Because it is provided as a shared instance
+    /// (not via a factory), the same object is reused across workflow runs. Implementing
+    /// <see cref="IResettableExecutor"/> allows the framework to call <see cref="ResetAsync"/>
+    /// between runs, clearing accumulated state so each run starts fresh.
+    ///
+    /// Without <see cref="IResettableExecutor"/>, attempting to reuse a workflow containing
+    /// shared executor instances that do not implement this interface would throw an
+    /// <see cref="InvalidOperationException"/>.
     /// </summary>
     [YieldsOutput(typeof(string))]
     private sealed class ConcurrentAggregationExecutor() :
@@ -65,7 +83,11 @@ internal static class WorkflowFactory
             }
         }
 
-        /// <inheritdoc/>
+        /// <summary>
+        /// Resets the executor state between workflow runs by clearing accumulated messages.
+        /// The framework calls this automatically when a workflow run completes, before the
+        /// workflow can be used for another run.
+        /// </summary>
         public ValueTask ResetAsync()
         {
             this._messages.Clear();

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/04_WorkflowMcpTool.csproj

@@ -0,0 +1,35 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <!-- The Functions build tools don't like namespaces that start with a number -->
+    <AssemblyName>WorkflowMcpTool</AssemblyName>
+    <RootNamespace>WorkflowMcpTool</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+
+  <!-- Azure Functions packages -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Hosting.AzureFunctions" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
+  </ItemGroup>
+</Project>

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/Executors.cs

@@ -0,0 +1,59 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowMcpTool;
+
+internal sealed class TranslateText() : Executor<string, TranslationResult>("TranslateText")
+{
+    public override ValueTask<TranslationResult> HandleAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine($"[Activity] TranslateText: '{message}'");
+        return ValueTask.FromResult(new TranslationResult(message, message.ToUpperInvariant()));
+    }
+}
+
+internal sealed class FormatOutput() : Executor<TranslationResult, string>("FormatOutput")
+{
+    public override ValueTask<string> HandleAsync(
+        TranslationResult message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine("[Activity] FormatOutput: Formatting result");
+        return ValueTask.FromResult($"Original: {message.Original} => Translated: {message.Translated}");
+    }
+}
+
+internal sealed class LookupOrder() : Executor<string, OrderInfo>("LookupOrder")
+{
+    public override ValueTask<OrderInfo> HandleAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine($"[Activity] LookupOrder: '{message}'");
+        return ValueTask.FromResult(new OrderInfo(message, "Alice Johnson", "Wireless Headphones", Quantity: 2, UnitPrice: 49.99m));
+    }
+}
+
+internal sealed class EnrichOrder() : Executor<OrderInfo, OrderSummary>("EnrichOrder")
+{
+    public override ValueTask<OrderSummary> HandleAsync(
+        OrderInfo message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine($"[Activity] EnrichOrder: '{message.OrderId}'");
+        return ValueTask.FromResult(new OrderSummary(message, TotalPrice: message.Quantity * message.UnitPrice, Status: "Confirmed"));
+    }
+}
+
+internal sealed record TranslationResult(string Original, string Translated);
+
+internal sealed record OrderInfo(string OrderId, string CustomerName, string Product, int Quantity, decimal UnitPrice);
+
+internal sealed record OrderSummary(OrderInfo Order, decimal TotalPrice, string Status);

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/Program.cs

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to expose a durable workflow as an MCP (Model Context Protocol) tool.
+// When using AddWorkflow with exposeMcpToolTrigger: true, the Functions host will automatically
+// generate a remote MCP endpoint for the app at /runtime/webhooks/mcp with a workflow-specific
+// tool name. MCP-compatible clients can then invoke the workflow as a tool.
+
+using Microsoft.Agents.AI.Hosting.AzureFunctions;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Azure.Functions.Worker.Builder;
+using Microsoft.Extensions.Hosting;
+using WorkflowMcpTool;
+
+// Define executors
+TranslateText translateText = new();
+FormatOutput formatOutput = new();
+LookupOrder lookupOrder = new();
+EnrichOrder enrichOrder = new();
+
+// Build a simple workflow: TranslateText -> FormatOutput
+Workflow translateWorkflow = new WorkflowBuilder(translateText)
+    .WithName("Translate")
+    .WithDescription("Translate text to uppercase and format the result")
+    .AddEdge(translateText, formatOutput)
+    .Build();
+
+// Build a workflow that returns a POCO: LookupOrder -> EnrichOrder
+Workflow orderLookupWorkflow = new WorkflowBuilder(lookupOrder)
+    .WithName("OrderLookup")
+    .WithDescription("Look up an order by ID and return enriched order details")
+    .AddEdge(lookupOrder, enrichOrder)
+    .Build();
+
+using IHost app = FunctionsApplication
+    .CreateBuilder(args)
+    .ConfigureFunctionsWebApplication()
+    .ConfigureDurableWorkflows(workflows =>
+    {
+        // Expose both workflows as MCP tool triggers.
+        workflows.AddWorkflow(translateWorkflow, exposeStatusEndpoint: false, exposeMcpToolTrigger: true);
+        workflows.AddWorkflow(orderLookupWorkflow, exposeStatusEndpoint: false, exposeMcpToolTrigger: true);
+    })
+    .Build();
+app.Run();

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/README.md

@@ -0,0 +1,81 @@
+# Workflow as MCP Tool Sample
+
+This sample demonstrates how to expose durable workflows as [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) tools, enabling MCP-compatible clients to invoke workflows directly.
+
+## Key Concepts Demonstrated
+
+- **Workflow as MCP Tool**: Expose workflows as callable MCP tools using `exposeMcpToolTrigger: true`
+- **MCP Server Hosting**: The Azure Functions host automatically generates a remote MCP endpoint at `/runtime/webhooks/mcp`
+- **String and POCO Results**: Shows workflows returning both plain strings and structured JSON objects
+
+## Sample Architecture
+
+The sample creates two workflows exposed as MCP tools:
+
+### Translate Workflow (returns a string)
+
+| Executor | Input | Output | Description |
+|----------|-------|--------|-------------|
+| **TranslateText** | `string` | `TranslationResult` | Converts input text to uppercase |
+| **FormatOutput** | `TranslationResult` | `string` | Formats the result into a readable string |
+
+### OrderLookup Workflow (returns a POCO)
+
+| Executor | Input | Output | Description |
+|----------|-------|--------|-------------|
+| **LookupOrder** | `string` | `OrderInfo` | Looks up an order by ID |
+| **EnrichOrder** | `OrderInfo` | `OrderSummary` | Adds computed fields (total price, status) |
+
+## Environment Setup
+
+See the [README.md](../../README.md) file in the parent directory for complete setup instructions, including:
+
+- Prerequisites installation
+- Durable Task Scheduler setup
+- Storage emulator configuration
+
+For this sample, you'll also need [Node.js](https://nodejs.org/en/download) to use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).
+
+## Running the Sample
+
+1. **Start the Function App**:
+
+   ```bash
+   cd dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool
+   func start
+   ```
+
+2. **Note the MCP Server Endpoint**: When the app starts, you'll see the MCP server endpoint in the terminal output:
+
+   ```text
+   MCP server endpoint:  http://localhost:7071/runtime/webhooks/mcp
+   ```
+
+## Invoking Workflows via MCP Inspector
+
+1. Install and run the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector):
+
+   ```bash
+   npx @modelcontextprotocol/inspector
+   ```
+
+2. Connect to the MCP server endpoint:
+   - For **Transport Type**, select **"Streamable HTTP"**
+   - For **URL**, enter `http://localhost:7071/runtime/webhooks/mcp`
+   - Click the **Connect** button
+
+3. Click the **List Tools** button. You should see two tools: `Translate` and `OrderLookup`.
+
+4. Test the **Translate** tool (returns a plain string):
+   - Select the `Translate` tool
+   - Set `hello world` as the `input` parameter
+   - Click **Run Tool**
+   - Expected result: `Original: hello world => Translated: HELLO WORLD`
+
+5. Test the **OrderLookup** tool (returns a JSON object):
+   - Select the `OrderLookup` tool
+   - Set `ORD-2025-42` as the `input` parameter
+   - Click **Run Tool**
+   - Expected result: A JSON object containing order details such as `OrderId`, `CustomerName`, `Product`, `TotalPrice`, and `Status`
+
+You'll see the workflow executor activities logged in the terminal where you ran `func start`.

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/host.json

@@ -0,0 +1,20 @@
+{
+  "version": "2.0",
+  "logging": {
+    "logLevel": {
+      "Microsoft.Agents.AI.DurableTask": "Information",
+      "Microsoft.Agents.AI.Hosting.AzureFunctions": "Information",
+      "DurableTask": "Information",
+      "Microsoft.DurableTask": "Information"
+    }
+  },
+  "extensions": {
+    "durableTask": {
+      "hubName": "default",
+      "storageProvider": {
+        "type": "AzureManaged",
+        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
+      }
+    }
+  }
+}

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/local.settings.json

@@ -0,0 +1,8 @@
+{
+  "IsEncrypted": false,
+  "Values": {
+    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
+    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
+    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
+  }
+}

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/05_WorkflowAndAgents.csproj

@@ -0,0 +1,42 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <!-- The Functions build tools don't like namespaces that start with a number -->
+    <AssemblyName>WorkflowAndAgents</AssemblyName>
+    <RootNamespace>WorkflowAndAgents</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+
+  <!-- Azure Functions packages -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Hosting.AzureFunctions" />
+    <PackageReference Include="Microsoft.Agents.AI.OpenAI" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+</Project>

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/Executors.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowAndAgents;
+
+internal sealed class TranslateText() : Executor<string, TranslationResult>("TranslateText")
+{
+    public override ValueTask<TranslationResult> HandleAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine($"[Activity] TranslateText: '{message}'");
+        return ValueTask.FromResult(new TranslationResult(message, message.ToUpperInvariant()));
+    }
+}
+
+internal sealed class FormatOutput() : Executor<TranslationResult, string>("FormatOutput")
+{
+    public override ValueTask<string> HandleAsync(
+        TranslationResult message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine("[Activity] FormatOutput: Formatting result");
+        return ValueTask.FromResult($"Original: {message.Original} => Translated: {message.Translated}");
+    }
+}
+
+internal sealed record TranslationResult(string Original, string Translated);

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/Program.cs

@@ -0,0 +1,64 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates using ConfigureDurableOptions to register BOTH agents AND workflows
+// in a single Azure Functions app. It uses a workflow to translate text and a standalone AI agent
+// accessible via HTTP and MCP tool triggers.
+
+#pragma warning disable IDE0002 // Simplify Member Access
+
+using Azure;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hosting.AzureFunctions;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Azure.Functions.Worker.Builder;
+using Microsoft.Extensions.Hosting;
+using OpenAI.Chat;
+using WorkflowAndAgents;
+
+// Get the Azure OpenAI endpoint and deployment name from environment variables.
+string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
+
+// Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
+string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY");
+AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
+    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+
+ChatClient chatClient = client.GetChatClient(deploymentName);
+
+// Define a standalone AI agent
+AIAgent assistant = chatClient.AsAIAgent(
+    "You are a helpful assistant. Answer questions clearly and concisely.",
+    "Assistant",
+    description: "A general-purpose helpful assistant.");
+
+// Define workflow executors
+TranslateText translateText = new();
+FormatOutput formatOutput = new();
+
+// Build a workflow: TranslateText -> FormatOutput
+Workflow translateWorkflow = new WorkflowBuilder(translateText)
+    .WithName("Translate")
+    .WithDescription("Translate text to uppercase and format the result")
+    .AddEdge(translateText, formatOutput)
+    .Build();
+
+// Use ConfigureDurableOptions to register both agents and workflows together
+using IHost app = FunctionsApplication
+    .CreateBuilder(args)
+    .ConfigureFunctionsWebApplication()
+    .ConfigureDurableOptions(options =>
+    {
+        // Register the standalone agent with HTTP and MCP tool triggers
+        options.Agents.AddAIAgent(assistant, enableHttpTrigger: true, enableMcpToolTrigger: true);
+
+        // Register the workflow with an HTTP endpoint and MCP tool trigger
+        options.Workflows.AddWorkflow(translateWorkflow, exposeStatusEndpoint: false, exposeMcpToolTrigger: true);
+    })
+    .Build();
+app.Run();

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/README.md

@@ -0,0 +1,76 @@
+# Workflow and Agents Sample
+
+This sample demonstrates how to use `ConfigureDurableOptions` to register **both** AI agents **and** workflows in a single Azure Functions app. This is the recommended approach when your application needs both standalone agents and orchestrated workflows.
+
+## Key Concepts Demonstrated
+
+- **Unified Configuration**: Use `ConfigureDurableOptions` to register agents and workflows together
+- **Standalone Agent**: An AI agent accessible via HTTP and MCP tool triggers
+- **Workflow**: A simple text translation workflow also exposed as an MCP tool
+- **Mixed Triggers**: Both agents and workflows coexist in the same Functions host
+
+## Sample Architecture
+
+### Standalone Agent
+
+| Agent | Description |
+|-------|-------------|
+| **Assistant** | A general-purpose AI assistant accessible via HTTP (`/agents/Assistant/run`) and as an MCP tool |
+
+### Translate Workflow
+
+| Executor | Input | Output | Description |
+|----------|-------|--------|-------------|
+| **TranslateText** | `string` | `TranslationResult` | Converts input text to uppercase |
+| **FormatOutput** | `TranslationResult` | `string` | Formats the result into a readable string |
+
+## Environment Setup
+
+See the [README.md](../../README.md) file in the parent directory for complete setup instructions, including:
+
+- Prerequisites installation
+- Durable Task Scheduler setup
+- Storage emulator configuration
+
+This sample also requires Azure OpenAI credentials. Set the following in `local.settings.json`:
+
+- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint URL
+- `AZURE_OPENAI_DEPLOYMENT_NAME`: Your chat model deployment name
+- `AZURE_OPENAI_API_KEY` (optional): If not set, Azure CLI credential is used
+
+## Running the Sample
+
+1. **Start the Function App**:
+
+   ```bash
+   cd dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents
+   func start
+   ```
+
+2. **Expected Functions**: When the app starts, you should see functions for both the agent and the workflow:
+
+   - `dafx-Assistant` (entity trigger for the agent)
+   - `http-Assistant` (HTTP trigger for the agent)
+   - `mcptool-Assistant` (MCP tool trigger for the agent)
+   - `wf-Translate` (orchestration trigger for the workflow)
+   - `mcptool-wf-Translate` (MCP tool trigger for the workflow)
+
+## Invoking the Agent via HTTP
+
+```bash
+curl -X POST http://localhost:7071/agents/Assistant/run \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What is the capital of France?"}'
+```
+
+## Invoking via MCP Inspector
+
+1. Install and run the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector):
+
+   ```bash
+   npx @modelcontextprotocol/inspector
+   ```
+
+2. Connect to `http://localhost:7071/runtime/webhooks/mcp` using **Streamable HTTP** transport.
+
+3. Click **List Tools** to see both the `Assistant` agent tool and the `Translate` workflow tool.

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/host.json

@@ -0,0 +1,20 @@
+{
+  "version": "2.0",
+  "logging": {
+    "logLevel": {
+      "Microsoft.Agents.AI.DurableTask": "Information",
+      "Microsoft.Agents.AI.Hosting.AzureFunctions": "Information",
+      "DurableTask": "Information",
+      "Microsoft.DurableTask": "Information"
+    }
+  },
+  "extensions": {
+    "durableTask": {
+      "hubName": "default",
+      "storageProvider": {
+        "type": "AzureManaged",
+        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
+      }
+    }
+  }
+}

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/local.settings.json

@@ -0,0 +1,10 @@
+{
+  "IsEncrypted": false,
+  "Values": {
+    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
+    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
+    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
+    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
+    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
+  }
+}

dotnet/samples/04-hosting/DurableWorkflows/README.md

@@ -48,3 +48,4 @@ $env:DURABLE_TASK_SCHEDULER_CONNECTION_STRING = "AccountEndpoint=http://localhos
 | [01_SequentialWorkflow](AzureFunctions/01_SequentialWorkflow/) | Sequential workflow hosted in Azure Functions |
 | [02_ConcurrentWorkflow](AzureFunctions/02_ConcurrentWorkflow/) | Concurrent workflow hosted in Azure Functions |
 | [03_WorkflowHITL](AzureFunctions/03_WorkflowHITL/) | Human-in-the-loop workflow hosted in Azure Functions |
+| [04_WorkflowMcpTool](AzureFunctions/04_WorkflowMcpTool/) | Workflow exposed as an MCP tool |

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/BuiltInFunctionExecutor.cs

@@ -167,6 +167,20 @@ internal sealed class BuiltInFunctionExecutor : IFunctionExecutor
             return;
         }
 
+        if (context.FunctionDefinition.EntryPoint == BuiltInFunctions.RunWorkflowMcpToolFunctionEntryPoint)
+        {
+            if (mcpToolInvocationContext is null)
+            {
+                throw new InvalidOperationException($"MCP tool invocation context binding is missing for the invocation {context.InvocationId}.");
+            }
+
+            context.GetInvocationResult().Value = await BuiltInFunctions.RunWorkflowMcpToolAsync(
+                mcpToolInvocationContext,
+                durableTaskClient,
+                context);
+            return;
+        }
+
         throw new InvalidOperationException($"Unsupported function entry point '{context.FunctionDefinition.EntryPoint}' for invocation {context.InvocationId}.");
     }
 

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/BuiltInFunctions.cs

@@ -29,6 +29,7 @@ internal static class BuiltInFunctions
     internal static readonly string InvokeWorkflowActivityFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(InvokeWorkflowActivityAsync)}";
     internal static readonly string GetWorkflowStatusHttpFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(GetWorkflowStatusAsync)}";
     internal static readonly string RespondToWorkflowHttpFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(RespondToWorkflowAsync)}";
+    internal static readonly string RunWorkflowMcpToolFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(RunWorkflowMcpToolAsync)}";
 
 #pragma warning disable IL3000 // Avoid accessing Assembly file path when publishing as a single file - Azure Functions does not use single-file publishing
     internal static readonly string ScriptFile = Path.GetFileName(typeof(BuiltInFunctions).Assembly.Location);
@@ -378,6 +379,55 @@ internal static class BuiltInFunctions
         return agentResponse.Text;
     }
 
+    /// <summary>
+    /// Runs a workflow via MCP tool trigger.
+    /// Extracts the <c>input</c> argument, schedules a new orchestration, waits for completion, and returns the output.
+    /// </summary>
+    public static async Task<string?> RunWorkflowMcpToolAsync(
+        [McpToolTrigger("BuiltInWorkflowMcpTool")] ToolInvocationContext context,
+        [DurableClient] DurableTaskClient client,
+        FunctionContext functionContext)
+    {
+        if (context.Arguments is null)
+        {
+            throw new ArgumentException("MCP Tool invocation is missing required arguments.");
+        }
+
+        if (!context.Arguments.TryGetValue("input", out object? inputObj) || inputObj is not string input)
+        {
+            throw new ArgumentException("MCP Tool invocation is missing required 'input' argument of type string.");
+        }
+
+        string workflowName = context.Name;
+        string orchestrationFunctionName = WorkflowNamingHelper.ToOrchestrationFunctionName(workflowName);
+
+        DurableWorkflowInput<string> orchestrationInput = new() { Input = input };
+        string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(orchestrationFunctionName, orchestrationInput);
+
+        OrchestrationMetadata? metadata = await client.WaitForInstanceCompletionAsync(
+            instanceId,
+            getInputsAndOutputs: true,
+            cancellation: functionContext.CancellationToken);
+
+        if (metadata is null)
+        {
+            throw new InvalidOperationException($"Workflow orchestration '{instanceId}' returned no metadata.");
+        }
+
+        if (metadata.RuntimeStatus is OrchestrationRuntimeStatus.Failed)
+        {
+            string errorMessage = metadata.FailureDetails?.ErrorMessage ?? "Unknown error";
+            throw new InvalidOperationException($"Workflow orchestration '{instanceId}' failed: {errorMessage}");
+        }
+
+        if (metadata.RuntimeStatus is not OrchestrationRuntimeStatus.Completed)
+        {
+            throw new InvalidOperationException($"Workflow orchestration '{instanceId}' ended with unexpected status '{metadata.RuntimeStatus}'.");
+        }
+
+        return metadata.ReadOutputAs<DurableWorkflowResult>()?.Result;
+    }
+
     /// <summary>
     /// Creates an error response with the specified status code and error message.
     /// </summary>

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Added MCP tool trigger support for durable workflows ([#4768](https://github.com/microsoft/agent-framework/pull/4768))
 - Added Azure Functions hosting support for durable workflows ([#4436](https://github.com/microsoft/agent-framework/pull/4436))
 
 ## v1.0.0-preview.251219.1

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/DefaultFunctionsAgentOptionsProvider.cs

@@ -6,7 +6,8 @@ namespace Microsoft.Agents.AI.Hosting.AzureFunctions;
 
 /// <summary>
 /// Provides access to agent-specific options for functions agents by name.
-/// Returns default options (HTTP trigger enabled, MCP tool disabled) when no explicit options were configured.
+/// Returns <see langword="false"/> when no explicit options have been configured for an agent,
+/// which distinguishes standalone agents from those auto-registered by workflows.
 /// </summary>
 internal sealed class DefaultFunctionsAgentOptionsProvider(IReadOnlyDictionary<string, FunctionsAgentOptions> functionsAgentOptions)
     : IFunctionsAgentOptionsProvider
@@ -14,32 +15,19 @@ internal sealed class DefaultFunctionsAgentOptionsProvider(IReadOnlyDictionary<s
     private readonly IReadOnlyDictionary<string, FunctionsAgentOptions> _functionsAgentOptions =
         functionsAgentOptions ?? throw new ArgumentNullException(nameof(functionsAgentOptions));
 
-    // Default options. HTTP trigger enabled, MCP tool disabled.
-    private static readonly FunctionsAgentOptions s_defaultOptions = new()
-    {
-        HttpTrigger = { IsEnabled = true },
-        McpToolTrigger = { IsEnabled = false }
-    };
-
     /// <summary>
     /// Attempts to retrieve the options associated with the specified agent name.
-    /// If not found, a default options instance (with HTTP trigger enabled) is returned.
+    /// Returns <see langword="false"/> when no options have been explicitly configured for the agent.
     /// </summary>
     /// <param name="agentName">The name of the agent whose options are to be retrieved. Cannot be null or empty.</param>
-    /// <param name="options">The options for the specified agent. Will never be null.</param>
-    /// <returns>Always true. Returns configured options if present; otherwise default fallback options.</returns>
+    /// <param name="options">
+    /// When this method returns <see langword="true"/>, contains the options for the specified agent;
+    /// otherwise, <see langword="null"/>.
+    /// </param>
+    /// <returns><see langword="true"/> if options were found for the agent; otherwise, <see langword="false"/>.</returns>
     public bool TryGet(string agentName, [NotNullWhen(true)] out FunctionsAgentOptions? options)
     {
         ArgumentException.ThrowIfNullOrEmpty(agentName);
-
-        if (this._functionsAgentOptions.TryGetValue(agentName, out FunctionsAgentOptions? existing))
-        {
-            options = existing;
-            return true;
-        }
-
-        // If not defined, return default options.
-        options = s_defaultOptions;
-        return true;
+        return this._functionsAgentOptions.TryGetValue(agentName, out options);
     }
 }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/DurableAgentFunctionMetadataTransformer.cs

@@ -6,9 +6,13 @@ using Microsoft.Extensions.Logging;
 namespace Microsoft.Agents.AI.Hosting.AzureFunctions;
 
 /// <summary>
-/// Transforms function metadata by registering durable agent functions for each configured agent.
+/// Transforms function metadata by registering durable agent functions for each explicitly configured agent.
 /// </summary>
-/// <remarks>This transformer adds both entity trigger and HTTP trigger functions for every agent registered in the application.</remarks>
+/// <remarks>
+/// This transformer adds entity, HTTP, and MCP tool trigger functions for agents that have
+/// explicit <see cref="FunctionsAgentOptions"/>. Agents auto-registered by workflows
+/// (which lack explicit options) are handled by <see cref="DurableWorkflowsFunctionMetadataTransformer"/>.
+/// </remarks>
 internal sealed class DurableAgentFunctionMetadataTransformer : IFunctionMetadataTransformer
 {
     private readonly ILogger<DurableAgentFunctionMetadataTransformer> _logger;
@@ -38,24 +42,27 @@ internal sealed class DurableAgentFunctionMetadataTransformer : IFunctionMetadat
         {
             string agentName = kvp.Key;
 
-            this._logger.LogRegisteringTriggerForAgent(agentName, "entity");
+            // Only generate triggers for agents with explicit Functions agent options.
+            // Agents auto-registered by workflows are handled by DurableWorkflowsFunctionMetadataTransformer.
+            if (!this._functionsAgentOptionsProvider.TryGet(agentName, out FunctionsAgentOptions? agentTriggerOptions))
+            {
+                continue;
+            }
 
+            this._logger.LogRegisteringTriggerForAgent(agentName, "entity");
             original.Add(FunctionMetadataFactory.CreateEntityTrigger(agentName));
 
-            if (this._functionsAgentOptionsProvider.TryGet(agentName, out FunctionsAgentOptions? agentTriggerOptions))
+            if (agentTriggerOptions.HttpTrigger.IsEnabled)
             {
-                if (agentTriggerOptions.HttpTrigger.IsEnabled)
-                {
-                    this._logger.LogRegisteringTriggerForAgent(agentName, "http");
-                    original.Add(FunctionMetadataFactory.CreateHttpTrigger(agentName, $"agents/{agentName}/run", BuiltInFunctions.RunAgentHttpFunctionEntryPoint));
-                }
+                this._logger.LogRegisteringTriggerForAgent(agentName, "http");
+                original.Add(FunctionMetadataFactory.CreateHttpTrigger(agentName, $"agents/{agentName}/run", BuiltInFunctions.RunAgentHttpFunctionEntryPoint));
+            }
 
-                if (agentTriggerOptions.McpToolTrigger.IsEnabled)
-                {
-                    AIAgent agent = kvp.Value(this._serviceProvider);
-                    this._logger.LogRegisteringTriggerForAgent(agentName, "mcpTool");
-                    original.Add(CreateMcpToolTrigger(agentName, agent.Description));
-                }
+            if (agentTriggerOptions.McpToolTrigger.IsEnabled)
+            {
+                AIAgent agent = kvp.Value(this._serviceProvider);
+                this._logger.LogRegisteringTriggerForAgent(agentName, "mcpTool");
+                original.Add(CreateMcpToolTrigger(agentName, agent.Description));
             }
         }
     }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/DurableAgentsOptionsExtensions.cs

@@ -134,4 +134,17 @@ public static class DurableAgentsOptionsExtensions
     {
         return new Dictionary<string, FunctionsAgentOptions>(s_agentOptions, StringComparer.OrdinalIgnoreCase);
     }
+
+    /// <summary>
+    /// Ensures every agent in <paramref name="agentNames"/> has an entry in the
+    /// options registry. Agents that already have explicit options are left untouched.
+    /// New entries receive the default configuration (HTTP trigger enabled, MCP tool disabled).
+    /// </summary>
+    internal static void EnsureDefaultOptionsForAll(IEnumerable<string> agentNames)
+    {
+        foreach (string name in agentNames)
+        {
+            s_agentOptions.TryAdd(name, new FunctionsAgentOptions { HttpTrigger = { IsEnabled = true } });
+        }
+    }
 }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/FunctionMetadataFactory.cs

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System.Text.Json.Nodes;
 using Microsoft.Agents.AI.DurableTask;
 using Microsoft.Azure.Functions.Worker.Core.FunctionMetadata;
 
@@ -98,4 +99,65 @@ internal static class FunctionMetadataFactory
             ScriptFile = BuiltInFunctions.ScriptFile,
         };
     }
+
+    /// <summary>
+    /// Creates function metadata for an MCP tool trigger function that starts a workflow.
+    /// </summary>
+    /// <param name="workflowName">The name of the workflow to expose as an MCP tool.</param>
+    /// <param name="description">An optional description for the MCP tool. If null, a default description is generated.</param>
+    /// <returns>A <see cref="DefaultFunctionMetadata"/> configured for an MCP tool trigger.</returns>
+    internal static DefaultFunctionMetadata CreateWorkflowMcpToolTrigger(
+        string workflowName,
+        string? description)
+    {
+        var functionName = $"{BuiltInFunctions.McpToolPrefix}{workflowName}";
+        var toolDescription = description ?? $"Run the {workflowName} workflow";
+
+        var toolProperties = new JsonArray(new JsonObject
+        {
+            ["propertyName"] = "input",
+            ["propertyType"] = "string",
+            ["description"] = "The input to the workflow.",
+            ["isRequired"] = true,
+            ["isArray"] = false,
+        });
+
+        var triggerBinding = new JsonObject
+        {
+            ["name"] = "context",
+            ["type"] = "mcpToolTrigger",
+            ["direction"] = "In",
+            ["toolName"] = workflowName,
+            ["description"] = toolDescription,
+            ["toolProperties"] = toolProperties.ToJsonString(),
+        };
+
+        var inputBinding = new JsonObject
+        {
+            ["name"] = "input",
+            ["type"] = "mcpToolProperty",
+            ["direction"] = "In",
+            ["propertyName"] = "input",
+            ["description"] = "The input to the workflow",
+            ["isRequired"] = true,
+            ["dataType"] = "String",
+            ["propertyType"] = "string",
+        };
+
+        var clientBinding = new JsonObject
+        {
+            ["name"] = "client",
+            ["type"] = "durableClient",
+            ["direction"] = "In",
+        };
+
+        return new DefaultFunctionMetadata
+        {
+            Name = functionName,
+            Language = "dotnet-isolated",
+            RawBindings = [triggerBinding.ToJsonString(), inputBinding.ToJsonString(), clientBinding.ToJsonString()],
+            EntryPoint = BuiltInFunctions.RunWorkflowMcpToolFunctionEntryPoint,
+            ScriptFile = BuiltInFunctions.ScriptFile,
+        };
+    }
 }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/FunctionsApplicationBuilderExtensions.cs

@@ -27,9 +27,16 @@ public static class FunctionsApplicationBuilderExtensions
     {
         ArgumentNullException.ThrowIfNull(configure);
 
+        // Create/get shared options BEFORE the DurableTask library call so it can find them.
+        FunctionsDurableOptions sharedOptions = GetOrCreateSharedOptions(builder.Services);
+
         // The main agent services registration is done in Microsoft.DurableTask.Agents.
         builder.Services.ConfigureDurableAgents(configure);
 
+        // Ensure all agents registered through this path have default FunctionsAgentOptions.
+        // This distinguishes them from agents auto-registered by workflows.
+        DurableAgentsOptionsExtensions.EnsureDefaultOptionsForAll(sharedOptions.Agents.GetAgentFactories().Keys);
+
         builder.Services.TryAddSingleton<IFunctionsAgentOptionsProvider>(_ =>
             new DefaultFunctionsAgentOptionsProvider(DurableAgentsOptionsExtensions.GetAgentOptionsSnapshot()));
 
@@ -67,6 +74,13 @@ public static class FunctionsApplicationBuilderExtensions
 
         builder.Services.ConfigureDurableOptions(configure);
 
+        if (DurableAgentsOptionsExtensions.GetAgentOptionsSnapshot().Count > 0)
+        {
+            builder.Services.TryAddSingleton<IFunctionsAgentOptionsProvider>(_ =>
+                new DefaultFunctionsAgentOptionsProvider(DurableAgentsOptionsExtensions.GetAgentOptionsSnapshot()));
+            builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IFunctionMetadataTransformer, DurableAgentFunctionMetadataTransformer>());
+        }
+
         if (sharedOptions.Workflows.Workflows.Count > 0)
         {
             builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IFunctionMetadataTransformer, DurableWorkflowsFunctionMetadataTransformer>());
@@ -102,12 +116,14 @@ public static class FunctionsApplicationBuilderExtensions
 
         builder.UseWhen<BuiltInFunctionExecutionMiddleware>(static context =>
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunAgentHttpFunctionEntryPoint, StringComparison.Ordinal) ||
+            string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunAgentMcpToolFunctionEntryPoint, StringComparison.Ordinal) ||
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunAgentEntityFunctionEntryPoint, StringComparison.Ordinal) ||
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunWorkflowOrchestrationHttpFunctionEntryPoint, StringComparison.Ordinal) ||
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunWorkflowOrchestrationFunctionEntryPoint, StringComparison.Ordinal) ||
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.InvokeWorkflowActivityFunctionEntryPoint, StringComparison.Ordinal) ||
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.GetWorkflowStatusHttpFunctionEntryPoint, StringComparison.Ordinal) ||
-            string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RespondToWorkflowHttpFunctionEntryPoint, StringComparison.Ordinal)
+            string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RespondToWorkflowHttpFunctionEntryPoint, StringComparison.Ordinal) ||
+            string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunWorkflowMcpToolFunctionEntryPoint, StringComparison.Ordinal)
         );
         builder.Services.TryAddSingleton<BuiltInFunctionExecutor>();
     }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/FunctionsDurableOptions.cs

@@ -10,6 +10,7 @@ namespace Microsoft.Agents.AI.Hosting.AzureFunctions;
 internal sealed class FunctionsDurableOptions : DurableOptions
 {
     private readonly HashSet<string> _statusEndpointWorkflows = new(StringComparer.OrdinalIgnoreCase);
+    private readonly HashSet<string> _mcpToolTriggerWorkflows = new(StringComparer.OrdinalIgnoreCase);
 
     /// <summary>
     /// Enables the status HTTP endpoint for the specified workflow.
@@ -26,4 +27,20 @@ internal sealed class FunctionsDurableOptions : DurableOptions
     {
         return this._statusEndpointWorkflows.Contains(workflowName);
     }
+
+    /// <summary>
+    /// Enables the MCP tool trigger for the specified workflow.
+    /// </summary>
+    internal void EnableMcpToolTrigger(string workflowName)
+    {
+        this._mcpToolTriggerWorkflows.Add(workflowName);
+    }
+
+    /// <summary>
+    /// Returns whether the MCP tool trigger is enabled for the specified workflow.
+    /// </summary>
+    internal bool IsMcpToolTriggerEnabled(string workflowName)
+    {
+        return this._mcpToolTriggerWorkflows.Contains(workflowName);
+    }
 }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/Workflows/DurableWorkflowOptionsExtensions.cs

@@ -27,4 +27,31 @@ public static class DurableWorkflowOptionsExtensions
             functionsOptions.EnableStatusEndpoint(workflow.Name!);
         }
     }
+
+    /// <summary>
+    /// Adds a workflow and configures whether to expose a status HTTP endpoint and/or an MCP tool trigger.
+    /// </summary>
+    /// <param name="options">The workflow options to add the workflow to.</param>
+    /// <param name="workflow">The workflow instance to add.</param>
+    /// <param name="exposeStatusEndpoint">If <see langword="true"/>, a GET endpoint is generated at <c>workflows/{name}/status/{runId}</c>.</param>
+    /// <param name="exposeMcpToolTrigger">If <see langword="true"/>, an MCP tool trigger is generated for the workflow.</param>
+    public static void AddWorkflow(this DurableWorkflowOptions options, Workflow workflow, bool exposeStatusEndpoint, bool exposeMcpToolTrigger)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        options.AddWorkflow(workflow);
+
+        if (options.ParentOptions is FunctionsDurableOptions functionsOptions)
+        {
+            if (exposeStatusEndpoint)
+            {
+                functionsOptions.EnableStatusEndpoint(workflow.Name!);
+            }
+
+            if (exposeMcpToolTrigger)
+            {
+                functionsOptions.EnableMcpToolTrigger(workflow.Name!);
+            }
+        }
+    }
 }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/Workflows/DurableWorkflowsFunctionMetadataTransformer.cs

@@ -50,8 +50,11 @@ internal sealed class DurableWorkflowsFunctionMetadataTransformer : IFunctionMet
         int initialCount = original.Count;
         this._logger.LogTransformingFunctionMetadata(initialCount);
 
-        // Track registered function names to avoid duplicates when workflows share executors.
-        HashSet<string> registeredFunctions = [];
+        // Seed with existing function names to avoid duplicates across transformers
+        // (e.g., when DurableAgentFunctionMetadataTransformer already registered entity triggers).
+        HashSet<string> registeredFunctions = new(
+            original.Select(f => f.Name!),
+            StringComparer.OrdinalIgnoreCase);
 
         DurableWorkflowOptions workflowOptions = this._options.Workflows;
         foreach (var workflow in workflowOptions.Workflows)
@@ -113,6 +116,17 @@ internal sealed class DurableWorkflowsFunctionMetadataTransformer : IFunctionMet
                 }
             }
 
+            // Register an MCP tool trigger if opted in via AddWorkflow(exposeMcpToolTrigger: true).
+            if (this._options.IsMcpToolTriggerEnabled(workflow.Key))
+            {
+                string mcpToolFunctionName = $"{BuiltInFunctions.McpToolPrefix}{workflow.Key}";
+                if (registeredFunctions.Add(mcpToolFunctionName))
+                {
+                    this._logger.LogRegisteringWorkflowTrigger(workflow.Key, mcpToolFunctionName, "mcpTool");
+                    original.Add(FunctionMetadataFactory.CreateWorkflowMcpToolTrigger(workflow.Key, workflow.Value.Description));
+                }
+            }
+
             // Register activity or entity functions for each executor in the workflow.
             // ReflectExecutors() returns all executors across the graph; no need to manually traverse edges.
             foreach (KeyValuePair<string, ExecutorBinding> entry in workflow.Value.ReflectExecutors())

dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/FileSystemJsonCheckpointStore.cs

@@ -5,11 +5,14 @@ using System.Collections.Generic;
 using System.IO;
 using System.Text;
 using System.Text.Json;
+using System.Text.Json.Serialization.Metadata;
 using System.Threading;
 using System.Threading.Tasks;
 
 namespace Microsoft.Agents.AI.Workflows.Checkpointing;
 
+internal record CheckpointFileIndexEntry(CheckpointInfo CheckpointInfo, string FileName);
+
 /// <summary>
 /// Provides a file system-based implementation of a JSON checkpoint store that persists checkpoint data and index
 /// information to disk using JSON files.
@@ -28,6 +31,8 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
     internal DirectoryInfo Directory { get; }
     internal HashSet<CheckpointInfo> CheckpointIndex { get; }
 
+    private static JsonTypeInfo<CheckpointFileIndexEntry> EntryTypeInfo => WorkflowsJsonUtilities.JsonContext.Default.CheckpointFileIndexEntry;
+
     /// <summary>
     /// Initializes a new instance of the <see cref="FileSystemJsonCheckpointStore"/> class that uses the specified directory
     /// </summary>
@@ -64,9 +69,11 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
             using StreamReader reader = new(this._indexFile, encoding: Encoding.UTF8, detectEncodingFromByteOrderMarks: false, BufferSize, leaveOpen: true);
             while (reader.ReadLine() is string line)
             {
-                if (JsonSerializer.Deserialize(line, KeyTypeInfo) is { } info)
+                if (JsonSerializer.Deserialize(line, EntryTypeInfo) is { } entry)
                 {
-                    this.CheckpointIndex.Add(info);
+                    // We never actually use the file names from the index entries since they can be derived from the CheckpointInfo, but it is useful to
+                    // have the UrlEncoded file names in the index file for human readability
+                    this.CheckpointIndex.Add(entry.CheckpointInfo);
                 }
             }
         }
@@ -93,8 +100,14 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
         }
     }
 
-    private string GetFileNameForCheckpoint(string sessionId, CheckpointInfo key)
-        => Path.Combine(this.Directory.FullName, $"{sessionId}_{key.CheckpointId}.json");
+    internal string GetFileNameForCheckpoint(string sessionId, CheckpointInfo key)
+    {
+        string protoPath = $"{sessionId}_{key.CheckpointId}.json";
+
+        // Escape the protoPath to ensure it is a valid file name, especially if sessionId or CheckpointId contain path separators, etc.
+        return Uri.EscapeDataString(protoPath) // This takes care of most of the invalid path characters
+                  .Replace(".", "%2E");        // This takes care of escaping the root folder, since EscapeDataString does not escape dots
+    }
 
     private CheckpointInfo GetUnusedCheckpointInfo(string sessionId)
     {
@@ -116,13 +129,16 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
 
         CheckpointInfo key = this.GetUnusedCheckpointInfo(sessionId);
         string fileName = this.GetFileNameForCheckpoint(sessionId, key);
+        string filePath = Path.Combine(this.Directory.FullName, fileName);
+
         try
         {
-            using Stream checkpointStream = File.Open(fileName, FileMode.Create, FileAccess.Write, FileShare.None);
+            using Stream checkpointStream = File.Open(filePath, FileMode.Create, FileAccess.Write, FileShare.None);
             using Utf8JsonWriter jsonWriter = new(checkpointStream, new JsonWriterOptions() { Indented = false });
             value.WriteTo(jsonWriter);
 
-            JsonSerializer.Serialize(this._indexFile!, key, KeyTypeInfo);
+            CheckpointFileIndexEntry entry = new(key, fileName);
+            JsonSerializer.Serialize(this._indexFile!, entry, EntryTypeInfo);
             byte[] bytes = Encoding.UTF8.GetBytes(Environment.NewLine);
             await this._indexFile!.WriteAsync(bytes, 0, bytes.Length, CancellationToken.None).ConfigureAwait(false);
             await this._indexFile!.FlushAsync(CancellationToken.None).ConfigureAwait(false);
@@ -136,7 +152,7 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
             try
             {
                 // try to clean up after ourselves
-                File.Delete(fileName);
+                File.Delete(filePath);
             }
             catch { }
 
@@ -149,6 +165,7 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
     {
         this.CheckDisposed();
         string fileName = this.GetFileNameForCheckpoint(sessionId, key);
+        string filePath = Path.Combine(this.Directory.FullName, fileName);
 
         if (!this.CheckpointIndex.Contains(key) ||
             !File.Exists(fileName))
@@ -156,7 +173,7 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
             throw new KeyNotFoundException($"Checkpoint '{key.CheckpointId}' not found in store at '{this.Directory.FullName}'.");
         }
 
-        using FileStream checkpointFileStream = File.Open(fileName, FileMode.Open, FileAccess.Read, FileShare.Read);
+        using FileStream checkpointFileStream = File.Open(filePath, FileMode.Open, FileAccess.Read, FileShare.Read);
         using JsonDocument document = await JsonDocument.ParseAsync(checkpointFileStream).ConfigureAwait(false);
 
         return document.RootElement.Clone();

dotnet/src/Microsoft.Agents.AI.Workflows/Execution/AsyncRunHandle.cs

@@ -53,6 +53,9 @@ internal sealed class AsyncRunHandle : ICheckpointingHandle, IAsyncDisposable
     public ValueTask<RunStatus> GetStatusAsync(CancellationToken cancellationToken = default)
         => this._eventStream.GetStatusAsync(cancellationToken);
 
+    internal bool TryGetResponsePortExecutorId(string portId, out string? executorId)
+        => this._stepRunner.TryGetResponsePortExecutorId(portId, out executorId);
+
     public async IAsyncEnumerable<WorkflowEvent> TakeEventStreamAsync(bool blockOnPendingRequest, [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
         //Debug.Assert(breakOnHalt);

dotnet/src/Microsoft.Agents.AI.Workflows/Execution/EdgeMap.cs

@@ -3,6 +3,7 @@
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
@@ -95,6 +96,18 @@ internal sealed class EdgeMap
         return portRunner.ChaseEdgeAsync(new MessageEnvelope(response, ExecutorIdentity.None), this._stepTracer, cancellationToken);
     }
 
+    internal bool TryGetResponsePortExecutorId(string portId, [NotNullWhen(true)] out string? executorId)
+    {
+        if (this._portEdgeRunners.TryGetValue(portId, out ResponseEdgeRunner? portRunner))
+        {
+            executorId = portRunner.ExecutorId;
+            return true;
+        }
+
+        executorId = null;
+        return false;
+    }
+
     internal async ValueTask<Dictionary<EdgeId, PortableValue>> ExportStateAsync()
     {
         Dictionary<EdgeId, PortableValue> exportedStates = [];

dotnet/src/Microsoft.Agents.AI.Workflows/Execution/ISuperStepRunner.cs

@@ -19,6 +19,7 @@ internal interface ISuperStepRunner
     bool HasUnprocessedMessages { get; }
 
     ValueTask EnqueueResponseAsync(ExternalResponse response, CancellationToken cancellationToken = default);
+    bool TryGetResponsePortExecutorId(string portId, out string? executorId);
 
     ValueTask<bool> IsValidInputTypeAsync<T>(CancellationToken cancellationToken = default);
     ValueTask<bool> EnqueueMessageAsync<T>(T message, CancellationToken cancellationToken = default);

dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessRunner.cs

@@ -160,6 +160,8 @@ internal sealed class InProcessRunner : ISuperStepRunner, ICheckpointingHandle
 
     bool ISuperStepRunner.HasUnservicedRequests => this.RunContext.HasUnservicedRequests;
     bool ISuperStepRunner.HasUnprocessedMessages => this.RunContext.NextStepHasActions;
+    bool ISuperStepRunner.TryGetResponsePortExecutorId(string portId, out string? executorId)
+        => this.RunContext.TryGetResponsePortExecutorId(portId, out executorId);
 
     public bool IsCheckpointingEnabled => this.RunContext.IsCheckpointingEnabled;
 

dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessRunnerContext.cs

@@ -296,6 +296,9 @@ internal sealed class InProcessRunnerContext : IRunnerContext
         return this._externalRequests.TryRemove(requestId, out _);
     }
 
+    internal bool TryGetResponsePortExecutorId(string portId, [NotNullWhen(true)] out string? executorId)
+        => this._edgeMap.TryGetResponsePortExecutorId(portId, out executorId);
+
     private IEventSink OutgoingEvents { get; }
 
     internal StateManager StateManager { get; } = new();

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/AIAgentHostExecutor.cs

@@ -68,10 +68,17 @@ internal sealed class AIAgentHostExecutor : ChatProtocolExecutor
             throw new InvalidOperationException($"No pending ToolApprovalRequest found with id '{response.RequestId}'.");
         }
 
-        List<ChatMessage> implicitTurnMessages = [new ChatMessage(ChatRole.User, [response])];
+        // Merge the external response with any already-buffered regular messages so mixed-content
+        // resumes can be processed in one invocation.
+        return this.ProcessTurnMessagesAsync(async (pendingMessages, ctx, ct) =>
+        {
+            pendingMessages.Add(new ChatMessage(ChatRole.User, [response]));
 
-        // ContinueTurnAsync owns failing to emit a TurnToken if this response does not clear up all remaining outstanding requests.
-        return this.ContinueTurnAsync(implicitTurnMessages, context, this._currentTurnEmitEvents ?? false, cancellationToken);
+            await this.ContinueTurnAsync(pendingMessages, ctx, this._currentTurnEmitEvents ?? false, ct).ConfigureAwait(false);
+
+            // Clear the buffered turn messages because they were consumed by ContinueTurnAsync.
+            return null;
+        }, context, cancellationToken);
     }
 
     private ValueTask HandleFunctionResultAsync(
@@ -84,8 +91,17 @@ internal sealed class AIAgentHostExecutor : ChatProtocolExecutor
             throw new InvalidOperationException($"No pending FunctionCall found with id '{result.CallId}'.");
         }
 
-        List<ChatMessage> implicitTurnMessages = [new ChatMessage(ChatRole.Tool, [result])];
-        return this.ContinueTurnAsync(implicitTurnMessages, context, this._currentTurnEmitEvents ?? false, cancellationToken);
+        // Merge the external response with any already-buffered regular messages so mixed-content
+        // resumes can be processed in one invocation.
+        return this.ProcessTurnMessagesAsync(async (pendingMessages, ctx, ct) =>
+        {
+            pendingMessages.Add(new ChatMessage(ChatRole.Tool, [result]));
+
+            await this.ContinueTurnAsync(pendingMessages, ctx, this._currentTurnEmitEvents ?? false, ct).ConfigureAwait(false);
+
+            // Clear the buffered turn messages because they were consumed by ContinueTurnAsync.
+            return null;
+        }, context, cancellationToken);
     }
 
     public bool ShouldEmitStreamingEvents(bool? emitEvents)
@@ -198,7 +214,7 @@ internal sealed class AIAgentHostExecutor : ChatProtocolExecutor
             ExtractUnservicedRequests(response.Messages.SelectMany(message => message.Contents));
         }
 
-        if (this._options.EmitAgentResponseEvents == true)
+        if (this._options.EmitAgentResponseEvents)
         {
             await context.YieldOutputAsync(response, cancellationToken).ConfigureAwait(false);
         }

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/AIContentExternalHandler.cs

@@ -16,10 +16,12 @@ internal sealed class AIContentExternalHandler<TRequestContent, TResponseContent
     where TResponseContent : AIContent
 {
     private readonly PortBinding? _portBinding;
+    private readonly string _portId;
     private ConcurrentDictionary<string, TRequestContent> _pendingRequests = new();
 
     public AIContentExternalHandler(ref ProtocolBuilder protocolBuilder, string portId, bool intercepted, Func<TResponseContent, IWorkflowContext, CancellationToken, ValueTask> handler)
     {
+        this._portId = portId;
         PortBinding? portBinding = null;
         protocolBuilder = protocolBuilder.ConfigureRoutes(routeBuilder => ConfigureRoutes(routeBuilder, out portBinding));
         this._portBinding = portBinding;
@@ -58,12 +60,14 @@ internal sealed class AIContentExternalHandler<TRequestContent, TResponseContent
     {
         if (!this._pendingRequests.TryAdd(id, requestContent))
         {
-            throw new InvalidOperationException($"A pending request with ID '{id}' already exists.");
+            // Request is already pending; treat as an idempotent re-emission.
+            // Do not repost to the sink because request IDs must remain unique while pending.
+            return default;
         }
 
         return this.IsIntercepted
              ? context.SendMessageAsync(requestContent, cancellationToken: cancellationToken)
-             : this._portBinding.PostRequestAsync(requestContent, id, cancellationToken);
+             : this._portBinding.PostRequestAsync(requestContent, this.CreateExternalRequestId(id), cancellationToken);
     }
 
     public bool MarkRequestAsHandled(string id)
@@ -74,6 +78,8 @@ internal sealed class AIContentExternalHandler<TRequestContent, TResponseContent
     [MemberNotNullWhen(false, nameof(_portBinding))]
     private bool IsIntercepted => this._portBinding == null;
 
+    private string CreateExternalRequestId(string requestId) => $"{this._portId.Length}:{this._portId}:{requestId}";
+
     private static string MakeKey(string id) => $"{id}_PendingRequests";
 
     public async ValueTask OnCheckpointingAsync(string id, IWorkflowContext context, CancellationToken cancellationToken = default)

dotnet/src/Microsoft.Agents.AI.Workflows/StreamingRun.cs

@@ -60,6 +60,9 @@ public sealed class StreamingRun : CheckpointableRunBase, IAsyncDisposable
     internal ValueTask<bool> TrySendMessageUntypedAsync(object message, Type? declaredType = null)
         => this._runHandle.EnqueueMessageUntypedAsync(message, declaredType);
 
+    internal bool TryGetResponsePortExecutorId(string portId, out string? executorId)
+        => this._runHandle.TryGetResponsePortExecutorId(portId, out executorId);
+
     /// <summary>
     /// Asynchronously streams workflow events as they occur during workflow execution.
     /// </summary>

dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowSession.cs

@@ -25,6 +25,25 @@ internal sealed class WorkflowSession : AgentSession
 
     private InMemoryCheckpointManager? _inMemoryCheckpointManager;
 
+    /// <summary>
+    /// Tracks pending external requests by their workflow-facing request ID.
+    /// This mapping enables converting incoming response content back to <see cref="ExternalResponse"/>
+    /// when resuming a workflow from a checkpoint.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Entries are added when a <see cref="RequestInfoEvent"/> is received during workflow execution,
+    /// and removed when a matching response is delivered via <see cref="SendMessagesWithResponseConversionAsync"/>.
+    /// </para>
+    /// <para>
+    /// The number of entries is bounded by the number of outstanding external requests in a single workflow run.
+    /// When a session is abandoned, all pending requests are released with the session object.
+    /// Request-level timeouts, if needed, should be implemented in the workflow definition itself
+    /// (e.g., using a timer racing against an external event).
+    /// </para>
+    /// </remarks>
+    private readonly Dictionary<string, ExternalRequest> _pendingRequests = [];
+
     internal static bool VerifyCheckpointingConfiguration(IWorkflowExecutionEnvironment executionEnvironment, [NotNullWhen(true)] out InProcessExecutionEnvironment? inProcEnv)
     {
         inProcEnv = null;
@@ -90,6 +109,7 @@ internal sealed class WorkflowSession : AgentSession
 
         this.LastCheckpoint = sessionState.LastCheckpoint;
         this.StateBag = sessionState.StateBag;
+        this._pendingRequests = sessionState.PendingRequests ?? [];
     }
 
     public CheckpointInfo? LastCheckpoint { get; set; }
@@ -101,7 +121,8 @@ internal sealed class WorkflowSession : AgentSession
             this.SessionId,
             this.LastCheckpoint,
             this._inMemoryCheckpointManager,
-            this.StateBag);
+            this.StateBag,
+            this._pendingRequests);
 
         return marshaller.Marshal(info);
     }
@@ -141,7 +162,7 @@ internal sealed class WorkflowSession : AgentSession
         return update;
     }
 
-    private async ValueTask<StreamingRun> CreateOrResumeRunAsync(List<ChatMessage> messages, CancellationToken cancellationToken = default)
+    private async ValueTask<ResumeRunResult> CreateOrResumeRunAsync(List<ChatMessage> messages, CancellationToken cancellationToken = default)
     {
         // The workflow is validated to be a ChatProtocol workflow by the WorkflowHostAgent before creating the session,
         // and does not need to be checked again here.
@@ -154,18 +175,155 @@ internal sealed class WorkflowSession : AgentSession
                                                cancellationToken)
                             .ConfigureAwait(false);
 
-            await run.TrySendMessageAsync(messages).ConfigureAwait(false);
-            return run;
+            // Process messages: convert response content to ExternalResponse, send regular messages as-is
+            ResumeDispatchInfo dispatchInfo = await this.SendMessagesWithResponseConversionAsync(run, messages).ConfigureAwait(false);
+            return new ResumeRunResult(run, dispatchInfo);
         }
 
-        return await this._executionEnvironment
+        StreamingRun newRun = await this._executionEnvironment
                             .RunStreamingAsync(this._workflow,
                                          messages,
                                          this.SessionId,
                                          cancellationToken)
                             .ConfigureAwait(false);
+        return new ResumeRunResult(newRun);
     }
 
+    /// <summary>
+    /// Sends messages to the run, converting FunctionResultContent and UserInputResponseContent
+    /// to ExternalResponse when there's a matching pending request.
+    /// </summary>
+    /// <returns>
+    /// Structured information about how resume content was dispatched.
+    /// </returns>
+    private async ValueTask<ResumeDispatchInfo> SendMessagesWithResponseConversionAsync(StreamingRun run, List<ChatMessage> messages)
+    {
+        List<ChatMessage> regularMessages = [];
+        // Responses are deferred until after regular messages are queued so response handlers
+        // can merge buffered regular content in the same continuation turn.
+        List<(ExternalResponse Response, string RequestId)> externalResponses = [];
+        bool hasMatchedResponseForStartExecutor = false;
+
+        // Tracks content IDs already matched to pending requests within this invocation,
+        // preventing duplicate responses for the same ID from being sent to the workflow engine.
+        HashSet<string>? matchedContentIds = null;
+
+        foreach (ChatMessage message in messages)
+        {
+            List<AIContent> regularContents = [];
+
+            foreach (AIContent content in message.Contents)
+            {
+                string? contentId = GetResponseContentId(content);
+
+                // Skip duplicate response content for an already-matched content ID
+                if (contentId != null && matchedContentIds?.Contains(contentId) == true)
+                {
+                    continue;
+                }
+
+                if (contentId != null
+                    && this.TryGetPendingRequest(contentId) is ExternalRequest pendingRequest)
+                {
+                    // For intercepted/complex topologies the port may not be registered in the EdgeMap.
+                    // Treat unknown port as non-start-executor (conservative): TurnToken will still be sent.
+                    if (run.TryGetResponsePortExecutorId(pendingRequest.PortInfo.PortId, out string? responseExecutorId))
+                    {
+                        hasMatchedResponseForStartExecutor |= string.Equals(responseExecutorId, this._workflow.StartExecutorId, StringComparison.Ordinal);
+                    }
+
+                    AIContent normalizedResponseContent = NormalizeResponseContentForDelivery(content, pendingRequest);
+                    externalResponses.Add((pendingRequest.CreateResponse(normalizedResponseContent), pendingRequest.RequestId));
+                    (matchedContentIds ??= new(StringComparer.Ordinal)).Add(contentId);
+                }
+                else
+                {
+                    regularContents.Add(content);
+                }
+            }
+
+            if (regularContents.Count > 0)
+            {
+                ChatMessage cloned = message.Clone();
+                cloned.Contents = regularContents;
+                regularMessages.Add(cloned);
+            }
+        }
+
+        // Send regular messages first so response handlers can merge them with responses.
+        bool hasRegularMessages = regularMessages.Count > 0;
+        if (hasRegularMessages)
+        {
+            await run.TrySendMessageAsync(regularMessages).ConfigureAwait(false);
+        }
+
+        // Send external responses after regular messages.
+        bool hasMatchedExternalResponses = false;
+        foreach ((ExternalResponse response, string requestId) in externalResponses)
+        {
+            await run.SendResponseAsync(response).ConfigureAwait(false);
+            hasMatchedExternalResponses = true;
+            this.RemovePendingRequest(requestId);
+        }
+
+        return new ResumeDispatchInfo(
+            hasRegularMessages,
+            hasMatchedExternalResponses,
+            hasMatchedResponseForStartExecutor);
+    }
+
+    /// <summary>
+    /// Creates the workflow-facing request content surfaced in response updates.
+    /// </summary>
+    private static AIContent CreateRequestContentForDelivery(ExternalRequest request) => request switch
+    {
+        ExternalRequest externalRequest when externalRequest.TryGetDataAs(out FunctionCallContent? functionCallContent)
+            => CloneFunctionCallContent(functionCallContent, externalRequest.RequestId),
+        ExternalRequest externalRequest when externalRequest.TryGetDataAs(out ToolApprovalRequestContent? toolApprovalRequestContent)
+            => CloneToolApprovalRequestContent(toolApprovalRequestContent, externalRequest.RequestId),
+        ExternalRequest externalRequest
+            => externalRequest.ToFunctionCall(),
+    };
+
+    /// <summary>
+    /// Rewrites workflow-facing response content back to the original agent-owned content ID.
+    /// </summary>
+    private static AIContent NormalizeResponseContentForDelivery(AIContent content, ExternalRequest request) => content switch
+    {
+        FunctionResultContent functionResultContent when request.TryGetDataAs(out FunctionCallContent? functionCallContent)
+            => CloneFunctionResultContent(functionResultContent, functionCallContent.CallId),
+        ToolApprovalResponseContent toolApprovalResponseContent when request.TryGetDataAs(out ToolApprovalRequestContent? toolApprovalRequestContent)
+            => CloneToolApprovalResponseContent(toolApprovalResponseContent, toolApprovalRequestContent.RequestId),
+        _ => content,
+    };
+
+    /// <summary>
+    /// Gets the workflow-facing request ID from response content types.
+    /// </summary>
+    private static string? GetResponseContentId(AIContent content) => content switch
+    {
+        FunctionResultContent functionResultContent => functionResultContent.CallId,
+        ToolApprovalResponseContent toolApprovalResponseContent => toolApprovalResponseContent.RequestId,
+        _ => null
+    };
+
+    /// <summary>
+    /// Tries to get a pending request by workflow-facing request ID.
+    /// </summary>
+    private ExternalRequest? TryGetPendingRequest(string requestId) =>
+        this._pendingRequests.TryGetValue(requestId, out ExternalRequest? request) ? request : null;
+
+    /// <summary>
+    /// Adds a pending request indexed by workflow-facing request ID.
+    /// </summary>
+    private void AddPendingRequest(string requestId, ExternalRequest request) => this._pendingRequests[requestId] = request;
+
+    /// <summary>
+    /// Removes a pending request by workflow-facing request ID.
+    /// </summary>
+    private void RemovePendingRequest(string requestId) =>
+        this._pendingRequests.Remove(requestId);
+
     internal async
     IAsyncEnumerable<AgentResponseUpdate> InvokeStageAsync(
         [EnumeratorCancellation] CancellationToken cancellationToken = default)
@@ -175,12 +333,25 @@ internal sealed class WorkflowSession : AgentSession
             this.LastResponseId = Guid.NewGuid().ToString("N");
             List<ChatMessage> messages = this.ChatHistoryProvider.GetFromBookmark(this).ToList();
 
-#pragma warning disable CA2007 // Analyzer misfiring and not seeing .ConfigureAwait(false) below.
-            await using StreamingRun run =
+            ResumeRunResult resumeResult =
                 await this.CreateOrResumeRunAsync(messages, cancellationToken).ConfigureAwait(false);
+#pragma warning disable CA2007 // Analyzer misfiring.
+            await using StreamingRun run = resumeResult.Run;
 #pragma warning restore CA2007
 
-            await run.TrySendMessageAsync(new TurnToken(emitEvents: true)).ConfigureAwait(false);
+            ResumeDispatchInfo dispatchInfo = resumeResult.DispatchInfo;
+
+            // Send a TurnToken to the start executor unless the only activity is an external
+            // response directed at the start executor itself (which self-emits a TurnToken via
+            // ContinueTurnAsync). Non-start executors (e.g., RequestInfoExecutor) do not emit
+            // TurnTokens after processing responses, so the session must always provide one.
+            bool shouldSendTurnToken =
+                !dispatchInfo.HasMatchedExternalResponses
+                || !dispatchInfo.HasMatchedResponseForStartExecutor;
+            if (shouldSendTurnToken)
+            {
+                await run.TrySendMessageAsync(new TurnToken(emitEvents: true)).ConfigureAwait(false);
+            }
             await foreach (WorkflowEvent evt in run.WatchStreamAsync(blockOnPendingRequest: false, cancellationToken)
                                                .ConfigureAwait(false)
                                                .WithCancellation(cancellationToken))
@@ -192,8 +363,13 @@ internal sealed class WorkflowSession : AgentSession
                         break;
 
                     case RequestInfoEvent requestInfo:
-                        FunctionCallContent fcContent = requestInfo.Request.ToFunctionCall();
-                        AgentResponseUpdate update = this.CreateUpdate(this.LastResponseId, evt, fcContent);
+                        AIContent requestContent = CreateRequestContentForDelivery(requestInfo.Request);
+
+                        // Track the pending request so we can convert incoming responses back to ExternalResponse.
+                        // External callers respond using the workflow-facing request ID, which is always RequestId.
+                        this.AddPendingRequest(requestInfo.Request.RequestId, requestInfo.Request);
+
+                        AgentResponseUpdate update = this.CreateUpdate(this.LastResponseId, evt, requestContent);
                         yield return update;
                         break;
 
@@ -267,15 +443,116 @@ internal sealed class WorkflowSession : AgentSession
     /// <inheritdoc/>
     public WorkflowChatHistoryProvider ChatHistoryProvider { get; }
 
+    /// <summary>
+    /// Captures the outcome of creating or resuming a workflow run,
+    /// indicating what types of messages were sent during resume.
+    /// </summary>
+    private readonly struct ResumeRunResult
+    {
+        /// <summary>The streaming run that was created or resumed.</summary>
+        public StreamingRun Run { get; }
+
+        /// <summary>How resume-time content was dispatched into the workflow runtime.</summary>
+        public ResumeDispatchInfo DispatchInfo { get; }
+
+        public ResumeRunResult(StreamingRun run, ResumeDispatchInfo dispatchInfo = default)
+        {
+            this.Run = Throw.IfNull(run);
+            this.DispatchInfo = dispatchInfo;
+        }
+    }
+
+    /// <summary>
+    /// Captures how resumed input was split across regular-message and external-response delivery paths.
+    /// </summary>
+    private readonly struct ResumeDispatchInfo
+    {
+        public ResumeDispatchInfo(bool hasRegularMessages, bool hasMatchedExternalResponses, bool hasMatchedResponseForStartExecutor)
+        {
+            this.HasRegularMessages = hasRegularMessages;
+            this.HasMatchedExternalResponses = hasMatchedExternalResponses;
+            this.HasMatchedResponseForStartExecutor = hasMatchedResponseForStartExecutor;
+        }
+
+        public bool HasRegularMessages { get; }
+
+        public bool HasMatchedExternalResponses { get; }
+
+        public bool HasMatchedResponseForStartExecutor { get; }
+    }
+
+    /// <summary>
+    /// Clones a <see cref="FunctionCallContent"/> with a workflow-facing call ID.
+    /// </summary>
+    private static FunctionCallContent CloneFunctionCallContent(FunctionCallContent content, string callId)
+    {
+        FunctionCallContent clone = new(callId, content.Name, content.Arguments)
+        {
+            Exception = content.Exception,
+            InformationalOnly = content.InformationalOnly,
+        };
+
+        return CopyContentMetadata(content, clone);
+    }
+
+    /// <summary>
+    /// Clones a <see cref="FunctionResultContent"/> with an agent-owned call ID.
+    /// </summary>
+    private static FunctionResultContent CloneFunctionResultContent(FunctionResultContent content, string callId)
+    {
+        FunctionResultContent clone = new(callId, content.Result)
+        {
+            Exception = content.Exception,
+        };
+
+        return CopyContentMetadata(content, clone);
+    }
+
+    /// <summary>
+    /// Clones a <see cref="ToolApprovalRequestContent"/> with a workflow-facing request ID.
+    /// </summary>
+    private static ToolApprovalRequestContent CloneToolApprovalRequestContent(ToolApprovalRequestContent content, string id)
+    {
+        ToolApprovalRequestContent clone = new(id, content.ToolCall);
+        return CopyContentMetadata(content, clone);
+    }
+
+    /// <summary>
+    /// Clones a <see cref="ToolApprovalResponseContent"/> with an agent-owned request ID.
+    /// </summary>
+    private static ToolApprovalResponseContent CloneToolApprovalResponseContent(ToolApprovalResponseContent content, string id)
+    {
+        ToolApprovalResponseContent clone = new(id, content.Approved, content.ToolCall)
+        {
+            Reason = content.Reason,
+        };
+
+        return CopyContentMetadata(content, clone);
+    }
+
+    /// <summary>
+    /// Copies shared <see cref="AIContent"/> metadata to a cloned content instance.
+    /// </summary>
+    private static TContent CopyContentMetadata<TContent>(AIContent source, TContent target)
+        where TContent : AIContent
+    {
+        target.AdditionalProperties = source.AdditionalProperties;
+        target.Annotations = source.Annotations;
+        target.RawRepresentation = source.RawRepresentation;
+        return target;
+    }
+
     internal sealed class SessionState(
         string sessionId,
         CheckpointInfo? lastCheckpoint,
         InMemoryCheckpointManager? checkpointManager = null,
-        AgentSessionStateBag? stateBag = null)
+        AgentSessionStateBag? stateBag = null,
+        Dictionary<string, ExternalRequest>? pendingRequests = null)
     {
         public string SessionId { get; } = sessionId;
         public CheckpointInfo? LastCheckpoint { get; } = lastCheckpoint;
         public InMemoryCheckpointManager? CheckpointManager { get; } = checkpointManager;
         public AgentSessionStateBag StateBag { get; } = stateBag ?? new();
+        public Dictionary<string, ExternalRequest>? PendingRequests { get; } = pendingRequests;
     }
 }

dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowsJsonUtilities.cs

@@ -71,6 +71,7 @@ internal static partial class WorkflowsJsonUtilities
     [JsonSerializable(typeof(PortableValue))]
     [JsonSerializable(typeof(PortableMessageEnvelope))]
     [JsonSerializable(typeof(InMemoryCheckpointManager))]
+    [JsonSerializable(typeof(CheckpointFileIndexEntry))]
 
     // Runtime State Types
     [JsonSerializable(typeof(ScopeKey))]

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs

@@ -138,6 +138,9 @@ public sealed partial class ChatClientAgent : AIAgent
         this._aiContextProviderStateKeys = ValidateAndCollectStateKeys(this._agentOptions?.AIContextProviders, this.ChatHistoryProvider);
 
         this._logger = (loggerFactory ?? chatClient.GetService<ILoggerFactory>() ?? NullLoggerFactory.Instance).CreateLogger<ChatClientAgent>();
+
+        // Warn if using a custom chat client stack with end-of-run persistence but no ChatHistoryPersistingChatClient.
+        this.WarnOnMissingPersistingClient();
     }
 
     /// <summary>
@@ -211,12 +214,14 @@ public sealed partial class ChatClientAgent : AIAgent
          ChatClientAgentContinuationToken? _) =
             await this.PrepareSessionAndMessagesAsync(session, inputMessages, options, cancellationToken).ConfigureAwait(false);
 
-        var chatClient = this.ChatClient;
+        // Update the run context with the resolved session so any downstream classes
+        // always have a valid session, even when the caller passed null.
+        EnsureRunContextHasSession(safeSession);
 
+        var chatClient = this.ChatClient;
         chatClient = ApplyRunOptionsTransformations(options, chatClient);
 
         var loggingAgentName = this.GetLoggingAgentName();
-
         this._logger.LogAgentChatClientInvokingAgent(nameof(RunAsync), this.Id, loggingAgentName, this._chatClientType);
 
         // Call the IChatClient and notify the AIContextProvider of any failures.
@@ -227,8 +232,7 @@ public sealed partial class ChatClientAgent : AIAgent
         }
         catch (Exception ex)
         {
-            await this.NotifyChatHistoryProviderOfFailureAsync(safeSession, ex, inputMessagesForChatClient, chatOptions, cancellationToken).ConfigureAwait(false);
-            await this.NotifyAIContextProviderOfFailureAsync(safeSession, ex, inputMessagesForChatClient, cancellationToken).ConfigureAwait(false);
+            await this.NotifyProvidersOfFailureAtEndOfRunAsync(safeSession, ex, inputMessagesForChatClient, chatOptions, cancellationToken).ConfigureAwait(false);
             throw;
         }
 
@@ -236,7 +240,8 @@ public sealed partial class ChatClientAgent : AIAgent
 
         // We can derive the type of supported session from whether we have a conversation id,
         // so let's update it and set the conversation id for the service session case.
-        this.UpdateSessionConversationId(safeSession, chatResponse.ConversationId, cancellationToken);
+        var forceEndOfRunPersistence = chatOptions?.ContinuationToken is not null || chatOptions?.AllowBackgroundResponses is true;
+        this.UpdateSessionConversationIdAtEndOfRun(safeSession, chatResponse.ConversationId, cancellationToken, forceUpdate: forceEndOfRunPersistence);
 
         // Ensure that the author name is set for each message in the response.
         foreach (ChatMessage chatResponseMessage in chatResponse.Messages)
@@ -244,11 +249,10 @@ public sealed partial class ChatClientAgent : AIAgent
             chatResponseMessage.AuthorName ??= this.Name;
         }
 
-        // Only notify the session of new messages if the chatResponse was successful to avoid inconsistent message state in the session.
-        await this.NotifyChatHistoryProviderOfNewMessagesAsync(safeSession, inputMessagesForChatClient, chatResponse.Messages, chatOptions, cancellationToken).ConfigureAwait(false);
-
-        // Notify the AIContextProvider of all new messages.
-        await this.NotifyAIContextProviderOfSuccessAsync(safeSession, inputMessagesForChatClient, chatResponse.Messages, cancellationToken).ConfigureAwait(false);
+        // Notify providers of all new messages unless persistence is handled per-service-call by the decorator.
+        // When background responses are allowed, force notification since per-service-call persistence
+        // is unreliable (the caller may stop consuming the stream before the decorator can persist).
+        await this.NotifyProvidersOfNewMessagesAtEndOfRunAsync(safeSession, inputMessagesForChatClient, chatResponse.Messages, chatOptions, cancellationToken, forceNotify: forceEndOfRunPersistence).ConfigureAwait(false);
 
         return new AgentResponse(chatResponse)
         {
@@ -296,6 +300,10 @@ public sealed partial class ChatClientAgent : AIAgent
          ChatClientAgentContinuationToken? continuationToken) =
             await this.PrepareSessionAndMessagesAsync(session, inputMessages, options, cancellationToken).ConfigureAwait(false);
 
+        // Update the run context with the resolved session so any downstream classes
+        // always have a valid session, even when the caller passed null.
+        EnsureRunContextHasSession(safeSession);
+
         var chatClient = this.ChatClient;
 
         chatClient = ApplyRunOptionsTransformations(options, chatClient);
@@ -315,8 +323,7 @@ public sealed partial class ChatClientAgent : AIAgent
         }
         catch (Exception ex)
         {
-            await this.NotifyChatHistoryProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
-            await this.NotifyAIContextProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), cancellationToken).ConfigureAwait(false);
+            await this.NotifyProvidersOfFailureAtEndOfRunAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
             throw;
         }
 
@@ -330,8 +337,7 @@ public sealed partial class ChatClientAgent : AIAgent
         }
         catch (Exception ex)
         {
-            await this.NotifyChatHistoryProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
-            await this.NotifyAIContextProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), cancellationToken).ConfigureAwait(false);
+            await this.NotifyProvidersOfFailureAtEndOfRunAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
             throw;
         }
 
@@ -353,27 +359,31 @@ public sealed partial class ChatClientAgent : AIAgent
 
             try
             {
+                // Re-ensure the run context has the resolved session before each MoveNextAsync.
+                // The base class RunStreamingAsync restores the original context (potentially with
+                // null session) after each yield, so we must re-establish it for the decorator.
+                EnsureRunContextHasSession(safeSession);
                 hasUpdates = await responseUpdatesEnumerator.MoveNextAsync().ConfigureAwait(false);
             }
             catch (Exception ex)
             {
-                await this.NotifyChatHistoryProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
-                await this.NotifyAIContextProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), cancellationToken).ConfigureAwait(false);
+                await this.NotifyProvidersOfFailureAtEndOfRunAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
                 throw;
             }
         }
 
         var chatResponse = responseUpdates.ToChatResponse();
 
+        var forceEndOfRunPersistence = continuationToken is not null || chatOptions?.AllowBackgroundResponses is true;
+
         // We can derive the type of supported session from whether we have a conversation id,
         // so let's update it and set the conversation id for the service session case.
-        this.UpdateSessionConversationId(safeSession, chatResponse.ConversationId, cancellationToken);
+        this.UpdateSessionConversationIdAtEndOfRun(safeSession, chatResponse.ConversationId, cancellationToken, forceUpdate: forceEndOfRunPersistence);
 
-        // To avoid inconsistent state we only notify the session of the input messages if no error occurs after the initial request.
-        await this.NotifyChatHistoryProviderOfNewMessagesAsync(safeSession, GetInputMessages(inputMessagesForChatClient, continuationToken), chatResponse.Messages, chatOptions, cancellationToken).ConfigureAwait(false);
-
-        // Notify the AIContextProvider of all new messages.
-        await this.NotifyAIContextProviderOfSuccessAsync(safeSession, GetInputMessages(inputMessagesForChatClient, continuationToken), chatResponse.Messages, cancellationToken).ConfigureAwait(false);
+        // Notify providers of all new messages unless persistence is handled per-service-call by the decorator.
+        // When resuming from a continuation token or using background responses, force notification
+        // to send the combined data (per-service-call persistence is unreliable for these scenarios).
+        await this.NotifyProvidersOfNewMessagesAtEndOfRunAsync(safeSession, GetInputMessages(inputMessagesForChatClient, continuationToken), chatResponse.Messages, chatOptions, cancellationToken, forceNotify: forceEndOfRunPersistence).ConfigureAwait(false);
     }
 
     /// <inheritdoc/>
@@ -441,17 +451,29 @@ public sealed partial class ChatClientAgent : AIAgent
     #region Private
 
     /// <summary>
-    /// Notify the <see cref="AIContextProvider"/> when an agent run succeeded, if there is an <see cref="AIContextProvider"/>.
+    /// Notifies the <see cref="ChatHistoryProvider"/> and all <see cref="AIContextProviders"/> of successfully completed messages.
     /// </summary>
-    private async Task NotifyAIContextProviderOfSuccessAsync(
+    /// <remarks>
+    /// This method is also called by <see cref="ChatHistoryPersistingChatClient"/> to persist messages per-service-call.
+    /// </remarks>
+    internal async Task NotifyProvidersOfNewMessagesAsync(
         ChatClientAgentSession session,
-        IEnumerable<ChatMessage> inputMessages,
+        IEnumerable<ChatMessage> requestMessages,
         IEnumerable<ChatMessage> responseMessages,
+        ChatOptions? chatOptions,
         CancellationToken cancellationToken)
     {
+        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions, session);
+
+        if (chatHistoryProvider is not null)
+        {
+            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, requestMessages, responseMessages);
+            await chatHistoryProvider.InvokedAsync(invokedContext, cancellationToken).ConfigureAwait(false);
+        }
+
         if (this.AIContextProviders is { Count: > 0 } contextProviders)
         {
-            AIContextProvider.InvokedContext invokedContext = new(this, session, inputMessages, responseMessages);
+            AIContextProvider.InvokedContext invokedContext = new(this, session, requestMessages, responseMessages);
 
             foreach (var contextProvider in contextProviders)
             {
@@ -461,17 +483,29 @@ public sealed partial class ChatClientAgent : AIAgent
     }
 
     /// <summary>
-    /// Notify the <see cref="AIContextProvider"/> of any failure during an agent run, if there is an <see cref="AIContextProvider"/>.
+    /// Notifies the <see cref="ChatHistoryProvider"/> and all <see cref="AIContextProviders"/> of a failure during a service call.
     /// </summary>
-    private async Task NotifyAIContextProviderOfFailureAsync(
+    /// <remarks>
+    /// This method is also called by <see cref="ChatHistoryPersistingChatClient"/> to report failures per-service-call.
+    /// </remarks>
+    internal async Task NotifyProvidersOfFailureAsync(
         ChatClientAgentSession session,
         Exception ex,
-        IEnumerable<ChatMessage> inputMessages,
+        IEnumerable<ChatMessage> requestMessages,
+        ChatOptions? chatOptions,
         CancellationToken cancellationToken)
     {
+        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions, session);
+
+        if (chatHistoryProvider is not null)
+        {
+            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, requestMessages, ex);
+            await chatHistoryProvider.InvokedAsync(invokedContext, cancellationToken).ConfigureAwait(false);
+        }
+
         if (this.AIContextProviders is { Count: > 0 } contextProviders)
         {
-            AIContextProvider.InvokedContext invokedContext = new(this, session, inputMessages, ex);
+            AIContextProvider.InvokedContext invokedContext = new(this, session, requestMessages, ex);
 
             foreach (var contextProvider in contextProviders)
             {
@@ -667,6 +701,12 @@ public sealed partial class ChatClientAgent : AIAgent
             throw new InvalidOperationException("A session must be provided when continuing a background response with a continuation token.");
         }
 
+        if ((continuationToken is not null || chatOptions?.AllowBackgroundResponses is true) && this.PersistsChatHistoryPerServiceCall && this._logger.IsEnabled(LogLevel.Warning))
+        {
+            var warningAgentName = this.GetLoggingAgentName();
+            this._logger.LogAgentChatClientBackgroundResponseFallback(this.Id, warningAgentName);
+        }
+
         session ??= await this.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
         if (session is not ChatClientAgentSession typedSession)
         {
@@ -754,7 +794,7 @@ public sealed partial class ChatClientAgent : AIAgent
         return (typedSession, chatOptions, messagesList, continuationToken);
     }
 
-    private void UpdateSessionConversationId(ChatClientAgentSession session, string? responseConversationId, CancellationToken cancellationToken)
+    internal void UpdateSessionConversationId(ChatClientAgentSession session, string? responseConversationId, CancellationToken cancellationToken)
     {
         if (string.IsNullOrWhiteSpace(responseConversationId) && !string.IsNullOrWhiteSpace(session.ConversationId))
         {
@@ -798,45 +838,162 @@ public sealed partial class ChatClientAgent : AIAgent
         }
     }
 
-    private Task NotifyChatHistoryProviderOfFailureAsync(
+    /// <summary>
+    /// Updates the session conversation ID at the end of an agent run.
+    /// </summary>
+    /// <remarks>
+    /// When a <see cref="ChatHistoryPersistingChatClient"/> in persist mode handles per-service-call
+    /// conversation ID updates, this end-of-run update is skipped. When the decorator is in mark-only
+    /// mode or absent, the update is performed here. When <paramref name="forceUpdate"/> is <see langword="true"/>
+    /// (continuation token scenarios), the update is always performed.
+    /// </remarks>
+    private void UpdateSessionConversationIdAtEndOfRun(ChatClientAgentSession session, string? responseConversationId, CancellationToken cancellationToken, bool forceUpdate = false)
+    {
+        if (!forceUpdate && this.PersistsChatHistoryPerServiceCall)
+        {
+            return;
+        }
+
+        this.UpdateSessionConversationId(session, responseConversationId, cancellationToken);
+    }
+
+    /// <summary>
+    /// Notifies providers of successfully completed messages at the end of an agent run.
+    /// </summary>
+    /// <remarks>
+    /// When a <see cref="ChatHistoryPersistingChatClient"/> in persist mode handles per-service-call
+    /// notification, this end-of-run notification is skipped. When the decorator is in mark-only mode,
+    /// only the marked messages are persisted. When no decorator is present (custom stack with
+    /// <see cref="ChatClientAgentOptions.PersistChatHistoryAtEndOfRun"/>), all messages are persisted.
+    /// When <paramref name="forceNotify"/> is <see langword="true"/> (continuation token or
+    /// background response scenarios), notification is always performed with all messages because
+    /// per-service-call persistence is unreliable in these scenarios.
+    /// </remarks>
+    private Task NotifyProvidersOfNewMessagesAtEndOfRunAsync(
+        ChatClientAgentSession session,
+        IEnumerable<ChatMessage> requestMessages,
+        IEnumerable<ChatMessage> responseMessages,
+        ChatOptions? chatOptions,
+        CancellationToken cancellationToken,
+        bool forceNotify = false)
+    {
+        if (!forceNotify && this.PersistsChatHistoryPerServiceCall)
+        {
+            return Task.CompletedTask;
+        }
+
+        if (!forceNotify && this.HasMarkOnlyChatHistoryPersistingClient)
+        {
+            // In mark-only mode, persist only messages that were marked by the decorator.
+            var markedRequestMessages = GetMarkedMessages(requestMessages);
+            var markedResponseMessages = GetMarkedMessages(responseMessages);
+            return this.NotifyProvidersOfNewMessagesAsync(session, markedRequestMessages, markedResponseMessages, chatOptions, cancellationToken);
+        }
+
+        return this.NotifyProvidersOfNewMessagesAsync(session, requestMessages, responseMessages, chatOptions, cancellationToken);
+    }
+
+    /// <summary>
+    /// Notifies providers of a failure at the end of an agent run.
+    /// </summary>
+    /// <remarks>
+    /// When a <see cref="ChatHistoryPersistingChatClient"/> in persist mode handles per-service-call
+    /// notification (including failure), this end-of-run notification is skipped to avoid
+    /// duplicate notification. In all other cases, failure is reported at the end of the run.
+    /// </remarks>
+    private Task NotifyProvidersOfFailureAtEndOfRunAsync(
         ChatClientAgentSession session,
         Exception ex,
         IEnumerable<ChatMessage> requestMessages,
         ChatOptions? chatOptions,
         CancellationToken cancellationToken)
     {
-        ChatHistoryProvider? provider = this.ResolveChatHistoryProvider(chatOptions, session);
-
-        // Only notify the provider if we have one.
-        // If we don't have one, it means that the chat history is service managed and the underlying service is responsible for storing messages.
-        if (provider is not null)
+        if (this.PersistsChatHistoryPerServiceCall)
         {
-            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, requestMessages, ex);
-
-            return provider.InvokedAsync(invokedContext, cancellationToken).AsTask();
+            return Task.CompletedTask;
         }
 
-        return Task.CompletedTask;
+        return this.NotifyProvidersOfFailureAsync(session, ex, requestMessages, chatOptions, cancellationToken);
     }
 
-    private Task NotifyChatHistoryProviderOfNewMessagesAsync(
-        ChatClientAgentSession session,
-        IEnumerable<ChatMessage> requestMessages,
-        IEnumerable<ChatMessage> responseMessages,
-        ChatOptions? chatOptions,
-        CancellationToken cancellationToken)
+    /// <summary>
+    /// Gets a value indicating whether the agent has a <see cref="ChatHistoryPersistingChatClient"/>
+    /// decorator in persist mode (not mark-only), which handles per-service-call persistence.
+    /// </summary>
+    private bool PersistsChatHistoryPerServiceCall
     {
-        ChatHistoryProvider? provider = this.ResolveChatHistoryProvider(chatOptions, session);
-
-        // Only notify the provider if we have one.
-        // If we don't have one, it means that the chat history is service managed and the underlying service is responsible for storing messages.
-        if (provider is not null)
+        get
         {
-            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, requestMessages, responseMessages);
-            return provider.InvokedAsync(invokedContext, cancellationToken).AsTask();
+            var persistingClient = this.ChatClient.GetService<ChatHistoryPersistingChatClient>();
+            return persistingClient?.MarkOnly == false;
+        }
+    }
+
+    /// <summary>
+    /// Gets a value indicating whether the agent has a <see cref="ChatHistoryPersistingChatClient"/>
+    /// decorator in mark-only mode, which marks messages for later persistence at the end of the run.
+    /// </summary>
+    private bool HasMarkOnlyChatHistoryPersistingClient
+    {
+        get
+        {
+            var persistingClient = this.ChatClient.GetService<ChatHistoryPersistingChatClient>();
+            return persistingClient?.MarkOnly == true;
+        }
+    }
+
+    /// <summary>
+    /// Returns only the messages that have been marked as persisted by a <see cref="ChatHistoryPersistingChatClient"/> in mark-only mode.
+    /// </summary>
+    private static List<ChatMessage> GetMarkedMessages(IEnumerable<ChatMessage> messages)
+    {
+        return messages.Where(m =>
+            m.AdditionalProperties?.TryGetValue(ChatHistoryPersistingChatClient.PersistedMarkerKey, out var value) == true && value is true).ToList();
+    }
+
+    /// <summary>
+    /// Ensures that <see cref="AIAgent.CurrentRunContext"/> contains the resolved session.
+    /// </summary>
+    /// <remarks>
+    /// The base class sets <see cref="AIAgent.CurrentRunContext"/> with the raw session parameter
+    /// (which may be null) and restores it after each yield in streaming scenarios. After
+    /// <see cref="PrepareSessionAndMessagesAsync"/> resolves or creates a session, we update the
+    /// context so the <see cref="ChatHistoryPersistingChatClient"/> decorator always has a valid session.
+    /// The original agent from the context is preserved to maintain the top-of-stack agent in
+    /// decorated agent scenarios.
+    /// </remarks>
+    private static void EnsureRunContextHasSession(ChatClientAgentSession safeSession)
+    {
+        var context = CurrentRunContext;
+        if (context is not null && context.Session != safeSession)
+        {
+            CurrentRunContext = new(context.Agent, safeSession, context.RequestMessages, context.RunOptions);
+        }
+    }
+
+    /// <summary>
+    /// Checks for potential misconfiguration when using a custom chat client stack and logs warnings.
+    /// </summary>
+    private void WarnOnMissingPersistingClient()
+    {
+        if (this._agentOptions?.UseProvidedChatClientAsIs is not true)
+        {
+            return;
         }
 
-        return Task.CompletedTask;
+        if (this._agentOptions?.PersistChatHistoryAtEndOfRun is not true)
+        {
+            return;
+        }
+
+        var persistingClient = this.ChatClient.GetService<ChatHistoryPersistingChatClient>();
+        if (persistingClient is null && this._logger.IsEnabled(LogLevel.Warning))
+        {
+            var loggingAgentName = this.GetLoggingAgentName();
+            this._logger.LogAgentChatClientMissingPersistingClient(
+                this.Id,
+                loggingAgentName);
+        }
     }
 
     private ChatHistoryProvider? ResolveChatHistoryProvider(ChatOptions? chatOptions, ChatClientAgentSession session)

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentLogMessages.cs

@@ -69,4 +69,32 @@ internal static partial class ChatClientAgentLogMessages
         string chatHistoryProviderName,
         string agentId,
         string agentName);
+
+    /// <summary>
+    /// Logs a warning when <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> is <see langword="true"/>
+    /// and <see cref="ChatClientAgentOptions.PersistChatHistoryAtEndOfRun"/> is <see langword="true"/>,
+    /// but no <see cref="ChatHistoryPersistingChatClient"/> is found in the custom chat client stack.
+    /// </summary>
+    [LoggerMessage(
+        Level = LogLevel.Warning,
+        Message = "Agent {AgentId}/{AgentName}: PersistChatHistoryAtEndOfRun is enabled with a custom chat client stack (UseProvidedChatClientAsIs), but no ChatHistoryPersistingChatClient was found in the pipeline. All messages will be persisted at the end of the run without marking. This setup is not supported with some other features, e.g. handoffs. Consider adding a ChatHistoryPersistingChatClient to the pipeline using the UseChatHistoryPersisting extension method.")]
+    public static partial void LogAgentChatClientMissingPersistingClient(
+        this ILogger logger,
+        string agentId,
+        string agentName);
+
+    /// <summary>
+    /// Logs a warning when per-service-call persistence falls back to end-of-run persistence
+    /// because the run involves background responses (continuation token resumption or
+    /// <c>AllowBackgroundResponses</c>). Per-service-call persistence is
+    /// unreliable in these scenarios because the caller may stop consuming the stream before
+    /// the decorator's post-stream persistence code can execute.
+    /// </summary>
+    [LoggerMessage(
+        Level = LogLevel.Warning,
+        Message = "Agent {AgentId}/{AgentName}: Per-service-call persistence is falling back to end-of-run persistence because the run involves background responses. Messages will be marked during the run and persisted at the end.")]
+    public static partial void LogAgentChatClientBackgroundResponseFallback(
+        this ILogger logger,
+        string agentId,
+        string agentName);
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs

@@ -1,7 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Agents.AI;
 
@@ -89,6 +91,56 @@ public sealed class ChatClientAgentOptions
     /// </value>
     public bool ThrowOnChatHistoryProviderConflict { get; set; } = true;
 
+    /// <summary>
+    /// Gets or sets a value indicating whether to persist chat history only at the end of the full agent run
+    /// rather than after each individual service call.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// By default, <see cref="ChatClientAgent"/> persists request and response messages either via
+    /// a <see cref="ChatHistoryProvider"/>, or the underlying AI service's chat history storage.
+    /// Persistence is done immediately after each call to the AI service within the function invocation loop.
+    /// When storing in the underlying AI service, the session's <see cref="ChatClientAgentSession.ConversationId"/>
+    /// is also updated after each service call, keeping it in sync with the service-side conversation state.
+    /// </para>
+    /// <para>
+    /// Setting this property to <see langword="true"/> causes messages to be marked during the function
+    /// invocation loop but persisted only at the end of the full agent run, providing atomic run semantics.
+    /// Updating the <see cref="ChatClientAgentSession.ConversationId"/> is likewise deferred and
+    /// updated only at the end of the run, consistent with atomic run semantics.
+    /// A <see cref="ChatHistoryPersistingChatClient"/> decorator is inserted into the chat client pipeline
+    /// in mark-only mode, and the <see cref="ChatClientAgent"/> persists only the marked messages at the
+    /// end of the run.
+    /// </para>
+    /// <para>
+    /// When this option is <see langword="false"/> (the default), the <see cref="ChatHistoryPersistingChatClient"/>
+    /// decorator persists messages and updates the <see cref="ChatClientAgentSession.ConversationId"/>
+    /// immediately after each service call. This may leave chat history in a state where
+    /// <see cref="FunctionResultContent"/> is required to start a new run if the last successful service
+    /// call returned <see cref="FunctionCallContent"/>.
+    /// </para>
+    /// <para>
+    /// This option has no effect when <see cref="UseProvidedChatClientAsIs"/> is <see langword="true"/>.
+    /// When using a custom chat client stack, you can add a <see cref="ChatHistoryPersistingChatClient"/>
+    /// manually via the <see cref="ChatClientBuilderExtensions.UseChatHistoryPersisting"/>
+    /// extension method.
+    /// </para>
+    /// <para>
+    /// Note that when using single threaded service stored chat history, like OpenAI Conversations,
+    /// there is only one id, so even if the conversation id is not updated after each service call,
+    /// the chat history will still contain intermediate messages. Setting this property to <see langword="true"/>
+    /// in this case will therefore have no real effect. Setting this property to <see langword="true"/> when using
+    /// OpenAI Responses with response ids on the other hand, allows atomic run semantics, since
+    /// each service request produces a new response id, and if the run fails mid-loop, the session will
+    /// still contain the pre-run respnose id, allowing the next run to start with a clean slate.
+    /// </para>
+    /// </remarks>
+    /// <value>
+    /// Default is <see langword="false"/>.
+    /// </value>
+    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+    public bool PersistChatHistoryAtEndOfRun { get; set; }
+
     /// <summary>
     /// Creates a new instance of <see cref="ChatClientAgentOptions"/> with the same values as this instance.
     /// </summary>
@@ -105,5 +157,6 @@ public sealed class ChatClientAgentOptions
             ClearOnChatHistoryProviderConflict = this.ClearOnChatHistoryProviderConflict,
             WarnOnChatHistoryProviderConflict = this.WarnOnChatHistoryProviderConflict,
             ThrowOnChatHistoryProviderConflict = this.ThrowOnChatHistoryProviderConflict,
+            PersistChatHistoryAtEndOfRun = this.PersistChatHistoryAtEndOfRun,
         };
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientBuilderExtensions.cs

@@ -2,8 +2,10 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.Logging;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
@@ -82,4 +84,46 @@ public static class ChatClientBuilderExtensions
             options: options,
             loggerFactory: loggerFactory,
             services: services);
+
+    /// <summary>
+    /// Adds a <see cref="ChatHistoryPersistingChatClient"/> to the chat client pipeline.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This decorator should be positioned between the <see cref="FunctionInvokingChatClient"/> and the leaf
+    /// <see cref="IChatClient"/> in the pipeline. It intercepts service calls to either persist messages
+    /// immediately or mark them for later persistence, depending on the <paramref name="markOnly"/> parameter.
+    /// </para>
+    /// <para>
+    /// If <paramref name="markOnly"/> is set to <see langword="true"/>, the <see cref="ChatClientAgent"/>
+    /// should be configured with <see cref="ChatClientAgentOptions.PersistChatHistoryAtEndOfRun"/> set to <see langword="true"/>
+    /// as without this combination, messages will never be persisted when using a <see cref="ChatHistoryProvider"/> for
+    /// chat history persistence.
+    /// </para>
+    /// <para>
+    /// This extension method is intended for use with custom chat client stacks when
+    /// <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> is <see langword="true"/>.
+    /// When <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> is <see langword="false"/> (the default),
+    /// the <see cref="ChatClientAgent"/> automatically injects this decorator.
+    /// </para>
+    /// <para>
+    /// This decorator only works within the context of a running <see cref="ChatClientAgent"/> and will throw an
+    /// exception if used in any other stack.
+    /// </para>
+    /// </remarks>
+    /// <param name="builder">The <see cref="ChatClientBuilder"/> to add the decorator to.</param>
+    /// <param name="markOnly">
+    /// When <see langword="true"/>, messages are marked with metadata but not persisted immediately,
+    /// and the session's <see cref="ChatClientAgentSession.ConversationId"/> is not updated.
+    /// The <see cref="ChatClientAgent"/> will persist only the marked messages and update the
+    /// conversation ID at the end of the run.
+    /// When <see langword="false"/> (the default), messages are persisted and the conversation ID
+    /// is updated immediately after each service call.
+    /// </param>
+    /// <returns>The <paramref name="builder"/> for chaining.</returns>
+    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+    public static ChatClientBuilder UseChatHistoryPersisting(this ChatClientBuilder builder, bool markOnly = false)
+    {
+        return builder.Use(innerClient => new ChatHistoryPersistingChatClient(innerClient, markOnly));
+    }
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientExtensions.cs

@@ -63,6 +63,15 @@ public static class ChatClientExtensions
             });
         }
 
+        // ChatHistoryPersistingChatClient is registered after FunctionInvokingChatClient so that it sits
+        // between FIC and the leaf client. ChatClientBuilder.Build applies factories in reverse order,
+        // making the first Use() call outermost. By adding our decorator second, the resulting pipeline is:
+        //   FunctionInvokingChatClient → ChatHistoryPersistingChatClient → leaf IChatClient
+        // This allows the decorator to persist messages after each individual service call within
+        // FIC's function invocation loop, or to mark them for later persistence at the end of the run.
+        bool markOnly = options?.PersistChatHistoryAtEndOfRun is true;
+        chatBuilder.Use(innerClient => new ChatHistoryPersistingChatClient(innerClient, markOnly));
+
         var agentChatClient = chatBuilder.Build(services);
 
         if (options?.ChatOptions?.Tools is { Count: > 0 })

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatHistoryPersistingChatClient.cs

@@ -0,0 +1,313 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Runtime.CompilerServices;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// A delegating chat client that notifies <see cref="ChatHistoryProvider"/> and <see cref="AIContextProvider"/>
+/// instances of request and response messages after each individual call to the inner chat client,
+/// or marks messages for later persistence depending on the configured mode.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This decorator is intended to operate between the <see cref="FunctionInvokingChatClient"/> and the leaf
+/// <see cref="IChatClient"/> in a <see cref="ChatClientAgent"/> pipeline.
+/// </para>
+/// <para>
+/// In persist mode (the default), it ensures that providers are notified and the session's
+/// <see cref="ChatClientAgentSession.ConversationId"/> is updated after each service call, so that
+/// intermediate messages (e.g., tool calls and results) are saved even if the process is interrupted
+/// mid-loop.
+/// </para>
+/// <para>
+/// In mark-only mode (<see cref="MarkOnly"/> is <see langword="true"/>), it marks messages with metadata
+/// but does not notify providers or update the <see cref="ChatClientAgentSession.ConversationId"/>.
+/// Both are deferred to the <see cref="ChatClientAgent"/> at the end of the run, providing atomic
+/// run semantics.
+/// </para>
+/// <para>
+/// This chat client must be used within the context of a running <see cref="ChatClientAgent"/>. It retrieves the
+/// current agent and session from <see cref="AIAgent.CurrentRunContext"/>, which is set automatically when an agent's
+/// <see cref="AIAgent.RunAsync(IEnumerable{ChatMessage}, AgentSession?, AgentRunOptions?, CancellationToken)"/> or
+/// <see cref="AIAgent.RunStreamingAsync(IEnumerable{ChatMessage}, AgentSession?, AgentRunOptions?, CancellationToken)"/>
+/// method is called. The <see cref="ChatClientAgent"/> ensures the run context always contains a resolved session,
+/// even when the caller passes null. An <see cref="InvalidOperationException"/> is thrown if no run context is
+/// available or if the agent is not a <see cref="ChatClientAgent"/>.
+/// </para>
+/// </remarks>
+internal sealed class ChatHistoryPersistingChatClient : DelegatingChatClient
+{
+    /// <summary>
+    /// The key used in <see cref="ChatMessage.AdditionalProperties"/> and <see cref="AIContent.AdditionalProperties"/>
+    /// to mark messages and their content as already persisted to chat history.
+    /// </summary>
+    internal const string PersistedMarkerKey = "_chatHistoryPersisted";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ChatHistoryPersistingChatClient"/> class.
+    /// </summary>
+    /// <param name="innerClient">The underlying chat client that will handle the core operations.</param>
+    /// <param name="markOnly">
+    /// When <see langword="true"/>, messages are marked with metadata but not persisted immediately,
+    /// and the session's <see cref="ChatClientAgentSession.ConversationId"/> is not updated.
+    /// The <see cref="ChatClientAgent"/> will persist only the marked messages and update the
+    /// conversation ID at the end of the run.
+    /// When <see langword="false"/> (the default), messages are persisted and the conversation ID
+    /// is updated immediately after each service call.
+    /// </param>
+    public ChatHistoryPersistingChatClient(IChatClient innerClient, bool markOnly = false)
+        : base(innerClient)
+    {
+        this.MarkOnly = markOnly;
+    }
+
+    /// <summary>
+    /// Gets a value indicating whether this decorator is in mark-only mode.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="true"/>, messages are marked with metadata but not persisted immediately,
+    /// and the session's <see cref="ChatClientAgentSession.ConversationId"/> is not updated.
+    /// Both are deferred to the <see cref="ChatClientAgent"/> at the end of the run.
+    /// When <see langword="false"/>, messages are persisted and the conversation ID is updated
+    /// after each service call.
+    /// </remarks>
+    public bool MarkOnly { get; }
+
+    /// <inheritdoc/>
+    public override async Task<ChatResponse> GetResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var (agent, session) = GetRequiredAgentAndSession();
+
+        ChatResponse response;
+        try
+        {
+            response = await base.GetResponseAsync(messages, options, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            var newRequestMessagesOnFailure = GetNewRequestMessages(messages);
+            await agent.NotifyProvidersOfFailureAsync(session, ex, newRequestMessagesOnFailure, options, cancellationToken).ConfigureAwait(false);
+            throw;
+        }
+
+        var newRequestMessages = GetNewRequestMessages(messages);
+
+        if (this.ShouldDeferPersistence(options))
+        {
+            // In mark-only mode or when resuming from a continuation token, just mark messages
+            // for later persistence by ChatClientAgent. Conversation ID and provider notification
+            // are deferred to end-of-run. For continuation tokens, the end-of-run handler needs
+            // to send the combined data from both the previous and current runs.
+            MarkAsPersisted(newRequestMessages);
+            MarkAsPersisted(response.Messages);
+        }
+        else
+        {
+            // In persist mode, persist immediately and update conversation ID.
+            agent.UpdateSessionConversationId(session, response.ConversationId, cancellationToken);
+            await agent.NotifyProvidersOfNewMessagesAsync(session, newRequestMessages, response.Messages, options, cancellationToken).ConfigureAwait(false);
+            MarkAsPersisted(newRequestMessages);
+            MarkAsPersisted(response.Messages);
+        }
+
+        return response;
+    }
+
+    /// <inheritdoc/>
+    public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        var (agent, session) = GetRequiredAgentAndSession();
+
+        List<ChatResponseUpdate> responseUpdates = [];
+
+        IAsyncEnumerator<ChatResponseUpdate> enumerator;
+        try
+        {
+            enumerator = base.GetStreamingResponseAsync(messages, options, cancellationToken).GetAsyncEnumerator(cancellationToken);
+        }
+        catch (Exception ex)
+        {
+            var newRequestMessagesOnFailure = GetNewRequestMessages(messages);
+            await agent.NotifyProvidersOfFailureAsync(session, ex, newRequestMessagesOnFailure, options, cancellationToken).ConfigureAwait(false);
+            throw;
+        }
+
+        bool hasUpdates;
+        try
+        {
+            hasUpdates = await enumerator.MoveNextAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            var newRequestMessagesOnFailure = GetNewRequestMessages(messages);
+            await agent.NotifyProvidersOfFailureAsync(session, ex, newRequestMessagesOnFailure, options, cancellationToken).ConfigureAwait(false);
+            throw;
+        }
+
+        while (hasUpdates)
+        {
+            var update = enumerator.Current;
+            responseUpdates.Add(update);
+            yield return update;
+
+            try
+            {
+                hasUpdates = await enumerator.MoveNextAsync().ConfigureAwait(false);
+            }
+            catch (Exception ex)
+            {
+                var newRequestMessagesOnFailure = GetNewRequestMessages(messages);
+                await agent.NotifyProvidersOfFailureAsync(session, ex, newRequestMessagesOnFailure, options, cancellationToken).ConfigureAwait(false);
+                throw;
+            }
+        }
+
+        var chatResponse = responseUpdates.ToChatResponse();
+        var newRequestMessages = GetNewRequestMessages(messages);
+
+        if (this.ShouldDeferPersistence(options))
+        {
+            // In mark-only mode or when resuming from a continuation token, just mark messages
+            // for later persistence by ChatClientAgent. Conversation ID and provider notification
+            // are deferred to end-of-run. For continuation tokens, the end-of-run handler needs
+            // to send the combined data from both the previous and current runs.
+            MarkAsPersisted(newRequestMessages);
+            MarkAsPersisted(chatResponse.Messages);
+        }
+        else
+        {
+            // In persist mode, persist immediately and update conversation ID.
+            agent.UpdateSessionConversationId(session, chatResponse.ConversationId, cancellationToken);
+            await agent.NotifyProvidersOfNewMessagesAsync(session, newRequestMessages, chatResponse.Messages, options, cancellationToken).ConfigureAwait(false);
+            MarkAsPersisted(newRequestMessages);
+            MarkAsPersisted(chatResponse.Messages);
+        }
+    }
+
+    /// <summary>
+    /// Gets the current <see cref="ChatClientAgent"/> and <see cref="ChatClientAgentSession"/> from the run context.
+    /// </summary>
+    private static (ChatClientAgent Agent, ChatClientAgentSession Session) GetRequiredAgentAndSession()
+    {
+        var runContext = AIAgent.CurrentRunContext
+            ?? throw new InvalidOperationException(
+                $"{nameof(ChatHistoryPersistingChatClient)} can only be used within the context of a running AIAgent. " +
+                "Ensure that the chat client is being invoked as part of an AIAgent.RunAsync or AIAgent.RunStreamingAsync call.");
+
+        var chatClientAgent = runContext.Agent.GetService<ChatClientAgent>()
+            ?? throw new InvalidOperationException(
+                $"{nameof(ChatHistoryPersistingChatClient)} can only be used with a {nameof(ChatClientAgent)}. " +
+                $"The current agent is of type '{runContext.Agent.GetType().Name}'.");
+
+        if (runContext.Session is not ChatClientAgentSession chatClientAgentSession)
+        {
+            throw new InvalidOperationException(
+                $"{nameof(ChatHistoryPersistingChatClient)} requires a {nameof(ChatClientAgentSession)}. " +
+                $"The current session is of type '{runContext.Session?.GetType().Name ?? "null"}'.");
+        }
+
+        return (chatClientAgent, chatClientAgentSession);
+    }
+
+    /// <summary>
+    /// Determines whether persistence should be deferred to end-of-run instead of happening immediately.
+    /// </summary>
+    /// <returns>
+    /// <see langword="true"/> when in <see cref="MarkOnly"/> mode, when the call is resuming from
+    /// a continuation token (since the end-of-run handler needs to combine data from the previous
+    /// and current runs), or when background responses are allowed (since the caller may stop
+    /// consuming the stream mid-run, preventing the post-stream persistence code from executing).
+    /// </returns>
+    private bool ShouldDeferPersistence(ChatOptions? options)
+    {
+        return this.MarkOnly || options?.ContinuationToken is not null || options?.AllowBackgroundResponses is true;
+    }
+
+    /// <summary>
+    /// Returns only the request messages that have not yet been persisted to chat history.
+    /// </summary>
+    /// <remarks>
+    /// A message is considered already persisted if any of the following is true:
+    /// <list type="bullet">
+    /// <item>It has the <see cref="PersistedMarkerKey"/> in its <see cref="ChatMessage.AdditionalProperties"/>.</item>
+    /// <item>It has an <see cref="AgentRequestMessageSourceType"/> of <see cref="AgentRequestMessageSourceType.ChatHistory"/>
+    /// (indicating it was loaded from chat history and does not need to be re-persisted).</item>
+    /// <item>It has <see cref="ChatMessage.Contents"/> and all of its <see cref="AIContent"/> items have the
+    /// <see cref="PersistedMarkerKey"/> in their <see cref="AIContent.AdditionalProperties"/>. This handles the
+    /// streaming case where <see cref="FunctionInvokingChatClient"/> reconstructs <see cref="ChatMessage"/> objects
+    /// independently via <c>ToChatResponse()</c>, producing different object references that share the same
+    /// underlying <see cref="AIContent"/> instances.</item>
+    /// </list>
+    /// </remarks>
+    /// <returns>A list of request messages that have not yet been persisted.</returns>
+    /// <param name="messages">The full set of request messages to filter.</param>
+    private static List<ChatMessage> GetNewRequestMessages(IEnumerable<ChatMessage> messages)
+    {
+        return messages.Where(m => !IsAlreadyPersisted(m)).ToList();
+    }
+
+    /// <summary>
+    /// Determines whether a message has already been persisted to chat history by this decorator.
+    /// </summary>
+    private static bool IsAlreadyPersisted(ChatMessage message)
+    {
+        if (message.AdditionalProperties?.TryGetValue(PersistedMarkerKey, out var value) == true && value is true)
+        {
+            return true;
+        }
+
+        if (message.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.ChatHistory)
+        {
+            return true;
+        }
+
+        // In streaming mode, FunctionInvokingChatClient reconstructs ChatMessage objects via ToChatResponse()
+        // independently, producing different ChatMessage instances. However, the underlying AIContent objects
+        // (e.g., FunctionCallContent, FunctionResultContent) are shared references. Checking for markers on
+        // AIContent handles dedup in this case.
+        if (message.Contents.Count > 0 && message.Contents.All(c => c.AdditionalProperties?.TryGetValue(PersistedMarkerKey, out var value) == true && value is true))
+        {
+            return true;
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    /// Marks the given messages as persisted by setting a marker on both the <see cref="ChatMessage"/>
+    /// and each of its <see cref="AIContent"/> items.
+    /// </summary>
+    /// <remarks>
+    /// Both levels are marked because <see cref="FunctionInvokingChatClient"/> may reconstruct
+    /// <see cref="ChatMessage"/> objects in streaming mode (losing the message-level marker),
+    /// but the <see cref="AIContent"/> references are shared and retain their markers.
+    /// </remarks>
+    /// <param name="messages">The messages to mark as persisted.</param>
+    private static void MarkAsPersisted(IEnumerable<ChatMessage> messages)
+    {
+        foreach (var message in messages)
+        {
+            message.AdditionalProperties ??= new();
+            message.AdditionalProperties[PersistedMarkerKey] = true;
+
+            foreach (var content in message.Contents)
+            {
+                content.AdditionalProperties ??= new();
+                content.AdditionalProperties[PersistedMarkerKey] = true;
+            }
+        }
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/WorkflowSamplesValidation.cs

@@ -5,6 +5,8 @@ using System.Reflection;
 using System.Text;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.Logging;
+using ModelContextProtocol.Client;
+using ModelContextProtocol.Protocol;
 namespace Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests;
 
 /// <summary>
@@ -235,6 +237,114 @@ public sealed class WorkflowSamplesValidation(ITestOutputHelper outputHelper) :
         });
     }
 
+    [Fact]
+    public async Task WorkflowMcpToolSampleValidationAsync()
+    {
+        string samplePath = Path.Combine(s_samplesPath, "04_WorkflowMcpTool");
+        await this.RunSampleTestAsync(samplePath, requiresOpenAI: false, async (logs) =>
+        {
+            // Connect to the MCP endpoint exposed by the Azure Functions host
+            IClientTransport clientTransport = new HttpClientTransport(new()
+            {
+                Endpoint = new Uri($"http://localhost:{AzureFunctionsPort}/runtime/webhooks/mcp")
+            });
+
+            await using McpClient mcpClient = await McpClient.CreateAsync(clientTransport);
+
+            // Verify both workflow tools are listed
+            IList<McpClientTool> tools = await mcpClient.ListToolsAsync();
+            this._outputHelper.WriteLine($"MCP tools found: {string.Join(", ", tools.Select(t => t.Name))}");
+
+            Assert.Single(tools, t => t.Name == "Translate");
+            Assert.Single(tools, t => t.Name == "OrderLookup");
+
+            // Invoke the Translate workflow via MCP tool (returns a string result)
+            this._outputHelper.WriteLine("Invoking MCP tool 'Translate'...");
+            CallToolResult translateResult = await mcpClient.CallToolAsync(
+                "Translate",
+                arguments: new Dictionary<string, object?> { { "input", "hello world" } });
+
+            Assert.NotEmpty(translateResult.Content);
+            string translateResponse = Assert.IsType<TextContentBlock>(translateResult.Content[0]).Text;
+            this._outputHelper.WriteLine($"Translate MCP tool response: {translateResponse}");
+            Assert.NotEmpty(translateResponse);
+            Assert.Contains("HELLO WORLD", translateResponse);
+
+            // Invoke the OrderLookup workflow via MCP tool (returns a POCO serialized as JSON)
+            this._outputHelper.WriteLine("Invoking MCP tool 'OrderLookup'...");
+            CallToolResult orderResult = await mcpClient.CallToolAsync(
+                "OrderLookup",
+                arguments: new Dictionary<string, object?> { { "input", "ORD-2025-42" } });
+
+            Assert.NotEmpty(orderResult.Content);
+            string orderResponse = Assert.IsType<TextContentBlock>(orderResult.Content[0]).Text;
+            this._outputHelper.WriteLine($"OrderLookup MCP tool response: {orderResponse}");
+            Assert.NotEmpty(orderResponse);
+            Assert.Contains("ORD-2025-42", orderResponse);
+
+            // Verify executor activities ran in the logs
+            lock (logs)
+            {
+                Assert.True(logs.Any(log => log.Message.Contains("[Activity] TranslateText:")), "TranslateText activity not found in logs.");
+                Assert.True(logs.Any(log => log.Message.Contains("[Activity] FormatOutput:")), "FormatOutput activity not found in logs.");
+                Assert.True(logs.Any(log => log.Message.Contains("[Activity] LookupOrder:")), "LookupOrder activity not found in logs.");
+                Assert.True(logs.Any(log => log.Message.Contains("[Activity] EnrichOrder:")), "EnrichOrder activity not found in logs.");
+            }
+        });
+    }
+
+    [Fact]
+    public async Task WorkflowAndAgentsSampleValidationAsync()
+    {
+        string samplePath = Path.Combine(s_samplesPath, "05_WorkflowAndAgents");
+        await this.RunSampleTestAsync(samplePath, requiresOpenAI: true, async (logs) =>
+        {
+            // Connect to the MCP endpoint exposed by the Azure Functions host
+            IClientTransport clientTransport = new HttpClientTransport(new()
+            {
+                Endpoint = new Uri($"http://localhost:{AzureFunctionsPort}/runtime/webhooks/mcp")
+            });
+
+            await using McpClient mcpClient = await McpClient.CreateAsync(clientTransport);
+
+            // Verify both the agent and workflow tools are listed
+            IList<McpClientTool> tools = await mcpClient.ListToolsAsync();
+            this._outputHelper.WriteLine($"MCP tools found: {string.Join(", ", tools.Select(t => t.Name))}");
+
+            Assert.Single(tools, t => t.Name == "Assistant");
+            Assert.Single(tools, t => t.Name == "Translate");
+
+            // Invoke the Translate workflow via MCP tool
+            this._outputHelper.WriteLine("Invoking MCP tool 'Translate'...");
+            CallToolResult translateResult = await mcpClient.CallToolAsync(
+                "Translate",
+                arguments: new Dictionary<string, object?> { { "input", "hello world" } });
+
+            Assert.NotEmpty(translateResult.Content);
+            string translateResponse = Assert.IsType<TextContentBlock>(translateResult.Content[0]).Text;
+            this._outputHelper.WriteLine($"Translate MCP tool response: {translateResponse}");
+            Assert.Contains("HELLO WORLD", translateResponse);
+
+            // Invoke the Assistant agent via MCP tool
+            this._outputHelper.WriteLine("Invoking MCP tool 'Assistant'...");
+            CallToolResult assistantResult = await mcpClient.CallToolAsync(
+                "Assistant",
+                arguments: new Dictionary<string, object?> { { "query", "What is 2 + 2?" } });
+
+            Assert.NotEmpty(assistantResult.Content);
+            string assistantResponse = Assert.IsType<TextContentBlock>(assistantResult.Content[0]).Text;
+            this._outputHelper.WriteLine($"Assistant MCP tool response: {assistantResponse}");
+            Assert.NotEmpty(assistantResponse);
+
+            // Verify workflow executor activities ran in the logs
+            lock (logs)
+            {
+                Assert.True(logs.Any(log => log.Message.Contains("[Activity] TranslateText:")), "TranslateText activity not found in logs.");
+                Assert.True(logs.Any(log => log.Message.Contains("[Activity] FormatOutput:")), "FormatOutput activity not found in logs.");
+            }
+        });
+    }
+
     [Fact]
     public async Task ConcurrentWorkflowSampleValidationAsync()
     {

dotnet/tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/DurableAgentFunctionMetadataTransformerTests.cs

@@ -148,6 +148,45 @@ public sealed class DurableAgentFunctionMetadataTransformerTests
         }
     }
 
+    [Fact]
+    public void Transform_SkipsAgents_WithoutExplicitOptions()
+    {
+        // Arrange: two agents in the dictionary, but only one has explicit FunctionsAgentOptions.
+        // This simulates a workflow-auto-registered agent (workflowAgent) alongside a standalone agent.
+        Dictionary<string, Func<IServiceProvider, AIAgent>> agents = new()
+        {
+            { "standaloneAgent", _ => new TestAgent("standaloneAgent", "Standalone agent") },
+            { "workflowAgent", _ => new TestAgent("workflowAgent", "Auto-registered by workflow") }
+        };
+
+        FunctionsAgentOptions standaloneOptions = new();
+        standaloneOptions.HttpTrigger.IsEnabled = true;
+
+        // Only standaloneAgent has explicit options; workflowAgent does not.
+        IFunctionsAgentOptionsProvider agentOptionsProvider = new FakeOptionsProvider(new Dictionary<string, FunctionsAgentOptions>
+        {
+            { "standaloneAgent", standaloneOptions }
+        });
+
+        List<IFunctionMetadata> metadataList = [];
+
+        DurableAgentFunctionMetadataTransformer transformer = new(
+            agents,
+            NullLogger<DurableAgentFunctionMetadataTransformer>.Instance,
+            new FakeServiceProvider(),
+            agentOptionsProvider);
+
+        // Act
+        transformer.Transform(metadataList);
+
+        // Assert: only standaloneAgent should have triggers (entity + http = 2).
+        // workflowAgent should be skipped entirely.
+        Assert.Equal(2, metadataList.Count);
+        Assert.Contains(metadataList, m => m.Name == "dafx-standaloneAgent");
+        Assert.Contains(metadataList, m => m.Name == "http-standaloneAgent");
+        Assert.DoesNotContain(metadataList, m => m.Name!.Contains("workflowAgent"));
+    }
+
     private static List<IFunctionMetadata> BuildFunctionMetadataList(int numberOfFunctions)
     {
         List<IFunctionMetadata> list = [];

dotnet/tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/FunctionMetadataFactoryTests.cs

@@ -0,0 +1,121 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Microsoft.Azure.Functions.Worker.Core.FunctionMetadata;
+
+namespace Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests;
+
+public sealed class FunctionMetadataFactoryTests
+{
+    [Fact]
+    public void CreateEntityTrigger_SetsCorrectNameAndBindings()
+    {
+        DefaultFunctionMetadata metadata = FunctionMetadataFactory.CreateEntityTrigger("myAgent");
+
+        Assert.Equal("dafx-myAgent", metadata.Name);
+        Assert.Equal("dotnet-isolated", metadata.Language);
+        Assert.Equal(BuiltInFunctions.RunAgentEntityFunctionEntryPoint, metadata.EntryPoint);
+        Assert.NotNull(metadata.RawBindings);
+        Assert.Equal(2, metadata.RawBindings.Count);
+        Assert.Contains("entityTrigger", metadata.RawBindings[0]);
+        Assert.Contains("durableClient", metadata.RawBindings[1]);
+    }
+
+    [Fact]
+    public void CreateHttpTrigger_SetsCorrectNameRouteAndDefaults()
+    {
+        DefaultFunctionMetadata metadata = FunctionMetadataFactory.CreateHttpTrigger(
+            "myWorkflow", "workflows/myWorkflow/run", BuiltInFunctions.RunWorkflowOrchestrationHttpFunctionEntryPoint);
+
+        Assert.Equal("http-myWorkflow", metadata.Name);
+        Assert.Equal("dotnet-isolated", metadata.Language);
+        Assert.Equal(BuiltInFunctions.RunWorkflowOrchestrationHttpFunctionEntryPoint, metadata.EntryPoint);
+        Assert.NotNull(metadata.RawBindings);
+        Assert.Equal(3, metadata.RawBindings.Count);
+        Assert.Contains("httpTrigger", metadata.RawBindings[0]);
+        Assert.Contains("workflows/myWorkflow/run", metadata.RawBindings[0]);
+        Assert.Contains("\"post\"", metadata.RawBindings[0]);
+        Assert.Contains("http", metadata.RawBindings[1]);
+        Assert.Contains("durableClient", metadata.RawBindings[2]);
+    }
+
+    [Fact]
+    public void CreateHttpTrigger_RespectsCustomMethods()
+    {
+        DefaultFunctionMetadata metadata = FunctionMetadataFactory.CreateHttpTrigger(
+            "status", "workflows/status/{runId}", BuiltInFunctions.GetWorkflowStatusHttpFunctionEntryPoint, methods: "\"get\"");
+
+        Assert.NotNull(metadata.RawBindings);
+        Assert.Contains("\"get\"", metadata.RawBindings[0]);
+        Assert.DoesNotContain("\"post\"", metadata.RawBindings[0]);
+    }
+
+    [Fact]
+    public void CreateActivityTrigger_SetsCorrectNameAndBindings()
+    {
+        DefaultFunctionMetadata metadata = FunctionMetadataFactory.CreateActivityTrigger("dafx-MyExecutor");
+
+        Assert.Equal("dafx-MyExecutor", metadata.Name);
+        Assert.Equal("dotnet-isolated", metadata.Language);
+        Assert.Equal(BuiltInFunctions.InvokeWorkflowActivityFunctionEntryPoint, metadata.EntryPoint);
+        Assert.NotNull(metadata.RawBindings);
+        Assert.Equal(2, metadata.RawBindings.Count);
+        Assert.Contains("activityTrigger", metadata.RawBindings[0]);
+        Assert.Contains("durableClient", metadata.RawBindings[1]);
+    }
+
+    [Fact]
+    public void CreateOrchestrationTrigger_SetsCorrectNameAndBindings()
+    {
+        DefaultFunctionMetadata metadata = FunctionMetadataFactory.CreateOrchestrationTrigger(
+            "dafx-MyWorkflow", BuiltInFunctions.RunWorkflowOrchestrationFunctionEntryPoint);
+
+        Assert.Equal("dafx-MyWorkflow", metadata.Name);
+        Assert.Equal("dotnet-isolated", metadata.Language);
+        Assert.Equal(BuiltInFunctions.RunWorkflowOrchestrationFunctionEntryPoint, metadata.EntryPoint);
+        Assert.NotNull(metadata.RawBindings);
+        Assert.Single(metadata.RawBindings);
+        Assert.Contains("orchestrationTrigger", metadata.RawBindings[0]);
+    }
+
+    [Fact]
+    public void CreateWorkflowMcpToolTrigger_SetsCorrectNameAndBindings()
+    {
+        DefaultFunctionMetadata metadata = FunctionMetadataFactory.CreateWorkflowMcpToolTrigger("Translate", "Translate text");
+
+        Assert.Equal("mcptool-Translate", metadata.Name);
+        Assert.Equal("dotnet-isolated", metadata.Language);
+        Assert.Equal(BuiltInFunctions.RunWorkflowMcpToolFunctionEntryPoint, metadata.EntryPoint);
+        Assert.NotNull(metadata.RawBindings);
+        Assert.Equal(3, metadata.RawBindings.Count);
+
+        // Verify all bindings are valid JSON
+        foreach (string binding in metadata.RawBindings)
+        {
+            JsonDocument.Parse(binding);
+        }
+
+        // mcpToolTrigger binding
+        Assert.Contains("mcpToolTrigger", metadata.RawBindings[0]);
+        Assert.Contains("\"toolName\":\"Translate\"", metadata.RawBindings[0]);
+        Assert.Contains("\"description\":\"Translate text\"", metadata.RawBindings[0]);
+        Assert.Contains("toolProperties", metadata.RawBindings[0]);
+
+        // mcpToolProperty binding for input
+        Assert.Contains("mcpToolProperty", metadata.RawBindings[1]);
+        Assert.Contains("\"propertyName\":\"input\"", metadata.RawBindings[1]);
+        Assert.Contains("\"isRequired\":true", metadata.RawBindings[1]);
+
+        // durableClient binding
+        Assert.Contains("durableClient", metadata.RawBindings[2]);
+    }
+
+    [Fact]
+    public void CreateWorkflowMcpToolTrigger_UsesDefaultDescription_WhenNull()
+    {
+        DefaultFunctionMetadata metadata = FunctionMetadataFactory.CreateWorkflowMcpToolTrigger("MyWorkflow", description: null);
+
+        Assert.NotNull(metadata.RawBindings);
+        Assert.Contains("Run the MyWorkflow workflow", metadata.RawBindings[0]);
+    }
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatHistoryPersistingChatClientTests.cs

@@ -0,0 +1,766 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Moq;
+using Moq.Protected;
+
+namespace Microsoft.Agents.AI.UnitTests;
+
+/// <summary>
+/// Contains unit tests for the <see cref="ChatHistoryPersistingChatClient"/> decorator,
+/// verifying that it persists messages via the <see cref="ChatHistoryProvider"/> after each
+/// individual service call by default, or marks messages for end-of-run persistence when the
+/// <see cref="ChatClientAgentOptions.PersistChatHistoryAtEndOfRun"/> option is enabled.
+/// </summary>
+public class ChatHistoryPersistingChatClientTests
+{
+    /// <summary>
+    /// Verifies that by default (PersistChatHistoryAtEndOfRun is false),
+    /// the ChatHistoryProvider receives messages after a successful non-streaming call.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_PersistsMessagesPerServiceCall_ByDefaultAsync()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>())).ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]));
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            PersistChatHistoryAtEndOfRun = false,
+        });
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await agent.RunAsync([new(ChatRole.User, "test")], session);
+
+        // Assert — InvokedCoreAsync should be called by the decorator (per service call)
+        mockChatHistoryProvider
+            .Protected()
+            .Verify<ValueTask>("InvokedCoreAsync", Times.Once(),
+                ItExpr.Is<ChatHistoryProvider.InvokedContext>(x =>
+                    x.RequestMessages.Any(m => m.Text == "test") &&
+                    x.ResponseMessages!.Any(m => m.Text == "response")),
+                ItExpr.IsAny<CancellationToken>());
+    }
+
+    /// <summary>
+    /// Verifies that when per-service-call persistence is active (default),
+    /// the ChatHistoryProvider receives messages at the end of the run.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_PersistsMessagesAtEndOfRun_WhenOptionEnabledAsync()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>())).ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]));
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            PersistChatHistoryAtEndOfRun = true,
+        });
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await agent.RunAsync([new(ChatRole.User, "test")], session);
+
+        // Assert — InvokedCoreAsync should be called once by the agent (end of run)
+        mockChatHistoryProvider
+            .Protected()
+            .Verify<ValueTask>("InvokedCoreAsync", Times.Once(),
+                ItExpr.Is<ChatHistoryProvider.InvokedContext>(x =>
+                    x.RequestMessages.Any(m => m.Text == "test") &&
+                    x.ResponseMessages!.Any(m => m.Text == "response")),
+                ItExpr.IsAny<CancellationToken>());
+    }
+
+    /// <summary>
+    /// Verifies that when per-service-call persistence is active (default) and the service call fails,
+    /// the ChatHistoryProvider is notified with the exception.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_NotifiesProviderOfFailure_WhenPerServiceCallPersistenceActiveAsync()
+    {
+        // Arrange
+        var expectedException = new InvalidOperationException("Service failed");
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>())).ThrowsAsync(expectedException);
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            PersistChatHistoryAtEndOfRun = false,
+        });
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await Assert.ThrowsAsync<InvalidOperationException>(() => agent.RunAsync([new(ChatRole.User, "test")], session));
+
+        // Assert — the decorator should have notified the provider of the failure
+        mockChatHistoryProvider
+            .Protected()
+            .Verify<ValueTask>("InvokedCoreAsync", Times.Once(),
+                ItExpr.Is<ChatHistoryProvider.InvokedContext>(x =>
+                    x.InvokeException != null &&
+                    x.InvokeException.Message == "Service failed"),
+                ItExpr.IsAny<CancellationToken>());
+    }
+
+    /// <summary>
+    /// Verifies that the decorator is injected in persist mode by default
+    /// and can be discovered via GetService.
+    /// </summary>
+    [Fact]
+    public void ChatClient_ContainsDecorator_InPersistMode_ByDefault()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+
+        // Act
+        ChatClientAgent agent = new(mockService.Object, options: new());
+
+        // Assert
+        var decorator = agent.ChatClient.GetService<ChatHistoryPersistingChatClient>();
+        Assert.NotNull(decorator);
+        Assert.False(decorator.MarkOnly);
+    }
+
+    /// <summary>
+    /// Verifies that the decorator is injected in mark-only mode when PersistChatHistoryAtEndOfRun is true.
+    /// </summary>
+    [Fact]
+    public void ChatClient_ContainsDecorator_InMarkOnlyMode_WhenPersistAtEndOfRun()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+
+        // Act
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            PersistChatHistoryAtEndOfRun = true,
+        });
+
+        // Assert
+        var decorator = agent.ChatClient.GetService<ChatHistoryPersistingChatClient>();
+        Assert.NotNull(decorator);
+        Assert.True(decorator.MarkOnly);
+    }
+
+    /// <summary>
+    /// Verifies that the decorator is NOT injected when UseProvidedChatClientAsIs is true.
+    /// </summary>
+    [Fact]
+    public void ChatClient_DoesNotContainDecorator_WhenUseProvidedChatClientAsIs()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+
+        // Act
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            UseProvidedChatClientAsIs = true,
+        });
+
+        // Assert
+        var decorator = agent.ChatClient.GetService<ChatHistoryPersistingChatClient>();
+        Assert.Null(decorator);
+    }
+
+    /// <summary>
+    /// Verifies that the PersistChatHistoryAtEndOfRun option is included in Clone().
+    /// </summary>
+    [Fact]
+    public void ChatClientAgentOptions_Clone_IncludesPersistChatHistoryAtEndOfRun()
+    {
+        // Arrange
+        var options = new ChatClientAgentOptions
+        {
+            PersistChatHistoryAtEndOfRun = true,
+        };
+
+        // Act
+        var cloned = options.Clone();
+
+        // Assert
+        Assert.True(cloned.PersistChatHistoryAtEndOfRun);
+    }
+
+    /// <summary>
+    /// Verifies that when per-service-call persistence is active (default) and the service call
+    /// involves a function invocation loop, the ChatHistoryProvider is called after each individual
+    /// service call (not just once at the end).
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_PersistsPerServiceCall_DuringFunctionInvocationLoopAsync()
+    {
+        // Arrange
+        int serviceCallCount = 0;
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Returns(() =>
+            {
+                serviceCallCount++;
+                if (serviceCallCount == 1)
+                {
+                    // First call returns a tool call
+                    return Task.FromResult(new ChatResponse([new(ChatRole.Assistant, [new FunctionCallContent("call1", "myTool", new Dictionary<string, object?>())])]));
+                }
+
+                // Second call returns a final response
+                return Task.FromResult(new ChatResponse([new(ChatRole.Assistant, "final response")]));
+            });
+
+        var invokedContexts = new List<ChatHistoryProvider.InvokedContext>();
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Callback((ChatHistoryProvider.InvokedContext ctx, CancellationToken _) => invokedContexts.Add(ctx))
+            .Returns(() => new ValueTask());
+
+        // Define a simple tool
+        var tool = AIFunctionFactory.Create(() => "tool result", "myTool", "A test tool");
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new() { Tools = [tool] },
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            PersistChatHistoryAtEndOfRun = false,
+        }, services: new ServiceCollection().BuildServiceProvider());
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        Exception? caughtException = null;
+        try
+        {
+            await agent.RunAsync([new(ChatRole.User, "test")], session);
+        }
+        catch (Exception ex)
+        {
+            caughtException = ex;
+        }
+
+        // Diagnostic: check if there was an unexpected exception
+        Assert.Null(caughtException);
+
+        // Assert — the decorator should have been called twice (once per service call in the function invocation loop)
+        Assert.Equal(2, serviceCallCount);
+        Assert.Equal(2, invokedContexts.Count);
+
+        // First invocation should have the user message as request and tool call response
+        Assert.NotNull(invokedContexts[0].ResponseMessages);
+        var firstRequestMessages = invokedContexts[0].RequestMessages.ToList();
+        Assert.Contains(firstRequestMessages, m => m.Text == "test");
+        Assert.Contains(invokedContexts[0].ResponseMessages!, m => m.Contents.OfType<FunctionCallContent>().Any());
+
+        // Second invocation: request messages should NOT include the original user message (already notified).
+        // It should only include messages added since the first call (assistant tool call + tool result).
+        Assert.NotNull(invokedContexts[1].ResponseMessages);
+        var secondRequestMessages = invokedContexts[1].RequestMessages.ToList();
+        Assert.DoesNotContain(secondRequestMessages, m => m.Text == "test");
+        Assert.Contains(invokedContexts[1].ResponseMessages!, m => m.Text == "final response");
+    }
+
+    /// <summary>
+    /// Verifies that when per-service-call persistence is active (default) with streaming,
+    /// the ChatHistoryProvider receives messages after the stream completes.
+    /// </summary>
+    [Fact]
+    public async Task RunStreamingAsync_PersistsMessagesPerServiceCall_ByDefaultAsync()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetStreamingResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Returns(CreateAsyncEnumerableAsync(
+                new ChatResponseUpdate(ChatRole.Assistant, "streaming "),
+                new ChatResponseUpdate(ChatRole.Assistant, "response")));
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            PersistChatHistoryAtEndOfRun = false,
+        });
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await foreach (var _ in agent.RunStreamingAsync([new(ChatRole.User, "test")], session))
+        {
+            // Consume stream
+        }
+
+        // Assert — InvokedCoreAsync should be called by the decorator
+        mockChatHistoryProvider
+            .Protected()
+            .Verify<ValueTask>("InvokedCoreAsync", Times.Once(),
+                ItExpr.Is<ChatHistoryProvider.InvokedContext>(x =>
+                    x.RequestMessages.Any(m => m.Text == "test") &&
+                    x.ResponseMessages != null),
+                ItExpr.IsAny<CancellationToken>());
+    }
+
+    /// <summary>
+    /// Verifies that when per-service-call persistence is active (default),
+    /// AIContextProviders are also notified of new messages after a successful call.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_NotifiesAIContextProviders_ByDefaultAsync()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>())).ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]));
+
+        Mock<AIContextProvider> mockContextProvider = new(null, null, null);
+        mockContextProvider.SetupGet(p => p.StateKeys).Returns(["TestAIContextProvider"]);
+        mockContextProvider
+            .Protected()
+            .Setup<ValueTask<AIContext>>("InvokingCoreAsync", ItExpr.IsAny<AIContextProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(() => new ValueTask<AIContext>(new AIContext()));
+        mockContextProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<AIContextProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(() => new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            AIContextProviders = [mockContextProvider.Object],
+            PersistChatHistoryAtEndOfRun = false,
+        });
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await agent.RunAsync([new(ChatRole.User, "test")], session);
+
+        // Assert — InvokedCoreAsync should be called by the decorator for the AIContextProvider
+        mockContextProvider
+            .Protected()
+            .Verify<ValueTask>("InvokedCoreAsync", Times.Once(),
+                ItExpr.Is<AIContextProvider.InvokedContext>(x =>
+                    x.ResponseMessages != null &&
+                    x.ResponseMessages.Any(m => m.Text == "response")),
+                ItExpr.IsAny<CancellationToken>());
+    }
+
+    /// <summary>
+    /// Verifies that when per-service-call persistence is active (default) and the service fails,
+    /// AIContextProviders are notified of the failure.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_NotifiesAIContextProvidersOfFailure_ByDefaultAsync()
+    {
+        // Arrange
+        var expectedException = new InvalidOperationException("Service failed");
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>())).ThrowsAsync(expectedException);
+
+        Mock<AIContextProvider> mockContextProvider = new(null, null, null);
+        mockContextProvider.SetupGet(p => p.StateKeys).Returns(["TestAIContextProvider"]);
+        mockContextProvider
+            .Protected()
+            .Setup<ValueTask<AIContext>>("InvokingCoreAsync", ItExpr.IsAny<AIContextProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(() => new ValueTask<AIContext>(new AIContext()));
+        mockContextProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<AIContextProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(() => new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            AIContextProviders = [mockContextProvider.Object],
+            PersistChatHistoryAtEndOfRun = false,
+        });
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await Assert.ThrowsAsync<InvalidOperationException>(() => agent.RunAsync([new(ChatRole.User, "test")], session));
+
+        // Assert — the decorator should have notified the AIContextProvider of the failure
+        mockContextProvider
+            .Protected()
+            .Verify<ValueTask>("InvokedCoreAsync", Times.Once(),
+                ItExpr.Is<AIContextProvider.InvokedContext>(x =>
+                    x.InvokeException != null &&
+                    x.InvokeException.Message == "Service failed"),
+                ItExpr.IsAny<CancellationToken>());
+    }
+
+    /// <summary>
+    /// Verifies that when per-service-call persistence is active (default),
+    /// both ChatHistoryProvider and AIContextProviders are notified together.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_NotifiesBothProviders_ByDefaultAsync()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>())).ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]));
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(() => new ValueTask());
+
+        Mock<AIContextProvider> mockContextProvider = new(null, null, null);
+        mockContextProvider.SetupGet(p => p.StateKeys).Returns(["TestAIContextProvider"]);
+        mockContextProvider
+            .Protected()
+            .Setup<ValueTask<AIContext>>("InvokingCoreAsync", ItExpr.IsAny<AIContextProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(() => new ValueTask<AIContext>(new AIContext()));
+        mockContextProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<AIContextProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(() => new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            AIContextProviders = [mockContextProvider.Object],
+            PersistChatHistoryAtEndOfRun = false,
+        });
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await agent.RunAsync([new(ChatRole.User, "test")], session);
+
+        // Assert — both providers should have been notified
+        mockChatHistoryProvider
+            .Protected()
+            .Verify<ValueTask>("InvokedCoreAsync", Times.Once(),
+                ItExpr.Is<ChatHistoryProvider.InvokedContext>(x =>
+                    x.ResponseMessages != null &&
+                    x.ResponseMessages.Any(m => m.Text == "response")),
+                ItExpr.IsAny<CancellationToken>());
+
+        mockContextProvider
+            .Protected()
+            .Verify<ValueTask>("InvokedCoreAsync", Times.Once(),
+                ItExpr.Is<AIContextProvider.InvokedContext>(x =>
+                    x.ResponseMessages != null &&
+                    x.ResponseMessages.Any(m => m.Text == "response")),
+                ItExpr.IsAny<CancellationToken>());
+    }
+
+    /// <summary>
+    /// Verifies that during a FIC loop, response messages from the first call are not
+    /// re-notified as request messages on the second call.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_DoesNotReNotifyResponseMessagesAsRequestMessages_DuringFicLoopAsync()
+    {
+        // Arrange
+        int serviceCallCount = 0;
+        var assistantToolCallMessage = new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", "myTool", new Dictionary<string, object?>())]);
+
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Returns(() =>
+            {
+                serviceCallCount++;
+                if (serviceCallCount == 1)
+                {
+                    return Task.FromResult(new ChatResponse([assistantToolCallMessage]));
+                }
+
+                return Task.FromResult(new ChatResponse([new(ChatRole.Assistant, "final response")]));
+            });
+
+        var invokedContexts = new List<ChatHistoryProvider.InvokedContext>();
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Callback((ChatHistoryProvider.InvokedContext ctx, CancellationToken _) => invokedContexts.Add(ctx))
+            .Returns(() => new ValueTask());
+
+        var tool = AIFunctionFactory.Create(() => "tool result", "myTool", "A test tool");
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new() { Tools = [tool] },
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            PersistChatHistoryAtEndOfRun = false,
+        }, services: new ServiceCollection().BuildServiceProvider());
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await agent.RunAsync([new(ChatRole.User, "test")], session);
+
+        // Assert
+        Assert.Equal(2, invokedContexts.Count);
+
+        // The assistant tool call message was a response in call 1
+        Assert.Contains(invokedContexts[0].ResponseMessages!, m => ReferenceEquals(m, assistantToolCallMessage));
+
+        // It should NOT appear as a request in call 2 (it was already notified as a response)
+        var secondRequestMessages = invokedContexts[1].RequestMessages.ToList();
+        Assert.DoesNotContain(secondRequestMessages, m => ReferenceEquals(m, assistantToolCallMessage));
+    }
+
+    /// <summary>
+    /// Verifies that when a failure occurs on the second call in a FIC loop,
+    /// only new request messages (not previously notified) are sent in the failure notification.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_DeduplicatesRequestMessages_OnFailureDuringFicLoopAsync()
+    {
+        // Arrange
+        int serviceCallCount = 0;
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Returns(() =>
+            {
+                serviceCallCount++;
+                if (serviceCallCount == 1)
+                {
+                    return Task.FromResult(new ChatResponse([new(ChatRole.Assistant, [new FunctionCallContent("call1", "myTool", new Dictionary<string, object?>())])]));
+                }
+
+                throw new InvalidOperationException("Service failure on second call");
+            });
+
+        var invokedContexts = new List<ChatHistoryProvider.InvokedContext>();
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Callback((ChatHistoryProvider.InvokedContext ctx, CancellationToken _) => invokedContexts.Add(ctx))
+            .Returns(() => new ValueTask());
+
+        var tool = AIFunctionFactory.Create(() => "tool result", "myTool", "A test tool");
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new() { Tools = [tool] },
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            PersistChatHistoryAtEndOfRun = false,
+        }, services: new ServiceCollection().BuildServiceProvider());
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await Assert.ThrowsAsync<InvalidOperationException>(() =>
+            agent.RunAsync([new(ChatRole.User, "test")], session));
+
+        // Assert — should have 2 notifications: success on call 1, failure on call 2
+        Assert.Equal(2, invokedContexts.Count);
+
+        // First notification: success, has user message as request
+        Assert.Null(invokedContexts[0].InvokeException);
+        Assert.Contains(invokedContexts[0].RequestMessages, m => m.Text == "test");
+
+        // Second notification: failure, should NOT include the user message (already notified)
+        Assert.NotNull(invokedContexts[1].InvokeException);
+        var failureRequestMessages = invokedContexts[1].RequestMessages.ToList();
+        Assert.DoesNotContain(failureRequestMessages, m => m.Text == "test");
+    }
+
+    /// <summary>
+    /// Verifies that after a successful run with per-service-call persistence, the notified
+    /// messages are stamped with the persisted marker so they are not re-notified.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_MarksNotifiedMessages_WithPersistedMarkerAsync()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>())).ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]));
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(() => new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            PersistChatHistoryAtEndOfRun = false,
+        });
+
+        // Act
+        var inputMessage = new ChatMessage(ChatRole.User, "test");
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await agent.RunAsync([inputMessage], session);
+
+        // Assert — input message should be marked as persisted
+        Assert.True(
+            inputMessage.AdditionalProperties?.ContainsKey(ChatHistoryPersistingChatClient.PersistedMarkerKey) == true,
+            "Input message should be marked as persisted after a successful run.");
+    }
+
+    /// <summary>
+    /// Verifies that when per-service-call persistence is enabled and the inner client returns a
+    /// conversation ID, the session's ConversationId is updated after the service call.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_UpdatesSessionConversationId_WhenPerServiceCallPersistenceEnabledAsync()
+    {
+        // Arrange
+        const string ExpectedConversationId = "conv-123";
+
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")])
+            {
+                ConversationId = ExpectedConversationId,
+            });
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            PersistChatHistoryAtEndOfRun = false,
+        });
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await agent.RunAsync([new(ChatRole.User, "test")], session);
+
+        // Assert — session should have the conversation ID returned by the inner client
+        Assert.Equal(ExpectedConversationId, session!.ConversationId);
+    }
+
+    private static async IAsyncEnumerable<ChatResponseUpdate> CreateAsyncEnumerableAsync(params ChatResponseUpdate[] updates)
+    {
+        foreach (var update in updates)
+        {
+            yield return update;
+        }
+
+        await Task.CompletedTask;
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/FileSystemJsonCheckpointStoreTests.cs

@@ -9,49 +9,173 @@ using Microsoft.Agents.AI.Workflows.Checkpointing;
 
 namespace Microsoft.Agents.AI.Workflows.UnitTests;
 
+internal sealed class TempDirectory : IDisposable
+{
+    public DirectoryInfo DirectoryInfo { get; }
+
+    public TempDirectory()
+    {
+        string tempDirPath = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString());
+        this.DirectoryInfo = Directory.CreateDirectory(tempDirPath);
+    }
+
+    public void Dispose()
+    {
+        this.DisposeInternal();
+        GC.SuppressFinalize(this);
+    }
+
+    private void DisposeInternal()
+    {
+        if (this.DirectoryInfo.Exists)
+        {
+            try
+            {
+                // Best efforts
+                this.DirectoryInfo.Delete(recursive: true);
+            }
+            catch { }
+        }
+    }
+
+    ~TempDirectory()
+    {
+        // Best efforts
+        this.DisposeInternal();
+    }
+
+    public static implicit operator DirectoryInfo(TempDirectory tempDirectory) => tempDirectory.DirectoryInfo;
+
+    public string FullName => this.DirectoryInfo.FullName;
+
+    public bool IsParentOf(FileInfo candidate)
+    {
+        if (candidate.Directory is null)
+        {
+            return false;
+        }
+
+        if (candidate.Directory.FullName == this.DirectoryInfo.FullName)
+        {
+            return true;
+        }
+
+        return this.IsParentOf(candidate.Directory);
+    }
+
+    public bool IsParentOf(DirectoryInfo candidate)
+    {
+        while (candidate.Parent is not null)
+        {
+            if (candidate.Parent.FullName == this.DirectoryInfo.FullName)
+            {
+                return true;
+            }
+
+            candidate = candidate.Parent;
+        }
+
+        return false;
+    }
+}
 public sealed class FileSystemJsonCheckpointStoreTests
 {
+    public static JsonElement TestData => JsonSerializer.SerializeToElement(new { test = "data" });
+
     [Fact]
     public async Task CreateCheckpointAsync_ShouldPersistIndexToDiskBeforeDisposeAsync()
     {
         // Arrange
-        DirectoryInfo tempDir = new(Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()));
-        FileSystemJsonCheckpointStore? store = null;
+        using TempDirectory tempDirectory = new();
+        using FileSystemJsonCheckpointStore? store = new(tempDirectory);
 
-        try
+        string runId = Guid.NewGuid().ToString("N");
+
+        // Act
+        CheckpointInfo checkpoint = await store.CreateCheckpointAsync(runId, TestData);
+
+        // Assert - Check the file size before disposing to verify data was flushed to disk
+        // The index.jsonl file is held exclusively by the store, so we check via FileInfo
+        string indexPath = Path.Combine(tempDirectory.FullName, "index.jsonl");
+        FileInfo indexFile = new(indexPath);
+        indexFile.Refresh();
+        long fileSizeBeforeDispose = indexFile.Length;
+
+        // Data should already be on disk (file size > 0) before we dispose
+        fileSizeBeforeDispose.Should().BeGreaterThan(0, "index.jsonl should be flushed to disk after CreateCheckpointAsync");
+
+        // Dispose to release file lock before final verification
+        store.Dispose();
+
+        string[] lines = File.ReadAllLines(indexPath);
+        lines.Should().HaveCount(1);
+        lines[0].Should().Contain(checkpoint.CheckpointId);
+    }
+
+    private async ValueTask Run_EscapeRootFolderTestAsync(string escapingPath)
+    {
+        // Arrange
+        using TempDirectory tempDirectory = new();
+        using FileSystemJsonCheckpointStore store = new(tempDirectory);
+
+        string naivePath = Path.Combine(tempDirectory.DirectoryInfo.FullName, escapingPath);
+
+        // Check that the naive path is actually outside the temp directory to validate the test is meaningful
+        FileInfo naiveCheckpointFile = new(naivePath);
+        tempDirectory.IsParentOf(naiveCheckpointFile).Should().BeFalse("The naive path should be outside the root folder to validate that escaping is necessary.");
+
+        // Act
+        CheckpointInfo checkpointInfo = await store.CreateCheckpointAsync(escapingPath, TestData);
+
+        // Assert
+        string naivePathWithCheckpointId = Path.Combine(tempDirectory.DirectoryInfo.FullName, $"{escapingPath}_{checkpointInfo.CheckpointId}.json");
+        new FileInfo(naivePathWithCheckpointId).Exists.Should().BeFalse("The naive path should not be used to save a checkpoint file.");
+
+        string actualFileName = store.GetFileNameForCheckpoint(escapingPath, checkpointInfo);
+        string actualFilePath = Path.Combine(tempDirectory.DirectoryInfo.FullName, actualFileName);
+        FileInfo actualFile = new(actualFilePath);
+
+        tempDirectory.IsParentOf(actualFile).Should().BeTrue("The actual checkpoint should be saved inside the root folder.");
+        actualFile.Exists.Should().BeTrue("The actual path should be used to save a checkpoint file.");
+    }
+
+    [Fact]
+    public async Task CreateCheckpointAsync_ShouldNotEscapeRootFolderAsync()
+    {
+        // The SessionId is used as part of the file name, but if it contains path characters such as /.. it can escape the root folder.
+        // Testing that such characters are escaped properly to prevent directory traversal attacks, etc.
+
+        await this.Run_EscapeRootFolderTestAsync("../valid_suffix");
+
+#if !NETFRAMEWORK
+        if (OperatingSystem.IsWindows())
         {
-            store = new(tempDir);
-            string runId = Guid.NewGuid().ToString("N");
-            JsonElement testData = JsonSerializer.SerializeToElement(new { test = "data" });
-
-            // Act
-            CheckpointInfo checkpoint = await store.CreateCheckpointAsync(runId, testData);
-
-            // Assert - Check the file size before disposing to verify data was flushed to disk
-            // The index.jsonl file is held exclusively by the store, so we check via FileInfo
-            string indexPath = Path.Combine(tempDir.FullName, "index.jsonl");
-            FileInfo indexFile = new(indexPath);
-            indexFile.Refresh();
-            long fileSizeBeforeDispose = indexFile.Length;
-
-            // Data should already be on disk (file size > 0) before we dispose
-            fileSizeBeforeDispose.Should().BeGreaterThan(0, "index.jsonl should be flushed to disk after CreateCheckpointAsync");
-
-            // Dispose to release file lock before final verification
-            store.Dispose();
-            store = null;
-
-            string[] lines = File.ReadAllLines(indexPath);
-            lines.Should().HaveCount(1);
-            lines[0].Should().Contain(checkpoint.CheckpointId);
-        }
-        finally
-        {
-            store?.Dispose();
-            if (tempDir.Exists)
-            {
-                tempDir.Delete(recursive: true);
-            }
+            // Windows allows both \ and / as path separators, so we test both
+            await this.Run_EscapeRootFolderTestAsync("..\\valid_suffix");
         }
+#else
+        // .NET Framework is always on Windows
+        await this.Run_EscapeRootFolderTestAsync("..\\valid_suffix");
+#endif
+    }
+
+    private const string InvalidPathCharsWin32 = "\\/:*?\"<>|";
+    private const string InvalidPathCharsUnix = "/";
+    private const string InvalidPathCharsMacOS = "/:";
+
+    [Theory]
+    [InlineData(InvalidPathCharsWin32)]
+    [InlineData(InvalidPathCharsUnix)]
+    [InlineData(InvalidPathCharsMacOS)]
+    public async Task CreateCheckpointAsync_EscapesInvalidCharsAsync(string invalidChars)
+    {
+        // Arrange
+        using TempDirectory tempDirectory = new();
+        using FileSystemJsonCheckpointStore store = new(tempDirectory);
+
+        string runId = $"prefix_{invalidChars}_suffix";
+
+        Func<Task> createCheckpointAction = async () => await store.CreateCheckpointAsync(runId, TestData);
+        await createCheckpointAction.Should().NotThrowAsync();
     }
 }

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/JsonSerializationTests.cs

@@ -673,6 +673,55 @@ public class JsonSerializationTests
         ValidateCheckpoint(retrievedCheckpoint, prototype);
     }
 
+    [Fact]
+    public void Test_SessionState_JsonRoundtrip_WithPendingRequests()
+    {
+        // Arrange
+        Dictionary<string, ExternalRequest> pendingRequests = new()
+        {
+            ["call-1"] = TestExternalRequest,
+            ["call-2"] = ExternalRequest.Create(TestPort, "Request2", "OtherData"),
+        };
+
+        WorkflowSession.SessionState prototype = new(
+            sessionId: "test-session-123",
+            lastCheckpoint: TestParentCheckpointInfo,
+            pendingRequests: pendingRequests);
+
+        // Act
+        WorkflowSession.SessionState result = RunJsonRoundtrip(prototype);
+
+        // Assert
+        result.SessionId.Should().Be(prototype.SessionId);
+        result.LastCheckpoint.Should().Be(prototype.LastCheckpoint);
+        result.StateBag.Should().NotBeNull();
+        result.PendingRequests.Should().NotBeNull()
+            .And.HaveCount(pendingRequests.Count);
+
+        foreach (string key in pendingRequests.Keys)
+        {
+            result.PendingRequests.Should().ContainKey(key);
+            ValidateExternalRequest(result.PendingRequests![key], pendingRequests[key]);
+        }
+    }
+
+    [Fact]
+    public void Test_SessionState_JsonRoundtrip_WithoutPendingRequests()
+    {
+        // Arrange
+        WorkflowSession.SessionState prototype = new(
+            sessionId: "test-session-456",
+            lastCheckpoint: null);
+
+        // Act
+        WorkflowSession.SessionState result = RunJsonRoundtrip(prototype);
+
+        // Assert
+        result.SessionId.Should().Be(prototype.SessionId);
+        result.LastCheckpoint.Should().BeNull();
+        result.PendingRequests.Should().BeNull();
+    }
+
     /// <summary>
     /// Verifies that the default behavior (without AllowOutOfOrderMetadataProperties) fails
     /// when $type metadata is not the first property, demonstrating the PostgreSQL jsonb issue.

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowHostSmokeTests.cs

@@ -28,6 +28,184 @@ public sealed class ExpectedException : Exception
     }
 }
 
+/// <summary>
+/// A simple agent that emits a FunctionCallContent or ToolApprovalRequestContent request.
+/// Used to test that RequestInfoEvent handling preserves the original content type.
+/// </summary>
+internal sealed class RequestEmittingAgent : AIAgent
+{
+    private readonly AIContent _requestContent;
+    private readonly bool _completeOnResponse;
+
+    /// <summary>
+    /// Creates a new <see cref="RequestEmittingAgent"/> that emits the given request content.
+    /// </summary>
+    /// <param name="requestContent">The content to emit on each turn.</param>
+    /// <param name="completeOnResponse">
+    /// When <see langword="true"/>, the agent emits a text completion instead of re-emitting
+    /// the request when the incoming messages contain a <see cref="FunctionResultContent"/>
+    /// or <see cref="ToolApprovalResponseContent"/>.  This models realistic agent behaviour
+    /// where the agent processes the tool result and produces a final answer.
+    /// </param>
+    public RequestEmittingAgent(AIContent requestContent, bool completeOnResponse = false)
+    {
+        this._requestContent = requestContent;
+        this._completeOnResponse = completeOnResponse;
+    }
+
+    private sealed class Session : AgentSession
+    {
+        public Session() { }
+    }
+
+    protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+        => new(new Session());
+
+    protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
+        => new(new Session());
+
+    protected override ValueTask<JsonElement> SerializeSessionCoreAsync(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+        => default;
+
+    protected override Task<AgentResponse> RunCoreAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
+        => this.RunStreamingAsync(messages, session, options, cancellationToken).ToAgentResponseAsync(cancellationToken);
+
+    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        if (this._completeOnResponse && messages.Any(m => m.Contents.Any(c =>
+            c is FunctionResultContent || c is ToolApprovalResponseContent)))
+        {
+            yield return new AgentResponseUpdate(ChatRole.Assistant, [new TextContent("Request processed")]);
+        }
+        else
+        {
+            // Emit the request content
+            yield return new AgentResponseUpdate(ChatRole.Assistant, [this._requestContent]);
+        }
+    }
+}
+
+internal sealed class KickoffOnStartExecutor : ChatProtocolExecutor
+{
+    private static readonly ChatProtocolExecutorOptions s_options = new()
+    {
+        AutoSendTurnToken = false,
+    };
+
+    private readonly string _downstreamExecutorId;
+    private readonly string _kickoffInputText;
+    private readonly string _kickoffMessageText;
+    private readonly string _regularResumeText;
+    private readonly string _regularProcessedText;
+
+    public KickoffOnStartExecutor(
+        string id,
+        string downstreamExecutorId,
+        string kickoffInputText,
+        string kickoffMessageText,
+        string regularResumeText,
+        string regularProcessedText)
+        : base(id, s_options)
+    {
+        this._downstreamExecutorId = downstreamExecutorId;
+        this._kickoffInputText = kickoffInputText;
+        this._kickoffMessageText = kickoffMessageText;
+        this._regularResumeText = regularResumeText;
+        this._regularProcessedText = regularProcessedText;
+    }
+
+    protected override async ValueTask TakeTurnAsync(List<ChatMessage> messages, IWorkflowContext context, bool? emitEvents, CancellationToken cancellationToken = default)
+    {
+        List<string> textContents =
+        [
+            .. messages
+                .SelectMany(message => message.Contents.OfType<TextContent>())
+                .Select(content => content.Text)
+        ];
+
+        if (textContents.Contains(this._kickoffInputText, StringComparer.Ordinal))
+        {
+            await context.SendMessageAsync(
+                new List<ChatMessage> { new(ChatRole.User, this._kickoffMessageText) },
+                this._downstreamExecutorId,
+                cancellationToken).ConfigureAwait(false);
+            await context.SendMessageAsync(
+                new TurnToken(emitEvents),
+                this._downstreamExecutorId,
+                cancellationToken).ConfigureAwait(false);
+        }
+
+        if (textContents.Contains(this._regularResumeText, StringComparer.Ordinal))
+        {
+            AgentResponseUpdate update = new(ChatRole.Assistant, [new TextContent(this._regularProcessedText)])
+            {
+                CreatedAt = DateTimeOffset.UtcNow,
+                MessageId = Guid.NewGuid().ToString("N"),
+                ResponseId = Guid.NewGuid().ToString("N"),
+                Role = ChatRole.Assistant,
+            };
+
+            await context.AddEventAsync(new AgentResponseUpdateEvent(this.Id, update), cancellationToken).ConfigureAwait(false);
+        }
+    }
+}
+
+/// <summary>
+/// A start executor that always emits a response update on every turn,
+/// useful for verifying that a TurnToken was delivered by the session.
+/// On the first turn (user messages present), it kicks off a downstream executor.
+/// </summary>
+internal sealed class TurnTrackingStartExecutor : ChatProtocolExecutor
+{
+    private static readonly ChatProtocolExecutorOptions s_options = new()
+    {
+        AutoSendTurnToken = false,
+    };
+
+    private readonly string _downstreamExecutorId;
+    private readonly string _activatedMarker;
+    private int _activationCount;
+
+    /// <summary>Gets the number of times this executor has been activated (i.e., <see cref="TakeTurnAsync"/> called).</summary>
+    public int ActivationCount => this._activationCount;
+
+    public TurnTrackingStartExecutor(string id, string downstreamExecutorId, string activatedMarker)
+        : base(id, s_options)
+    {
+        this._downstreamExecutorId = downstreamExecutorId;
+        this._activatedMarker = activatedMarker;
+    }
+
+    protected override async ValueTask TakeTurnAsync(List<ChatMessage> messages, IWorkflowContext context, bool? emitEvents, CancellationToken cancellationToken = default)
+    {
+        Interlocked.Increment(ref this._activationCount);
+
+        // On the first turn, forward user messages and a TurnToken to the downstream executor.
+        if (messages.Any(m => m.Role == ChatRole.User))
+        {
+            await context.SendMessageAsync(
+                messages,
+                this._downstreamExecutorId,
+                cancellationToken).ConfigureAwait(false);
+            await context.SendMessageAsync(
+                new TurnToken(emitEvents),
+                this._downstreamExecutorId,
+                cancellationToken).ConfigureAwait(false);
+        }
+
+        // Always emit a marker to prove this executor was activated.
+        AgentResponseUpdate update = new(ChatRole.Assistant, [new TextContent(this._activatedMarker)])
+        {
+            CreatedAt = DateTimeOffset.UtcNow,
+            MessageId = Guid.NewGuid().ToString("N"),
+            ResponseId = Guid.NewGuid().ToString("N"),
+            Role = ChatRole.Assistant,
+        };
+
+        await context.AddEventAsync(new AgentResponseUpdateEvent(this.Id, update), cancellationToken).ConfigureAwait(false);
+    }
+}
+
 public class WorkflowHostSmokeTests
 {
     private sealed class AlwaysFailsAIAgent(bool failByThrowing) : AIAgent
@@ -112,4 +290,445 @@ public class WorkflowHostSmokeTests
 
         hadErrorContent.Should().BeTrue();
     }
+
+    /// <summary>
+    /// Tests that when a workflow emits a RequestInfoEvent with FunctionCallContent data,
+    /// the AgentResponseUpdate preserves the original FunctionCallContent type.
+    /// </summary>
+    [Fact]
+    public async Task Test_AsAgent_FunctionCallContentPreservedInRequestInfoAsync()
+    {
+        // Arrange
+        const string CallId = "test-call-id";
+        const string FunctionName = "testFunction";
+        FunctionCallContent originalContent = new(CallId, FunctionName);
+        RequestEmittingAgent requestAgent = new(originalContent);
+        ExecutorBinding agentBinding = requestAgent.BindAsExecutor(
+            new AIAgentHostOptions { InterceptUnterminatedFunctionCalls = false, EmitAgentUpdateEvents = true });
+        Workflow workflow = new WorkflowBuilder(agentBinding).Build();
+
+        // Act
+        List<AgentResponseUpdate> updates = await workflow.AsAIAgent("WorkflowAgent")
+                                                           .RunStreamingAsync(new ChatMessage(ChatRole.User, "Hello"))
+                                                           .ToListAsync();
+
+        // Assert
+        AgentResponseUpdate? updateWithFunctionCall = updates.FirstOrDefault(u =>
+            u.RawRepresentation is RequestInfoEvent && u.Contents.Any(c => c is FunctionCallContent));
+
+        updateWithFunctionCall.Should().NotBeNull("a FunctionCallContent should be present in the response updates");
+        FunctionCallContent retrievedContent = updateWithFunctionCall!.Contents
+            .OfType<FunctionCallContent>()
+            .Should().ContainSingle()
+            .Which;
+
+        retrievedContent.CallId.Should().NotBe(CallId);
+        retrievedContent.CallId.Should().EndWith($":{CallId}");
+        retrievedContent.Name.Should().Be(FunctionName);
+    }
+
+    /// <summary>
+    /// Tests that when a workflow emits a RequestInfoEvent with ToolApprovalRequestContent data,
+    /// the AgentResponseUpdate preserves the original ToolApprovalRequestContent type.
+    /// </summary>
+    [Fact]
+    public async Task Test_AsAgent_ToolApprovalRequestContentPreservedInRequestInfoAsync()
+    {
+        // Arrange
+        const string RequestId = "test-request-id";
+        McpServerToolCallContent mcpCall = new("call-id", "testToolName", "http://localhost");
+        ToolApprovalRequestContent originalContent = new(RequestId, mcpCall);
+        RequestEmittingAgent requestAgent = new(originalContent);
+        ExecutorBinding agentBinding = requestAgent.BindAsExecutor(
+            new AIAgentHostOptions { InterceptUserInputRequests = false, EmitAgentUpdateEvents = true });
+        Workflow workflow = new WorkflowBuilder(agentBinding).Build();
+
+        // Act
+        List<AgentResponseUpdate> updates = await workflow.AsAIAgent("WorkflowAgent")
+                                                           .RunStreamingAsync(new ChatMessage(ChatRole.User, "Hello"))
+                                                           .ToListAsync();
+
+        // Assert
+        AgentResponseUpdate? updateWithUserInput = updates.FirstOrDefault(u =>
+            u.RawRepresentation is RequestInfoEvent && u.Contents.Any(c => c is ToolApprovalRequestContent));
+
+        updateWithUserInput.Should().NotBeNull("a ToolApprovalRequestContent should be present in the response updates");
+        ToolApprovalRequestContent retrievedContent = updateWithUserInput!.Contents
+            .OfType<ToolApprovalRequestContent>()
+            .Should().ContainSingle()
+            .Which;
+
+        retrievedContent.Should().NotBeNull();
+        retrievedContent.RequestId.Should().NotBe(RequestId);
+        retrievedContent.RequestId.Should().EndWith($":{RequestId}");
+    }
+
+    /// <summary>
+    /// Tests the full roundtrip: workflow emits a request, external caller responds, workflow processes response.
+    /// </summary>
+    [Fact]
+    public async Task Test_AsAgent_FunctionCallRoundtrip_ResponseIsProcessedAsync()
+    {
+        // Arrange: Create an agent that emits a FunctionCallContent request
+        const string CallId = "roundtrip-call-id";
+        const string FunctionName = "testFunction";
+        FunctionCallContent requestContent = new(CallId, FunctionName);
+        RequestEmittingAgent requestAgent = new(requestContent, completeOnResponse: true);
+        ExecutorBinding agentBinding = requestAgent.BindAsExecutor(
+            new AIAgentHostOptions { InterceptUnterminatedFunctionCalls = false, EmitAgentUpdateEvents = true });
+        Workflow workflow = new WorkflowBuilder(agentBinding).Build();
+        AIAgent agent = workflow.AsAIAgent("WorkflowAgent");
+
+        // Act 1: First call - should receive the FunctionCallContent request
+        AgentSession session = await agent.CreateSessionAsync();
+        List<AgentResponseUpdate> firstCallUpdates = await agent.RunStreamingAsync(
+            new ChatMessage(ChatRole.User, "Start"),
+            session).ToListAsync();
+
+        // Assert 1: We should have received a FunctionCallContent
+        AgentResponseUpdate? updateWithRequest = firstCallUpdates.FirstOrDefault(u =>
+            u.RawRepresentation is RequestInfoEvent && u.Contents.Any(c => c is FunctionCallContent));
+        updateWithRequest.Should().NotBeNull("a FunctionCallContent should be present in the response updates");
+
+        FunctionCallContent receivedRequest = updateWithRequest!.Contents
+            .OfType<FunctionCallContent>()
+            .First();
+        receivedRequest.CallId.Should().EndWith($":{CallId}");
+
+        // Act 2: Send the response back
+        FunctionResultContent responseContent = new(receivedRequest.CallId, "test result");
+        ChatMessage responseMessage = new(ChatRole.Tool, [responseContent]);
+
+        // Act 2: Run the workflow with the response and capture the resulting updates
+        List<AgentResponseUpdate> secondCallUpdates = await agent.RunStreamingAsync(responseMessage, session).ToListAsync();
+
+        // Assert 2: The response should be processed and the original request should no longer be pending.
+        // Concretely, the workflow should not re-emit a FunctionCallContent with the same CallId.
+        secondCallUpdates.Should().NotBeNull("processing the response should produce updates");
+        secondCallUpdates.Should().NotBeEmpty("processing the response should progress the workflow");
+        secondCallUpdates
+            .Where(u => u.RawRepresentation is RequestInfoEvent)
+            .SelectMany(u => u.Contents.OfType<FunctionCallContent>())
+            .Should()
+            .NotContain(c => c.CallId == receivedRequest.CallId, "the external FunctionCallContent request should be cleared after processing the response");
+    }
+
+    /// <summary>
+    /// Tests the full roundtrip for ToolApprovalRequestContent: workflow emits request, external caller responds.
+    /// Verifying inbound ToolApprovalResponseContent conversion.
+    /// </summary>
+    [Fact]
+    public async Task Test_AsAgent_ToolApprovalRoundtrip_ResponseIsProcessedAsync()
+    {
+        // Arrange: Create an agent that emits a ToolApprovalRequestContent request
+        const string RequestId = "roundtrip-request-id";
+        McpServerToolCallContent mcpCall = new("mcp-call-id", "testMcpTool", "http://localhost");
+        ToolApprovalRequestContent requestContent = new(RequestId, mcpCall);
+        RequestEmittingAgent requestAgent = new(requestContent, completeOnResponse: true);
+        ExecutorBinding agentBinding = requestAgent.BindAsExecutor(
+            new AIAgentHostOptions { InterceptUserInputRequests = false, EmitAgentUpdateEvents = true });
+        Workflow workflow = new WorkflowBuilder(agentBinding).Build();
+        AIAgent agent = workflow.AsAIAgent("WorkflowAgent");
+
+        // Act 1: First call - should receive the ToolApprovalRequestContent request
+        AgentSession session = await agent.CreateSessionAsync();
+        List<AgentResponseUpdate> firstCallUpdates = await agent.RunStreamingAsync(
+            new ChatMessage(ChatRole.User, "Start"),
+            session).ToListAsync();
+
+        // Assert 1: We should have received a ToolApprovalRequestContent
+        AgentResponseUpdate? updateWithRequest = firstCallUpdates.FirstOrDefault(u =>
+            u.RawRepresentation is RequestInfoEvent && u.Contents.Any(c => c is ToolApprovalRequestContent));
+        updateWithRequest.Should().NotBeNull("a ToolApprovalRequestContent should be present in the response updates");
+
+        ToolApprovalRequestContent receivedRequest = updateWithRequest!.Contents
+            .OfType<ToolApprovalRequestContent>()
+            .First();
+        receivedRequest.RequestId.Should().EndWith($":{RequestId}");
+
+        // Act 2: Send the response back - use CreateResponse to get the right response type
+        ToolApprovalResponseContent responseContent = receivedRequest.CreateResponse(approved: true);
+        ChatMessage responseMessage = new(ChatRole.User, [responseContent]);
+
+        // Act 2: Run the workflow again with the response and capture the updates
+        List<AgentResponseUpdate> secondCallUpdates = await agent.RunStreamingAsync(responseMessage, session).ToListAsync();
+
+        // Assert 2: The response should be applied so that the original request is no longer pending
+        secondCallUpdates.Should().NotBeEmpty("handling the user input response should produce follow-up updates");
+        bool requestStillPresent = secondCallUpdates.Any(u =>
+            u.RawRepresentation is RequestInfoEvent
+            && u.Contents.OfType<ToolApprovalRequestContent>().Any(r => r.RequestId == receivedRequest.RequestId));
+        requestStillPresent.Should().BeFalse("the original ToolApprovalRequestContent should not be re-emitted after its response is processed");
+    }
+
+    /// <summary>
+    /// Tests the mixed-message scenario: resume contains both an external response
+    /// (FunctionResultContent matching a pending request) and regular non-response content
+    /// in the same message.
+    /// Verifies that regular content is still processed and that no duplicate
+    /// pending-request errors, redundant FunctionCallContent re-emissions,
+    /// or workflow errors occur.
+    /// </summary>
+    [Fact]
+    public async Task Test_AsAgent_MixedResponseAndRegularMessage_BothProcessedAsync()
+    {
+        // Arrange: Create an agent that emits a FunctionCallContent request
+        const string CallId = "mixed-call-id";
+        const string FunctionName = "mixedTestFunction";
+        FunctionCallContent requestContent = new(CallId, FunctionName);
+        RequestEmittingAgent requestAgent = new(requestContent, completeOnResponse: true);
+        ExecutorBinding agentBinding = requestAgent.BindAsExecutor(
+            new AIAgentHostOptions { InterceptUnterminatedFunctionCalls = false, EmitAgentUpdateEvents = true });
+        Workflow workflow = new WorkflowBuilder(agentBinding).Build();
+        AIAgent agent = workflow.AsAIAgent("WorkflowAgent");
+
+        // Act 1: First call - should receive the FunctionCallContent request
+        AgentSession session = await agent.CreateSessionAsync();
+        List<AgentResponseUpdate> firstCallUpdates = await agent.RunStreamingAsync(
+            new ChatMessage(ChatRole.User, "Start"),
+            session).ToListAsync();
+
+        // Assert 1: We should have received a FunctionCallContent
+        AgentResponseUpdate requestUpdate = firstCallUpdates.First(u =>
+            u.RawRepresentation is RequestInfoEvent && u.Contents.Any(c => c is FunctionCallContent));
+        FunctionCallContent emittedRequest = requestUpdate.Contents.OfType<FunctionCallContent>().Single();
+
+        firstCallUpdates.Should().Contain(u => u.Contents.Any(c => c is FunctionCallContent),
+            "the first call should emit a FunctionCallContent request");
+
+        // Act 2: Send a mixed message containing both the function result AND regular non-response content
+        FunctionResultContent responseContent = new(emittedRequest.CallId, "tool output");
+        ChatMessage mixedMessage = new(ChatRole.Tool, [responseContent, new TextContent("additional context")]);
+
+        List<AgentResponseUpdate> secondCallUpdates = await agent.RunStreamingAsync(mixedMessage, session).ToListAsync();
+
+        // Assert 2: The workflow should have processed both parts without errors
+        secondCallUpdates.Should().NotBeEmpty("the mixed message should produce follow-up updates");
+        secondCallUpdates
+            .Where(u => u.RawRepresentation is RequestInfoEvent)
+            .SelectMany(u => u.Contents.OfType<FunctionCallContent>())
+            .Should()
+            .NotContain(c => c.CallId == emittedRequest.CallId, "the external FunctionCallContent should be cleared after the response is processed");
+        secondCallUpdates
+            .SelectMany(u => u.Contents.OfType<ErrorContent>())
+            .Should()
+            .BeEmpty("no workflow errors should occur when processing a mixed response-and-regular message");
+    }
+
+    [Fact]
+    public async Task Test_AsAgent_ResponseThenRegularAcrossMessages_NoDuplicateFunctionCallAsync()
+    {
+        const string CallId = "mixed-separate-call-id";
+        const string FunctionName = "mixedSeparateTestFunction";
+
+        RequestEmittingAgent requestAgent = new(new FunctionCallContent(CallId, FunctionName), completeOnResponse: true);
+        ExecutorBinding agentBinding = requestAgent.BindAsExecutor(
+            new AIAgentHostOptions { InterceptUnterminatedFunctionCalls = false, EmitAgentUpdateEvents = true });
+        Workflow workflow = new WorkflowBuilder(agentBinding).Build();
+        AIAgent agent = workflow.AsAIAgent("WorkflowAgent");
+
+        AgentSession session = await agent.CreateSessionAsync();
+        List<AgentResponseUpdate> firstCallUpdates = await agent.RunStreamingAsync(new ChatMessage(ChatRole.User, "Start"), session).ToListAsync();
+        FunctionCallContent emittedRequest = firstCallUpdates
+            .Where(u => u.RawRepresentation is RequestInfoEvent)
+            .SelectMany(u => u.Contents.OfType<FunctionCallContent>())
+            .Single();
+
+        ChatMessage[] resumeMessages =
+        [
+            new(ChatRole.Tool, [new FunctionResultContent(emittedRequest.CallId, "tool output")]),
+            new(ChatRole.Tool, [new TextContent("extra context in separate message")])
+        ];
+
+        List<AgentResponseUpdate> secondCallUpdates = await agent.RunStreamingAsync(resumeMessages, session).ToListAsync();
+
+        secondCallUpdates.Should().NotBeEmpty();
+        secondCallUpdates
+            .Where(u => u.RawRepresentation is RequestInfoEvent)
+            .SelectMany(u => u.Contents.OfType<FunctionCallContent>())
+            .Should()
+            .NotContain(c => c.CallId == emittedRequest.CallId, "response+regular content split across messages should not re-emit the handled external request");
+        secondCallUpdates
+            .SelectMany(u => u.Contents.OfType<ErrorContent>())
+            .Should()
+            .BeEmpty();
+    }
+
+    [Fact]
+    public async Task Test_AsAgent_MatchingResponse_DoesNotCauseExtraTurnAsync()
+    {
+        const string CallId = "matching-response-call-id";
+        const string FunctionName = "matchingResponseFunction";
+
+        RequestEmittingAgent requestAgent = new(new FunctionCallContent(CallId, FunctionName), completeOnResponse: false);
+        ExecutorBinding agentBinding = requestAgent.BindAsExecutor(
+            new AIAgentHostOptions { InterceptUnterminatedFunctionCalls = false, EmitAgentUpdateEvents = true });
+        Workflow workflow = new WorkflowBuilder(agentBinding).Build();
+        AIAgent agent = workflow.AsAIAgent("WorkflowAgent");
+
+        AgentSession session = await agent.CreateSessionAsync();
+        List<AgentResponseUpdate> firstCallUpdates = await agent.RunStreamingAsync(new ChatMessage(ChatRole.User, "Start"), session).ToListAsync();
+        FunctionCallContent emittedRequest = firstCallUpdates
+            .Where(u => u.RawRepresentation is RequestInfoEvent)
+            .SelectMany(u => u.Contents.OfType<FunctionCallContent>())
+            .Single();
+
+        List<AgentResponseUpdate> secondCallUpdates = await agent.RunStreamingAsync(
+            new ChatMessage(ChatRole.Tool, [new FunctionResultContent(emittedRequest.CallId, "tool output")]),
+            session).ToListAsync();
+
+        int functionCallCount = secondCallUpdates
+            .Where(u => u.RawRepresentation is RequestInfoEvent)
+            .SelectMany(u => u.Contents.OfType<FunctionCallContent>())
+            .Count(c => c.CallId == emittedRequest.CallId);
+
+        functionCallCount.Should().Be(1, "a matching external response should not trigger an extra TurnToken-driven turn");
+    }
+
+    [Fact]
+    public async Task Test_AsAgent_MixedResponseAndRegularMessage_CrossExecutorStartExecutorIsReawakenedAsync()
+    {
+        const string StartExecutorId = "start-executor";
+        const string KickoffInputText = "Start";
+        const string KickoffMessageText = "kickoff downstream";
+        const string ResumeRegularText = "resume regular";
+        const string ResumeProcessedText = "regular message processed";
+        const string CallId = "cross-executor-call-id";
+        const string FunctionName = "crossExecutorFunction";
+
+        RequestEmittingAgent requestAgent = new(new FunctionCallContent(CallId, FunctionName), completeOnResponse: true);
+        ExecutorBinding requestBinding = requestAgent.BindAsExecutor(
+            new AIAgentHostOptions { InterceptUnterminatedFunctionCalls = false, EmitAgentUpdateEvents = true });
+
+        KickoffOnStartExecutor startExecutor = new(
+            StartExecutorId,
+            requestBinding.Id,
+            KickoffInputText,
+            KickoffMessageText,
+            ResumeRegularText,
+            ResumeProcessedText);
+        ExecutorBinding startBinding = startExecutor.BindExecutor();
+
+        Workflow workflow = new WorkflowBuilder(startBinding)
+            .AddEdge<List<ChatMessage>>(startBinding, requestBinding, messages =>
+                messages?.Any(message => message.Contents.OfType<TextContent>().Any(content => content.Text == KickoffMessageText)) == true)
+            .AddEdge<TurnToken>(startBinding, requestBinding, _ => true)
+            .Build();
+        AIAgent agent = workflow.AsAIAgent("WorkflowAgent");
+
+        AgentSession session = await agent.CreateSessionAsync();
+        List<AgentResponseUpdate> firstCallUpdates = await agent.RunStreamingAsync(
+            new ChatMessage(ChatRole.User, KickoffInputText),
+            session).ToListAsync();
+        FunctionCallContent emittedRequest = firstCallUpdates
+            .Where(u => u.RawRepresentation is RequestInfoEvent)
+            .SelectMany(u => u.Contents.OfType<FunctionCallContent>())
+            .Single();
+
+        ChatMessage[] resumeMessages =
+        [
+            new(ChatRole.Tool, [new FunctionResultContent(emittedRequest.CallId, "tool output")]),
+            new(ChatRole.User, ResumeRegularText)
+        ];
+
+        List<AgentResponseUpdate> secondCallUpdates = await agent.RunStreamingAsync(resumeMessages, session).ToListAsync();
+        List<string> textContents = [.. secondCallUpdates.SelectMany(update => update.Contents.OfType<TextContent>()).Select(content => content.Text)];
+
+        textContents.Should().Contain(ResumeProcessedText, "the start executor should receive an explicit TurnToken when the matched response wakes a different executor");
+        textContents.Should().Contain("Request processed", "the matched external response should still be delivered to the downstream request owner");
+        secondCallUpdates
+            .Where(u => u.RawRepresentation is RequestInfoEvent)
+            .SelectMany(u => u.Contents.OfType<FunctionCallContent>())
+            .Should()
+            .NotContain(c => c.CallId == emittedRequest.CallId, "the handled external request should not be re-emitted while waking the start executor");
+        secondCallUpdates.SelectMany(u => u.Contents.OfType<ErrorContent>()).Should().BeEmpty();
+    }
+
+    [Fact]
+    public async Task Test_AsAgent_UnmatchedResponse_TriggersTurnAndKeepsProgressingAsync()
+    {
+        const string CallId = "unmatched-response-call-id";
+        const string FunctionName = "unmatchedResponseFunction";
+
+        RequestEmittingAgent requestAgent = new(new FunctionCallContent(CallId, FunctionName), completeOnResponse: false);
+        ExecutorBinding agentBinding = requestAgent.BindAsExecutor(
+            new AIAgentHostOptions { InterceptUnterminatedFunctionCalls = false, EmitAgentUpdateEvents = true });
+        Workflow workflow = new WorkflowBuilder(agentBinding).Build();
+        AIAgent agent = workflow.AsAIAgent("WorkflowAgent");
+
+        AgentSession session = await agent.CreateSessionAsync();
+        List<AgentResponseUpdate> firstCallUpdates = await agent.RunStreamingAsync(new ChatMessage(ChatRole.User, "Start"), session).ToListAsync();
+        firstCallUpdates.Should().Contain(u => u.Contents.Any(c => c is FunctionCallContent));
+
+        List<AgentResponseUpdate> secondCallUpdates = await agent.RunStreamingAsync(
+            new ChatMessage(ChatRole.Tool, [new FunctionResultContent("different-call-id", "tool output")]),
+            session).ToListAsync();
+
+        int functionCallCount = secondCallUpdates
+            .SelectMany(u => u.Contents.OfType<FunctionCallContent>())
+            .Count(c => c.CallId == CallId);
+
+        functionCallCount.Should().Be(1, "an unmatched response should be treated as regular input and still drive a TurnToken continuation without workflow errors");
+        secondCallUpdates.SelectMany(u => u.Contents.OfType<ErrorContent>()).Should().BeEmpty();
+    }
+
+    /// <summary>
+    /// Tests that when a resume contains only an external response directed at a non-start executor
+    /// (no regular messages), the start executor still receives a TurnToken and is activated.
+    /// This is a regression test for the case where the TurnToken was previously skipped because
+    /// <c>HasRegularMessages</c> was <see langword="false"/>, leaving the start executor dormant.
+    /// </summary>
+    [Fact]
+    public async Task Test_AsAgent_ResponseOnlyToNonStartExecutor_StartExecutorIsStillActivatedAsync()
+    {
+        // Arrange
+        const string StartExecutorId = "start-executor";
+        const string ActivatedMarker = "start-executor-activated";
+        const string CallId = "response-only-call-id";
+        const string FunctionName = "responseOnlyFunction";
+
+        RequestEmittingAgent requestAgent = new(new FunctionCallContent(CallId, FunctionName), completeOnResponse: true);
+        ExecutorBinding requestBinding = requestAgent.BindAsExecutor(
+            new AIAgentHostOptions { InterceptUnterminatedFunctionCalls = false, EmitAgentUpdateEvents = true });
+
+        TurnTrackingStartExecutor startExecutor = new(StartExecutorId, requestBinding.Id, ActivatedMarker);
+        ExecutorBinding startBinding = startExecutor.BindExecutor();
+
+        Workflow workflow = new WorkflowBuilder(startBinding)
+            .AddEdge<List<ChatMessage>>(startBinding, requestBinding, messages =>
+                messages?.Any(m => m.Contents.OfType<TextContent>().Any()) == true)
+            .AddEdge<TurnToken>(startBinding, requestBinding, _ => true)
+            .Build();
+        AIAgent agent = workflow.AsAIAgent("WorkflowAgent");
+
+        // Act 1: First call triggers the downstream FunctionCallContent request
+        AgentSession session = await agent.CreateSessionAsync();
+        List<AgentResponseUpdate> firstCallUpdates = await agent.RunStreamingAsync(
+            new ChatMessage(ChatRole.User, "Start"),
+            session).ToListAsync();
+
+        FunctionCallContent emittedRequest = firstCallUpdates
+            .Where(u => u.RawRepresentation is RequestInfoEvent)
+            .SelectMany(u => u.Contents.OfType<FunctionCallContent>())
+            .Single();
+
+        // Act 2: Resume with ONLY the external response (no regular messages)
+        List<AgentResponseUpdate> secondCallUpdates = await agent.RunStreamingAsync(
+            new ChatMessage(ChatRole.Tool, [new FunctionResultContent(emittedRequest.CallId, "tool output")]),
+            session).ToListAsync();
+
+        // Assert: Both the downstream and start executor should have been activated
+        List<string> textContents = [.. secondCallUpdates
+            .SelectMany(u => u.Contents.OfType<TextContent>())
+            .Select(c => c.Text)];
+
+        textContents.Should().Contain("Request processed",
+            "the downstream executor should process the external response");
+        textContents.Should().Contain(ActivatedMarker,
+            "the start executor should receive a TurnToken and be activated even when resume contains only an external response");
+        secondCallUpdates
+            .SelectMany(u => u.Contents.OfType<ErrorContent>())
+            .Should()
+            .BeEmpty();
+    }
 }