.NET: Allow Simulating service stored ChatHistory to improve consistency (#4974)

* Allow Simulating service stored ChatHistory to improve consistency

* Fixing bug in ServiceStoredSimulatingChatClient

* Addressing PR comments.

* Address PR comments

* Apply suggestion from @SergeyMenshykh

Co-authored-by: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com>

* Fix bug

---------

Co-authored-by: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com>

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

@@ -1,15 +1,16 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 // This sample demonstrates how the ChatClientAgent persists chat history after each individual
-// call to the AI service.
+// call to the AI service, using the SimulateServiceStoredChatHistory option.
 // 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.
+// To use end-of-run persistence instead (atomic run semantics), remove the
+// SimulateServiceStoredChatHistory = true setting (or set it to false). End-of-run
+// persistence is the default behavior.
 //
 // The sample runs two multi-turn conversations: one using non-streaming (RunAsync) and one
 // using streaming (RunStreamingAsync), to demonstrate correct behavior in both modes.
@@ -53,7 +54,7 @@ static string GetTime([Description("The city name.")] string city) =>
         _ => $"{city}: time data not available."
     };
 
-// Create the agent — per-service-call persistence is the default behavior.
+// Create the agent — per-service-call persistence is enabled via SimulateServiceStoredChatHistory.
 // 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) ?
@@ -63,6 +64,7 @@ AIAgent agent = chatClient.AsAIAgent(
     new ChatClientAgentOptions
     {
         Name = "WeatherAssistant",
+        SimulateServiceStoredChatHistory = true,
         ChatOptions = new()
         {
             Instructions = "You are a helpful assistant. When asked about multiple cities, call the appropriate tool for each city.",

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

@@ -1,16 +1,19 @@
 # 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.
+This sample demonstrates how `ChatClientAgent` can persist chat history after each individual call to the AI service using the `SimulateServiceStoredChatHistory` option. 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:
+When an agent uses tools, the `FunctionInvokingChatClient` loops multiple times (service call → tool execution → service call → …). By enabling `SimulateServiceStoredChatHistory = true`, chat history is persisted after each service call via the `ServiceStoredSimulatingChatClient` decorator:
 
-- A `ChatHistoryPersistingChatClient` decorator is automatically inserted into the chat client pipeline
+- A `ServiceStoredSimulatingChatClient` decorator is inserted into the chat client pipeline
+- Before each service call, the decorator loads history from the `ChatHistoryProvider` and prepends it to the request
 - 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.
+By default (without `SimulateServiceStoredChatHistory`), chat history is persisted at the end of the full agent run instead. To use per-service-call persistence, set `SimulateServiceStoredChatHistory = true` on `ChatClientAgentOptions`.
+
+With `SimulateServiceStoredChatHistory` = true, the behavior matches that of chat history stored in the underlying AI service exactly.
 
 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
@@ -26,7 +29,7 @@ The sample asks the agent about the weather and time in three cities. The model
 ```
 ChatClientAgent
   └─ FunctionInvokingChatClient    (handles tool call loop)
-       └─ ChatHistoryPersistingChatClient  (persists after each service call)
+       └─ ServiceStoredSimulatingChatClient  (persists after each service call)
             └─ Leaf IChatClient            (Azure OpenAI)
 ```