.NET: Adding default providers and tools to HarnessAgent (#5896)

* Adding default providers and tools to HarnessAgent * Address PR comments * Add further comments to clarify certain setings. * Apply suggestion from @SergeyMenshykh Co-authored-by: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com> --------- Co-authored-by: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2026-05-18 10:07:16 +00:00
parent a60e541c9a
commit ddc0fcf81f
13 changed files with 1154 additions and 188 deletions
@@ -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;
+    }
 }
@@ -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; }
 }
@@ -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)
@@ -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.
@@ -48,9 +48,9 @@ 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).