.NET: Add shell support to the HarnessAgent

[westey-m]

Motivation and Context

Description

• Add shell support to the HarnessAgent

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Pull request overview

This PR adds first-class shell tool support to the .NET HarnessAgent so that, when a ShellExecutor is provided, the agent automatically (1) registers a shell tool (AIFunction) and (2) injects environment context via ShellEnvironmentProvider.

Changes:

• Add ShellExecutor and ShellEnvironmentProviderOptions to HarnessAgentOptions and wire them into HarnessAgent (tools + context providers).
• Add a new ShellExecutor.AsAIFunction(...) API and update shell executors/tests accordingly.
• Add unit tests covering presence/absence of the shell context provider and tool registration.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
dotnet/tests/Microsoft.Agents.AI.Tools.Shell.UnitTests/ShellEnvironmentProviderTests.cs	Updates test executors to satisfy new ShellExecutor.AsAIFunction requirement.
dotnet/tests/Microsoft.Agents.AI.Harness.UnitTests/HarnessAgentTests.cs	Adds tests for shell provider inclusion and tool registration when ShellExecutor is configured.
dotnet/tests/Microsoft.Agents.AI.Harness.UnitTests/HarnessAgentOptionsTests.cs	Adds assertions for new HarnessAgentOptions shell-related properties.
dotnet/src/Microsoft.Agents.AI.Tools.Shell/ShellExecutor.cs	Introduces AsAIFunction(...) API on the executor abstraction.
dotnet/src/Microsoft.Agents.AI.Tools.Shell/LocalShellExecutor.cs	Implements AsAIFunction(...) override.
dotnet/src/Microsoft.Agents.AI.Tools.Shell/DockerShellExecutor.cs	Implements AsAIFunction(...) override and adjusts approval parameter handling.
dotnet/src/Microsoft.Agents.AI.Harness/Microsoft.Agents.AI.Harness.csproj	Adds conditional project reference to Shell tools for net8+ TFMs.
dotnet/src/Microsoft.Agents.AI.Harness/HarnessAgentOptions.cs	Adds shell configuration knobs (conditional on NET).
dotnet/src/Microsoft.Agents.AI.Harness/HarnessAgent.cs	Wires shell tool + ShellEnvironmentProvider into the agent pipeline (conditional on NET).

Comments suppressed due to low confidence (2)

dotnet/src/Microsoft.Agents.AI.Tools.Shell/DockerShellExecutor.cs:266

• Changing DockerShellExecutor.AsAIFunction from bool? requireApproval = null to bool requireApproval = true is a public API breaking change for callers that were explicitly passing null. Consider keeping a backward-compatible overload with the old signature (optionally [Obsolete]) that forwards to the new override, or ensure this is intentionally treated as a breaking change in versioning/PR metadata.

    public override AIFunction AsAIFunction(string name = "run_shell", string? description = null, bool requireApproval = true)

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

• ShellEnvironmentProvider_UsesProvidedOptions creates a non-default ShellEnvironmentProviderOptions instance, but the assertions only check that a ShellEnvironmentProvider exists — they don’t validate that the provided options were actually used/wired through. Either assert on observable behavior affected by envOptions (e.g., that only the specified ProbeTools are probed) or rename the test to reflect what it actually verifies (provider is present when options are supplied).

    /// <summary>
    /// Verify that ShellEnvironmentProviderOptions is passed through when specified.
    /// </summary>
    [Fact]
    public void ShellEnvironmentProvider_UsesProvidedOptions()
    {
        // Arrange
        var chatClient = new Mock<IChatClient>().Object;
        var executorMock = new Mock<ShellExecutor>();
        executorMock.Setup(e => e.AsAIFunction(It.IsAny<string>(), It.IsAny<string?>(), It.IsAny<bool>()))
            .Returns(AIFunctionFactory.Create(() => "test", "run_shell"));
        var envOptions = new ShellEnvironmentProviderOptions
        {
            ProbeTools = ["git", "python"],
        };
        var options = CreateAllDisabledOptions();
        options.ShellExecutor = executorMock.Object;
        options.ShellEnvironmentProviderOptions = envOptions;

        // Act
        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
        var innerAgent = agent.GetService<ChatClientAgent>();

        // Assert — provider should exist (options wiring is validated by the provider's behavior)
        Assert.NotNull(innerAgent?.AIContextProviders);
        Assert.Contains(innerAgent!.AIContextProviders!, p => p is ShellEnvironmentProvider);
    }

[lokitoth]

If we are starting to put features behind the #if NET switch, we should consider discussing how much longer we intend to support NetFX 4.7.2

[westey-m]

If we are starting to put features behind the #if NET switch, we should consider discussing how much longer we intend to support NetFX 4.7.2

Yeah, I'm not sure why the shell lib is core only. Will need to check what the reason is.