.NET: Added ShellTool and LocalShellExecutor

dotnet/agent-framework-dotnet.slnx

@@ -94,6 +94,7 @@
     <Project Path="samples/GettingStarted/Agents/Agent_Step18_DeepResearch/Agent_Step18_DeepResearch.csproj" />
     <Project Path="samples/GettingStarted/Agents/Agent_Step19_Declarative/Agent_Step19_Declarative.csproj" />
     <Project Path="samples/GettingStarted/Agents/Agent_Step20_AdditionalAIContext/Agent_Step20_AdditionalAIContext.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step21_ShellTool/Agent_Step21_ShellTool.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/DeclarativeAgents/">
     <Project Path="samples/GettingStarted/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
@@ -406,6 +407,7 @@
     <Project Path="src/Microsoft.Agents.AI.Mem0/Microsoft.Agents.AI.Mem0.csproj" />
     <Project Path="src/Microsoft.Agents.AI.OpenAI/Microsoft.Agents.AI.OpenAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Shell.Local/Microsoft.Agents.AI.Shell.Local.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.AzureAI/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
@@ -449,5 +451,6 @@
     <Project Path="tests/Microsoft.Agents.AI.UnitTests/Microsoft.Agents.AI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Shell.Local.IntegrationTests/Microsoft.Agents.AI.Shell.Local.IntegrationTests.csproj" />
   </Folder>
 </Solution>

dotnet/samples/GettingStarted/Agents/Agent_Step21_ShellTool/Agent_Step21_ShellTool.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="OpenAI" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Shell.Local\Microsoft.Agents.AI.Shell.Local.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/Agents/Agent_Step21_ShellTool/Program.cs

@@ -0,0 +1,134 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use the ShellTool with an AI agent.
+// It shows security configuration options and human-in-the-loop approval for shell commands.
+//
+// SECURITY NOTE: The ShellTool executes real shell commands on your system.
+// Always configure appropriate security restrictions before use.
+// The safest approach is to run shell commands in isolated environments (containers, VMs, sandboxes)
+// with restricted permissions and network access.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
+
+var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY")
+    ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
+var modelName = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-4o-mini";
+
+// Get working directory (from environment variable or use temp folder)
+var workingDirectory = Environment.GetEnvironmentVariable("SHELL_WORKING_DIR")
+    ?? Path.Combine(Path.GetTempPath(), "shell-tool-sample");
+Directory.CreateDirectory(workingDirectory);
+
+Console.WriteLine($"Working directory: {workingDirectory}");
+Console.WriteLine();
+
+// Create the shell tool with security options.
+// This configuration restricts what commands can be executed.
+var shellTool = new ShellTool(
+    executor: new LocalShellExecutor(),
+    options: new ShellToolOptions
+    {
+        // Set the working directory for command execution
+        WorkingDirectory = workingDirectory,
+
+        // Restrict file system access to specific paths
+        AllowedPaths = [workingDirectory],
+
+        // Block access to sensitive paths (takes priority over AllowedPaths)
+        // BlockedPaths = ["/etc", "/var"],
+
+        // Only allow specific commands (regex patterns supported)
+        AllowedCommands = ["^ls", "^dir", "^echo", "^cat", "^type", "^mkdir", "^pwd", "^cd"],
+
+        // Block dangerous patterns (enabled by default)
+        BlockDangerousPatterns = true,
+
+        // Block command chaining operators like ; | && || (enabled by default)
+        BlockCommandChaining = true,
+
+        // Block privilege escalation commands like sudo, su (enabled by default)
+        BlockPrivilegeEscalation = true,
+
+        // Set execution timeout (default: 60 seconds)
+        TimeoutInMilliseconds = 30000,
+
+        // Set maximum output size (default: 50KB)
+        MaxOutputLength = 10240
+    });
+
+// Convert the shell tool to an AIFunction for use with agents.
+// Wrap with ApprovalRequiredAIFunction to require user approval before execution.
+var shellFunction = new ApprovalRequiredAIFunction(shellTool.AsAIFunction());
+
+// Detect platform for shell command guidance
+var operatingSystem = OperatingSystem.IsWindows() ? "Windows" : "Unix/Linux";
+
+// Create the chat client and agent with the shell tool.
+AIAgent agent = new OpenAIClient(apiKey)
+    .GetChatClient(modelName)
+    .AsIChatClient()
+    .AsAIAgent(
+        instructions: $"""
+            You are a helpful assistant with access to a shell tool.
+            You can execute shell commands to help the user with file system tasks.
+            The operating system is {operatingSystem}.
+            """,
+        tools: [shellFunction]);
+
+Console.WriteLine("Agent with Shell Tool");
+Console.WriteLine("=====================");
+Console.WriteLine("This agent can execute shell commands with security restrictions.");
+Console.WriteLine("Commands require user approval before execution.");
+Console.WriteLine();
+
+// Interactive conversation loop
+AgentThread thread = await agent.GetNewThreadAsync();
+
+while (true)
+{
+    Console.Write("You: ");
+    var userInput = Console.ReadLine();
+
+    if (string.IsNullOrWhiteSpace(userInput) || userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))
+    {
+        break;
+    }
+
+    var response = await agent.RunAsync(userInput, thread);
+    var userInputRequests = response.UserInputRequests.ToList();
+
+    // Handle approval requests for shell commands
+    while (userInputRequests.Count > 0)
+    {
+        var userInputResponses = userInputRequests
+            .OfType<FunctionApprovalRequestContent>()
+            .Select(functionApprovalRequest =>
+            {
+                Console.WriteLine();
+                Console.WriteLine($"[APPROVAL REQUIRED] The agent wants to execute: {functionApprovalRequest.FunctionCall.Name}");
+
+                // Display the commands that will be executed
+                var arguments = functionApprovalRequest.FunctionCall.Arguments;
+                if (arguments is not null && arguments.TryGetValue("commands", out var commands) && commands is not null)
+                {
+                    Console.WriteLine($"Commands: {commands}");
+                }
+
+                Console.Write("Approve? (Y/N): ");
+                var approved = Console.ReadLine()?.Equals("Y", StringComparison.OrdinalIgnoreCase) ?? false;
+
+                return new ChatMessage(ChatRole.User, [functionApprovalRequest.CreateResponse(approved)]);
+            })
+            .ToList();
+
+        response = await agent.RunAsync(userInputResponses, thread);
+        userInputRequests = response.UserInputRequests.ToList();
+    }
+
+    Console.WriteLine();
+    Console.WriteLine($"Agent: {response}");
+    Console.WriteLine();
+}

dotnet/samples/GettingStarted/Agents/README.md

@@ -47,6 +47,7 @@ Before you begin, ensure you have the following prerequisites:
 |[Deep research with an agent](./Agent_Step18_DeepResearch/)|This sample demonstrates how to use the Deep Research Tool to perform comprehensive research on complex topics|
 |[Declarative agent](./Agent_Step19_Declarative/)|This sample demonstrates how to declaratively define an agent.|
 |[Providing additional AI Context to an agent using multiple AIContextProviders](./Agent_Step20_AdditionalAIContext/)|This sample demonstrates how to inject additional AI context into a ChatClientAgent using multiple custom AIContextProvider components that are attached to the agent.|
+|[Using Shell Tool with security controls](./Agent_Step21_ShellTool/)|This sample demonstrates how to use the ShellTool with an AI agent, including security configuration options and human-in-the-loop approval for shell commands.|
 
 ## Running the samples from the console
 

dotnet/src/Microsoft.Agents.AI.Abstractions/Shell/ShellCallContent.cs

@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents a shell command execution request.
+/// </summary>
+[DebuggerDisplay("{DebuggerDisplay,nq}")]
+public sealed class ShellCallContent : AIContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ShellCallContent"/> class.
+    /// </summary>
+    /// <param name="callId">The unique identifier for this shell call.</param>
+    /// <param name="commands">The commands to execute.</param>
+    [JsonConstructor]
+    public ShellCallContent(string callId, IReadOnlyList<string> commands)
+    {
+        this.CallId = Throw.IfNull(callId);
+        this.Commands = Throw.IfNull(commands);
+    }
+
+    /// <summary>
+    /// Gets the unique identifier for this shell call.
+    /// </summary>
+    public string CallId { get; }
+
+    /// <summary>
+    /// Gets the commands to execute.
+    /// </summary>
+    public IReadOnlyList<string> Commands { get; }
+
+    /// <summary>Gets a string representing this instance to display in the debugger.</summary>
+    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
+    private string DebuggerDisplay =>
+        $"ShellCall = {this.CallId}, Commands = {this.Commands.Count}";
+}

dotnet/src/Microsoft.Agents.AI.Abstractions/Shell/ShellCommandOutput.cs

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the output of a single shell command execution.
+/// </summary>
+public sealed class ShellCommandOutput
+{
+    /// <summary>
+    /// Gets or sets the command that was executed.
+    /// </summary>
+    public string? Command { get; set; }
+
+    /// <summary>
+    /// Gets or sets the standard output from the command.
+    /// </summary>
+    public string? StandardOutput { get; set; }
+
+    /// <summary>
+    /// Gets or sets the standard error from the command.
+    /// </summary>
+    public string? StandardError { get; set; }
+
+    /// <summary>
+    /// Gets or sets the exit code. Null if the command timed out or failed to start.
+    /// </summary>
+    public int? ExitCode { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the command execution timed out.
+    /// </summary>
+    public bool IsTimedOut { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the output was truncated due to MaxOutputLength.
+    /// </summary>
+    public bool IsTruncated { get; set; }
+
+    /// <summary>
+    /// Gets or sets an error message if the command failed to start.
+    /// </summary>
+    public string? Error { get; set; }
+}

dotnet/src/Microsoft.Agents.AI.Abstractions/Shell/ShellExecutor.cs

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Abstract base class for shell command execution.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Implementations of this class handle the actual execution of shell commands.
+/// The base class is designed to be extensible for different execution contexts
+/// (local, SSH, container, etc.).
+/// </para>
+/// <para>
+/// Executors return raw <see cref="ShellExecutorOutput"/> objects, which are
+/// converted to <see cref="ShellCommandOutput"/> by <see cref="ShellTool"/>.
+/// </para>
+/// </remarks>
+public abstract class ShellExecutor
+{
+    /// <summary>
+    /// Executes the specified shell commands.
+    /// </summary>
+    /// <param name="commands">The commands to execute.</param>
+    /// <param name="options">The options controlling execution behavior.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>Raw output data for each command.</returns>
+    public abstract Task<IReadOnlyList<ShellExecutorOutput>> ExecuteAsync(
+        IReadOnlyList<string> commands,
+        ShellToolOptions options,
+        CancellationToken cancellationToken = default);
+}

dotnet/src/Microsoft.Agents.AI.Abstractions/Shell/ShellExecutorOutput.cs

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Raw output from shell executor.
+/// </summary>
+public sealed class ShellExecutorOutput
+{
+    /// <summary>
+    /// Gets or sets the command that was executed.
+    /// </summary>
+    public string? Command { get; set; }
+
+    /// <summary>
+    /// Gets or sets the standard output from the command.
+    /// </summary>
+    public string? StandardOutput { get; set; }
+
+    /// <summary>
+    /// Gets or sets the standard error from the command.
+    /// </summary>
+    public string? StandardError { get; set; }
+
+    /// <summary>
+    /// Gets or sets the exit code. Null if the command timed out or failed to start.
+    /// </summary>
+    public int? ExitCode { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the command execution timed out.
+    /// </summary>
+    public bool IsTimedOut { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the output was truncated due to MaxOutputLength.
+    /// </summary>
+    public bool IsTruncated { get; set; }
+
+    /// <summary>
+    /// Gets or sets an error message if the command failed to start.
+    /// </summary>
+    public string? Error { get; set; }
+}