.NET: Added ShellTool and LocalShellExecutor #3369

dmytrostruk · 2026-01-22T08:17:49Z

Motivation and Context

This PR adds shell command execution capabilities to the Agent Framework through a new ShellTool abstraction and LocalShellExecutor implementation.

Added ShellTool abstraction for shell command execution with configurable security policies (Microsoft.Agents.AI.Abstractions)
Added LocalShellExecutor (Microsoft.Agents.AI.Shell.Local)
Security controls: privilege escalation blocking, dangerous pattern detection, path validation
Support for allowlist/denylist patterns
Configurable timeouts, output truncation, and working directory
AsAIFunction conversion for use with existing AI agents

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 shell command execution capabilities to the Agent Framework through a new ShellTool abstraction and LocalShellExecutor implementation. The implementation includes comprehensive security controls for privilege escalation blocking, dangerous pattern detection, path validation, and configurable allow/deny lists.

Changes:

Added ShellTool abstraction with security policies (Microsoft.Agents.AI.Abstractions)
Added LocalShellExecutor implementation for local shell execution (Microsoft.Agents.AI.Shell.Local)
Added comprehensive unit tests for ShellTool security validation and integration tests for LocalShellExecutor
Added sample demonstrating ShellTool usage with human-in-the-loop approval (Agent_Step21_ShellTool)

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
Microsoft.Agents.AI.Shell.Local/LocalShellExecutor.cs	Implements local shell command execution with timeout, output truncation, and cross-platform support
Microsoft.Agents.AI.Shell.Local/Microsoft.Agents.AI.Shell.Local.csproj	Project configuration for the LocalShellExecutor implementation
Microsoft.Agents.AI.Abstractions/Shell/*.cs	Core abstractions including ShellTool, ShellExecutor, ShellToolOptions, and content types
Microsoft.Agents.AI.Shell.Local.IntegrationTests/*.cs	Integration tests for LocalShellExecutor covering various execution scenarios
Microsoft.Agents.AI.Abstractions.UnitTests/Shell/*.cs	Unit tests for ShellTool security validation and options configuration
Agent_Step21_ShellTool/*	Sample demonstrating ShellTool usage with security configuration and approval workflow
agent-framework-dotnet.slnx	Solution file updated to include new projects
README.md	Updated to reference the new ShellTool sample

Comments suppressed due to low confidence (1)

dotnet/tests/Microsoft.Agents.AI.Shell.Local.IntegrationTests/LocalShellExecutorTests.cs:89

This condition is redundant because both branches assign the same array of commands. This appears to be a copy-paste error where the Windows and Unix commands were supposed to be different but ended up being identical.

        string[] commands = RuntimeInformation.IsOSPlatform(OSPlatform.Windows)
            ? ["echo first", "echo second", "echo third"]
            : ["echo first", "echo second", "echo third"];

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

dotnet/tests/Microsoft.Agents.AI.Shell.Local.IntegrationTests/LocalShellExecutorTests.cs

dotnet/src/Microsoft.Agents.AI.Shell.Local/LocalShellExecutor.cs

...ents.AI.Shell.Local.IntegrationTests/Microsoft.Agents.AI.Shell.Local.IntegrationTests.csproj

westey-m · 2026-01-22T11:26:08Z

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

+    /// the output for each command.
+    /// </para>
+    /// </remarks>
+    public static AIFunction AsAIFunction(this ShellTool shellTool)


Why is ShellTool not inheriting from AIFunction if we want to have it as an AIFunction anyway?

Good question, see comment: #3369 (comment)

westey-m · 2026-01-22T11:28:57Z

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

+        // BlockedPaths = ["/etc", "/var"],
+
+        // Only allow specific commands (regex patterns supported)
+        AllowedCommands = ["^ls", "^dir", "^echo", "^cat", "^type", "^mkdir", "^pwd", "^cd"],


Should we vary these by operating system as well? Some of these don't work in the windows command prompt shell.
Also, commands vary by shell type, so on windows powershell supports ls and pwd, but command prompt does not.

westey-m · 2026-01-22T11:42:10Z

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

+/// <summary>
+/// Raw output from shell executor.
+/// </summary>
+public sealed class ShellExecutorOutput


Also consider ShellExecutorResponse to match AgentRunResponse, and ChatResponse.

westey-m · 2026-01-22T11:48:22Z

dotnet/src/Microsoft.Agents.AI.Shell.Local/LocalShellExecutor.cs

+            return ("cmd.exe", $"/c {command}");
+        }
+
+        return ("/bin/sh", $"-c \"{command.Replace("\"", "\\\"")}\"");


Do we only want to support cmd and sh, or should we make this configurable?

westey-m · 2026-01-22T12:10:10Z

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

+/// Represents the result of a shell command execution.
+/// </summary>
+[DebuggerDisplay("{DebuggerDisplay,nq}")]
+public sealed class ShellResultContent : AIContent


Won't this be provided to the LLM as FunctionResultContent? What's the idea with inheriting from AIContent?
Similar question with ShellCallContent?

So, in current example, we convert ShellTool to AIFunction, just so it can be used with any provider that supports function calls. But function calling is not the only case.

There are providers that support shell tools out of the box, like OpenAI Responses Client:
https://platform.openai.com/docs/guides/tools-shell

They provide executor as example only, but they do have "type": "shell_call" and "type": "shell_call_output" message types, so the user can decide how exactly they want to process this.

That's the primary reason for separate ShellCallContent and ShellResultContent - for the ability to work independently from function calls.

Is the intent then that ShellCallContent/ShellResultContent will be used to represent the server-side shell calls? That translation would best be done in the IChatClient for responses. We should really look at pushing down these parts (at least the call and result content) of the abstractions, along with a HostedShellTool, into MEAI.

Also, it feels like for such a case the local execution would be handled by a piece of middleware akin to FunctionInvokingChatClient, but a ShellCommandInvokingChatClient, which would look for ShellCallContent and produce ShellResultContent. Or FunctionInvokingChatClient could be taught to do that.

cc: @jozkee

Is the intent then that ShellCallContent/ShellResultContent will be used to represent the server-side shell calls? That translation would best be done in the IChatClient for responses. We should really look at pushing down these parts (at least the call and result content) of the abstractions, along with a HostedShellTool, into MEAI.

Correct, and the idea of adding this to MEAI was my initial plan :) I just added it here first, because I want to test it end-to-end, just to understand if there is anything missing.

westey-m · 2026-01-22T12:12:35Z

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

+    private readonly IReadOnlyList<Regex>? _compiledAllowedPatterns;
+    private readonly IReadOnlyList<Regex>? _compiledDeniedPatterns;
+
+    private static readonly string[] s_privilegeEscalationCommands =


Should these be configurable in addition to having defaults? Same for shellWrapperCOmmands and dangerous patterns

westey-m · 2026-01-22T12:14:54Z

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

+        "pkexec"
+    ];
+
+    private static readonly string[] s_shellWrapperCommands =


Should we also have powershell and pswh?

SergeyMenshykh · 2026-01-22T16:35:16Z

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

+    /// Gets or sets the working directory for command execution.
+    /// When null, uses the current working directory.
+    /// </summary>
+    public string? WorkingDirectory { get; set; }


To be on the safe side, I wonder if this property should be mandatory so that users must explicitly provide a working directory, rather than defaulting to Environment.CurrentDirectory. This would ensure users consider where the code is executed and reduce potential security risks.

stephentoub · 2026-01-22T19:10:20Z

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

+/// Represents a shell command execution request.
+/// </summary>
+[DebuggerDisplay("{DebuggerDisplay,nq}")]
+public sealed class ShellCallContent : AIContent


If we unsealed FCC/FRC and made this extend that, I think FunctionInvokingChatClient as-is could be able to handle these shell calls.

Alternatively, I think these shell contents could be completely written in terms of FCC/FRC but it may be too loose i.e. some properties would need to travel in AdditionalProperties.

stephentoub · 2026-01-22T19:11:39Z

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

+/// Represents a shell command execution request.
+/// </summary>
+[DebuggerDisplay("{DebuggerDisplay,nq}")]
+public sealed class ShellCallContent : AIContent


Custom AIContent needs to be added into the AgentsAbstractionJsonUtilities' options so that it correctly participates in polymorphic serialization.

stephentoub · 2026-01-22T19:14:12Z

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

+/// Represents the result of a shell command execution.
+/// </summary>
+[DebuggerDisplay("{DebuggerDisplay,nq}")]
+public sealed class ShellResultContent : AIContent


Is the intent then that ShellCallContent/ShellResultContent will be used to represent the server-side shell calls? That translation would best be done in the IChatClient for responses. We should really look at pushing down these parts (at least the call and result content) of the abstractions, along with a HostedShellTool, into MEAI.

Also, it feels like for such a case the local execution would be handled by a piece of middleware akin to FunctionInvokingChatClient, but a ShellCommandInvokingChatClient, which would look for ShellCallContent and produce ShellResultContent. Or FunctionInvokingChatClient could be taught to do that.

cc: @jozkee

stephentoub · 2026-01-22T19:15:18Z

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

+/// this tool to an <see cref="AIFunction"/> for use with AI agents.
+/// </para>
+/// </remarks>
+public class ShellTool : AITool


If this is invokable, why doesn't it inherit AIFunction?

I decided to keep it separately, because I'm not sure how well it will work with AIFunction-related classes like AIFunctionArguments and FunctionInvokingChatClient.

My thinking was that if OpenAI Responses API defines function tools and shell tools as separate entities, then it's probably a good idea to keep it in the same way on abstraction level.

But I'm looking for the best guidance here.

There's value in making this extend AIFunction since it would be needed for handling shell tool calls in FunctionInvokingChatClient.
https://github.com/dotnet/extensions/blob/ab5bdf603e04a6bbef6366cc93e6e4c5a89d29a3/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/FunctionInvokingChatClient.cs#L854-L855
Unless there's a reason to not want shell tool calls handled there.

I'm still unclear on the purpose of ShellTool as it's written. It doesn't derive from AIFunction so it's not invokable as an AITool, but it has invocation APIs so it doesn't seem like it's a marker tool to be recognized by leaf IChatClients and translated into the right underlying tool for that particular API (OpenAI Responses's shell tool, Anthropic's bash tool, etc.)

stephentoub · 2026-01-22T19:15:42Z

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

+        "runas",
+        "doas",
+        "pkexec"
+    ];


Is there a threat model for all of this?
cc: @GrabYourPitchforks

stephentoub · 2026-01-22T19:17:44Z

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

+        // Overwrite disk
+        new Regex(@">\s*/dev/sd", RegexOptions.Compiled, TimeSpan.FromSeconds(1)),
+        // chmod 777 /
+        new Regex(@"chmod\s+(-[rR]\s+)?777\s+/", RegexOptions.Compiled, TimeSpan.FromSeconds(1)),


If we're concerned about such dangerous commands, I'm concerned this list is insufficient.

How are we thinking about having this vs having folks treat such invocations as requiring of user approval?

(Regardless, shouldn't "dangerous patterns" be configurable?)

stephentoub · 2026-01-22T19:19:24Z

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

+    /// Gets the description of the tool.
+    /// </summary>
+    public override string Description =>
+        "Execute shell commands. Returns stdout, stderr, and exit code for each command.";


If this is the description provided to AI, it should be more descriptive / prescriptive, e.g. about what's supported and what's not supported, what language to use, etc. Is this bash? powershell? etc.?

stephentoub · 2026-01-22T19:20:04Z

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

+        return false;
+    }
+
+    private static bool ContainsPrivilegeEscalation(string command)


If we're relying on this for security, this needs strenuous review.
cc: @GrabYourPitchforks

To be honest, I'm not sure that it will be possible to cover all cases in this PR. The idea here is to add initial set of security validations with a notice that this is recommended to be used only in sandboxed environments with limited access.

stephentoub · 2026-01-26T04:34:30Z

I thought about this a bit today, and here's what I think might make sense:

ShellTool : AIFunction. The tool would itself advertize a schema and description that would allow for arbitrary commands to be handed to it as an argument, such that arbitrary IChatClient implementations would "just work" with it as a shell tool. However, IChatClient implementations backed by a service that has its own notion of a shell tool could instead special-case it (as they special case all the other HostedXxTool types, translating it into usage of the relevant service tool.
ShellCallContent : FunctionCallContent. The FCC would be for the ShellTool, with the derived type having all the specific information relevant to a service's specialized shell invocation. An IChatClient that doesn't have a special shell tool would just produce the base FunctionCallContent like it would for any other tool. An IChatClient with a special shell tool would instead construct the derived ShellCallContent. When ShellTool is invoked, it would look at the FunctionCallContent; if it's of the derived type, it'd do the more specialized thing, and if it's the base, it would just proceed as would any other AIFunction.
ShellResultContent : FunctionResultContent. When doing the special thing, ShellTool's InvokeAsync override would return a ShellResultContent rather than just returning the textual results from invoking the shell tool. We'd tweak the handling of AIFunction in FunctionInvokingChatClient so that an AIFunction returning a FunctionResultContent as the result would just use that FRC rather than creating a new one to wrap the result. That's a useful addition in general, as it gives a function more control over the FunctionResultContent instance that's created, and in this case it means the tool can flow the additional data back strongly-typed. The IChatClient that gets a ShellResultContent would translate that back to the appropriate shell result content expected by the service.

@dmytrostruk, @jozkee, thoughts? If you agree this makes sense, something we could prototype quickly?

dmytrostruk added 10 commits January 21, 2026 20:59

Added ShellTool and LocalShellExecutor

57938f4

Added more validation

1b91910

Added sample

5b024e9

Small improvement

09f8022

Small updates

03404bf

Fixed warnings

4cc16b7

Updated sample

8c9a721

Improvements

fab1035

Small updates

bf535bb

Small improvements

c662f4d

dmytrostruk self-assigned this Jan 22, 2026

dmytrostruk added the .NET label Jan 22, 2026

Copilot AI review requested due to automatic review settings January 22, 2026 08:17

markwallace-microsoft added the documentation Improvements or additions to documentation label Jan 22, 2026

dmytrostruk had a problem deploying to integration January 22, 2026 08:18 — with GitHub Actions Error

Copilot started reviewing on behalf of dmytrostruk January 22, 2026 08:18 View session

Merge branch 'main' into shell-tool-dotnet

2419961

dmytrostruk had a problem deploying to integration January 22, 2026 08:21 — with GitHub Actions Error

Copilot AI reviewed Jan 22, 2026

View reviewed changes

Fixed formatting

d4d96fc

dmytrostruk had a problem deploying to integration January 22, 2026 08:29 — with GitHub Actions Failure

dmytrostruk temporarily deployed to integration January 22, 2026 08:29 — with GitHub Actions Inactive

Resolved comments and fixed tests

bff6cb7

dmytrostruk temporarily deployed to integration January 22, 2026 08:42 — with GitHub Actions Inactive

westey-m reviewed Jan 22, 2026

View reviewed changes

Merge branch 'main' into shell-tool-dotnet

2ddf8a9

dmytrostruk temporarily deployed to integration January 22, 2026 16:02 — with GitHub Actions Inactive

SergeyMenshykh reviewed Jan 22, 2026

View reviewed changes

Merge branch 'main' into shell-tool-dotnet

889ba25

dmytrostruk temporarily deployed to integration January 22, 2026 17:21 — with GitHub Actions Inactive

stephentoub requested changes Jan 22, 2026

View reviewed changes

dmytrostruk marked this pull request as draft January 23, 2026 02:01

.NET: Added ShellTool and LocalShellExecutor #3369

Are you sure you want to change the base?

.NET: Added ShellTool and LocalShellExecutor #3369

Uh oh!

Conversation

dmytrostruk commented Jan 22, 2026

Motivation and Context

Contribution Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephentoub Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

westey-m Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephentoub Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephentoub commented Jan 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

stephentoub Jan 22, 2026 •

edited

Loading

westey-m Jan 22, 2026 •

edited

Loading

stephentoub Jan 22, 2026 •

edited

Loading