Merge branch 'main' into test-it-bump-aaip210b2

dotnet/agent-framework-dotnet.slnx

@@ -122,7 +122,7 @@
     <File Path="samples/02-agents/Harness/README.md" />
     <Project Path="samples/02-agents/Harness/Harness_Shared_Console/Harness_Shared_Console.csproj" />
     <Project Path="samples/02-agents/Harness/Harness_Step01_Research/Harness_Step01_Research.csproj" />
-    <Project Path="samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/Harness_Step02_Research_WithSubAgents.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step02_Research_WithBackgroundAgents/Harness_Step02_Research_WithBackgroundAgents.csproj" />
     <Project Path="samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj" />
     <Project Path="samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveFramework.csproj" />
     <Project Path="samples/02-agents/Harness/ConsoleReactiveComponents/ConsoleReactiveComponents.csproj" />

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ToolCallDisplayObserver.cs

@@ -31,6 +31,10 @@ public sealed class ToolCallDisplayObserver : ConsoleObserver
         {
             await ux.WriteInfoLineAsync($"🔧 Calling tool: {ToolCallFormatter.Format(this._formatters, functionCall)}...", ConsoleColor.DarkYellow);
         }
+        else if (content is WebSearchToolCallContent)
+        {
+            // Handled by OpenAIResponsesWebSearchDisplayObserver when present; skip here to avoid duplication.
+        }
         else if (content is ToolCallContent toolCall)
         {
             await ux.WriteInfoLineAsync($"🔧 Calling tool: {toolCall}...", ConsoleColor.DarkYellow);

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/BackgroundAgentToolFormatter.cs

@@ -6,26 +6,26 @@ using Microsoft.Extensions.AI;
 namespace Harness.Shared.Console.ToolFormatters;
 
 /// <summary>
-/// Formats <c>SubAgents_*</c> tool calls with human-readable details
+/// Formats <c>BackgroundAgents_*</c> tool calls with human-readable details
 /// for task start, continue, wait, and result retrieval operations.
 /// </summary>
-public sealed class SubAgentToolFormatter : ToolCallFormatter
+public sealed class BackgroundAgentToolFormatter : ToolCallFormatter
 {
     /// <inheritdoc/>
-    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("SubAgents_", StringComparison.Ordinal);
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("BackgroundAgents_", StringComparison.Ordinal);
 
     /// <inheritdoc/>
     public override string? FormatDetail(FunctionCallContent call) => call.Name switch
     {
-        "SubAgents_StartTask" => FormatStartSubTask(call),
-        "SubAgents_WaitForFirstCompletion" => FormatIdList(call, "taskIds", "Wait for"),
-        "SubAgents_GetTaskResults" => FormatSingleId(call, "taskId"),
-        "SubAgents_ContinueTask" => FormatContinueTask(call),
-        "SubAgents_ClearCompletedTask" => FormatSingleId(call, "taskId"),
+        "BackgroundAgents_StartTask" => FormatStartBackgroundTask(call),
+        "BackgroundAgents_WaitForFirstCompletion" => FormatIdList(call, "taskIds", "Wait for"),
+        "BackgroundAgents_GetTaskResults" => FormatSingleId(call, "taskId"),
+        "BackgroundAgents_ContinueTask" => FormatContinueTask(call),
+        "BackgroundAgents_ClearCompletedTask" => FormatSingleId(call, "taskId"),
         _ => null,
     };
 
-    private static string? FormatStartSubTask(FunctionCallContent call)
+    private static string? FormatStartBackgroundTask(FunctionCallContent call)
     {
         string? agentName = GetStringArgumentValue(call, "agentName");
         string? description = GetStringArgumentValue(call, "description");

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/TodoToolFormatter.cs

@@ -19,7 +19,7 @@ public sealed class TodoToolFormatter : ToolCallFormatter
     public override string? FormatDetail(FunctionCallContent call) => call.Name switch
     {
         "TodoList_Add" => FormatAddTodos(call),
-        "TodoList_Complete" => FormatIdList(call, "ids", "Complete"),
+        "TodoList_Complete" => FormatCompleteTodos(call),
         "TodoList_Remove" => FormatIdList(call, "ids", "Remove"),
         _ => null,
     };
@@ -64,6 +64,50 @@ public sealed class TodoToolFormatter : ToolCallFormatter
         return sb.ToString();
     }
 
+    private static string? FormatCompleteTodos(FunctionCallContent call)
+    {
+        if (call.Arguments?.TryGetValue("items", out object? itemsObj) != true || itemsObj is null)
+        {
+            return null;
+        }
+
+        var entries = new List<(int Id, string? Reason)>();
+
+        if (itemsObj is JsonElement jsonArray && jsonArray.ValueKind == JsonValueKind.Array)
+        {
+            foreach (JsonElement item in jsonArray.EnumerateArray())
+            {
+                if (!item.TryGetProperty("id", out JsonElement idElement) || !idElement.TryGetInt32(out int id))
+                {
+                    continue;
+                }
+
+                string? reason = item.TryGetProperty("reason", out JsonElement reasonElement)
+                    ? reasonElement.GetString()
+                    : null;
+                entries.Add((id, reason));
+            }
+        }
+
+        if (entries.Count == 0)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder();
+        for (int i = 0; i < entries.Count; i++)
+        {
+            string connector = i < entries.Count - 1 ? "├─" : "└─";
+            sb.Append($"\n   {connector} Complete #{entries[i].Id}");
+            if (!string.IsNullOrEmpty(entries[i].Reason))
+            {
+                sb.Append($" — {Truncate(entries[i].Reason!, 80)}");
+            }
+        }
+
+        return sb.ToString();
+    }
+
     private static string? FormatIdList(FunctionCallContent call, string paramName, string verb)
     {
         List<int>? ids = GetIntListArgumentValue(call, paramName);

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/ToolCallFormatter.cs

@@ -56,7 +56,7 @@ public abstract class ToolCallFormatter
         [
             new TodoToolFormatter(),
             new ModeToolFormatter(),
-            new SubAgentToolFormatter(),
+            new BackgroundAgentToolFormatter(),
             new FileMemoryToolFormatter(),
             new WebSearchToolFormatter(),
             new FallbackToolFormatter(),

dotnet/samples/02-agents/Harness/Harness_Step01_Research/OpenAIResponsesWebSearchDisplayObserver.cs

@@ -0,0 +1,206 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+
+using System.Text;
+using Harness.Shared.Console;
+using Harness.Shared.Console.Observers;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI.Responses;
+
+namespace SampleApp;
+
+/// <summary>
+/// Displays web search activity in the scroll area. Shows search queries,
+/// page opens, and find-in-page actions as they stream in from the API.
+/// </summary>
+internal sealed class OpenAIResponsesWebSearchDisplayObserver : ConsoleObserver
+{
+    private const int MaxQueryDisplayLength = 120;
+
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
+    {
+        if (content is WebSearchToolResultContent resultContent
+            && resultContent.RawRepresentation is WebSearchCallResponseItem wscri)
+        {
+            await WriteActionAsync(ux, wscri, resultContent.Outputs);
+        }
+    }
+
+    private static async Task WriteActionAsync(IUXStateDriver ux, WebSearchCallResponseItem wscri, IList<AIContent>? outputs)
+    {
+        WebSearchAction? action = wscri.Action;
+        if (action is null)
+        {
+            await ux.WriteInfoLineAsync("🌐 Web Search Tool (no action details)", ConsoleColor.DarkCyan);
+            return;
+        }
+
+        switch (action)
+        {
+            case WebSearchFindInPageAction findInPage:
+                await WriteFindInPageAsync(ux, findInPage);
+                break;
+
+            case WebSearchOpenPageAction openPage:
+                await WriteOpenPageAsync(ux, openPage);
+                break;
+
+            case WebSearchSearchAction search:
+                await WriteSearchAsync(ux, search, outputs);
+                break;
+
+            default:
+                await ux.WriteInfoLineAsync("🌐 Web Search Tool (unknown action)", ConsoleColor.DarkCyan);
+                break;
+        }
+    }
+
+    private static async Task WriteSearchAsync(IUXStateDriver ux, WebSearchSearchAction search, IList<AIContent>? outputs)
+    {
+        // Read queries directly from the typed action.
+        IList<string> queries = search.Queries;
+
+        if (queries.Count == 0)
+        {
+            await ux.WriteInfoLineAsync("🌐 Web Search Tool: search", ConsoleColor.DarkCyan);
+            return;
+        }
+
+        var sb = new StringBuilder();
+        sb.Append("🌐 Web Search Tool: search");
+
+        // Show the search queries.
+        bool hasResults = outputs is { Count: > 0 };
+        for (int i = 0; i < queries.Count; i++)
+        {
+            string connector = (i < queries.Count - 1 || hasResults) ? "├─" : "└─";
+            string query = Truncate(queries[i], MaxQueryDisplayLength);
+            sb.Append($"\n   {connector} \"{query}\"");
+        }
+
+        // Show search result sources (URLs + titles) when available.
+        // Sources come from M.E.AI's Outputs when IncludedResponseProperty.WebSearchCallActionSources is set,
+        // or directly from the SDK's WebSearchSearchAction.Sources.
+        if (hasResults)
+        {
+            sb.Append("\n   │");
+            for (int i = 0; i < outputs!.Count; i++)
+            {
+                string connector = i < outputs.Count - 1 ? "├─" : "└─";
+                string line = FormatOutput(outputs[i]);
+                sb.Append($"\n   {connector} {line}");
+            }
+        }
+        else if (search.Sources is { Count: > 0 } sources)
+        {
+            sb.Append("\n   │");
+            for (int i = 0; i < sources.Count; i++)
+            {
+                string connector = i < sources.Count - 1 ? "├─" : "└─";
+                string line = FormatSource(sources[i]);
+                sb.Append($"\n   {connector} {line}");
+            }
+        }
+
+        await ux.WriteInfoLineAsync(sb.ToString(), ConsoleColor.DarkCyan);
+    }
+
+    private static async Task WriteOpenPageAsync(IUXStateDriver ux, WebSearchOpenPageAction openPage)
+    {
+        string url = openPage.Uri?.AbsoluteUri ?? "(unknown)";
+        await ux.WriteInfoLineAsync(
+            $"🌐 Web Search Tool: open page\n   └─ {url}",
+            ConsoleColor.DarkCyan);
+    }
+
+    private static async Task WriteFindInPageAsync(IUXStateDriver ux, WebSearchFindInPageAction findInPage)
+    {
+        string url = findInPage.Uri?.AbsoluteUri ?? "(unknown)";
+        string pattern = findInPage.Pattern ?? "(unknown)";
+
+        await ux.WriteInfoLineAsync(
+            $"🌐 Web Search Tool: find in page\n   ├─ \"{Truncate(pattern, MaxQueryDisplayLength)}\"\n   └─ {url}",
+            ConsoleColor.DarkCyan);
+    }
+
+    /// <summary>
+    /// Formats a single search result source from the SDK's <see cref="WebSearchActionSource"/> for display.
+    /// </summary>
+    private static string FormatSource(WebSearchActionSource source)
+    {
+        if (source is WebSearchActionUriSource uriSource)
+        {
+            string url = uriSource.Uri?.AbsoluteUri ?? "(unknown)";
+
+            // WebSearchActionUriSource doesn't expose a title property,
+            // but the API may include one in the raw response JSON.
+            string? title = GetTitleFromRawRepresentation(uriSource);
+
+            return title is not null
+                ? $"{Truncate(title, MaxQueryDisplayLength)} — {url}"
+                : url;
+        }
+
+        return source.ToString() ?? "(unknown source)";
+    }
+
+    /// <summary>
+    /// Formats a single search result output from M.E.AI's <see cref="AIContent"/> for display.
+    /// </summary>
+    private static string FormatOutput(AIContent output)
+    {
+        if (output is UriContent uriContent)
+        {
+            string url = uriContent.Uri?.AbsoluteUri ?? "(unknown)";
+
+            // Try to extract a title from the raw JSON of the source.
+            // The SDK's WebSearchActionUriSource doesn't expose a title property,
+            // but the API may include one in the raw response.
+            string? title = GetTitleFromRawRepresentation(uriContent.RawRepresentation)
+                ?? (uriContent.AdditionalProperties?.TryGetValue("title", out var t) is true ? t?.ToString() : null);
+
+            return title is not null
+                ? $"{Truncate(title, MaxQueryDisplayLength)} — {url}"
+                : url;
+        }
+
+        return output.ToString() ?? "(unknown output)";
+    }
+
+    /// <summary>
+    /// Attempts to extract a "title" field from a raw representation object by serializing it to JSON.
+    /// The SDK's <see cref="WebSearchActionUriSource"/> doesn't expose a title property,
+    /// but the API may include one in the raw JSON — this is forward-compatible for when
+    /// the SDK adds title support.
+    /// </summary>
+    private static string? GetTitleFromRawRepresentation(object? rawRepresentation)
+    {
+        if (rawRepresentation is null)
+        {
+            return null;
+        }
+
+        try
+        {
+            var data = System.ClientModel.Primitives.ModelReaderWriter.Write(rawRepresentation);
+            using var doc = System.Text.Json.JsonDocument.Parse(data);
+            if (doc.RootElement.TryGetProperty("title", out var titleEl)
+                && titleEl.ValueKind == System.Text.Json.JsonValueKind.String)
+            {
+                return titleEl.GetString();
+            }
+        }
+        catch
+        {
+            // Serialization may not be supported for this object type.
+        }
+
+        return null;
+    }
+
+    private static string Truncate(string text, int maxLength)
+        => text.Length <= maxLength ? text : string.Concat(text.AsSpan(0, maxLength - 1), "…");
+}

dotnet/samples/02-agents/Harness/Harness_Step01_Research/Program.cs

@@ -1,8 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample demonstrates how to use a HarnessAgent with the Harness AIContextProviders
-// (TodoProvider and AgentModeProvider) for interactive research tasks with web search
-// capabilities powered by Azure AI Foundry.
+// This sample demonstrates how to use a HarnessAgent for interactive research tasks.
+// The HarnessAgent comes pre-configured with TodoProvider, AgentModeProvider, FileMemoryProvider,
+// ToolApproval, WebSearch, and OpenTelemetry — so this sample only needs custom instructions
+// and a WebBrowsingTool.
 // The agent plans research tasks, creates a todo list, gets user approval,
 // and then executes each step — all within an interactive conversation loop.
 //
@@ -34,86 +35,32 @@ const int MaxOutputTokens = 128_000;
 // and research-focused instructions including the mandatory planning workflow.
 var instructions =
     """
+    ## Research Assistant Instructions
+
     You are a research assistant. When given a research topic, research it thoroughly using web search and web browsing.
     Use your knowledge to form good search queries and hypotheses, but always verify claims with the tools available to you rather than relying on memory alone.
 
-    ## Mandatory planning workflow
-
-    For every new substantive user request, including short factual questions, your behavior is determined by the mode you are in.
-    If you are in plan mode, start with the *Plan Mode* steps, and if you are in execute mode, skip directly to the *Execute Mode* steps below.
-
-    *Plan Mode*
-
-    1. Analyze the request with the purpose of building a research plan.
-    2. Create a list of todo items.
-    3. If needed, use the provided tools to do some exploratory checks to help build a plan and determine what clarifying questions you may need from the user.
-    4. Ask for clarifications from the user where needed.
-      1. Ask each clarification one by one.
-      2. When asking for clarification and you have specific options in mind, present them to the user, so they can choose the option instead of having to retype the entire response.
-      3. Do not proceed until you have received all the needed clarifications.
-      4. Do short exploratory research if it helps with being able to ask sensible clarifications from the user.
-    5. Write the plan to a memory file, so that it is retained even if compaction happens. Make sure to update the plan file if the user requests changes.
-    6. Present the plan to the user and ask for approval to switch to execute mode and process the plan.
-    7. When approval is granted, always switch to execute mode (using the `AgentMode_Set` tool), and follow the steps for *Execute mode*.
-
-    *Execute Mode*
-
-    1. If you don't have a plan or tasks yet, analyse the user request and create tasks and a plan. (**Skip this step if you came from plan mode**)
-    2. Work autonomously — use your best judgement to make decisions and keep progressing without asking the user questions. The goal is to have a complete, useful result ready when the user returns.
-    3. If you encounter ambiguity or an unexpected situation during execution, choose the most reasonable option, note your choice, and keep going.
-    4. Mark tasks as completed as you finish them.
-    5. Continue working, thinking and calling tools until you have the research result for the user.
-
-    ## General Instructions
-
-    - You must check the current mode after any user input, since the user may have changed the mode themselves,
-      e.g. the user may have switched to 'plan' mode after a previous research task finished in 'execute' mode, meaning they want to review a plan first before execution.
-    - Explain your reasoning and thought process as you work through tasks.
-    - Explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.
-    - Avoid making more than 4 tool calls in a row without explaining what you are doing.
-    - Do not answer the underlying question before the plan has been presented and approved.
-    - This rule applies even when the answer seems obvious or the task seems small.
-    - For short requests, use a brief micro-plan rather than skipping planning. The only exceptions are:
-      - greetings,
-      - pure acknowledgments,
-      - clarification questions needed to form the plan,
-      - follow-up questions about results you have already presented,
-      - meta-discussion about the workflow itself.
-
-    **Todo management**
-
-    Mark each todo complete as you finish it so the list stays current.
-    If a todo turns out to be unnecessary or is blocked, remove it and briefly explain why.
-    Once the user finishes with a topic and moves onto a new one, clean up old completed todos by deleting them.
-
-    **Research quality**
+    ### Research quality
 
     Consult multiple sources when possible and cross-reference key claims.
     When sources disagree, note the discrepancy and explain which source you consider more reliable and why.
     If a web page fails to load or a search returns irrelevant results, try alternative search queries or sources before moving on.
     Track your sources — you will need them when presenting results.
 
-    **Presenting results**
+    ### Presenting results
 
     When presenting your final findings:
+    - Use Markdown formatting for clarity.
     - Use clear sections with headings for each major topic or sub-question.
     - Cite your sources inline (e.g., "According to [source name](URL), ...").
     - End with a brief summary of key takeaways.
-    - Save the final research report to file memory so it survives compaction and can be referenced later.
-
-    **File memory**
-
-    Use the FileMemory_* tools to:
-    - Store downloaded search results or web pages.
-    - Store plans.
-    - Read the current plan to make sure tasks were done according to plan.
-    - Store findings.
-    - Check for relevant previously downloaded data / findings before starting new research.
+    - In addition to returning the results to the user, save the final research report to file memory so it survives compaction and can be referenced later.
     """;
 
 // Create the agent using AsHarnessAgent, which pre-configures function invocation,
-// per-service-call chat history persistence, and in-loop compaction.
-// Then wrap with UseToolApproval to allow auto-approving tools once confirmed.
+// per-service-call chat history persistence, in-loop compaction, TodoProvider, AgentModeProvider,
+// FileMemoryProvider, ToolApproval, WebSearch, AgentSkillsProvider, and OpenTelemetry.
+// Only custom instructions, a WebBrowsingTool, and FileAccess opt-out are needed.
 AIAgent agent =
     // Create an OpenAIClient that communicates with the Foundry responses service.
     new OpenAIClient(
@@ -127,35 +74,26 @@ AIAgent agent =
             RetryPolicy = new ClientRetryPolicy(3)          // Enable retries to improve resiliency.
         })
     .GetResponsesClient()
-    .AsIChatClientWithStoredOutputDisabled(deploymentName)   // We want to manage chat history locally (not stored in the responses service), so that we can manage compaction ourselves.
+    .AsIChatClientWithStoredOutputDisabled(deploymentName)  // We want to manage chat history locally (not stored in the responses service), so that we can manage compaction ourselves.
     .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
     {
         Name = "ResearchAgent",
         Description = "A research assistant that plans and executes research tasks.",
-        AIContextProviders =
-        [
-            new TodoProvider(),         // Add an AIContextProvider to allow the agent to create a TODO list, which is stored in the session.
-            new AgentModeProvider(),    // Add an AIContextProvider that tracks the agent mode and allows switching mode. Current mode is stored in the session.
-            new FileMemoryProvider(     // Add an AIContextProvider that can store memories in files under a session specific working folder.
-                new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "agent-files")),
-                (_) => new FileMemoryState() { WorkingFolder = DateTime.UtcNow.ToString("yyyyMMdd_HHmmss") + "_" + Guid.NewGuid().ToString() })
-        ],
+        DisableFileMemory = true,                           // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        FileMemoryStore = new FileSystemAgentFileStore(     // Configure the file memory provider to store files in a local folder called "agent-files".
+            Path.Combine(AppContext.BaseDirectory, "agent-files")),
         ChatOptions = new ChatOptions
         {
             Instructions = instructions,
             Tools =
             [
-                ResponseTool.CreateWebSearchTool().AsAITool(),          // Add the foundry hosted web search tool that runs in the service.
-                new WebBrowsingTool(                                    // Add a local web browsing tool that converts html to markdown.
+                new WebBrowsingTool(                        // Add a local web browsing tool that converts html to markdown.
                     new WebBrowsingToolOptions { AllowPublicNetworks = true }),
             ],
-            MaxOutputTokens = MaxOutputTokens,                          // Set a high token limit for long research tasks with many tool calls and long outputs.
+            MaxOutputTokens = MaxOutputTokens,              // Set a high token limit for long research tasks with many tool calls and long outputs.
             Reasoning = new() { Effort = ReasoningEffort.Medium },
         },
-    })
-    .AsBuilder()
-    .UseToolApproval()                                                      // Add the ability to auto approve tools once a user has said they don't want to be asked again. Approval rules are tied to the session.
-    .Build();
+    });
 
 // Run the interactive console session using the shared HarnessConsole helper.
 await HarnessConsole.RunAgentAsync(
@@ -163,12 +101,14 @@ await HarnessConsole.RunAgentAsync(
     userPrompt: "Enter a research topic to get started.",
     new HarnessConsoleOptions
     {
-        Observers = HarnessConsoleOptions.BuildObserversWithPlanning(
-            agent,
-            planModeName: "plan",
-            executionModeName: "execute",
-            maxContextWindowTokens: MaxContextWindowTokens,
-            maxOutputTokens: MaxOutputTokens,
-            toolFormatters: [new DownloadUriToolFormatter(), .. ToolCallFormatter.BuildDefaultToolFormatters()]),
+        Observers = [
+            new OpenAIResponsesWebSearchDisplayObserver(),
+            .. HarnessConsoleOptions.BuildObserversWithPlanning(
+                agent,
+                planModeName: "plan",
+                executionModeName: "execute",
+                maxContextWindowTokens: MaxContextWindowTokens,
+                maxOutputTokens: MaxOutputTokens,
+                toolFormatters: [new DownloadUriToolFormatter(), .. ToolCallFormatter.BuildDefaultToolFormatters()])],
         CommandHandlers = HarnessConsoleOptions.BuildDefaultCommandHandlers(agent),
     });

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithBackgroundAgents/Program.cs

@@ -1,9 +1,10 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample demonstrates how to use the SubAgentsProvider to delegate work to sub-agents.
+// This sample demonstrates how to use the BackgroundAgentsProvider to delegate work to background agents.
 // A parent agent is given a list of stock tickers and instructed to find the closing price
-// for each ticker on December 31, 2025. It delegates the web searches to a sub-agent
-// equipped with Foundry's hosted web search tool.
+// for each ticker on December 31, 2025. It delegates the web searches to a background agent.
+// The HarnessAgent provides built-in WebSearch (HostedWebSearchTool) so no manual web search
+// tool configuration is needed on the background agent.
 //
 // Special commands:
 //   /exit    — End the session.
@@ -25,8 +26,9 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYME
 const int MaxContextWindowTokens = 1_050_000;
 const int MaxOutputTokens = 128_000;
 
-// --- Sub-agent: Web Search Agent ---
-// This agent can search the web and is used by the parent agent to look up stock prices.
+// --- Background agent: Web Search Agent ---
+// This agent uses the HarnessAgent's built-in HostedWebSearchTool to search the web.
+// Features not needed by this sub-agent are disabled.
 AIAgent webSearchAgent =
     new OpenAIClient(
         new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
@@ -41,40 +43,44 @@ AIAgent webSearchAgent =
     {
         Name = "WebSearchAgent",
         Description = "An agent that can search the web to find information.",
+        DisableTodoProvider = true,
+        DisableAgentModeProvider = true,
+        DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        DisableFileAccess = true,   // If enabled, this would allow the agent to read/write files in a working directory
+        DisableToolApproval = true, // If enabled, this allows don't-ask-again approval functionality.
         ChatOptions = new ChatOptions
         {
             Instructions = "You are a web search assistant. When asked to find information, use the web search tool to look it up and return a concise, factual answer.",
-            Tools =
-            [
-                ResponseTool.CreateWebSearchTool().AsAITool(),
-            ],
         },
     });
 
 // --- Parent agent: Stock Price Researcher ---
-// This agent orchestrates the sub-agent to look up stock prices in parallel.
+// This agent orchestrates the background agent to look up stock prices in parallel.
 var parentInstructions =
     """
-    You are a stock price research assistant. You have access to a web search sub-agent that can look up information on the web.
+    You are a stock price research assistant. You have access to a web search background agent that can look up information on the web.
 
     When given a list of stock tickers, your job is to find the closing price for each ticker on December 31, 2025.
 
     ## Workflow
 
-    1. For each ticker, start a sub-task on the WebSearchAgent asking it to find the closing price on December 31, 2025.
-       - Start all sub-tasks before waiting for any of them to complete, so they run concurrently.
-    2. Wait for all sub-tasks to complete.
-    3. Retrieve the results from each sub-task.
+    1. For each ticker, start a background task on the WebSearchAgent asking it to find the closing price on December 31, 2025.
+       - Start all background tasks before waiting for any of them to complete, so they run concurrently.
+    2. Wait for all background tasks to complete.
+    3. Retrieve the results from each background task.
     4. Present a summary table with the ticker symbol and closing price for each stock.
     5. Clear all completed tasks to free memory.
 
     ## Important
 
-    - Always delegate web searches to the WebSearchAgent sub-agent. Do not try to answer from memory.
-    - If a sub-task fails or returns unclear results, continue the task with a more specific query.
+    - Always delegate web searches to the WebSearchAgent background agent. Do not try to answer from memory.
+    - If a background task fails or returns unclear results, continue the task with a more specific query.
     - Present results in a clean markdown table format.
     """;
 
+// --- Parent agent: Stock Price Researcher ---
+// This agent orchestrates the sub-agent to look up stock prices in parallel.
+// Most features are disabled since the parent only needs SubAgentsProvider.
 AIAgent parentAgent =
     new OpenAIClient(
         new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
@@ -88,10 +94,16 @@ AIAgent parentAgent =
     .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
     {
         Name = "StockPriceResearcher",
-        Description = "An agent that researches stock prices using sub-agents.",
+        Description = "An agent that researches stock prices using background agents.",
+        DisableTodoProvider = true,
+        DisableAgentModeProvider = true,
+        DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        DisableFileAccess = true,   // If enabled, this would allow the agent to read/write files in a working directory
+        DisableToolApproval = true, // If enabled, this allows don't-ask-again approval functionality.
+        DisableWebSearch = true,
         AIContextProviders =
         [
-            new SubAgentsProvider([webSearchAgent]),
+            new BackgroundAgentsProvider([webSearchAgent]),
         ],
         ChatOptions = new ChatOptions
         {

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithBackgroundAgents/README.md

@@ -1,24 +1,24 @@
-# Harness Step 02 — SubAgents (Stock Price Research)
+# Harness Step 02 — BackgroundAgents (Stock Price Research)
 
-This sample demonstrates how to use the **SubAgentsProvider** to delegate work from a parent agent to sub-agents. Both agents use `HarnessAgent` for pre-configured function invocation, per-service-call persistence, and context-window compaction.
+This sample demonstrates how to use the **BackgroundAgentsProvider** to delegate work from a parent agent to background agents. Both agents use `HarnessAgent` for pre-configured function invocation, per-service-call persistence, and context-window compaction.
 
 ## What It Does
 
-A parent agent receives a list of stock tickers and uses a web-search sub-agent to find the closing price for each ticker on December 31, 2025. The sub-tasks run concurrently, and results are presented in a summary table.
+A parent agent receives a list of stock tickers and uses a web-search background agent to find the closing price for each ticker on December 31, 2025. The background tasks run concurrently, and results are presented in a summary table.
 
 ### Architecture
 
 ```
-┌─────────────────────────────────┐
-│     StockPriceResearcher        │
-│         (Parent Agent)          │
-│                                 │
-│  SubAgentsProvider              │
-│    ├─ SubAgents_StartTask       │
-│    ├─ SubAgents_WaitFor...      │
-│    ├─ SubAgents_GetTaskResults  │
-│    └─ ...                       │
-└────────────┬────────────────────┘
+┌────────────────────────────────────────┐
+│     StockPriceResearcher               │
+│         (Parent Agent)                 │
+│                                        │
+│  BackgroundAgentsProvider              │
+│    ├─ BackgroundAgents_StartTask       │
+│    ├─ BackgroundAgents_WaitFor...      │
+│    ├─ BackgroundAgents_GetTaskResults  │
+│    └─ ...                              │
+└────────────┬───────────────────────────┘
              │  delegates to
              ▼
 ┌─────────────────────────────────┐
@@ -40,7 +40,7 @@ A parent agent receives a list of stock tickers and uses a web-search sub-agent
 ## Running the Sample
 
 ```bash
-cd dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents
+cd dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithBackgroundAgents
 dotnet run
 ```
 
@@ -50,4 +50,4 @@ When prompted, enter a list of stock tickers such as:
 BAC, MSFT, BA
 ```
 
-The parent agent will delegate each ticker lookup to the web search sub-agent concurrently and present the results in a table.
+The parent agent will delegate each ticker lookup to the web search background agent concurrently and present the results in a table.

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj

@@ -19,7 +19,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <Content Include="data\**\*" CopyToOutputDirectory="PreserveNewest" />
+    <Content Include="working\**\*" CopyToOutputDirectory="PreserveNewest" />
   </ItemGroup>
 
 </Project>

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/Program.cs

@@ -1,10 +1,12 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample demonstrates how to use a HarnessAgent with the FileAccessProvider
+// This sample demonstrates how to use a HarnessAgent with the default FileAccessProvider
 // to give an agent access to a folder of CSV data files. The agent can read, analyze,
 // and extract information from the data, then write results back as new files.
 //
-// The sample includes a pre-populated `data/` folder with sales transaction data.
+// The sample includes a pre-populated `working/` folder with sales transaction data.
+// The HarnessAgent's default FileAccessProvider uses `{cwd}/working` as its working directory,
+// which matches this sample's folder layout.
 // Ask the agent to analyze the data, produce summaries, or create new output files.
 //
 // Special commands:
@@ -27,10 +29,6 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYME
 const int MaxContextWindowTokens = 1_050_000;
 const int MaxOutputTokens = 128_000;
 
-// Point the file store at the data/ folder that ships with the sample.
-var dataFolder = Path.Combine(AppContext.BaseDirectory, "data");
-var fileStore = new FileSystemAgentFileStore(dataFolder);
-
 var instructions =
     """
     You are a data analyst assistant. You have access to a folder of data files via the FileAccess_* tools.
@@ -56,7 +54,9 @@ var instructions =
     - Always explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.
     """;
 
-// Create the chat client from the OpenAI provider.
+// Create the agent using AsHarnessAgent. The FileAccessStore is explicitly set to the
+// sample's working/ folder (copied to the output directory) so it works regardless of cwd.
+// Unused features are disabled.
 AIAgent agent =
     new OpenAIClient(
         new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
@@ -71,10 +71,11 @@ AIAgent agent =
     {
         Name = "DataAnalyst",
         Description = "A data analyst assistant that reads, analyzes, and processes data files.",
-        AIContextProviders =
-        [
-            new FileAccessProvider(fileStore),
-        ],
+        FileAccessStore = new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "working")),
+        DisableTodoProvider = true,
+        DisableAgentModeProvider = true,
+        DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        DisableWebSearch = true,
         ChatOptions = new ChatOptions
         {
             Instructions = instructions,

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/README.md

@@ -1,11 +1,11 @@
 # What this sample demonstrates
 
-This sample demonstrates how to use a `HarnessAgent` with the `FileAccessProvider` to give an agent access to a folder of data files for reading, analyzing, and writing results. The `HarnessAgent` pre-configures function invocation, per-service-call chat history persistence, and in-loop compaction — so the sample only needs to supply the chat client, token limits, and application-specific options.
+This sample demonstrates how to use a `HarnessAgent` with the default `FileAccessProvider` to give an agent access to a folder of data files for reading, analyzing, and writing results. The `HarnessAgent` pre-configures function invocation, per-service-call chat history persistence, in-loop compaction, tool approval, and OpenTelemetry — so the sample only needs to supply the chat client, token limits, custom instructions, and opt out of unused features.
 
 Key features showcased:
 
 - **HarnessAgent** — a pre-configured agent that wraps a `ChatClientAgent` with function invocation, per-service-call persistence, and context-window compaction
-- **FileAccessProvider** — gives the agent tools to read, write, list, search, and delete files in a shared data folder
+- **FileAccessProvider** — the HarnessAgent's default file access provider uses `{cwd}/working` as its working directory, matching this sample's `working/` folder
 - **CSV data processing** — the agent reads sales transaction data and performs analysis on demand
 - **Output file creation** — the agent can write summaries, filtered data, or reports back to the data folder
 - **Streaming output** — responses are streamed token-by-token for a natural experience
@@ -39,7 +39,7 @@ dotnet run --project samples/02-agents/Harness/Harness_Step03_DataProcessing
 
 ## What to Expect
 
-The sample starts an interactive conversation with a data analyst agent. The `data/` folder contains a `sales.csv` file with ~50 rows of sales transaction data (date, product, category, quantity, unit price, region, salesperson).
+The sample starts an interactive conversation with a data analyst agent. The `working/` folder contains a `sales.csv` file with ~50 rows of sales transaction data (date, product, category, quantity, unit price, region, salesperson).
 
 You can ask the agent to:
 
@@ -53,7 +53,7 @@ E.g. try the following prompt `Please process the sales.csv file by first filter
 
 ## Sample Data
 
-The included `data/sales.csv` contains sales transactions from January to March 2025 with the following columns:
+The included `working/sales.csv` contains sales transactions from January to March 2025 with the following columns:
 
 | Column | Description |
 | --- | --- |

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

@@ -7,5 +7,5 @@ Samples demonstrating the [Harness AIContextProviders](../../../src/Microsoft.Ag
 | Sample | Description |
 | --- | --- |
 | [Harness_Step01_Research](./Harness_Step01_Research/README.md) | Using a ChatClientAgent with TodoProvider and AgentModeProvider for research, showcasing planning mode and todo management |
-| [Harness_Step02_Research_WithSubAgents](./Harness_Step02_Research_WithSubAgents/README.md) | Using SubAgentsProvider to delegate stock price lookups to a web-search sub-agent concurrently |
+| [Harness_Step02_Research_WithBackgroundAgents](./Harness_Step02_Research_WithBackgroundAgents/README.md) | Using BackgroundAgentsProvider to delegate stock price lookups to a web-search background agent concurrently |
 | [Harness_Step03_DataProcessing](./Harness_Step03_DataProcessing/README.md) | Using FileAccessProvider to give an agent access to CSV data files for reading, analysis, and output generation |

dotnet/src/Microsoft.Agents.AI.AGUI/Shared/ChatResponseUpdateAGUIExtensions.cs

@@ -458,8 +458,9 @@ internal static class ChatResponseUpdateAGUIExtensions
             // This ensures all AGUI events have a valid messageId regardless of agent type.
             if (string.IsNullOrWhiteSpace(chatResponse.MessageId))
             {
-                streamingMessageId ??= Guid.NewGuid().ToString("N");
-                chatResponse.MessageId = streamingMessageId;
+                chatResponse.MessageId = ContainsToolResult(chatResponse)
+                    ? Guid.NewGuid().ToString("N")
+                    : (streamingMessageId ??= Guid.NewGuid().ToString("N"));
             }
 
             if (chatResponse is { Contents.Count: > 0 } &&
@@ -725,4 +726,17 @@ internal static class ChatResponseUpdateAGUIExtensions
             _ => JsonSerializer.Serialize(functionResultContent.Result, options.GetTypeInfo(functionResultContent.Result.GetType())),
         };
     }
+
+    private static bool ContainsToolResult(ChatResponseUpdate chatResponse)
+    {
+        foreach (AIContent content in chatResponse.Contents)
+        {
+            if (content is FunctionResultContent)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
 }

dotnet/src/Microsoft.Agents.AI.Harness/HarnessAgent.cs

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
+using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using System.IO;
 using Microsoft.Agents.AI.Compaction;
 using Microsoft.Extensions.AI;
 using Microsoft.Shared.DiagnosticIds;
@@ -10,7 +13,8 @@ namespace Microsoft.Agents.AI;
 
 /// <summary>
 /// A pre-configured <see cref="DelegatingAIAgent"/> that wraps a <see cref="ChatClientAgent"/> with
-/// function invocation, per-service-call chat history persistence, and in-loop compaction.
+/// function invocation, per-service-call chat history persistence, in-loop compaction, and a rich set
+/// of default context providers and agent decorators.
 /// </summary>
 /// <remarks>
 /// <para>
@@ -23,6 +27,27 @@ namespace Microsoft.Agents.AI;
 /// </list>
 /// </para>
 /// <para>
+/// By default, the following context providers are included (each can be disabled via <see cref="HarnessAgentOptions"/>):
+/// <list type="bullet">
+/// <item><description><see cref="TodoProvider"/> — todo list management.</description></item>
+/// <item><description><see cref="AgentModeProvider"/> — agent mode tracking (plan/execute).</description></item>
+/// <item><description><see cref="FileMemoryProvider"/> — file-based session memory.</description></item>
+/// <item><description><see cref="FileAccessProvider"/> — shared file access.</description></item>
+/// <item><description><see cref="AgentSkillsProvider"/> — skill discovery and loading.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// The agent is also wrapped with the following decorators by default (each can be disabled):
+/// <list type="bullet">
+/// <item><description><see cref="ToolApprovalAgent"/> — "don't ask again" tool approval rules.</description></item>
+/// <item><description><see cref="OpenTelemetryAgent"/> — OpenTelemetry instrumentation.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// A <see cref="HostedWebSearchTool"/> is added to the chat options by default (can be disabled via
+/// <see cref="HarnessAgentOptions.DisableWebSearch"/>).
+/// </para>
+/// <para>
 /// The underlying <see cref="ChatClientAgent"/> is configured with
 /// <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> and
 /// <see cref="ChatClientAgentOptions.RequirePerServiceCallChatHistoryPersistence"/> set to <see langword="true"/>
@@ -48,7 +73,9 @@ public sealed class HarnessAgent : DelegatingAIAgent
 
         - Think through the task before acting. Break complex work into clear steps.
         - Use the tools available to you to gather information, perform actions, and verify results.
-        - Explain your reasoning between tool calls so the user can follow your progress.
+        - Explain your reasoning and thought process as you work through tasks.
+        - Explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.
+        - Avoid making more than 4 tool calls in a row without explaining what you are doing.
         - If a tool call fails or returns unexpected results, adapt your approach rather than repeating the same call.
         - When you have completed the task, present a clear and concise summary of what you did and what you found.
         """;
@@ -74,15 +101,15 @@ public sealed class HarnessAgent : DelegatingAIAgent
     /// additional context providers, and chat history provider.
     /// When <see langword="null"/>, the agent uses built-in default settings.
     /// </param>
-    /// <exception cref="System.ArgumentNullException">
+    /// <exception cref="ArgumentNullException">
     /// <paramref name="chatClient"/> is <see langword="null"/>.
     /// </exception>
-    /// <exception cref="System.ArgumentOutOfRangeException">
+    /// <exception cref="ArgumentOutOfRangeException">
     /// <paramref name="maxContextWindowTokens"/> is not positive, or
     /// <paramref name="maxOutputTokens"/> is negative or greater than or equal to <paramref name="maxContextWindowTokens"/>.
     /// </exception>
     public HarnessAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options = null)
-        : base(BuildInnerAgent(
+        : base(BuildAgent(
             Throw.IfNull(chatClient),
             maxContextWindowTokens,
             maxOutputTokens,
@@ -90,6 +117,25 @@ public sealed class HarnessAgent : DelegatingAIAgent
     {
     }
 
+    private static AIAgent BuildAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options)
+    {
+        ChatClientAgent innerAgent = BuildInnerAgent(chatClient, maxContextWindowTokens, maxOutputTokens, options);
+
+        AIAgentBuilder builder = innerAgent.AsBuilder();
+
+        if (options?.DisableToolApproval is not true)
+        {
+            builder.UseToolApproval();
+        }
+
+        if (options?.DisableOpenTelemetry is not true)
+        {
+            builder.UseOpenTelemetry();
+        }
+
+        return builder.Build();
+    }
+
     private static ChatClientAgent BuildInnerAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options)
     {
         var compactionStrategy = new ContextWindowCompactionStrategy(
@@ -102,15 +148,28 @@ public sealed class HarnessAgent : DelegatingAIAgent
                 ChatReducer = compactionStrategy.AsChatReducer(),
             });
 
-        string instructions = options?.ChatOptions?.Instructions ?? DefaultInstructions;
+        string harnessInstructions = options?.HarnessInstructions ?? DefaultInstructions;
+        string? agentInstructions = options?.ChatOptions?.Instructions;
 
-        ChatOptions chatOptions = BuildChatOptions(options?.ChatOptions, instructions, maxOutputTokens);
+        string instructions = (string.IsNullOrWhiteSpace(harnessInstructions), string.IsNullOrWhiteSpace(agentInstructions)) switch
+        {
+            (true, true) => harnessInstructions,
+            (true, false) => agentInstructions!,
+            (false, true) => harnessInstructions,
+            (false, false) => $"{harnessInstructions}\n\n{agentInstructions}",
+        };
+
+        ChatOptions chatOptions = BuildChatOptions(options, instructions, maxOutputTokens);
 
         var compactionProvider = new CompactionProvider(compactionStrategy);
 
+        IEnumerable<AIContextProvider> contextProviders = BuildContextProviders(options);
+
         return chatClient
             .AsBuilder()
-            .UseFunctionInvocation()
+            .UseFunctionInvocation(configure: options?.MaximumIterationsPerRequest is int maxIterations
+                ? ficc => ficc.MaximumIterationsPerRequest = maxIterations
+                : null)
             .UseMessageInjection()
             .UsePerServiceCallChatHistoryPersistence()
             .UseAIContextProviders(compactionProvider)
@@ -121,17 +180,78 @@ public sealed class HarnessAgent : DelegatingAIAgent
                 Description = options?.Description,
                 ChatOptions = chatOptions,
                 ChatHistoryProvider = chatHistoryProvider,
-                AIContextProviders = options?.AIContextProviders,
+                AIContextProviders = contextProviders,
                 UseProvidedChatClientAsIs = true,
                 RequirePerServiceCallChatHistoryPersistence = true,
             });
     }
 
-    private static ChatOptions BuildChatOptions(ChatOptions? source, string instructions, int maxOutputTokens)
+    private static ChatOptions BuildChatOptions(HarnessAgentOptions? options, string instructions, int maxOutputTokens)
     {
-        ChatOptions result = source?.Clone() ?? new ChatOptions();
+        ChatOptions result = options?.ChatOptions?.Clone() ?? new ChatOptions();
         result.Instructions = instructions;
         result.MaxOutputTokens ??= maxOutputTokens;
+
+        if (options?.DisableWebSearch is not true)
+        {
+            result.Tools ??= [];
+            result.Tools.Add(new HostedWebSearchTool());
+        }
+
         return result;
     }
+
+    private static List<AIContextProvider> BuildContextProviders(HarnessAgentOptions? options)
+    {
+        var providers = new List<AIContextProvider>();
+
+        if (options?.DisableTodoProvider is not true)
+        {
+            providers.Add(new TodoProvider());
+        }
+
+        if (options?.DisableAgentModeProvider is not true)
+        {
+            providers.Add(new AgentModeProvider(options?.AgentModeProviderOptions));
+        }
+
+        if (options?.DisableFileMemory is not true)
+        {
+            AgentFileStore fileMemoryStore = options?.FileMemoryStore
+                ?? new FileSystemAgentFileStore(
+                    Path.Combine(Directory.GetCurrentDirectory(), "agent-file-memory"));
+
+            providers.Add(new FileMemoryProvider(
+                fileMemoryStore,
+                _ => new FileMemoryState
+                {
+                    WorkingFolder = DateTime.UtcNow.ToString("yyyyMMdd_HHmmss") + "_" + Guid.NewGuid().ToString(),
+                }));
+        }
+
+        if (options?.DisableFileAccess is not true)
+        {
+            AgentFileStore fileAccessStore = options?.FileAccessStore
+                ?? new FileSystemAgentFileStore(
+                    Path.Combine(Directory.GetCurrentDirectory(), "working"));
+
+            providers.Add(new FileAccessProvider(fileAccessStore));
+        }
+
+        if (options?.DisableAgentSkillsProvider is not true)
+        {
+            AgentSkillsProvider skillsProvider = options?.AgentSkillsSource is AgentSkillsSource source
+                ? new AgentSkillsProvider(source)
+                : new AgentSkillsProvider(Directory.GetCurrentDirectory());
+
+            providers.Add(skillsProvider);
+        }
+
+        if (options?.AIContextProviders is IEnumerable<AIContextProvider> userProviders)
+        {
+            providers.AddRange(userProviders);
+        }
+
+        return providers;
+    }
 }

dotnet/src/Microsoft.Agents.AI.Harness/HarnessAgentOptions.cs

@@ -36,13 +36,31 @@ public sealed class HarnessAgentOptions
     /// Use <see cref="ChatOptions.Tools"/> to supply additional tools the agent can invoke.
     /// </para>
     /// <para>
-    /// Use <see cref="ChatOptions.Instructions"/> to override the <see cref="HarnessAgent"/>'s built-in
-    /// default instructions. When <see cref="ChatOptions.Instructions"/> is <see langword="null"/> or not set,
-    /// the default instructions are used.
+    /// Use <see cref="ChatOptions.Instructions"/> to provide agent-specific instructions (e.g., research methodology,
+    /// data analysis workflow). These are combined with <see cref="HarnessInstructions"/> to form the final instructions
+    /// sent to the model: harness instructions appear first, followed by agent-specific instructions.
+    /// When <see cref="ChatOptions.Instructions"/> is <see langword="null"/>, only <see cref="HarnessInstructions"/>
+    /// (or the default) is used.
     /// </para>
     /// </remarks>
     public ChatOptions? ChatOptions { get; set; }
 
+    /// <summary>
+    /// Gets or sets the harness-level instructions that control general tool usage and behavior patterns.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Harness instructions provide guidance on how to use tools, explain reasoning, and structure work.
+    /// They are combined with <see cref="ChatOptions"/>.<see cref="ChatOptions.Instructions"/> (agent-specific instructions)
+    /// to produce the final instructions sent to the model: harness instructions first, then agent-specific instructions.
+    /// </para>
+    /// <para>
+    /// When <see langword="null"/> (the default), <see cref="HarnessAgent.DefaultInstructions"/> is used.
+    /// Set to <see cref="string.Empty"/> to omit harness instructions entirely.
+    /// </para>
+    /// </remarks>
+    public string? HarnessInstructions { get; set; }
+
     /// <summary>
     /// Gets or sets the <see cref="ChatHistoryProvider"/> to use for storing chat history.
     /// </summary>
@@ -61,4 +79,131 @@ public sealed class HarnessAgentOptions
     /// <see cref="ChatClientAgentOptions.AIContextProviders"/>.
     /// </remarks>
     public IEnumerable<AIContextProvider>? AIContextProviders { get; set; }
+
+    /// <summary>
+    /// Gets or sets the maximum number of function-invocation loop iterations per request.
+    /// </summary>
+    /// <remarks>
+    /// When set, this value is passed to <see cref="FunctionInvokingChatClient.MaximumIterationsPerRequest"/>.
+    /// When <see langword="null"/>, the <see cref="FunctionInvokingChatClient"/> default is used.
+    /// </remarks>
+    public int? MaximumIterationsPerRequest { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="ToolApprovalAgent"/> wrapper is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), the agent is wrapped with tool approval middleware
+    /// that supports "don't ask again" auto-approval rules.
+    /// </remarks>
+    public bool DisableToolApproval { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="FileMemoryProvider"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), a <see cref="FileMemoryProvider"/> is included in the
+    /// agent's context providers, using either <see cref="FileMemoryStore"/> or a default
+    /// <see cref="FileSystemAgentFileStore"/> rooted at <c>{cwd}/agent-file-memory/{timestamp}_{guid}</c>.
+    /// </remarks>
+    public bool DisableFileMemory { get; set; }
+
+    /// <summary>
+    /// Gets or sets a custom <see cref="AgentFileStore"/> for the <see cref="FileMemoryProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/> and <see cref="DisableFileMemory"/> is <see langword="false"/>,
+    /// a default <see cref="FileSystemAgentFileStore"/> is created.
+    /// This property is ignored when <see cref="DisableFileMemory"/> is <see langword="true"/>.
+    /// </remarks>
+    public AgentFileStore? FileMemoryStore { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="FileAccessProvider"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), a <see cref="FileAccessProvider"/> is included in the
+    /// agent's context providers, using either <see cref="FileAccessStore"/> or a default
+    /// <see cref="FileSystemAgentFileStore"/> rooted at <c>{cwd}/working</c>.
+    /// </remarks>
+    public bool DisableFileAccess { get; set; }
+
+    /// <summary>
+    /// Gets or sets a custom <see cref="AgentFileStore"/> for the <see cref="FileAccessProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/> and <see cref="DisableFileAccess"/> is <see langword="false"/>,
+    /// a default <see cref="FileSystemAgentFileStore"/> is created.
+    /// This property is ignored when <see cref="DisableFileAccess"/> is <see langword="true"/>.
+    /// </remarks>
+    public AgentFileStore? FileAccessStore { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="HostedWebSearchTool"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), a <see cref="HostedWebSearchTool"/> is added
+    /// to <see cref="ChatOptions"/>.<see cref="ChatOptions.Tools"/>.
+    /// </remarks>
+    public bool DisableWebSearch { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="TodoProvider"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), a <see cref="TodoProvider"/> is included
+    /// in the agent's context providers for tracking work items.
+    /// </remarks>
+    public bool DisableTodoProvider { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="AgentModeProvider"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), an <see cref="AgentModeProvider"/> is included
+    /// in the agent's context providers. Use <see cref="AgentModeProviderOptions"/> to configure
+    /// custom modes.
+    /// </remarks>
+    public bool DisableAgentModeProvider { get; set; }
+
+    /// <summary>
+    /// Gets or sets custom options for the <see cref="AgentModeProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/>, the <see cref="AgentModeProvider"/> uses its built-in default
+    /// modes ("plan" and "execute"). This property is ignored when
+    /// <see cref="DisableAgentModeProvider"/> is <see langword="true"/>.
+    /// </remarks>
+    public AgentModeProviderOptions? AgentModeProviderOptions { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="AgentSkillsProvider"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), an <see cref="AgentSkillsProvider"/> is included
+    /// in the agent's context providers. Use <see cref="AgentSkillsSource"/> to provide a custom
+    /// skills source; otherwise, the provider defaults to file-based skill discovery from the current
+    /// working directory.
+    /// </remarks>
+    public bool DisableAgentSkillsProvider { get; set; }
+
+    /// <summary>
+    /// Gets or sets a custom <see cref="AI.AgentSkillsSource"/> for the <see cref="AgentSkillsProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/> and <see cref="DisableAgentSkillsProvider"/> is <see langword="false"/>,
+    /// the provider defaults to file-based skill discovery from the current working directory.
+    /// This property is ignored when <see cref="DisableAgentSkillsProvider"/> is <see langword="true"/>.
+    /// </remarks>
+    public AgentSkillsSource? AgentSkillsSource { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="OpenTelemetryAgent"/> wrapper is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), the agent is wrapped with an
+    /// <see cref="OpenTelemetryAgent"/> that provides OpenTelemetry instrumentation
+    /// following the Semantic Conventions for Generative AI systems.
+    /// </remarks>
+    public bool DisableOpenTelemetry { get; set; }
 }

dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIResponseClientExtensions.cs

@@ -120,9 +120,24 @@ public static class OpenAIResponseClientExtensions
         return Throw.IfNull(responseClient)
             .AsIChatClient(model)
             .AsBuilder()
-            .ConfigureOptions(x => x.RawRepresentationFactory = _ => includeReasoningEncryptedContent
-                ? new CreateResponseOptions() { StoredOutputEnabled = false, IncludedProperties = { IncludedResponseProperty.ReasoningEncryptedContent } }
-                : new CreateResponseOptions() { StoredOutputEnabled = false })
+            .ConfigureOptions(x =>
+            {
+                var previousFactory = x.RawRepresentationFactory;
+                x.RawRepresentationFactory = state =>
+                {
+                    var responseOptions = previousFactory?.Invoke(state) as CreateResponseOptions ?? new CreateResponseOptions();
+
+                    responseOptions.StoredOutputEnabled = false;
+
+                    if (includeReasoningEncryptedContent &&
+                        !responseOptions.IncludedProperties.Contains(IncludedResponseProperty.ReasoningEncryptedContent))
+                    {
+                        responseOptions.IncludedProperties.Add(IncludedResponseProperty.ReasoningEncryptedContent);
+                    }
+
+                    return responseOptions;
+                };
+            })
             .Build();
     }
 }

dotnet/src/Microsoft.Agents.AI/AgentJsonUtilities.cs

@@ -74,9 +74,11 @@ internal static partial class AgentJsonUtilities
     [JsonSerializable(typeof(TodoState))]
     [JsonSerializable(typeof(TodoItem))]
     [JsonSerializable(typeof(TodoItemInput))]
+    [JsonSerializable(typeof(TodoCompleteInput))]
     [JsonSerializable(typeof(List<int>), TypeInfoPropertyName = "IntList")]
     [JsonSerializable(typeof(List<TodoItem>), TypeInfoPropertyName = "TodoItemList")]
     [JsonSerializable(typeof(List<TodoItemInput>), TypeInfoPropertyName = "TodoItemInputList")]
+    [JsonSerializable(typeof(List<TodoCompleteInput>), TypeInfoPropertyName = "TodoCompleteInputList")]
 
     // AgentModeProvider types
     [JsonSerializable(typeof(AgentModeState))]
@@ -95,12 +97,12 @@ internal static partial class AgentJsonUtilities
     [JsonSerializable(typeof(FileListEntry))]
     [JsonSerializable(typeof(List<FileListEntry>), TypeInfoPropertyName = "FileListEntryList")]
 
-    // SubAgentsProvider types
-    [JsonSerializable(typeof(SubAgentState))]
-    [JsonSerializable(typeof(SubAgentRuntimeState))]
-    [JsonSerializable(typeof(SubTaskInfo))]
-    [JsonSerializable(typeof(SubTaskStatus))]
-    [JsonSerializable(typeof(List<SubTaskInfo>), TypeInfoPropertyName = "SubTaskInfoList")]
+    // BackgroundAgentsProvider types
+    [JsonSerializable(typeof(BackgroundAgentState))]
+    [JsonSerializable(typeof(BackgroundAgentRuntimeState))]
+    [JsonSerializable(typeof(BackgroundTaskInfo))]
+    [JsonSerializable(typeof(BackgroundTaskStatus))]
+    [JsonSerializable(typeof(List<BackgroundTaskInfo>), TypeInfoPropertyName = "BackgroundTaskInfoList")]
 
     [ExcludeFromCodeCoverage]
     internal sealed partial class JsonContext : JsonSerializerContext;

dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProvider.cs

@@ -45,20 +45,54 @@ public sealed class AgentModeProvider : AIContextProvider
         """
         ## Agent Mode
 
-        You can operate in different modes. Depending on the mode you are in, you will be required to follow different processes.
+        - You can operate in different modes. Depending on the mode you are in, you will be required to follow different processes.
+        - You must check the current mode after any user input, since the user may have changed the mode themselves,
+          e.g. the user may have switched to 'plan' mode after a previous research task finished in 'execute' mode, meaning they want to review a plan first before execution.
 
         Use the AgentMode_Get tool to check your current operating mode.
         Use the AgentMode_Set tool to switch between modes as your work progresses. Only use AgentMode_Set if the user explicitly instructs/allows you to change modes.
 
-        {available_modes}
-
         You are currently operating in the {current_mode} mode.
+
+        ### Mandatory Mode based Workflow
+
+        For every new substantive user request, including short factual questions, your behavior is determined by the mode you are in.
+
+        {available_modes}
         """;
 
     private static readonly IReadOnlyList<AgentModeProviderOptions.AgentMode> s_defaultModes =
     [
-        new("plan", "Use this mode when analyzing requirements, breaking down tasks, and creating plans. This is the interactive mode — ask clarifying questions, discuss options, and get user approval before proceeding."),
-        new("execute", "Use this mode when carrying out approved plans. Work autonomously using your best judgement — do not ask the user questions or wait for feedback. Make reasonable decisions on your own so that there is a complete, useful result when the user returns. If you encounter ambiguity, choose the most reasonable option and note your choice."),
+        new(
+            "plan",
+            """
+            Use this mode when analyzing requirements, breaking down tasks, and creating plans. This is the interactive mode — ask clarifying questions, discuss options, and get user approval before proceeding.
+
+            Process to follow when in plan mode:
+            1. Analyze the request with the purpose of building a research plan.
+            2. Create a list of todo items.
+            3. If needed, use the provided tools to do some exploratory checks to help build a plan and determine what clarifying questions you may need from the user.
+            4. Ask for clarifications from the user where needed.
+              1. Ask each clarification one by one.
+              2. When asking for clarification and you have specific options in mind, present them to the user, so they can choose the option instead of having to retype the entire response.
+              3. Do not proceed until you have received all the needed clarifications.
+              4. Do short exploratory research if it helps with being able to ask sensible clarifications from the user.
+            5. Write the plan to a memory file, so that it is retained even if compaction happens. Make sure to update the plan file if the user requests changes.
+            6. Present the plan to the user and ask for approval to switch to execute mode and process the plan.
+            7. When approval is granted, always switch to execute mode (using the `AgentMode_Set` tool), and follow the steps for *Execute mode*.
+            """),
+        new(
+            "execute",
+            """
+            Use this mode when carrying out approved plans. Work autonomously using your best judgment — do not ask the user questions or wait for feedback.
+            
+            Process to follow when in execute mode:
+            1. If you don't have a plan or tasks yet, analyze the user request and create tasks and a plan. (**Skip this step if you came from plan mode**)
+            2. Work autonomously — use your best judgment to make decisions and keep progressing without asking the user questions. The goal is to have a complete, useful result ready when the user returns.
+            3. If you encounter ambiguity or an unexpected situation during execution, choose the most reasonable option, note your choice, and keep going.
+            4. Mark tasks as completed as you finish them.
+            5. Continue working, thinking and calling tools until you have the research result for the user.
+            """),
     ];
 
     private readonly ProviderSessionState<AgentModeState> _sessionState;
@@ -187,12 +221,15 @@ public sealed class AgentModeProvider : AIContextProvider
 
     private string BuildInstructions(string currentMode)
     {
-        // Build list of modes text:
         var modesListBuilder = new StringBuilder();
         foreach (var mode in this._modes)
         {
-            modesListBuilder.AppendLine($"- \"{mode.Name}\": {mode.Description}");
+            modesListBuilder.AppendLine($"#### {mode.Name}");
+            modesListBuilder.AppendLine();
+            modesListBuilder.AppendLine(mode.Description.TrimEnd());
+            modesListBuilder.AppendLine();
         }
+
         var modesListText = modesListBuilder.ToString();
 
         return new StringBuilder(this._instructions)

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundAgentRuntimeState.cs

@@ -7,15 +7,15 @@ using System.Threading.Tasks;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Holds non-serializable runtime references for in-flight sub-tasks within a single parent session.
+/// Holds non-serializable runtime references for in-flight background tasks within a single parent session.
 /// </summary>
 /// <remarks>
 /// Properties are marked with <see cref="JsonIgnoreAttribute"/> because <see cref="Task{TResult}"/>
 /// and <see cref="AgentSession"/> are not JSON-serializable. After deserialization (e.g., after a restart),
 /// a fresh empty instance is created and any previously-running tasks are marked as
-/// <see cref="SubTaskStatus.Lost"/> by <see cref="SubAgentsProvider"/>.
+/// <see cref="BackgroundTaskStatus.Lost"/> by <see cref="BackgroundAgentsProvider"/>.
 /// </remarks>
-internal sealed class SubAgentRuntimeState
+internal sealed class BackgroundAgentRuntimeState
 {
     /// <summary>
     /// Gets the mapping of task IDs to their in-flight <see cref="Task{AgentResponse}"/> instances.
@@ -24,9 +24,9 @@ internal sealed class SubAgentRuntimeState
     public Dictionary<int, Task<AgentResponse>> InFlightTasks { get; } = [];
 
     /// <summary>
-    /// Gets the mapping of task IDs to their sub-agent <see cref="AgentSession"/> instances,
+    /// Gets the mapping of task IDs to their background agent <see cref="AgentSession"/> instances,
     /// needed for <c>ContinueTask</c>.
     /// </summary>
     [JsonIgnore]
-    public Dictionary<int, AgentSession> SubTaskSessions { get; } = [];
+    public Dictionary<int, AgentSession> BackgroundTaskSessions { get; } = [];
 }

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundAgentState.cs

@@ -8,21 +8,21 @@ using Microsoft.Shared.DiagnosticIds;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Represents the serializable state of sub-tasks managed by the <see cref="SubAgentsProvider"/>,
+/// Represents the serializable state of background tasks managed by the <see cref="BackgroundAgentsProvider"/>,
 /// stored in the session's <see cref="AgentSessionStateBag"/>.
 /// </summary>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-internal sealed class SubAgentState
+internal sealed class BackgroundAgentState
 {
     /// <summary>
-    /// Gets or sets the next ID to assign to a new sub-task.
+    /// Gets or sets the next ID to assign to a new background task.
     /// </summary>
     [JsonPropertyName("nextTaskId")]
     public int NextTaskId { get; set; } = 1;
 
     /// <summary>
-    /// Gets the list of sub-task metadata entries.
+    /// Gets the list of background task metadata entries.
     /// </summary>
     [JsonPropertyName("tasks")]
-    public List<SubTaskInfo> Tasks { get; set; } = [];
+    public List<BackgroundTaskInfo> Tasks { get; set; } = [];
 }

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundAgentsProvider.cs

@@ -15,56 +15,56 @@ using Microsoft.Shared.Diagnostics;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// An <see cref="AIContextProvider"/> that enables an agent to delegate work to sub-agents asynchronously.
+/// An <see cref="AIContextProvider"/> that enables an agent to delegate work to background agents asynchronously.
 /// </summary>
 /// <remarks>
 /// <para>
-/// The <see cref="SubAgentsProvider"/> allows a parent agent to start sub-tasks on child agents,
-/// wait for their completion, and retrieve results. Each sub-task runs in its own session and
+/// The <see cref="BackgroundAgentsProvider"/> allows a parent agent to start background tasks on child agents,
+/// wait for their completion, and retrieve results. Each background task runs in its own session and
 /// executes concurrently.
 /// </para>
 /// <para>
 /// This provider exposes the following tools to the agent:
 /// <list type="bullet">
-/// <item><description><c>SubAgents_StartTask</c> — Start a sub-task on a named agent with text input. Returns the task ID.</description></item>
-/// <item><description><c>SubAgents_WaitForFirstCompletion</c> — Block until the first of the specified tasks completes. Returns the completed task's ID.</description></item>
-/// <item><description><c>SubAgents_GetTaskResults</c> — Retrieve the text output of a completed sub-task.</description></item>
-/// <item><description><c>SubAgents_GetAllTasks</c> — List all sub-tasks with their IDs, statuses, descriptions, and agent names.</description></item>
-/// <item><description><c>SubAgents_ContinueTask</c> — Send follow-up input to a completed sub-task's session to resume work.</description></item>
-/// <item><description><c>SubAgents_ClearCompletedTask</c> — Remove a completed sub-task and release its session to free memory.</description></item>
+/// <item><description><c>BackgroundAgents_StartTask</c> — Start a background task on a named agent with text input. Returns the task ID.</description></item>
+/// <item><description><c>BackgroundAgents_WaitForFirstCompletion</c> — Block until the first of the specified tasks completes. Returns the completed task's ID.</description></item>
+/// <item><description><c>BackgroundAgents_GetTaskResults</c> — Retrieve the text output of a completed background task.</description></item>
+/// <item><description><c>BackgroundAgents_GetAllTasks</c> — List all background tasks with their IDs, statuses, descriptions, and agent names.</description></item>
+/// <item><description><c>BackgroundAgents_ContinueTask</c> — Send follow-up input to a completed background task's session to resume work.</description></item>
+/// <item><description><c>BackgroundAgents_ClearCompletedTask</c> — Remove a completed background task and release its session to free memory.</description></item>
 /// </list>
 /// </para>
 /// </remarks>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class SubAgentsProvider : AIContextProvider
+public sealed class BackgroundAgentsProvider : AIContextProvider
 {
     private const string DefaultInstructions =
         """
-        ## SubAgents
-        You have access to sub-agents that can perform work on your behalf.
+        ## BackgroundAgents
+        You have access to background agents that can perform work on your behalf.
 
-        - Use the `SubAgents_*` list of tools to start tasks on sub agents and check their results.
-        - Creating a sub task does not block, and sub-tasks run concurrently.
+        - Use the `BackgroundAgents_*` list of tools to start tasks on background agents and check their results.
+        - Creating a background task does not block, and background tasks run concurrently.
         - Important: Always wait for outstanding tasks to finish before you finish processing.
-        - Important: After retrieving results from a completed task, clear it with SubAgents_ClearCompletedTask to free memory, unless you plan to continue it with SubAgents_ContinueTask.
+        - Important: After retrieving results from a completed task, clear it with BackgroundAgents_ClearCompletedTask to free memory, unless you plan to continue it with BackgroundAgents_ContinueTask.
 
-        {sub_agents}
+        {background_agents}
         """;
 
     private readonly Dictionary<string, AIAgent> _agents;
-    private readonly ProviderSessionState<SubAgentState> _sessionState;
-    private readonly ProviderSessionState<SubAgentRuntimeState> _runtimeSessionState;
+    private readonly ProviderSessionState<BackgroundAgentState> _sessionState;
+    private readonly ProviderSessionState<BackgroundAgentRuntimeState> _runtimeSessionState;
     private readonly string _instructions;
     private IReadOnlyList<string>? _stateKeys;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="SubAgentsProvider"/> class.
+    /// Initializes a new instance of the <see cref="BackgroundAgentsProvider"/> class.
     /// </summary>
-    /// <param name="agents">The collection of sub-agents available for delegation.</param>
+    /// <param name="agents">The collection of background agents available for delegation.</param>
     /// <param name="options">Optional settings controlling the provider behavior.</param>
     /// <exception cref="ArgumentNullException"><paramref name="agents"/> is <see langword="null"/>.</exception>
     /// <exception cref="ArgumentException">An agent has a null or empty name, or agent names are not unique.</exception>
-    public SubAgentsProvider(IEnumerable<AIAgent> agents, SubAgentsProviderOptions? options = null)
+    public BackgroundAgentsProvider(IEnumerable<AIAgent> agents, BackgroundAgentsProviderOptions? options = null)
     {
         _ = Throw.IfNull(agents);
 
@@ -74,15 +74,15 @@ public sealed class SubAgentsProvider : AIContextProvider
         string agentListText = options?.AgentListBuilder is not null
             ? options.AgentListBuilder(this._agents)
             : BuildDefaultAgentListText(this._agents);
-        this._instructions = baseInstructions.Replace("{sub_agents}", agentListText);
+        this._instructions = baseInstructions.Replace("{background_agents}", agentListText);
 
-        this._sessionState = new ProviderSessionState<SubAgentState>(
-            _ => new SubAgentState(),
+        this._sessionState = new ProviderSessionState<BackgroundAgentState>(
+            _ => new BackgroundAgentState(),
             this.GetType().Name,
             AgentJsonUtilities.DefaultOptions);
 
-        this._runtimeSessionState = new ProviderSessionState<SubAgentRuntimeState>(
-            _ => new SubAgentRuntimeState(),
+        this._runtimeSessionState = new ProviderSessionState<BackgroundAgentRuntimeState>(
+            _ => new BackgroundAgentRuntimeState(),
             this.GetType().Name + "_Runtime",
             AgentJsonUtilities.DefaultOptions);
     }
@@ -93,8 +93,8 @@ public sealed class SubAgentsProvider : AIContextProvider
     /// <inheritdoc />
     protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
     {
-        SubAgentState state = this._sessionState.GetOrInitializeState(context.Session);
-        SubAgentRuntimeState runtimeState = this._runtimeSessionState.GetOrInitializeState(context.Session);
+        BackgroundAgentState state = this._sessionState.GetOrInitializeState(context.Session);
+        BackgroundAgentRuntimeState runtimeState = this._runtimeSessionState.GetOrInitializeState(context.Session);
 
         return new ValueTask<AIContext>(new AIContext
         {
@@ -113,12 +113,12 @@ public sealed class SubAgentsProvider : AIContextProvider
         {
             if (string.IsNullOrWhiteSpace(agent.Name))
             {
-                throw new ArgumentException("All sub-agents must have a non-empty Name.", nameof(agents));
+                throw new ArgumentException("All background agents must have a non-empty Name.", nameof(agents));
             }
 
             if (dict.ContainsKey(agent.Name))
             {
-                throw new ArgumentException($"Duplicate sub-agent name: '{agent.Name}'. Agent names must be unique (case-insensitive).", nameof(agents));
+                throw new ArgumentException($"Duplicate background agent name: '{agent.Name}'. Agent names must be unique (case-insensitive).", nameof(agents));
             }
 
             dict[agent.Name] = agent;
@@ -126,19 +126,19 @@ public sealed class SubAgentsProvider : AIContextProvider
 
         if (dict.Count == 0)
         {
-            throw new ArgumentException("At least one sub-agent must be provided.", nameof(agents));
+            throw new ArgumentException("At least one background agent must be provided.", nameof(agents));
         }
 
         return dict;
     }
 
     /// <summary>
-    /// Builds the default text listing available sub-agents and their descriptions.
+    /// Builds the default text listing available background agents and their descriptions.
     /// </summary>
     private static string BuildDefaultAgentListText(IReadOnlyDictionary<string, AIAgent> agents)
     {
         var sb = new StringBuilder();
-        sb.AppendLine("Available sub-agents:");
+        sb.AppendLine("Available background agents:");
         foreach (var kvp in agents)
         {
             sb.Append("- ").Append(kvp.Key);
@@ -156,12 +156,12 @@ public sealed class SubAgentsProvider : AIContextProvider
     /// <summary>
     /// Refreshes the status of in-flight tasks in the given state for the specified session.
     /// </summary>
-    private void TryRefreshTaskState(SubAgentState state, SubAgentRuntimeState runtimeState, AgentSession? session)
+    private void TryRefreshTaskState(BackgroundAgentState state, BackgroundAgentRuntimeState runtimeState, AgentSession? session)
     {
         bool changed = false;
-        foreach (SubTaskInfo task in state.Tasks)
+        foreach (BackgroundTaskInfo task in state.Tasks)
         {
-            if (task.Status != SubTaskStatus.Running)
+            if (task.Status != BackgroundTaskStatus.Running)
             {
                 continue;
             }
@@ -169,7 +169,7 @@ public sealed class SubAgentsProvider : AIContextProvider
             if (!runtimeState.InFlightTasks.TryGetValue(task.Id, out Task<AgentResponse>? inFlight))
             {
                 // In-flight reference lost (e.g., after restart/deserialization).
-                task.Status = SubTaskStatus.Lost;
+                task.Status = BackgroundTaskStatus.Lost;
                 changed = true;
                 continue;
             }
@@ -188,32 +188,32 @@ public sealed class SubAgentsProvider : AIContextProvider
     }
 
     /// <summary>
-    /// Finalizes a task by extracting results from the completed Task and updating the SubTaskInfo.
+    /// Finalizes a task by extracting results from the completed Task and updating the BackgroundTaskInfo.
     /// </summary>
-    private static void FinalizeTask(SubTaskInfo taskInfo, Task<AgentResponse> completedTask, SubAgentRuntimeState runtimeState)
+    private static void FinalizeTask(BackgroundTaskInfo taskInfo, Task<AgentResponse> completedTask, BackgroundAgentRuntimeState runtimeState)
     {
         if (completedTask.Status == TaskStatus.RanToCompletion)
         {
-            taskInfo.Status = SubTaskStatus.Completed;
+            taskInfo.Status = BackgroundTaskStatus.Completed;
 #pragma warning disable VSTHRD002 // Avoid problematic synchronous waits — task is already completed
             taskInfo.ResultText = completedTask.Result.Text;
 #pragma warning restore VSTHRD002
         }
         else if (completedTask.IsFaulted)
         {
-            taskInfo.Status = SubTaskStatus.Failed;
+            taskInfo.Status = BackgroundTaskStatus.Failed;
             taskInfo.ErrorText = completedTask.Exception?.InnerException?.Message ?? completedTask.Exception?.Message ?? "Unknown error";
         }
         else if (completedTask.IsCanceled)
         {
-            taskInfo.Status = SubTaskStatus.Failed;
+            taskInfo.Status = BackgroundTaskStatus.Failed;
             taskInfo.ErrorText = "Task was canceled.";
         }
 
         runtimeState.InFlightTasks.Remove(taskInfo.Id);
     }
 
-    private AITool[] CreateTools(SubAgentState state, SubAgentRuntimeState runtimeState, AgentSession? session)
+    private AITool[] CreateTools(BackgroundAgentState state, BackgroundAgentRuntimeState runtimeState, AgentSession? session)
     {
         var serializerOptions = AgentJsonUtilities.DefaultOptions;
 
@@ -221,43 +221,43 @@ public sealed class SubAgentsProvider : AIContextProvider
         [
             AIFunctionFactory.Create(
                 async (
-                    [Description("The name of the sub agent to delegate the task to.")] string agentName,
-                    [Description("The request to pass to the sub agent.")] string input,
+                    [Description("The name of the background agent to delegate the task to.")] string agentName,
+                    [Description("The request to pass to the background agent.")] string input,
                     [Description("A description of the task used to identify the task later.")] string description) =>
                 {
                     if (!this._agents.TryGetValue(agentName, out AIAgent? agent))
                     {
-                        return $"Error: No sub-agent found with name '{agentName}'. Available agents: {string.Join(", ", this._agents.Keys)}";
+                        return $"Error: No background agent found with name '{agentName}'. Available agents: {string.Join(", ", this._agents.Keys)}";
                     }
 
                     int taskId = state.NextTaskId++;
-                    var taskInfo = new SubTaskInfo
+                    var taskInfo = new BackgroundTaskInfo
                     {
                         Id = taskId,
                         AgentName = agentName,
                         Description = description,
-                        Status = SubTaskStatus.Running,
+                        Status = BackgroundTaskStatus.Running,
                     };
                     state.Tasks.Add(taskInfo);
 
-                    // Create a dedicated session for this sub-task so it can be continued later.
+                    // Create a dedicated session for this background task so it can be continued later.
                     AgentSession subSession = await agent.CreateSessionAsync().ConfigureAwait(false);
 
                     // Wrap in Task.Run to fork the ExecutionContext. AIAgent.RunAsync is a non-async
                     // method that synchronously sets the static AsyncLocal CurrentRunContext. Without
-                    // this isolation, the sub-agent's RunAsync would overwrite the outer (calling)
+                    // this isolation, the background agent's RunAsync would overwrite the outer (calling)
                     // agent's CurrentRunContext, corrupting all subsequent tool invocations in the
                     // same FICC batch.
                     runtimeState.InFlightTasks[taskId] = Task.Run(() => agent.RunAsync(input, subSession));
-                    runtimeState.SubTaskSessions[taskId] = subSession;
+                    runtimeState.BackgroundTaskSessions[taskId] = subSession;
 
                     this._sessionState.SaveState(session, state);
-                    return $"Sub-task {taskId} started on agent '{agentName}'.";
+                    return $"Background task {taskId} started on agent '{agentName}'.";
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_StartTask",
-                    Description = "Start a sub-task on a named sub-agent. Returns a confirmation message containing the task ID.",
+                    Name = "BackgroundAgents_StartTask",
+                    Description = "Start a background task on a named background agent. Returns a confirmation message containing the task ID.",
                     SerializerOptions = serializerOptions,
                 }),
 
@@ -287,7 +287,7 @@ public sealed class SubAgentsProvider : AIContextProvider
                         this._sessionState.SaveState(session, state);
 
                         // Check if any of the requested IDs are already complete.
-                        SubTaskInfo? alreadyComplete = state.Tasks.FirstOrDefault(t => taskIds.Contains(t.Id) && t.Status != SubTaskStatus.Running);
+                        BackgroundTaskInfo? alreadyComplete = state.Tasks.FirstOrDefault(t => taskIds.Contains(t.Id) && t.Status != BackgroundTaskStatus.Running);
                         if (alreadyComplete is not null)
                         {
                             return $"Task {alreadyComplete.Id} is not running; current status: {alreadyComplete.Status}.";
@@ -303,7 +303,7 @@ public sealed class SubAgentsProvider : AIContextProvider
                     var completedEntry = waitableTasks.First(t => t.Task == completedTask);
 
                     // Finalize the completed task.
-                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == completedEntry.Id);
+                    BackgroundTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == completedEntry.Id);
                     if (taskInfo is not null)
                     {
                         FinalizeTask(taskInfo, completedEntry.Task, runtimeState);
@@ -314,8 +314,8 @@ public sealed class SubAgentsProvider : AIContextProvider
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_WaitForFirstCompletion",
-                    Description = "Block until the first of the specified sub-tasks completes. Provide one or more task IDs. Returns a status message containing the ID of the task that completed first.",
+                    Name = "BackgroundAgents_WaitForFirstCompletion",
+                    Description = "Block until the first of the specified background tasks completes. Provide one or more task IDs. Returns a status message containing the ID of the task that completed first.",
                     SerializerOptions = serializerOptions,
                 }),
 
@@ -324,7 +324,7 @@ public sealed class SubAgentsProvider : AIContextProvider
                 {
                     this.TryRefreshTaskState(state, runtimeState, session);
 
-                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    BackgroundTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
                     if (taskInfo is null)
                     {
                         return $"Error: No task found with ID {taskId}.";
@@ -332,17 +332,17 @@ public sealed class SubAgentsProvider : AIContextProvider
 
                     return taskInfo.Status switch
                     {
-                        SubTaskStatus.Completed => taskInfo.ResultText ?? "(no output)",
-                        SubTaskStatus.Failed => $"Task failed: {taskInfo.ErrorText ?? "Unknown error"}",
-                        SubTaskStatus.Lost => "Task state was lost (reference unavailable).",
-                        SubTaskStatus.Running => $"Task {taskId} is still running.",
+                        BackgroundTaskStatus.Completed => taskInfo.ResultText ?? "(no output)",
+                        BackgroundTaskStatus.Failed => $"Task failed: {taskInfo.ErrorText ?? "Unknown error"}",
+                        BackgroundTaskStatus.Lost => "Task state was lost (reference unavailable).",
+                        BackgroundTaskStatus.Running => $"Task {taskId} is still running.",
                         _ => $"Task {taskId} has status: {taskInfo.Status}.",
                     };
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_GetTaskResults",
-                    Description = "Get the text output of a sub-task by its ID. Returns the result text if complete, or status information if still running or failed.",
+                    Name = "BackgroundAgents_GetTaskResults",
+                    Description = "Get the text output of a background task by its ID. Returns the result text if complete, or status information if still running or failed.",
                     SerializerOptions = serializerOptions,
                 }),
 
@@ -358,7 +358,7 @@ public sealed class SubAgentsProvider : AIContextProvider
 
                     var sb = new StringBuilder();
                     sb.AppendLine("Tasks:");
-                    foreach (SubTaskInfo task in state.Tasks)
+                    foreach (BackgroundTaskInfo task in state.Tasks)
                     {
                         sb.Append("- Task ").Append(task.Id).Append(" [").Append(task.Status).Append("] (").Append(task.AgentName).Append("): ").AppendLine(task.Description);
                     }
@@ -367,8 +367,8 @@ public sealed class SubAgentsProvider : AIContextProvider
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_GetAllTasks",
-                    Description = "List all sub-tasks with their IDs, statuses, agent names, and descriptions.",
+                    Name = "BackgroundAgents_GetAllTasks",
+                    Description = "List all background tasks with their IDs, statuses, agent names, and descriptions.",
                     SerializerOptions = serializerOptions,
                 }),
 
@@ -377,18 +377,18 @@ public sealed class SubAgentsProvider : AIContextProvider
                 {
                     this.TryRefreshTaskState(state, runtimeState, session);
 
-                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    BackgroundTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
                     if (taskInfo is null)
                     {
                         return $"Error: No task found with ID {taskId}.";
                     }
 
-                    if (taskInfo.Status == SubTaskStatus.Lost)
+                    if (taskInfo.Status == BackgroundTaskStatus.Lost)
                     {
                         return $"Error: Task {taskId} cannot be continued because its session was lost (e.g., after a session restore). Start a new task instead.";
                     }
 
-                    if (taskInfo.Status == SubTaskStatus.Running)
+                    if (taskInfo.Status == BackgroundTaskStatus.Running)
                     {
                         return $"Error: Task {taskId} is still running. Wait for it to complete before continuing.";
                     }
@@ -398,17 +398,17 @@ public sealed class SubAgentsProvider : AIContextProvider
                         return $"Error: Agent '{taskInfo.AgentName}' is no longer available.";
                     }
 
-                    if (!runtimeState.SubTaskSessions.TryGetValue(taskId, out AgentSession? subSession))
+                    if (!runtimeState.BackgroundTaskSessions.TryGetValue(taskId, out AgentSession? subSession))
                     {
                         return $"Error: Session for task {taskId} is no longer available.";
                     }
 
                     // Reset task state and start a new run on the existing session.
-                    taskInfo.Status = SubTaskStatus.Running;
+                    taskInfo.Status = BackgroundTaskStatus.Running;
                     taskInfo.ResultText = null;
                     taskInfo.ErrorText = null;
 
-                    // Wrap in Task.Run to isolate the ExecutionContext (see StartSubTask comment).
+                    // Wrap in Task.Run to isolate the ExecutionContext (see StartBackgroundTask comment).
                     runtimeState.InFlightTasks[taskId] = Task.Run(() => agent.RunAsync(text, subSession));
 
                     this._sessionState.SaveState(session, state);
@@ -416,8 +416,8 @@ public sealed class SubAgentsProvider : AIContextProvider
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_ContinueTask",
-                    Description = "Send follow-up input to a completed or failed sub-task to resume its work. The sub-task's session is preserved, so the agent retains conversational context.",
+                    Name = "BackgroundAgents_ContinueTask",
+                    Description = "Send follow-up input to a completed or failed background task to resume its work. The background task's session is preserved, so the agent retains conversational context.",
                     SerializerOptions = serializerOptions,
                 }),
 
@@ -426,13 +426,13 @@ public sealed class SubAgentsProvider : AIContextProvider
                 {
                     this.TryRefreshTaskState(state, runtimeState, session);
 
-                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    BackgroundTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
                     if (taskInfo is null)
                     {
                         return $"Error: No task found with ID {taskId}.";
                     }
 
-                    if (taskInfo.Status == SubTaskStatus.Running)
+                    if (taskInfo.Status == BackgroundTaskStatus.Running)
                     {
                         return $"Error: Task {taskId} is still running. Wait for it to complete before clearing.";
                     }
@@ -442,15 +442,15 @@ public sealed class SubAgentsProvider : AIContextProvider
 
                     // Clean up runtime references.
                     runtimeState.InFlightTasks.Remove(taskId);
-                    runtimeState.SubTaskSessions.Remove(taskId);
+                    runtimeState.BackgroundTaskSessions.Remove(taskId);
 
                     this._sessionState.SaveState(session, state);
                     return $"Task {taskId} cleared.";
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_ClearCompletedTask",
-                    Description = "Remove a completed or failed sub-task and release its session to free memory. Use this after retrieving results when you no longer need to continue the task.",
+                    Name = "BackgroundAgents_ClearCompletedTask",
+                    Description = "Remove a completed or failed background task and release its session to free memory. Use this after retrieving results when you no longer need to continue the task.",
                     SerializerOptions = serializerOptions,
                 }),
         ];

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundAgentsProviderOptions.cs

@@ -8,21 +8,21 @@ using Microsoft.Shared.DiagnosticIds;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Options controlling the behavior of <see cref="SubAgentsProvider"/>.
+/// Options controlling the behavior of <see cref="BackgroundAgentsProvider"/>.
 /// </summary>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class SubAgentsProviderOptions
+public sealed class BackgroundAgentsProviderOptions
 {
     /// <summary>
-    /// Gets or sets custom instructions provided to the agent for using the sub-agent tools.
+    /// Gets or sets custom instructions provided to the agent for using the background agent tools.
     /// </summary>
     /// <remarks>
-    /// Use the <c>{sub_agents}</c> placeholder to allow the provider to inject
-    /// the formatted list of available sub agents.
+    /// Use the <c>{background_agents}</c> placeholder to allow the provider to inject
+    /// the formatted list of available background agents.
     /// </remarks>
     /// <value>
     /// When <see langword="null"/> (the default), the provider uses built-in instructions
-    /// that guide the agent on how to use the sub-agent tools.
+    /// that guide the agent on how to use the background agent tools.
     /// The agent list is always appended after the instructions regardless of this setting.
     /// </value>
     public string? Instructions { get; set; }
@@ -33,7 +33,7 @@ public sealed class SubAgentsProviderOptions
     /// <value>
     /// When <see langword="null"/> (the default), the provider generates a standard list of agent names and descriptions.
     /// When set, this function receives the dictionary of available agents (keyed by name) and should return
-    /// a formatted string describing the available sub-agents.
+    /// a formatted string describing the available background agents.
     /// </value>
     public Func<IReadOnlyDictionary<string, AIAgent>, string>? AgentListBuilder { get; set; }
 }

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundTaskInfo.cs

@@ -7,43 +7,43 @@ using Microsoft.Shared.DiagnosticIds;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Represents the metadata and result of a sub-task managed by the <see cref="SubAgentsProvider"/>.
+/// Represents the metadata and result of a background task managed by the <see cref="BackgroundAgentsProvider"/>.
 /// </summary>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class SubTaskInfo
+public sealed class BackgroundTaskInfo
 {
     /// <summary>
-    /// Gets or sets the unique identifier for this sub-task.
+    /// Gets or sets the unique identifier for this background task.
     /// </summary>
     [JsonPropertyName("id")]
     public int Id { get; set; }
 
     /// <summary>
-    /// Gets or sets the name of the agent that is executing this sub-task.
+    /// Gets or sets the name of the agent that is executing this background task.
     /// </summary>
     [JsonPropertyName("agentName")]
     public string AgentName { get; set; } = string.Empty;
 
     /// <summary>
-    /// Gets or sets a description of what this sub-task is doing.
+    /// Gets or sets a description of what this background task is doing.
     /// </summary>
     [JsonPropertyName("description")]
     public string Description { get; set; } = string.Empty;
 
     /// <summary>
-    /// Gets or sets the current status of this sub-task.
+    /// Gets or sets the current status of this background task.
     /// </summary>
     [JsonPropertyName("status")]
-    public SubTaskStatus Status { get; set; }
+    public BackgroundTaskStatus Status { get; set; }
 
     /// <summary>
-    /// Gets or sets the text result of the sub-task, populated when the task completes successfully.
+    /// Gets or sets the text result of the background task, populated when the task completes successfully.
     /// </summary>
     [JsonPropertyName("resultText")]
     public string? ResultText { get; set; }
 
     /// <summary>
-    /// Gets or sets the error message if the sub-task failed.
+    /// Gets or sets the error message if the background task failed.
     /// </summary>
     [JsonPropertyName("errorText")]
     public string? ErrorText { get; set; }

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundTaskStatus.cs

@@ -6,28 +6,28 @@ using Microsoft.Shared.DiagnosticIds;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Represents the status of a sub-task managed by the <see cref="SubAgentsProvider"/>.
+/// Represents the status of a background task managed by the <see cref="BackgroundAgentsProvider"/>.
 /// </summary>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public enum SubTaskStatus
+public enum BackgroundTaskStatus
 {
     /// <summary>
-    /// The sub-task is currently running.
+    /// The background task is currently running.
     /// </summary>
     Running,
 
     /// <summary>
-    /// The sub-task completed successfully.
+    /// The background task completed successfully.
     /// </summary>
     Completed,
 
     /// <summary>
-    /// The sub-task failed with an error.
+    /// The background task failed with an error.
     /// </summary>
     Failed,
 
     /// <summary>
-    /// The sub-task's in-flight reference was lost (e.g., after a restart),
+    /// The background task's in-flight reference was lost (e.g., after a restart),
     /// and its final state cannot be determined.
     /// </summary>
     Lost,

dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs

@@ -55,7 +55,7 @@ public sealed class FileMemoryProvider : AIContextProvider, IDisposable
 
         - Use descriptive file names (e.g., "projectarchitecture.md", "userpreferences.md").
         - Include a description when saving a file to help with future discovery.
-        - Before starting new tasks, use FileMemory_ListFiles and FileMemory_SearchFiles to check for relevant existing memories.
+        - Before starting new tasks, use FileMemory_ListFiles and FileMemory_SearchFiles to check for relevant existing memories to avoid duplicate work.
         - Keep memories up-to-date by overwriting files when information changes.
         - When you receive large amounts of data (e.g., downloaded web pages, API responses, research results),
           save them to files if they will be required later, so that they are not lost when older context is compacted or truncated.

dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoCompleteInput.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the input for completing a single todo item via the <see cref="TodoProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+internal sealed class TodoCompleteInput
+{
+    /// <summary>
+    /// Gets or sets the ID of the todo item to mark as complete.
+    /// </summary>
+    [JsonPropertyName("id")]
+    public int Id { get; set; }
+
+    /// <summary>
+    /// Gets or sets the reason describing how or why the item was completed.
+    /// </summary>
+    [JsonPropertyName("reason")]
+    public string Reason { get; set; } = string.Empty;
+}

dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoProvider.cs

@@ -48,13 +48,13 @@ public sealed class TodoProvider : AIContextProvider, IDisposable
         You have access to a todo list for tracking work items.
         While planning, make sure that you break down complex tasks into manageable todo items and add them to the list.
         Ask questions from the user where clarification is needed to create effective todos.
-        If the user provides feedback on your plan, adjust your todos accordingly by adding new items or removing irrelevant ones.
+        If the user provides feedback on your plan, adjust your todos accordingly by adding new items or removing irrelevant/old ones.
         During execution, use the todo list to keep track of what needs to be done, mark items as complete when finished, and remove any items that are no longer needed.
-        When a user changes the topic or changes their mind, ensure that you update the todo list accordingly by removing irrelevant items or adding new ones as needed.
+        When a user changes the topic or changes their mind, ensure that you update the todo list accordingly by removing irrelevant/old items or adding new ones as needed.
         
         Use these tools to manage your tasks:
         - Use TodoList_Add to break down complex work into trackable items (supports adding one or many at once).
-        - Use TodoList_Complete to mark items as done when finished (supports one or many at once).
+        - Use TodoList_Complete to mark items as done when finished (supports one or many at once). Include a reason describing how the items were completed.
         - Use TodoList_GetRemaining to check what work is still pending.
         - Use TodoList_GetAll to review the full list including completed items.
         - Use TodoList_Remove to remove items that are no longer needed (supports one or many at once).
@@ -235,14 +235,14 @@ public sealed class TodoProvider : AIContextProvider, IDisposable
                 }),
 
             AIFunctionFactory.Create(
-                async (List<int> ids) =>
+                async (List<TodoCompleteInput> items) =>
                 {
                     SemaphoreSlim sessionLock = this.GetSessionLock(session);
                     await sessionLock.WaitAsync().ConfigureAwait(false);
                     try
                     {
                         TodoState state = this._sessionState.GetOrInitializeState(session);
-                        var idSet = new HashSet<int>(ids);
+                        var idSet = new HashSet<int>(items.Select(i => i.Id));
                         int completed = 0;
                         foreach (TodoItem item in state.Items)
                         {
@@ -268,7 +268,7 @@ public sealed class TodoProvider : AIContextProvider, IDisposable
                 new AIFunctionFactoryOptions
                 {
                     Name = "TodoList_Complete",
-                    Description = "Mark one or more todo items as complete by their IDs. Returns the number of items that were found and marked complete.",
+                    Description = "Mark one or more todo items as complete. Each entry has an ID and a reason describing how/why the item was completed. Returns the number of items that were found and marked complete.",
                     SerializerOptions = serializerOptions,
                 }),
 

dotnet/tests/Microsoft.Agents.AI.AGUI.UnitTests/AGUIStreamingMessageIdTests.cs

@@ -149,6 +149,93 @@ public sealed class AGUIStreamingMessageIdTests
             "ParentMessageId should have a generated fallback for empty provider MessageId");
     }
 
+    /// <summary>
+    /// Tool results are separate tool-role messages, so their fallback IDs must not
+    /// collide with the assistant message that requested the tool call.
+    /// </summary>
+    [Fact]
+    public async Task ToolResults_NullMessageId_GeneratesDistinctMessageIdAsync()
+    {
+        FunctionCallContent functionCall = new("call_abc123", "GetWeather")
+        {
+            Arguments = new Dictionary<string, object?> { ["location"] = "San Francisco" }
+        };
+
+        List<ChatResponseUpdate> providerUpdates =
+        [
+            new ChatResponseUpdate(ChatRole.Assistant, "Checking the weather"),
+            new ChatResponseUpdate
+            {
+                Role = ChatRole.Assistant,
+                Contents = [functionCall]
+            },
+            new ChatResponseUpdate(ChatRole.Tool, [new FunctionResultContent("call_abc123", "72F and sunny")])
+        ];
+
+        List<BaseEvent> aguiEvents = [];
+        await foreach (BaseEvent evt in providerUpdates.ToAsyncEnumerableAsync()
+            .AsAGUIEventStreamAsync("thread-1", "run-1", AGUIJsonSerializerContext.Default.Options))
+        {
+            aguiEvents.Add(evt);
+        }
+
+        TextMessageStartEvent textStart = Assert.Single(aguiEvents.OfType<TextMessageStartEvent>());
+        ToolCallStartEvent toolCallStart = Assert.Single(aguiEvents.OfType<ToolCallStartEvent>());
+        ToolCallResultEvent toolCallResult = Assert.Single(aguiEvents.OfType<ToolCallResultEvent>());
+
+        Assert.Equal(textStart.MessageId, toolCallStart.ParentMessageId);
+        Assert.Equal("call_abc123", toolCallResult.ToolCallId);
+        Assert.False(string.IsNullOrEmpty(toolCallResult.MessageId));
+        Assert.NotEqual(textStart.MessageId, toolCallResult.MessageId);
+    }
+
+    [Fact]
+    public async Task ToolResults_WithTextContent_GeneratesDistinctMessageIdAsync()
+    {
+        FunctionCallContent functionCall = new("call_abc123", "GetWeather")
+        {
+            Arguments = new Dictionary<string, object?> { ["location"] = "San Francisco" }
+        };
+
+        List<ChatResponseUpdate> providerUpdates =
+        [
+            new ChatResponseUpdate(ChatRole.Assistant, "Checking the weather"),
+            new ChatResponseUpdate
+            {
+                Role = ChatRole.Assistant,
+                Contents = [functionCall]
+            },
+            new ChatResponseUpdate
+            {
+                Role = ChatRole.Tool,
+                Contents =
+                [
+                    new TextContent("Tool says: "),
+                    new FunctionResultContent("call_abc123", "72F and sunny")
+                ]
+            }
+        ];
+
+        List<BaseEvent> aguiEvents = [];
+        await foreach (BaseEvent evt in providerUpdates.ToAsyncEnumerableAsync()
+            .AsAGUIEventStreamAsync("thread-1", "run-1", AGUIJsonSerializerContext.Default.Options))
+        {
+            aguiEvents.Add(evt);
+        }
+
+        TextMessageStartEvent[] textStarts = aguiEvents.OfType<TextMessageStartEvent>().ToArray();
+        TextMessageContentEvent toolText = Assert.Single(
+            aguiEvents.OfType<TextMessageContentEvent>(),
+            content => content.Delta == "Tool says: ");
+        ToolCallStartEvent toolCallStart = Assert.Single(aguiEvents.OfType<ToolCallStartEvent>());
+        ToolCallResultEvent toolCallResult = Assert.Single(aguiEvents.OfType<ToolCallResultEvent>());
+
+        Assert.Equal(textStarts[0].MessageId, toolCallStart.ParentMessageId);
+        Assert.NotEqual(textStarts[0].MessageId, toolCallResult.MessageId);
+        Assert.Equal(toolCallResult.MessageId, toolText.MessageId);
+        Assert.Equal(textStarts[^1].MessageId, toolCallResult.MessageId);
+    }
+
     /// <summary>
     /// When a provider properly sets MessageId (e.g., OpenAI), the AGUI pipeline
     /// produces valid events with correct messageId values.

dotnet/tests/Microsoft.Agents.AI.Abstractions.UnitTests/AgentSessionTests.cs

@@ -24,6 +24,45 @@ public class AgentSessionTests
         Assert.Equal("value1", session.StateBag.GetValue<string>("key1"));
     }
 
+    [Fact]
+    public void StateBag_Default_IsEmpty()
+    {
+        // Arrange & Act
+        var session = new TestAgentSession();
+
+        // Assert
+        Assert.Equal(0, session.StateBag.Count);
+    }
+
+    [Fact]
+    public void StateBag_MultipleKeys_StoreAndRetrieveIndependently()
+    {
+        // Arrange
+        var session = new TestAgentSession();
+
+        // Act
+        session.StateBag.SetValue("key1", "value1");
+        session.StateBag.SetValue("key2", "value2");
+
+        // Assert
+        Assert.Equal("value1", session.StateBag.GetValue<string>("key1"));
+        Assert.Equal("value2", session.StateBag.GetValue<string>("key2"));
+    }
+
+    [Fact]
+    public void StateBag_OverwriteValue_ReturnsUpdatedValue()
+    {
+        // Arrange
+        var session = new TestAgentSession();
+        session.StateBag.SetValue("key1", "original");
+
+        // Act
+        session.StateBag.SetValue("key1", "updated");
+
+        // Assert
+        Assert.Equal("updated", session.StateBag.GetValue<string>("key1"));
+    }
+
     #endregion
 
     #region GetService Method Tests

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/ProjectResponsesClientExtensionsTests.cs

@@ -129,6 +129,75 @@ public sealed class ProjectResponsesClientExtensionsTests
         Assert.DoesNotContain(IncludedResponseProperty.ReasoningEncryptedContent, createResponseOptions.IncludedProperties);
     }
 
+    /// <summary>
+    /// Verify that AsIChatClientWithStoredOutputDisabled preserves an existing RawRepresentationFactory
+    /// set on ChatOptions, augmenting it with StoredOutputEnabled and ReasoningEncryptedContent
+    /// rather than replacing it.
+    /// </summary>
+    [Fact]
+    public void AsIChatClientWithStoredOutputDisabled_PreservesExistingRawRepresentationFactory()
+    {
+        // Arrange
+        var responseClient = CreateTestClient();
+        var chatClient = responseClient.AsIChatClientWithStoredOutputDisabled();
+
+        // Simulate a caller setting their own RawRepresentationFactory on ChatOptions
+        // (e.g., to add WebSearchCallActionSources).
+        var options = new ChatOptions
+        {
+            RawRepresentationFactory = _ => new CreateResponseOptions
+            {
+                IncludedProperties = { IncludedResponseProperty.WebSearchCallActionSources },
+            },
+        };
+
+        // Act
+        var createResponseOptions = GetCreateResponseOptionsFromPipeline(chatClient, options);
+
+        // Assert
+        Assert.NotNull(createResponseOptions);
+        Assert.False(createResponseOptions.StoredOutputEnabled);
+        Assert.Contains(IncludedResponseProperty.ReasoningEncryptedContent, createResponseOptions.IncludedProperties);
+        Assert.Contains(IncludedResponseProperty.WebSearchCallActionSources, createResponseOptions.IncludedProperties);
+    }
+
+    /// <summary>
+    /// Verify that AsIChatClientWithStoredOutputDisabled does not duplicate ReasoningEncryptedContent
+    /// when the existing factory already includes it.
+    /// </summary>
+    [Fact]
+    public void AsIChatClientWithStoredOutputDisabled_DoesNotDuplicateReasoningEncryptedContent()
+    {
+        // Arrange
+        var responseClient = CreateTestClient();
+        var chatClient = responseClient.AsIChatClientWithStoredOutputDisabled();
+
+        // Simulate a caller that already includes ReasoningEncryptedContent
+        var options = new ChatOptions
+        {
+            RawRepresentationFactory = _ => new CreateResponseOptions
+            {
+                IncludedProperties = { IncludedResponseProperty.ReasoningEncryptedContent },
+            },
+        };
+
+        // Act
+        var createResponseOptions = GetCreateResponseOptionsFromPipeline(chatClient, options);
+
+        // Assert - ReasoningEncryptedContent should appear exactly once
+        Assert.NotNull(createResponseOptions);
+        int count = 0;
+        foreach (var prop in createResponseOptions.IncludedProperties)
+        {
+            if (prop == IncludedResponseProperty.ReasoningEncryptedContent)
+            {
+                count++;
+            }
+        }
+
+        Assert.Equal(1, count);
+    }
+
     /// <summary>
     /// Verify that AsIChatClientWithStoredOutputDisabled works with an optional deployment name.
     /// </summary>
@@ -153,6 +222,15 @@ public sealed class ProjectResponsesClientExtensionsTests
     /// by using reflection to access the configure action and invoking it on a test <see cref="ChatOptions"/>.
     /// </summary>
     private static CreateResponseOptions? GetCreateResponseOptionsFromPipeline(IChatClient chatClient)
+    {
+        return GetCreateResponseOptionsFromPipeline(chatClient, new ChatOptions());
+    }
+
+    /// <summary>
+    /// Overload that runs the configure action on caller-supplied <see cref="ChatOptions"/>,
+    /// useful for testing that existing factories are preserved.
+    /// </summary>
+    private static CreateResponseOptions? GetCreateResponseOptionsFromPipeline(IChatClient chatClient, ChatOptions options)
     {
         var configureField = chatClient.GetType().GetField("_configureOptions", BindingFlags.NonPublic | BindingFlags.Instance);
         Assert.NotNull(configureField);
@@ -160,7 +238,6 @@ public sealed class ProjectResponsesClientExtensionsTests
         var configureAction = configureField.GetValue(chatClient) as Action<ChatOptions>;
         Assert.NotNull(configureAction);
 
-        var options = new ChatOptions();
         configureAction(options);
 
         Assert.NotNull(options.RawRepresentationFactory);

dotnet/tests/Microsoft.Agents.AI.Harness.UnitTests/HarnessAgentOptionsTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using Moq;
+
 namespace Microsoft.Agents.AI.UnitTests;
 
 public class HarnessAgentOptionsTests
@@ -18,8 +20,22 @@ public class HarnessAgentOptionsTests
         Assert.Null(options.Name);
         Assert.Null(options.Description);
         Assert.Null(options.ChatOptions);
+        Assert.Null(options.HarnessInstructions);
         Assert.Null(options.ChatHistoryProvider);
         Assert.Null(options.AIContextProviders);
+        Assert.False(options.DisableToolApproval);
+        Assert.False(options.DisableFileMemory);
+        Assert.False(options.DisableFileAccess);
+        Assert.False(options.DisableWebSearch);
+        Assert.False(options.DisableTodoProvider);
+        Assert.False(options.DisableAgentModeProvider);
+        Assert.False(options.DisableAgentSkillsProvider);
+        Assert.False(options.DisableOpenTelemetry);
+        Assert.Null(options.MaximumIterationsPerRequest);
+        Assert.Null(options.FileMemoryStore);
+        Assert.Null(options.FileAccessStore);
+        Assert.Null(options.AgentModeProviderOptions);
+        Assert.Null(options.AgentSkillsSource);
     }
 
     /// <summary>
@@ -31,6 +47,10 @@ public class HarnessAgentOptionsTests
         // Arrange
         var chatHistoryProvider = new InMemoryChatHistoryProvider();
         var contextProviders = new AIContextProvider[] { new TodoProvider() };
+        var fileMemoryStore = new Mock<AgentFileStore>().Object;
+        var fileAccessStore = new Mock<AgentFileStore>().Object;
+        var agentModeOptions = new AgentModeProviderOptions();
+        var skillsSource = new Mock<AgentSkillsSource>().Object;
 
         // Act
         var options = new HarnessAgentOptions
@@ -39,8 +59,22 @@ public class HarnessAgentOptionsTests
             Name = "test-name",
             Description = "test-description",
             ChatOptions = new() { Temperature = 0.5f, Instructions = "custom instructions" },
+            HarnessInstructions = "custom harness instructions",
             ChatHistoryProvider = chatHistoryProvider,
             AIContextProviders = contextProviders,
+            MaximumIterationsPerRequest = 42,
+            DisableToolApproval = true,
+            DisableFileMemory = true,
+            FileMemoryStore = fileMemoryStore,
+            DisableFileAccess = true,
+            FileAccessStore = fileAccessStore,
+            DisableWebSearch = true,
+            DisableTodoProvider = true,
+            DisableAgentModeProvider = true,
+            AgentModeProviderOptions = agentModeOptions,
+            DisableAgentSkillsProvider = true,
+            AgentSkillsSource = skillsSource,
+            DisableOpenTelemetry = true,
         };
 
         // Assert
@@ -50,7 +84,21 @@ public class HarnessAgentOptionsTests
         Assert.NotNull(options.ChatOptions);
         Assert.Equal(0.5f, options.ChatOptions!.Temperature);
         Assert.Equal("custom instructions", options.ChatOptions.Instructions);
+        Assert.Equal("custom harness instructions", options.HarnessInstructions);
         Assert.Same(chatHistoryProvider, options.ChatHistoryProvider);
         Assert.Same(contextProviders, options.AIContextProviders);
+        Assert.Equal(42, options.MaximumIterationsPerRequest);
+        Assert.True(options.DisableToolApproval);
+        Assert.True(options.DisableFileMemory);
+        Assert.Same(fileMemoryStore, options.FileMemoryStore);
+        Assert.True(options.DisableFileAccess);
+        Assert.Same(fileAccessStore, options.FileAccessStore);
+        Assert.True(options.DisableWebSearch);
+        Assert.True(options.DisableTodoProvider);
+        Assert.True(options.DisableAgentModeProvider);
+        Assert.Same(agentModeOptions, options.AgentModeProviderOptions);
+        Assert.True(options.DisableAgentSkillsProvider);
+        Assert.Same(skillsSource, options.AgentSkillsSource);
+        Assert.True(options.DisableOpenTelemetry);
     }
 }

dotnet/tests/Microsoft.Agents.AI.Harness.UnitTests/HarnessAgentTests.cs

@@ -15,6 +15,21 @@ public class HarnessAgentTests
     private const int TestMaxContextWindowTokens = 100_000;
     private const int TestMaxOutputTokens = 10_000;
 
+    /// <summary>
+    /// Creates a HarnessAgent with all default features disabled to isolate tests for specific behaviors.
+    /// </summary>
+    private static HarnessAgentOptions CreateAllDisabledOptions() => new()
+    {
+        DisableToolApproval = true,
+        DisableOpenTelemetry = true,
+        DisableFileMemory = true,
+        DisableFileAccess = true,
+        DisableWebSearch = true,
+        DisableTodoProvider = true,
+        DisableAgentModeProvider = true,
+        DisableAgentSkillsProvider = true,
+    };
+
     #region Constructor Validation
 
     /// <summary>
@@ -81,13 +96,12 @@ public class HarnessAgentTests
     {
         // Arrange
         var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.Name = "TestAgent";
+        options.Description = "A test agent";
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
-        {
-            Name = "TestAgent",
-            Description = "A test agent",
-        });
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
 
         // Assert
         Assert.Equal("TestAgent", agent.Name);
@@ -102,12 +116,11 @@ public class HarnessAgentTests
     {
         // Arrange
         var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.Id = "my-agent-id";
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
-        {
-            Id = "my-agent-id",
-        });
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
 
         // Assert
         Assert.Equal("my-agent-id", agent.Id);
@@ -127,7 +140,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -136,19 +149,18 @@ public class HarnessAgentTests
     }
 
     /// <summary>
-    /// Verify that default instructions are used when options is provided but ChatOptions.Instructions is null.
+    /// Verify that default instructions are used when options is provided but neither HarnessInstructions nor ChatOptions.Instructions is set.
     /// </summary>
     [Fact]
-    public void Instructions_DefaultsWhenChatOptionsInstructionsIsNull()
+    public void Instructions_DefaultsWhenBothNull()
     {
         // Arrange
         var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.ChatOptions = new ChatOptions { Temperature = 0.5f };
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
-        {
-            ChatOptions = new ChatOptions { Temperature = 0.5f },
-        });
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -157,24 +169,106 @@ public class HarnessAgentTests
     }
 
     /// <summary>
-    /// Verify that ChatOptions.Instructions overrides the defaults.
+    /// Verify that ChatOptions.Instructions is appended to the default HarnessInstructions.
     /// </summary>
     [Fact]
-    public void Instructions_CanBeOverriddenViaChatOptions()
+    public void Instructions_CombinesDefaultHarnessWithAgentInstructions()
     {
         // Arrange
         var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.ChatOptions = new ChatOptions { Instructions = "You are a custom assistant." };
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
-        {
-            ChatOptions = new ChatOptions { Instructions = "You are a custom assistant." },
-        });
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
         Assert.NotNull(innerAgent);
-        Assert.Equal("You are a custom assistant.", innerAgent!.Instructions);
+        var expected = $"{HarnessAgent.DefaultInstructions}\n\nYou are a custom assistant.";
+        Assert.Equal(expected, innerAgent!.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that custom HarnessInstructions replaces the default.
+    /// </summary>
+    [Fact]
+    public void Instructions_CustomHarnessInstructionsReplacesDefault()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.HarnessInstructions = "Custom harness rules.";
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        Assert.Equal("Custom harness rules.", innerAgent!.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that custom HarnessInstructions and ChatOptions.Instructions are combined.
+    /// </summary>
+    [Fact]
+    public void Instructions_CombinesCustomHarnessWithAgentInstructions()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.HarnessInstructions = "Custom harness rules.";
+        options.ChatOptions = new ChatOptions { Instructions = "You are a research agent." };
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        Assert.Equal("Custom harness rules.\n\nYou are a research agent.", innerAgent!.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that empty HarnessInstructions omits harness portion, using only agent instructions.
+    /// </summary>
+    [Fact]
+    public void Instructions_EmptyHarnessInstructionsUsesOnlyAgentInstructions()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.HarnessInstructions = string.Empty;
+        options.ChatOptions = new ChatOptions { Instructions = "Agent only instructions." };
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        Assert.Equal("Agent only instructions.", innerAgent!.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that empty HarnessInstructions with no agent instructions results in empty string.
+    /// </summary>
+    [Fact]
+    public void Instructions_EmptyHarnessInstructionsWithNoAgentInstructions()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.HarnessInstructions = string.Empty;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        Assert.Equal(string.Empty, innerAgent!.Instructions);
     }
 
     #endregion
@@ -191,7 +285,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -208,12 +302,11 @@ public class HarnessAgentTests
         // Arrange
         var chatClient = new Mock<IChatClient>().Object;
         var customProvider = new InMemoryChatHistoryProvider();
+        var options = CreateAllDisabledOptions();
+        options.ChatHistoryProvider = customProvider;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
-        {
-            ChatHistoryProvider = customProvider,
-        });
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -235,7 +328,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -256,7 +349,7 @@ public class HarnessAgentTests
         var rawClient = mockClient.Object;
 
         // Act
-        var agent = new HarnessAgent(rawClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var agent = new HarnessAgent(rawClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert — the pipeline wraps the raw client, so the outer client is not the same object.
@@ -269,45 +362,45 @@ public class HarnessAgentTests
     #region AIContextProviders
 
     /// <summary>
-    /// Verify that additional AIContextProviders from options are passed to the inner ChatClientAgent,
-    /// not merged into the chat client builder pipeline.
+    /// Verify that additional AIContextProviders from options are passed to the inner ChatClientAgent.
     /// </summary>
     [Fact]
     public void AIContextProviders_ArePassedToInnerAgent()
     {
         // Arrange
         var chatClient = new Mock<IChatClient>().Object;
-        var todoProvider = new TodoProvider();
+        var customProvider = new TodoProvider();
+        var options = CreateAllDisabledOptions();
+        options.AIContextProviders = [customProvider];
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
-        {
-            AIContextProviders = [todoProvider],
-        });
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
-        // Assert — the TodoProvider should appear in the inner agent's AIContextProviders.
+        // Assert — the custom provider should appear in the inner agent's AIContextProviders.
         Assert.NotNull(innerAgent);
         Assert.NotNull(innerAgent!.AIContextProviders);
-        Assert.Contains(todoProvider, innerAgent.AIContextProviders!);
+        Assert.Contains(customProvider, innerAgent.AIContextProviders!);
     }
 
     /// <summary>
-    /// Verify that when no AIContextProviders are specified, the inner agent has no additional providers.
+    /// Verify that when all default providers are disabled and no user AIContextProviders are specified,
+    /// the inner agent has an empty providers list.
     /// </summary>
     [Fact]
-    public void AIContextProviders_IsNullWhenNoneSpecified()
+    public void AIContextProviders_IsEmptyWhenAllDisabledAndNoneSpecified()
     {
         // Arrange
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
         Assert.NotNull(innerAgent);
-        Assert.Null(innerAgent!.AIContextProviders);
+        Assert.NotNull(innerAgent!.AIContextProviders);
+        Assert.Empty(innerAgent.AIContextProviders!);
     }
 
     #endregion
@@ -332,13 +425,10 @@ public class HarnessAgentTests
             .Callback<IEnumerable<ChatMessage>, ChatOptions?, CancellationToken>((_, opts, _) => capturedOptions = opts)
             .ReturnsAsync(new ChatResponse(new ChatMessage(ChatRole.Assistant, "Done")));
 
-        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
-        {
-            ChatOptions = new ChatOptions
-            {
-                Tools = [tool],
-            },
-        });
+        var options = CreateAllDisabledOptions();
+        options.ChatOptions = new ChatOptions { Tools = [tool] };
+
+        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
         var session = await agent.CreateSessionAsync();
 
         // Act
@@ -389,7 +479,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
 
         // Assert
         Assert.Same(agent, agent.GetService<HarnessAgent>());
@@ -405,7 +495,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
 
         // Assert
         Assert.NotNull(agent.GetService<ChatClientAgent>());
@@ -430,7 +520,7 @@ public class HarnessAgentTests
                 It.IsAny<CancellationToken>()))
             .ReturnsAsync(new ChatResponse(new ChatMessage(ChatRole.Assistant, "Hello!")));
 
-        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
         var session = await agent.CreateSessionAsync();
 
         // Act
@@ -487,19 +577,19 @@ public class HarnessAgentTests
     {
         // Arrange
         var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.Name = "ExtensionAgent";
+        options.ChatOptions = new ChatOptions { Instructions = "Custom instructions" };
 
         // Act
-        var agent = chatClient.AsHarnessAgent(TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
-        {
-            Name = "ExtensionAgent",
-            ChatOptions = new ChatOptions { Instructions = "Custom instructions" },
-        });
+        var agent = chatClient.AsHarnessAgent(TestMaxContextWindowTokens, TestMaxOutputTokens, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
         Assert.Equal("ExtensionAgent", agent.Name);
         Assert.NotNull(innerAgent);
-        Assert.Equal("Custom instructions", innerAgent!.Instructions);
+        var expected = $"{HarnessAgent.DefaultInstructions}\n\nCustom instructions";
+        Assert.Equal(expected, innerAgent!.Instructions);
     }
 
     /// <summary>
@@ -513,4 +603,579 @@ public class HarnessAgentTests
     }
 
     #endregion
+
+    #region Feature: ToolApproval
+
+    /// <summary>
+    /// Verify that ToolApprovalAgent is included in the pipeline by default.
+    /// </summary>
+    [Fact]
+    public void ToolApproval_IncludedByDefault()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.DisableToolApproval = false;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+
+        // Assert
+        Assert.NotNull(agent.GetService<ToolApprovalAgent>());
+    }
+
+    /// <summary>
+    /// Verify that ToolApprovalAgent is excluded when disabled.
+    /// </summary>
+    [Fact]
+    public void ToolApproval_ExcludedWhenDisabled()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+
+        // Assert
+        Assert.Null(agent.GetService<ToolApprovalAgent>());
+    }
+
+    #endregion
+
+    #region Feature: OpenTelemetry
+
+    /// <summary>
+    /// Verify that OpenTelemetryAgent is included in the pipeline by default.
+    /// </summary>
+    [Fact]
+    public void OpenTelemetry_IncludedByDefault()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.DisableOpenTelemetry = false;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+
+        // Assert
+        Assert.NotNull(agent.GetService<OpenTelemetryAgent>());
+    }
+
+    /// <summary>
+    /// Verify that OpenTelemetryAgent is excluded when disabled.
+    /// </summary>
+    [Fact]
+    public void OpenTelemetry_ExcludedWhenDisabled()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+
+        // Assert
+        Assert.Null(agent.GetService<OpenTelemetryAgent>());
+    }
+
+    #endregion
+
+    #region Feature: WebSearch
+
+    /// <summary>
+    /// Verify that HostedWebSearchTool is added to ChatOptions.Tools by default.
+    /// </summary>
+    [Fact]
+    public async Task WebSearch_IncludedByDefaultAsync()
+    {
+        // Arrange
+        var mockClient = new Mock<IChatClient>();
+        ChatOptions? capturedOptions = null;
+        mockClient
+            .Setup(c => c.GetResponseAsync(It.IsAny<IEnumerable<ChatMessage>>(), It.IsAny<ChatOptions>(), It.IsAny<CancellationToken>()))
+            .Callback<IEnumerable<ChatMessage>, ChatOptions?, CancellationToken>((_, opts, _) => capturedOptions = opts)
+            .ReturnsAsync(new ChatResponse(new ChatMessage(ChatRole.Assistant, "Done")));
+
+        var options = CreateAllDisabledOptions();
+        options.DisableWebSearch = false;
+
+        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var session = await agent.CreateSessionAsync();
+
+        // Act
+        await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")], session);
+
+        // Assert
+        Assert.NotNull(capturedOptions?.Tools);
+        Assert.Contains(capturedOptions!.Tools!, t => t is HostedWebSearchTool);
+    }
+
+    /// <summary>
+    /// Verify that HostedWebSearchTool is not added when disabled.
+    /// </summary>
+    [Fact]
+    public async Task WebSearch_ExcludedWhenDisabledAsync()
+    {
+        // Arrange
+        var mockClient = new Mock<IChatClient>();
+        ChatOptions? capturedOptions = null;
+        mockClient
+            .Setup(c => c.GetResponseAsync(It.IsAny<IEnumerable<ChatMessage>>(), It.IsAny<ChatOptions>(), It.IsAny<CancellationToken>()))
+            .Callback<IEnumerable<ChatMessage>, ChatOptions?, CancellationToken>((_, opts, _) => capturedOptions = opts)
+            .ReturnsAsync(new ChatResponse(new ChatMessage(ChatRole.Assistant, "Done")));
+
+        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var session = await agent.CreateSessionAsync();
+
+        // Act
+        await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")], session);
+
+        // Assert
+        Assert.NotNull(capturedOptions);
+        if (capturedOptions!.Tools != null)
+        {
+            Assert.DoesNotContain(capturedOptions.Tools, t => t is HostedWebSearchTool);
+        }
+    }
+
+    /// <summary>
+    /// Verify that user-provided tools are preserved alongside the default HostedWebSearchTool.
+    /// </summary>
+    [Fact]
+    public async Task WebSearch_CoexistsWithUserToolsAsync()
+    {
+        // Arrange
+        var mockClient = new Mock<IChatClient>();
+        ChatOptions? capturedOptions = null;
+        mockClient
+            .Setup(c => c.GetResponseAsync(It.IsAny<IEnumerable<ChatMessage>>(), It.IsAny<ChatOptions>(), It.IsAny<CancellationToken>()))
+            .Callback<IEnumerable<ChatMessage>, ChatOptions?, CancellationToken>((_, opts, _) => capturedOptions = opts)
+            .ReturnsAsync(new ChatResponse(new ChatMessage(ChatRole.Assistant, "Done")));
+
+        var userTool = AIFunctionFactory.Create(() => "test", "UserTool");
+        var options = CreateAllDisabledOptions();
+        options.DisableWebSearch = false;
+        options.ChatOptions = new ChatOptions { Tools = [userTool] };
+
+        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var session = await agent.CreateSessionAsync();
+
+        // Act
+        await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")], session);
+
+        // Assert
+        Assert.NotNull(capturedOptions?.Tools);
+        Assert.Contains(capturedOptions!.Tools!, t => t is HostedWebSearchTool);
+        Assert.Contains(capturedOptions.Tools!, t => t == userTool);
+    }
+
+    #endregion
+
+    #region Feature: TodoProvider
+
+    /// <summary>
+    /// Verify that TodoProvider is included in AIContextProviders by default.
+    /// </summary>
+    [Fact]
+    public void TodoProvider_IncludedByDefault()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.DisableTodoProvider = false;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent?.AIContextProviders);
+        Assert.Contains(innerAgent!.AIContextProviders!, p => p is TodoProvider);
+    }
+
+    /// <summary>
+    /// Verify that TodoProvider is excluded when disabled.
+    /// </summary>
+    [Fact]
+    public void TodoProvider_ExcludedWhenDisabled()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        if (innerAgent!.AIContextProviders != null)
+        {
+            Assert.DoesNotContain(innerAgent.AIContextProviders, p => p is TodoProvider);
+        }
+    }
+
+    #endregion
+
+    #region Feature: AgentModeProvider
+
+    /// <summary>
+    /// Verify that AgentModeProvider is included in AIContextProviders by default.
+    /// </summary>
+    [Fact]
+    public void AgentModeProvider_IncludedByDefault()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.DisableAgentModeProvider = false;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent?.AIContextProviders);
+        Assert.Contains(innerAgent!.AIContextProviders!, p => p is AgentModeProvider);
+    }
+
+    /// <summary>
+    /// Verify that AgentModeProvider is excluded when disabled.
+    /// </summary>
+    [Fact]
+    public void AgentModeProvider_ExcludedWhenDisabled()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        if (innerAgent!.AIContextProviders != null)
+        {
+            Assert.DoesNotContain(innerAgent.AIContextProviders, p => p is AgentModeProvider);
+        }
+    }
+
+    /// <summary>
+    /// Verify that custom AgentModeProviderOptions are passed through.
+    /// </summary>
+    [Fact]
+    public void AgentModeProvider_UsesCustomOptions()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.DisableAgentModeProvider = false;
+        options.AgentModeProviderOptions = new AgentModeProviderOptions
+        {
+            Modes =
+            [
+                new AgentModeProviderOptions.AgentMode("custom-mode", "A custom mode for testing"),
+            ],
+            DefaultMode = "custom-mode",
+        };
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert — AgentModeProvider should be present (we can't easily inspect its internal options,
+        // but we verify it is created and present).
+        Assert.NotNull(innerAgent?.AIContextProviders);
+        Assert.Contains(innerAgent!.AIContextProviders!, p => p is AgentModeProvider);
+    }
+
+    #endregion
+
+    #region Feature: FileMemoryProvider
+
+    /// <summary>
+    /// Verify that FileMemoryProvider is included in AIContextProviders by default.
+    /// </summary>
+    [Fact]
+    public void FileMemoryProvider_IncludedByDefault()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.DisableFileMemory = false;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent?.AIContextProviders);
+        Assert.Contains(innerAgent!.AIContextProviders!, p => p is FileMemoryProvider);
+    }
+
+    /// <summary>
+    /// Verify that FileMemoryProvider is excluded when disabled.
+    /// </summary>
+    [Fact]
+    public void FileMemoryProvider_ExcludedWhenDisabled()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        if (innerAgent!.AIContextProviders != null)
+        {
+            Assert.DoesNotContain(innerAgent.AIContextProviders, p => p is FileMemoryProvider);
+        }
+    }
+
+    /// <summary>
+    /// Verify that a custom FileMemoryStore is used when provided.
+    /// </summary>
+    [Fact]
+    public void FileMemoryProvider_UsesCustomStore()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var customStore = new Mock<AgentFileStore>().Object;
+        var options = CreateAllDisabledOptions();
+        options.DisableFileMemory = false;
+        options.FileMemoryStore = customStore;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert — FileMemoryProvider should be present with the custom store.
+        Assert.NotNull(innerAgent?.AIContextProviders);
+        Assert.Contains(innerAgent!.AIContextProviders!, p => p is FileMemoryProvider);
+    }
+
+    #endregion
+
+    #region Feature: FileAccessProvider
+
+    /// <summary>
+    /// Verify that FileAccessProvider is included in AIContextProviders by default.
+    /// </summary>
+    [Fact]
+    public void FileAccessProvider_IncludedByDefault()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.DisableFileAccess = false;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent?.AIContextProviders);
+        Assert.Contains(innerAgent!.AIContextProviders!, p => p is FileAccessProvider);
+    }
+
+    /// <summary>
+    /// Verify that FileAccessProvider is excluded when disabled.
+    /// </summary>
+    [Fact]
+    public void FileAccessProvider_ExcludedWhenDisabled()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        if (innerAgent!.AIContextProviders != null)
+        {
+            Assert.DoesNotContain(innerAgent.AIContextProviders, p => p is FileAccessProvider);
+        }
+    }
+
+    /// <summary>
+    /// Verify that a custom FileAccessStore is used when provided.
+    /// </summary>
+    [Fact]
+    public void FileAccessProvider_UsesCustomStore()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var customStore = new Mock<AgentFileStore>().Object;
+        var options = CreateAllDisabledOptions();
+        options.DisableFileAccess = false;
+        options.FileAccessStore = customStore;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert — FileAccessProvider should be present with the custom store.
+        Assert.NotNull(innerAgent?.AIContextProviders);
+        Assert.Contains(innerAgent!.AIContextProviders!, p => p is FileAccessProvider);
+    }
+
+    #endregion
+
+    #region Feature: AgentSkillsProvider
+
+    /// <summary>
+    /// Verify that AgentSkillsProvider is included in AIContextProviders by default.
+    /// </summary>
+    [Fact]
+    public void AgentSkillsProvider_IncludedByDefault()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.DisableAgentSkillsProvider = false;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent?.AIContextProviders);
+        Assert.Contains(innerAgent!.AIContextProviders!, p => p is AgentSkillsProvider);
+    }
+
+    /// <summary>
+    /// Verify that AgentSkillsProvider is excluded when disabled.
+    /// </summary>
+    [Fact]
+    public void AgentSkillsProvider_ExcludedWhenDisabled()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        if (innerAgent!.AIContextProviders != null)
+        {
+            Assert.DoesNotContain(innerAgent.AIContextProviders, p => p is AgentSkillsProvider);
+        }
+    }
+
+    /// <summary>
+    /// Verify that a custom AgentSkillsSource is used when provided.
+    /// </summary>
+    [Fact]
+    public void AgentSkillsProvider_UsesCustomSource()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var customSource = new Mock<AgentSkillsSource>().Object;
+        var options = CreateAllDisabledOptions();
+        options.DisableAgentSkillsProvider = false;
+        options.AgentSkillsSource = customSource;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert — AgentSkillsProvider should be present.
+        Assert.NotNull(innerAgent?.AIContextProviders);
+        Assert.Contains(innerAgent!.AIContextProviders!, p => p is AgentSkillsProvider);
+    }
+
+    #endregion
+
+    #region Feature: MaximumIterationsPerRequest
+
+    /// <summary>
+    /// Verify that MaximumIterationsPerRequest configures the FunctionInvokingChatClient.
+    /// </summary>
+    [Fact]
+    public void MaximumIterationsPerRequest_ConfiguresFunctionInvokingChatClient()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = CreateAllDisabledOptions();
+        options.MaximumIterationsPerRequest = 42;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+        var ficc = innerAgent!.ChatClient.GetService<FunctionInvokingChatClient>();
+
+        // Assert
+        Assert.NotNull(ficc);
+        Assert.Equal(42, ficc!.MaximumIterationsPerRequest);
+    }
+
+    /// <summary>
+    /// Verify that the default MaximumIterationsPerRequest is used when not set.
+    /// </summary>
+    [Fact]
+    public void MaximumIterationsPerRequest_UsesDefaultWhenNotSet()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var innerAgent = agent.GetService<ChatClientAgent>();
+        var ficc = innerAgent!.ChatClient.GetService<FunctionInvokingChatClient>();
+
+        // Assert — default is not 0 and not our custom value.
+        Assert.NotNull(ficc);
+        Assert.NotEqual(0, ficc!.MaximumIterationsPerRequest);
+    }
+
+    #endregion
+
+    #region Feature: All Defaults Enabled
+
+    /// <summary>
+    /// Verify that when no options are provided, all default features are enabled.
+    /// </summary>
+    [Fact]
+    public async Task AllDefaults_AllFeaturesEnabledAsync()
+    {
+        // Arrange
+        var mockClient = new Mock<IChatClient>();
+        ChatOptions? capturedOptions = null;
+        mockClient
+            .Setup(c => c.GetResponseAsync(It.IsAny<IEnumerable<ChatMessage>>(), It.IsAny<ChatOptions>(), It.IsAny<CancellationToken>()))
+            .Callback<IEnumerable<ChatMessage>, ChatOptions?, CancellationToken>((_, opts, _) => capturedOptions = opts)
+            .ReturnsAsync(new ChatResponse(new ChatMessage(ChatRole.Assistant, "Done")));
+
+        // Act
+        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert — agent wrappers
+        Assert.NotNull(agent.GetService<ToolApprovalAgent>());
+        Assert.NotNull(agent.GetService<OpenTelemetryAgent>());
+
+        // Assert — default context providers
+        Assert.NotNull(innerAgent);
+        Assert.NotNull(innerAgent!.AIContextProviders);
+
+        var providers = innerAgent.AIContextProviders!.ToList();
+        Assert.Contains(providers, p => p is TodoProvider);
+        Assert.Contains(providers, p => p is AgentModeProvider);
+        Assert.Contains(providers, p => p is FileMemoryProvider);
+        Assert.Contains(providers, p => p is FileAccessProvider);
+        Assert.Contains(providers, p => p is AgentSkillsProvider);
+
+        // Assert — HostedWebSearchTool is present in the tools sent to the model
+        var session = await agent.CreateSessionAsync();
+        await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")], session);
+        Assert.NotNull(capturedOptions?.Tools);
+        Assert.Contains(capturedOptions!.Tools!, t => t is HostedWebSearchTool);
+    }
+
+    #endregion
 }

dotnet/tests/Microsoft.Agents.AI.OpenAI.UnitTests/Extensions/OpenAIResponseClientExtensionsTests.cs

@@ -370,6 +370,75 @@ public sealed class OpenAIResponseClientExtensionsTests
         Assert.DoesNotContain(IncludedResponseProperty.ReasoningEncryptedContent, createResponseOptions.IncludedProperties);
     }
 
+    /// <summary>
+    /// Verify that AsIChatClientWithStoredOutputDisabled preserves an existing RawRepresentationFactory
+    /// set on ChatOptions, augmenting it with StoredOutputEnabled and ReasoningEncryptedContent
+    /// rather than replacing it.
+    /// </summary>
+    [Fact]
+    public void AsIChatClientWithStoredOutputDisabled_PreservesExistingRawRepresentationFactory()
+    {
+        // Arrange
+        var responseClient = new TestOpenAIResponseClient();
+        var chatClient = responseClient.AsIChatClientWithStoredOutputDisabled();
+
+        // Simulate a caller setting their own RawRepresentationFactory on ChatOptions
+        // (e.g., to add WebSearchCallActionSources).
+        var options = new ChatOptions
+        {
+            RawRepresentationFactory = _ => new CreateResponseOptions
+            {
+                IncludedProperties = { IncludedResponseProperty.WebSearchCallActionSources },
+            },
+        };
+
+        // Act
+        var createResponseOptions = GetCreateResponseOptionsFromPipeline(chatClient, options);
+
+        // Assert
+        Assert.NotNull(createResponseOptions);
+        Assert.False(createResponseOptions.StoredOutputEnabled);
+        Assert.Contains(IncludedResponseProperty.ReasoningEncryptedContent, createResponseOptions.IncludedProperties);
+        Assert.Contains(IncludedResponseProperty.WebSearchCallActionSources, createResponseOptions.IncludedProperties);
+    }
+
+    /// <summary>
+    /// Verify that AsIChatClientWithStoredOutputDisabled does not duplicate ReasoningEncryptedContent
+    /// when the existing factory already includes it.
+    /// </summary>
+    [Fact]
+    public void AsIChatClientWithStoredOutputDisabled_DoesNotDuplicateReasoningEncryptedContent()
+    {
+        // Arrange
+        var responseClient = new TestOpenAIResponseClient();
+        var chatClient = responseClient.AsIChatClientWithStoredOutputDisabled();
+
+        // Simulate a caller that already includes ReasoningEncryptedContent
+        var options = new ChatOptions
+        {
+            RawRepresentationFactory = _ => new CreateResponseOptions
+            {
+                IncludedProperties = { IncludedResponseProperty.ReasoningEncryptedContent },
+            },
+        };
+
+        // Act
+        var createResponseOptions = GetCreateResponseOptionsFromPipeline(chatClient, options);
+
+        // Assert - ReasoningEncryptedContent should appear exactly once
+        Assert.NotNull(createResponseOptions);
+        int count = 0;
+        foreach (var prop in createResponseOptions.IncludedProperties)
+        {
+            if (prop == IncludedResponseProperty.ReasoningEncryptedContent)
+            {
+                count++;
+            }
+        }
+
+        Assert.Equal(1, count);
+    }
+
     /// <summary>
     /// A simple test IServiceProvider implementation for testing.
     /// </summary>
@@ -394,6 +463,15 @@ public sealed class OpenAIResponseClientExtensionsTests
     /// by using reflection to access the configure action and invoking it on a test <see cref="ChatOptions"/>.
     /// </summary>
     private static CreateResponseOptions? GetCreateResponseOptionsFromPipeline(IChatClient chatClient)
+    {
+        return GetCreateResponseOptionsFromPipeline(chatClient, new ChatOptions());
+    }
+
+    /// <summary>
+    /// Overload that runs the configure action on caller-supplied <see cref="ChatOptions"/>,
+    /// useful for testing that existing factories are preserved.
+    /// </summary>
+    private static CreateResponseOptions? GetCreateResponseOptionsFromPipeline(IChatClient chatClient, ChatOptions options)
     {
         // The ConfigureOptionsChatClient stores the configure action in a private field.
         var configureField = chatClient.GetType().GetField("_configureOptions", BindingFlags.NonPublic | BindingFlags.Instance);
@@ -402,7 +480,6 @@ public sealed class OpenAIResponseClientExtensionsTests
         var configureAction = configureField.GetValue(chatClient) as Action<ChatOptions>;
         Assert.NotNull(configureAction);
 
-        var options = new ChatOptions();
         configureAction(options);
 
         Assert.NotNull(options.RawRepresentationFactory);

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/BackgroundAgents/BackgroundAgentsProviderTests.cs

@@ -13,9 +13,9 @@ using Moq.Protected;
 namespace Microsoft.Agents.AI.UnitTests;
 
 /// <summary>
-/// Unit tests for the <see cref="SubAgentsProvider"/> class.
+/// Unit tests for the <see cref="BackgroundAgentsProvider"/> class.
 /// </summary>
-public class SubAgentsProviderTests
+public class BackgroundAgentsProviderTests
 {
     #region Constructor Tests
 
@@ -26,7 +26,7 @@ public class SubAgentsProviderTests
     public void Constructor_NullAgents_Throws()
     {
         // Act & Assert
-        Assert.Throws<ArgumentNullException>(() => new SubAgentsProvider(null!));
+        Assert.Throws<ArgumentNullException>(() => new BackgroundAgentsProvider(null!));
     }
 
     /// <summary>
@@ -36,7 +36,7 @@ public class SubAgentsProviderTests
     public void Constructor_EmptyAgents_Throws()
     {
         // Act & Assert
-        Assert.Throws<ArgumentException>(() => new SubAgentsProvider(Array.Empty<AIAgent>()));
+        Assert.Throws<ArgumentException>(() => new BackgroundAgentsProvider(Array.Empty<AIAgent>()));
     }
 
     /// <summary>
@@ -49,7 +49,7 @@ public class SubAgentsProviderTests
         var agent = CreateMockAgent(null!, "desc");
 
         // Act & Assert
-        Assert.Throws<ArgumentException>(() => new SubAgentsProvider(new[] { agent }));
+        Assert.Throws<ArgumentException>(() => new BackgroundAgentsProvider(new[] { agent }));
     }
 
     /// <summary>
@@ -62,7 +62,7 @@ public class SubAgentsProviderTests
         var agent = CreateMockAgent("", "desc");
 
         // Act & Assert
-        Assert.Throws<ArgumentException>(() => new SubAgentsProvider(new[] { agent }));
+        Assert.Throws<ArgumentException>(() => new BackgroundAgentsProvider(new[] { agent }));
     }
 
     /// <summary>
@@ -76,7 +76,7 @@ public class SubAgentsProviderTests
         var agent2 = CreateMockAgent("research", "Agent 2");
 
         // Act & Assert
-        Assert.Throws<ArgumentException>(() => new SubAgentsProvider(new[] { agent1, agent2 }));
+        Assert.Throws<ArgumentException>(() => new BackgroundAgentsProvider(new[] { agent1, agent2 }));
     }
 
     /// <summary>
@@ -90,7 +90,7 @@ public class SubAgentsProviderTests
         var agent2 = CreateMockAgent("Writer", "Writer agent");
 
         // Act
-        var provider = new SubAgentsProvider(new[] { agent1, agent2 });
+        var provider = new BackgroundAgentsProvider(new[] { agent1, agent2 });
 
         // Assert
         Assert.NotNull(provider);
@@ -108,7 +108,7 @@ public class SubAgentsProviderTests
     {
         // Arrange
         var agent = CreateMockAgent("Research", "Research agent");
-        var provider = new SubAgentsProvider(new[] { agent });
+        var provider = new BackgroundAgentsProvider(new[] { agent });
         var context = CreateInvokingContext();
 
         // Act
@@ -129,7 +129,7 @@ public class SubAgentsProviderTests
         // Arrange
         var agent1 = CreateMockAgent("Research", "Performs research");
         var agent2 = CreateMockAgent("Writer", "Writes content");
-        var provider = new SubAgentsProvider(new[] { agent1, agent2 });
+        var provider = new BackgroundAgentsProvider(new[] { agent1, agent2 });
         var context = CreateInvokingContext();
 
         // Act
@@ -144,22 +144,22 @@ public class SubAgentsProviderTests
 
     #endregion
 
-    #region StartSubTask Tests
+    #region StartBackgroundTask Tests
 
     /// <summary>
-    /// Verify that StartSubTask returns a task ID.
+    /// Verify that StartBackgroundTask returns a task ID.
     /// </summary>
     [Fact]
-    public async Task StartSubTask_ReturnsTaskIdAsync()
+    public async Task StartBackgroundTask_ReturnsTaskIdAsync()
     {
         // Arrange
         var tcs = new TaskCompletionSource<AgentResponse>();
         var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
 
         // Act
-        object? result = await startSubTask.InvokeAsync(new AIFunctionArguments
+        object? result = await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Find information about AI",
@@ -175,18 +175,18 @@ public class SubAgentsProviderTests
     }
 
     /// <summary>
-    /// Verify that StartSubTask with invalid agent name returns an error.
+    /// Verify that StartBackgroundTask with invalid agent name returns an error.
     /// </summary>
     [Fact]
-    public async Task StartSubTask_InvalidAgentName_ReturnsErrorAsync()
+    public async Task StartBackgroundTask_InvalidAgentName_ReturnsErrorAsync()
     {
         // Arrange
         var agent = CreateMockAgent("Research", "Research agent");
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
 
         // Act
-        object? result = await startSubTask.InvokeAsync(new AIFunctionArguments
+        object? result = await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "NonExistent",
             ["input"] = "Some input",
@@ -200,10 +200,10 @@ public class SubAgentsProviderTests
     }
 
     /// <summary>
-    /// Verify that StartSubTask assigns sequential IDs.
+    /// Verify that StartBackgroundTask assigns sequential IDs.
     /// </summary>
     [Fact]
-    public async Task StartSubTask_AssignsSequentialIdsAsync()
+    public async Task StartBackgroundTask_AssignsSequentialIdsAsync()
     {
         // Arrange
         var tcs1 = new TaskCompletionSource<AgentResponse>();
@@ -215,16 +215,16 @@ public class SubAgentsProviderTests
             return callCount == 1 ? tcs1.Task : tcs2.Task;
         });
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
 
         // Act
-        object? result1 = await startSubTask.InvokeAsync(new AIFunctionArguments
+        object? result1 = await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Task 1",
             ["description"] = "First task",
         });
-        object? result2 = await startSubTask.InvokeAsync(new AIFunctionArguments
+        object? result2 = await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Task 2",
@@ -253,11 +253,11 @@ public class SubAgentsProviderTests
         var tcs = new TaskCompletionSource<AgentResponse>();
         var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
-        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "BackgroundAgents_WaitForFirstCompletion");
 
         // Start one task
-        await startSubTask.InvokeAsync(new AIFunctionArguments
+        await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Task 1",
@@ -288,7 +288,7 @@ public class SubAgentsProviderTests
         // Arrange
         var agent = CreateMockAgent("Research", "Research agent");
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
+        AIFunction waitForFirst = GetTool(tools, "BackgroundAgents_WaitForFirstCompletion");
 
         // Act
         object? result = await waitForFirst.InvokeAsync(new AIFunctionArguments
@@ -302,24 +302,24 @@ public class SubAgentsProviderTests
 
     #endregion
 
-    #region GetSubTaskResults Tests
+    #region GetBackgroundTaskResults Tests
 
     /// <summary>
-    /// Verify that GetSubTaskResults returns the result text of a completed task.
+    /// Verify that GetBackgroundTaskResults returns the result text of a completed task.
     /// </summary>
     [Fact]
-    public async Task GetSubTaskResults_CompletedTask_ReturnsResultTextAsync()
+    public async Task GetBackgroundTaskResults_CompletedTask_ReturnsResultTextAsync()
     {
         // Arrange
         var tcs = new TaskCompletionSource<AgentResponse>();
         var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
-        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
-        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "BackgroundAgents_WaitForFirstCompletion");
+        AIFunction getResults = GetTool(tools, "BackgroundAgents_GetTaskResults");
 
         // Start a task
-        await startSubTask.InvokeAsync(new AIFunctionArguments
+        await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Research AI",
@@ -346,20 +346,20 @@ public class SubAgentsProviderTests
     }
 
     /// <summary>
-    /// Verify that GetSubTaskResults for a still-running task returns status info.
+    /// Verify that GetBackgroundTaskResults for a still-running task returns status info.
     /// </summary>
     [Fact]
-    public async Task GetSubTaskResults_RunningTask_ReturnsStatusAsync()
+    public async Task GetBackgroundTaskResults_RunningTask_ReturnsStatusAsync()
     {
         // Arrange
         var tcs = new TaskCompletionSource<AgentResponse>();
         var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
-        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
+        AIFunction getResults = GetTool(tools, "BackgroundAgents_GetTaskResults");
 
         // Start a task (don't complete it)
-        await startSubTask.InvokeAsync(new AIFunctionArguments
+        await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Research AI",
@@ -379,15 +379,15 @@ public class SubAgentsProviderTests
     }
 
     /// <summary>
-    /// Verify that GetSubTaskResults for a nonexistent task returns an error.
+    /// Verify that GetBackgroundTaskResults for a nonexistent task returns an error.
     /// </summary>
     [Fact]
-    public async Task GetSubTaskResults_NonexistentTask_ReturnsErrorAsync()
+    public async Task GetBackgroundTaskResults_NonexistentTask_ReturnsErrorAsync()
     {
         // Arrange
         var agent = CreateMockAgent("Research", "Research agent");
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+        AIFunction getResults = GetTool(tools, "BackgroundAgents_GetTaskResults");
 
         // Act
         object? result = await getResults.InvokeAsync(new AIFunctionArguments
@@ -400,21 +400,21 @@ public class SubAgentsProviderTests
     }
 
     /// <summary>
-    /// Verify that GetSubTaskResults for a failed task returns the error.
+    /// Verify that GetBackgroundTaskResults for a failed task returns the error.
     /// </summary>
     [Fact]
-    public async Task GetSubTaskResults_FailedTask_ReturnsErrorTextAsync()
+    public async Task GetBackgroundTaskResults_FailedTask_ReturnsErrorTextAsync()
     {
         // Arrange
         var tcs = new TaskCompletionSource<AgentResponse>();
         var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
-        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
-        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "BackgroundAgents_WaitForFirstCompletion");
+        AIFunction getResults = GetTool(tools, "BackgroundAgents_GetTaskResults");
 
         // Start a task
-        await startSubTask.InvokeAsync(new AIFunctionArguments
+        await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Research AI",
@@ -456,11 +456,11 @@ public class SubAgentsProviderTests
         var tcs = new TaskCompletionSource<AgentResponse>();
         var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
-        AIFunction getAllTasks = GetTool(tools, "SubAgents_GetAllTasks");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
+        AIFunction getAllTasks = GetTool(tools, "BackgroundAgents_GetAllTasks");
 
         // Start a task
-        await startSubTask.InvokeAsync(new AIFunctionArguments
+        await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Research AI",
@@ -490,12 +490,12 @@ public class SubAgentsProviderTests
         var tcs = new TaskCompletionSource<AgentResponse>();
         var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
-        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
-        AIFunction getAllTasks = GetTool(tools, "SubAgents_GetAllTasks");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "BackgroundAgents_WaitForFirstCompletion");
+        AIFunction getAllTasks = GetTool(tools, "BackgroundAgents_GetAllTasks");
 
         // Start and complete a task
-        await startSubTask.InvokeAsync(new AIFunctionArguments
+        await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Research AI",
@@ -525,7 +525,7 @@ public class SubAgentsProviderTests
         // Arrange
         var agent = CreateMockAgent("Research", "Research agent");
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction getAllTasks = GetTool(tools, "SubAgents_GetAllTasks");
+        AIFunction getAllTasks = GetTool(tools, "BackgroundAgents_GetAllTasks");
 
         // Act
         object? result = await getAllTasks.InvokeAsync(new AIFunctionArguments());
@@ -554,13 +554,13 @@ public class SubAgentsProviderTests
             return callCount == 1 ? tcs1.Task : tcs2.Task;
         });
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
-        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
-        AIFunction continueTask = GetTool(tools, "SubAgents_ContinueTask");
-        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "BackgroundAgents_WaitForFirstCompletion");
+        AIFunction continueTask = GetTool(tools, "BackgroundAgents_ContinueTask");
+        AIFunction getResults = GetTool(tools, "BackgroundAgents_GetTaskResults");
 
         // Start and complete a task
-        await startSubTask.InvokeAsync(new AIFunctionArguments
+        await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Research AI",
@@ -606,11 +606,11 @@ public class SubAgentsProviderTests
         var tcs = new TaskCompletionSource<AgentResponse>();
         var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
-        AIFunction continueTask = GetTool(tools, "SubAgents_ContinueTask");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
+        AIFunction continueTask = GetTool(tools, "BackgroundAgents_ContinueTask");
 
         // Start a task (don't complete it)
-        await startSubTask.InvokeAsync(new AIFunctionArguments
+        await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Research AI",
@@ -639,7 +639,7 @@ public class SubAgentsProviderTests
         // Arrange
         var agent = CreateMockAgent("Research", "Research agent");
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction continueTask = GetTool(tools, "SubAgents_ContinueTask");
+        AIFunction continueTask = GetTool(tools, "BackgroundAgents_ContinueTask");
 
         // Act
         object? result = await continueTask.InvokeAsync(new AIFunctionArguments
@@ -666,13 +666,13 @@ public class SubAgentsProviderTests
         var tcs = new TaskCompletionSource<AgentResponse>();
         var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
-        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
-        AIFunction clearTask = GetTool(tools, "SubAgents_ClearCompletedTask");
-        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "BackgroundAgents_WaitForFirstCompletion");
+        AIFunction clearTask = GetTool(tools, "BackgroundAgents_ClearCompletedTask");
+        AIFunction getResults = GetTool(tools, "BackgroundAgents_GetTaskResults");
 
         // Start and complete a task
-        await startSubTask.InvokeAsync(new AIFunctionArguments
+        await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Research AI",
@@ -711,11 +711,11 @@ public class SubAgentsProviderTests
         var tcs = new TaskCompletionSource<AgentResponse>();
         var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
-        AIFunction clearTask = GetTool(tools, "SubAgents_ClearCompletedTask");
+        AIFunction startBackgroundTask = GetTool(tools, "BackgroundAgents_StartTask");
+        AIFunction clearTask = GetTool(tools, "BackgroundAgents_ClearCompletedTask");
 
         // Start a task (don't complete it)
-        await startSubTask.InvokeAsync(new AIFunctionArguments
+        await startBackgroundTask.InvokeAsync(new AIFunctionArguments
         {
             ["agentName"] = "Research",
             ["input"] = "Research AI",
@@ -743,7 +743,7 @@ public class SubAgentsProviderTests
         // Arrange
         var agent = CreateMockAgent("Research", "Research agent");
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        AIFunction clearTask = GetTool(tools, "SubAgents_ClearCompletedTask");
+        AIFunction clearTask = GetTool(tools, "BackgroundAgents_ClearCompletedTask");
 
         // Act
         object? result = await clearTask.InvokeAsync(new AIFunctionArguments
@@ -767,7 +767,7 @@ public class SubAgentsProviderTests
     {
         // Arrange
         var agent = CreateMockAgent("Research", "Research agent");
-        var provider = new SubAgentsProvider(new[] { agent });
+        var provider = new BackgroundAgentsProvider(new[] { agent });
 
         // Act
         var keys = provider.StateKeys;
@@ -782,23 +782,23 @@ public class SubAgentsProviderTests
     #region CurrentRunContext Isolation Tests
 
     /// <summary>
-    /// Verify that StartSubTask does not corrupt CurrentRunContext of the calling agent.
+    /// Verify that StartBackgroundTask does not corrupt CurrentRunContext of the calling agent.
     /// Because RunAsync is a non-async method that synchronously sets the static AsyncLocal
-    /// CurrentRunContext, the provider must isolate the sub-agent call to prevent overwriting
+    /// CurrentRunContext, the provider must isolate the background agent call to prevent overwriting
     /// the outer agent's context.
     /// </summary>
     [Fact]
-    public async Task StartSubTask_DoesNotCorruptCurrentRunContextAsync()
+    public async Task StartBackgroundTask_DoesNotCorruptCurrentRunContextAsync()
     {
         // Arrange
         var tcs = new TaskCompletionSource<AgentResponse>();
         var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
         var (tools, _) = await CreateToolsWithProviderAsync(agent);
-        var startTool = GetTool(tools, "SubAgents_StartTask");
+        var startTool = GetTool(tools, "BackgroundAgents_StartTask");
 
         AgentRunContext? contextBefore = AIAgent.CurrentRunContext;
 
-        // Act — invoke StartSubTask; this calls agent.RunAsync internally.
+        // Act — invoke StartBackgroundTask; this calls agent.RunAsync internally.
         var args = new AIFunctionArguments(new Dictionary<string, object?>
         {
             ["agentName"] = "Research",
@@ -826,16 +826,16 @@ public class SubAgentsProviderTests
     {
         // Arrange
         var agent = CreateMockAgent("Research", "Research agent");
-        const string CustomInstructions = "These are custom sub-agent instructions.\n{sub_agents}";
-        var options = new SubAgentsProviderOptions { Instructions = CustomInstructions };
-        var provider = new SubAgentsProvider(new[] { agent }, options);
+        const string CustomInstructions = "These are custom background agent instructions.\n{background_agents}";
+        var options = new BackgroundAgentsProviderOptions { Instructions = CustomInstructions };
+        var provider = new BackgroundAgentsProvider(new[] { agent }, options);
         var context = CreateInvokingContext();
 
         // Act
         AIContext result = await provider.InvokingAsync(context);
 
         // Assert — custom instructions replace default, agent list is injected via {sub_agents} placeholder
-        Assert.Contains("These are custom sub-agent instructions.", result.Instructions);
+        Assert.Contains("These are custom background agent instructions.", result.Instructions);
         Assert.Contains("Research", result.Instructions);
     }
 
@@ -847,15 +847,15 @@ public class SubAgentsProviderTests
     {
         // Arrange
         var agent = CreateMockAgent("Research", "Research agent");
-        var provider = new SubAgentsProvider(new[] { agent });
+        var provider = new BackgroundAgentsProvider(new[] { agent });
         var context = CreateInvokingContext();
 
         // Act
         AIContext result = await provider.InvokingAsync(context);
 
         // Assert — instructions contain tool usage guidance and agent list
-        Assert.Contains("SubAgents_*", result.Instructions);
-        Assert.Contains("SubAgents_ClearCompletedTask", result.Instructions);
+        Assert.Contains("BackgroundAgents_*", result.Instructions);
+        Assert.Contains("BackgroundAgents_ClearCompletedTask", result.Instructions);
         Assert.Contains("Research", result.Instructions);
         Assert.Contains("Research agent", result.Instructions);
     }
@@ -868,11 +868,11 @@ public class SubAgentsProviderTests
     {
         // Arrange
         var agent = CreateMockAgent("Research", "Research agent");
-        var options = new SubAgentsProviderOptions
+        var options = new BackgroundAgentsProviderOptions
         {
             AgentListBuilder = agents => $"Custom list: {string.Join(", ", agents.Keys)}",
         };
-        var provider = new SubAgentsProvider(new[] { agent }, options);
+        var provider = new BackgroundAgentsProvider(new[] { agent }, options);
         var context = CreateInvokingContext();
 
         // Act
@@ -880,7 +880,7 @@ public class SubAgentsProviderTests
 
         // Assert — custom agent list builder output is in instructions
         Assert.Contains("Custom list: Research", result.Instructions);
-        Assert.DoesNotContain("Available sub-agents:", result.Instructions);
+        Assert.DoesNotContain("Available background agents:", result.Instructions);
     }
 
     #endregion
@@ -935,9 +935,9 @@ public class SubAgentsProviderTests
         return mock.Object;
     }
 
-    private static async Task<(IEnumerable<AITool> Tools, SubAgentsProvider Provider)> CreateToolsWithProviderAsync(AIAgent agent)
+    private static async Task<(IEnumerable<AITool> Tools, BackgroundAgentsProvider Provider)> CreateToolsWithProviderAsync(AIAgent agent)
     {
-        var provider = new SubAgentsProvider(new[] { agent });
+        var provider = new BackgroundAgentsProvider(new[] { agent });
         var context = CreateInvokingContext();
 
         AIContext result = await provider.InvokingAsync(context);

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/Todo/TodoProviderTests.cs

@@ -116,7 +116,7 @@ public class TodoProviderTests
         await addTodos.InvokeAsync(new AIFunctionArguments() { ["todos"] = new List<TodoItemInput> { new() { Title = "Test", Description = null } } });
 
         // Act
-        object? result = await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1 } });
+        object? result = await completeTodos.InvokeAsync(new AIFunctionArguments() { ["items"] = new List<TodoCompleteInput> { new() { Id = 1, Reason = "Done" } } });
 
         // Assert
         Assert.True(state.Items[0].IsComplete);
@@ -139,7 +139,7 @@ public class TodoProviderTests
         });
 
         // Act
-        object? result = await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1, 3 } });
+        object? result = await completeTodos.InvokeAsync(new AIFunctionArguments() { ["items"] = new List<TodoCompleteInput> { new() { Id = 1, Reason = "Done" }, new() { Id = 3, Reason = "Done" } } });
 
         // Assert
         Assert.True(state.Items[0].IsComplete);
@@ -159,12 +159,35 @@ public class TodoProviderTests
         AIFunction completeTodos = GetTool(tools, "TodoList_Complete");
 
         // Act
-        object? result = await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 999 } });
+        object? result = await completeTodos.InvokeAsync(new AIFunctionArguments() { ["items"] = new List<TodoCompleteInput> { new() { Id = 999, Reason = "Done" } } });
 
         // Assert
         Assert.Equal(0, GetIntResult(result));
     }
 
+    /// <summary>
+    /// Verify that CompleteTodos accepts an optional reason parameter.
+    /// </summary>
+    [Fact]
+    public async Task CompleteTodos_AcceptsReasonParameterAsync()
+    {
+        // Arrange
+        var (tools, state) = await CreateToolsWithStateAsync();
+        AIFunction addTodos = GetTool(tools, "TodoList_Add");
+        AIFunction completeTodos = GetTool(tools, "TodoList_Complete");
+        await addTodos.InvokeAsync(new AIFunctionArguments() { ["todos"] = new List<TodoItemInput> { new() { Title = "Research topic" } } });
+
+        // Act
+        object? result = await completeTodos.InvokeAsync(new AIFunctionArguments()
+        {
+            ["items"] = new List<TodoCompleteInput> { new() { Id = 1, Reason = "Found the answer in the documentation." } },
+        });
+
+        // Assert
+        Assert.True(state.Items[0].IsComplete);
+        Assert.Equal(1, GetIntResult(result));
+    }
+
     #endregion
 
     #region RemoveTodos Tests
@@ -249,7 +272,7 @@ public class TodoProviderTests
         {
             ["todos"] = new List<TodoItemInput> { new() { Title = "Done", Description = null }, new() { Title = "Pending", Description = null } },
         });
-        await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1 } });
+        await completeTodos.InvokeAsync(new AIFunctionArguments() { ["items"] = new List<TodoCompleteInput> { new() { Id = 1, Reason = "Done" } } });
 
         // Act
         object? result = await getRemainingTodos.InvokeAsync(new AIFunctionArguments());
@@ -279,7 +302,7 @@ public class TodoProviderTests
         {
             ["todos"] = new List<TodoItemInput> { new() { Title = "Done", Description = null }, new() { Title = "Pending", Description = null } },
         });
-        await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1 } });
+        await completeTodos.InvokeAsync(new AIFunctionArguments() { ["items"] = new List<TodoCompleteInput> { new() { Id = 1, Reason = "Done" } } });
 
         // Act
         object? result = await getAllTodos.InvokeAsync(new AIFunctionArguments());
@@ -376,7 +399,7 @@ public class TodoProviderTests
         {
             ["todos"] = new List<TodoItemInput> { new() { Title = "Done", Description = null }, new() { Title = "Pending", Description = null } },
         });
-        await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1 } });
+        await completeTodos.InvokeAsync(new AIFunctionArguments() { ["items"] = new List<TodoCompleteInput> { new() { Id = 1, Reason = "Done" } } });
 
         // Act
         var remaining = await provider.GetRemainingTodosAsync(session);
@@ -543,7 +566,7 @@ public class TodoProviderTests
                 new() { Title = "Second", Description = "Has details" },
             },
         });
-        await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1 } });
+        await completeTodos.InvokeAsync(new AIFunctionArguments() { ["items"] = new List<TodoCompleteInput> { new() { Id = 1, Reason = "Done" } } });
 
         // Act — second invocation should see the updated list in messages
         AIContext result2 = await provider.InvokingAsync(context);
@@ -762,7 +785,7 @@ public class TodoProviderTests
             {
                 ["todos"] = new List<TodoItemInput> { new() { Title = "New C" } },
             }).AsTask(),
-            completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1, 2, 3 } }).AsTask());
+            completeTodos.InvokeAsync(new AIFunctionArguments() { ["items"] = new List<TodoCompleteInput> { new() { Id = 1, Reason = "Done" }, new() { Id = 2, Reason = "Done" }, new() { Id = 3, Reason = "Done" } } }).AsTask());
 
         // Assert
         object? allResult = await getAllTodos.InvokeAsync(new AIFunctionArguments());