.NET Workflows - Add support for tool approval (#1685)

* Draft

* Nullable init

* Complete

* Consistency

* Test fix

* Typo

* Comment

* Updated

* Fix identifier

* Test fix

* Comment typo

* Better naming

* Comment

* Tweak comment

Author: crickman

dotnet/samples/GettingStarted/Workflows/Declarative/ExecuteWorkflow/Program.cs

@@ -336,17 +336,19 @@ private async ValueTask<object> HandleExternalRequestAsync(ExternalRequest reque
         request.Data.TypeId.TypeName switch
         {
             // Request for human input
-            _ when request.Data.TypeId.IsMatch<InputRequest>() => HandleInputRequest(request.DataAs<InputRequest>()!),
+            _ when request.Data.TypeId.IsMatch<AnswerRequest>() => HandleUserMessageRequest(request.DataAs<AnswerRequest>()!),
             // Request for function tool invocation.  (Only active when functions are defined and IncludeFunctions is true.)
-            _ when request.Data.TypeId.IsMatch<AgentToolRequest>() => await this.HandleToolRequestAsync(request.DataAs<AgentToolRequest>()!),
+            _ when request.Data.TypeId.IsMatch<AgentFunctionToolRequest>() => await this.HandleToolRequestAsync(request.DataAs<AgentFunctionToolRequest>()!),
+            // Request for user input, such as function or mcp tool approval
+            _ when request.Data.TypeId.IsMatch<UserInputRequest>() => HandleUserInputRequest(request.DataAs<UserInputRequest>()!),
             // Unknown request type.
             _ => throw new InvalidOperationException($"Unsupported external request type: {request.GetType().Name}."),
         };
 
     /// <summary>
     /// Handle request for human input.
     /// </summary>
-    private static InputResponse HandleInputRequest(InputRequest request)
+    private static AnswerResponse HandleUserMessageRequest(AnswerRequest request)
     {
         string? userInput;
         do
@@ -358,7 +360,7 @@ private static InputResponse HandleInputRequest(InputRequest request)
         }
         while (string.IsNullOrWhiteSpace(userInput));
 
-        return new InputResponse(userInput);
+        return new AnswerResponse(userInput);
     }
 
     /// <summary>
@@ -368,13 +370,13 @@ private static InputResponse HandleInputRequest(InputRequest request)
     /// This handler is only active when <see cref="IncludeFunctions"/> is set to true and
     /// one or more <see cref="AIFunction"/> instances are defined in the constructor.
     /// </remarks>
-    private async ValueTask<AgentToolResponse> HandleToolRequestAsync(AgentToolRequest request)
+    private async ValueTask<AgentFunctionToolResponse> HandleToolRequestAsync(AgentFunctionToolRequest request)
     {
         Task<FunctionResultContent>[] functionTasks = request.FunctionCalls.Select(functionCall => InvokesToolAsync(functionCall)).ToArray();
 
         await Task.WhenAll(functionTasks);
 
-        return AgentToolResponse.Create(request, functionTasks.Select(task => task.Result));
+        return AgentFunctionToolResponse.Create(request, functionTasks.Select(task => task.Result));
 
         async Task<FunctionResultContent> InvokesToolAsync(FunctionCallContent functionCall)
         {
@@ -385,6 +387,30 @@ async Task<FunctionResultContent> InvokesToolAsync(FunctionCallContent functionC
         }
     }
 
+    /// <summary>
+    /// Handle request for user input for mcp and function tool approval.
+    /// </summary>
+    private static UserInputResponse HandleUserInputRequest(UserInputRequest request)
+    {
+        return UserInputResponse.Create(request, ProcessRequests());
+
+        IEnumerable<UserInputResponseContent> ProcessRequests()
+        {
+            foreach (UserInputRequestContent approvalRequest in request.InputRequests)
+            {
+                // Here we are explicitly approving all requests.
+                // In a real-world scenario, you would replace this logic to either solicit user approval or implement a more complex approval process.
+                yield return
+                    approvalRequest switch
+                    {
+                        McpServerToolApprovalRequestContent mcpApprovalRequest => mcpApprovalRequest.CreateResponse(approved: true),
+                        FunctionApprovalRequestContent functionApprovalRequest => functionApprovalRequest.CreateResponse(approved: true),
+                        _ => throw new NotSupportedException($"Unsupported request of type {approvalRequest.GetType().Name}"),
+                    };
+            }
+        }
+    }
+
     private static string? ParseWorkflowFile(string[] args)
     {
         string? workflowFile = args.FirstOrDefault();

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Events/AgentToolRequest.cs renamed to dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Events/AgentFunctionToolRequest.cs

@@ -7,24 +7,24 @@
 namespace Microsoft.Agents.AI.Workflows.Declarative.Events;
 
 /// <summary>
-/// Represents a request for user input.
+/// Represents one or more function tool requests.
 /// </summary>
-public sealed class AgentToolRequest
+public sealed class AgentFunctionToolRequest
 {
     /// <summary>
     /// The name of the agent associated with the tool request.
     /// </summary>
     public string AgentName { get; }
 
     /// <summary>
-    /// A list of tool requests.
+    /// A list of function tool requests.
     /// </summary>
     public IList<FunctionCallContent> FunctionCalls { get; }
 
     [JsonConstructor]
-    internal AgentToolRequest(string agentName, IList<FunctionCallContent>? functionCalls = null)
+    internal AgentFunctionToolRequest(string agentName, IList<FunctionCallContent> functionCalls)
     {
         this.AgentName = agentName;
-        this.FunctionCalls = functionCalls ?? [];
+        this.FunctionCalls = functionCalls;
     }
 }

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Events/AgentToolResponse.cs renamed to dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Events/AgentFunctionToolResponse.cs

@@ -8,9 +8,9 @@
 namespace Microsoft.Agents.AI.Workflows.Declarative.Events;
 
 /// <summary>
-/// Represents a user input response.
+/// Represents one or more function tool responses.
 /// </summary>
-public sealed class AgentToolResponse
+public sealed class AgentFunctionToolResponse
 {
     /// <summary>
     /// The name of the agent associated with the tool response.
@@ -22,32 +22,31 @@ public sealed class AgentToolResponse
     /// </summary>
     public IList<FunctionResultContent> FunctionResults { get; }
 
-    /// <summary>
-    /// Initializes a new instance of the <see cref="InputResponse"/> class.
-    /// </summary>
     [JsonConstructor]
-    internal AgentToolResponse(string agentName, IList<FunctionResultContent> functionResults)
+    internal AgentFunctionToolResponse(string agentName, IList<FunctionResultContent> functionResults)
     {
         this.AgentName = agentName;
         this.FunctionResults = functionResults;
     }
 
     /// <summary>
-    /// Factory method to create an <see cref="AgentToolResponse"/> from an <see cref="AgentToolRequest"/>
+    /// Factory method to create an <see cref="AgentFunctionToolResponse"/> from an <see cref="AgentFunctionToolRequest"/>
     /// Ensures that all function calls in the request have a corresponding result.
     /// </summary>
     /// <param name="toolRequest">The tool request.</param>
-    /// <param name="functionResults">On or more function results</param>
-    /// <returns>An <see cref="AgentToolResponse"/> that can be provided to the workflow.</returns>
-    /// <exception cref="DeclarativeActionException">Not all <see cref="AgentToolRequest.FunctionCalls"/> have a corresponding <see cref="FunctionResultContent"/>.</exception>
-    public static AgentToolResponse Create(AgentToolRequest toolRequest, params IEnumerable<FunctionResultContent> functionResults)
+    /// <param name="functionResults">One or more function results</param>
+    /// <returns>An <see cref="AgentFunctionToolResponse"/> that can be provided to the workflow.</returns>
+    /// <exception cref="DeclarativeActionException">Not all <see cref="AgentFunctionToolRequest.FunctionCalls"/> have a corresponding <see cref="FunctionResultContent"/>.</exception>
+    public static AgentFunctionToolResponse Create(AgentFunctionToolRequest toolRequest, params IEnumerable<FunctionResultContent> functionResults)
     {
         HashSet<string> callIds = [.. toolRequest.FunctionCalls.Select(call => call.CallId)];
         HashSet<string> resultIds = [.. functionResults.Select(call => call.CallId)];
+
         if (!callIds.SetEquals(resultIds))
         {
             throw new DeclarativeActionException($"Missing results for: {string.Join(",", callIds.Except(resultIds))}");
         }
-        return new AgentToolResponse(toolRequest.AgentName, [.. functionResults]);
+
+        return new AgentFunctionToolResponse(toolRequest.AgentName, [.. functionResults]);
     }
 }

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Events/AnswerRequest.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative.Events;
+
+/// <summary>
+/// Represents a request for user input in response to a `Question` action.
+/// </summary>
+public sealed class AnswerRequest
+{
+    /// <summary>
+    /// An optional prompt for the user.
+    /// </summary>
+    /// <remarks>
+    /// This prompt is utilized for the "Question" action type in the Declarative Workflow,
+    /// but is redundant when the user is responding to an agent since the agent's message
+    /// is the implicit prompt.
+    /// </remarks>
+    public string? Prompt { get; }
+
+    [JsonConstructor]
+    internal AnswerRequest(string? prompt = null)
+    {
+        this.Prompt = prompt;
+    }
+}

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Events/InputResponse.cs renamed to dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Events/AnswerResponse.cs

@@ -8,28 +8,28 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.Events;
 /// <summary>
 /// Represents a user input response.
 /// </summary>
-public sealed class InputResponse
+public sealed class AnswerResponse
 {
     /// <summary>
     /// The response value.
     /// </summary>
     public ChatMessage Value { get; }
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="InputResponse"/> class.
+    /// Initializes a new instance of the <see cref="AnswerResponse"/> class.
     /// </summary>
     /// <param name="value">The response value.</param>
     [JsonConstructor]
-    public InputResponse(ChatMessage value)
+    public AnswerResponse(ChatMessage value)
     {
         this.Value = value;
     }
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="InputResponse"/> class.
+    /// Initializes a new instance of the <see cref="AnswerResponse"/> class.
     /// </summary>
     /// <param name="value">The response value.</param>
-    public InputResponse(string value)
+    public AnswerResponse(string value)
     {
         this.Value = new ChatMessage(ChatRole.User, value);
     }

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Events/InputRequest.cs

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative.Events;
+
+/// <summary>
+/// Represents one or more user-input requests.
+/// </summary>
+public sealed class UserInputRequest
+{
+    /// <summary>
+    /// The name of the agent associated with the tool request.
+    /// </summary>
+    public string AgentName { get; }
+
+    /// <summary>
+    /// A list of user input requests.
+    /// </summary>
+    public IList<AIContent> InputRequests { get; }
+
+    [JsonConstructor]
+    internal UserInputRequest(string agentName, IList<AIContent> inputRequests)
+    {
+        this.AgentName = agentName;
+        this.InputRequests = inputRequests;
+    }
+}

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Events/UserInputRequest.cs

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Linq;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative.Events;
+
+/// <summary>
+/// Represents one or more user-input responses.
+/// </summary>
+public sealed class UserInputResponse
+{
+    /// <summary>
+    /// The name of the agent associated with the tool request.
+    /// </summary>
+    public string AgentName { get; }
+
+    /// <summary>
+    /// A list of approval responses.
+    /// </summary>
+    public IList<AIContent> InputResponses { get; }
+
+    [JsonConstructor]
+    internal UserInputResponse(string agentName, IList<AIContent> inputResponses)
+    {
+        this.AgentName = agentName;
+        this.InputResponses = inputResponses;
+    }
+
+    /// <summary>
+    /// Factory method to create an <see cref="UserInputResponse"/> from a <see cref="UserInputRequest"/>
+    /// Ensures that all requests have a corresponding result.
+    /// </summary>
+    /// <param name="inputRequest">The input request.</param>
+    /// <param name="inputResponses">One or more responses</param>
+    /// <returns>An <see cref="UserInputResponse"/> that can be provided to the workflow.</returns>
+    /// <exception cref="DeclarativeActionException">Not all <see cref="AgentFunctionToolRequest.FunctionCalls"/> have a corresponding <see cref="FunctionResultContent"/>.</exception>
+    public static UserInputResponse Create(UserInputRequest inputRequest, params IEnumerable<UserInputResponseContent> inputResponses)
+    {
+        HashSet<string> callIds = [.. inputRequest.InputRequests.OfType<UserInputRequestContent>().Select(call => call.Id)];
+        HashSet<string> resultIds = [.. inputResponses.Select(call => call.Id)];
+
+        if (!callIds.SetEquals(resultIds))
+        {
+            throw new DeclarativeActionException($"Missing responses for: {string.Join(",", callIds.Except(resultIds))}");
+        }
+
+        return new UserInputResponse(inputRequest.AgentName, [.. inputResponses]);
+    }
+}

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Events/UserInputResponse.cs

@@ -249,13 +249,13 @@ protected override void Visit(Question item)
 
         // Define input action
         string inputId = QuestionExecutor.Steps.Input(action.Id);
-        RequestPortAction inputPort = new(RequestPort.Create<InputRequest, InputResponse>(inputId));
+        RequestPortAction inputPort = new(RequestPort.Create<AnswerRequest, AnswerResponse>(inputId));
         this._workflowModel.AddNode(inputPort, action.ParentId);
         this._workflowModel.AddLinkFromPeer(action.ParentId, inputId);
 
         // Capture input response
         string captureId = QuestionExecutor.Steps.Capture(action.Id);
-        this.ContinueWith(new DelegateActionExecutor<InputResponse>(captureId, this._workflowState, action.CaptureResponseAsync, emitResult: false), action.ParentId);
+        this.ContinueWith(new DelegateActionExecutor<AnswerResponse>(captureId, this._workflowState, action.CaptureResponseAsync, emitResult: false), action.ParentId);
 
         // Transition to post action if complete
         this.ContinueWith(new DelegateActionExecutor(postId, this._workflowState, action.CompleteAsync), action.ParentId, QuestionExecutor.IsComplete);
@@ -315,22 +315,31 @@ protected override void Visit(InvokeAzureAgent item)
         this.ContinueWith(action);
         // Transition to post action if complete
         string postId = Steps.Post(action.Id);
-        this._workflowModel.AddLink(action.Id, postId, result => !InvokeAzureAgentExecutor.RequiresInput(result));
+        this._workflowModel.AddLink(action.Id, postId, InvokeAzureAgentExecutor.RequiresNothing);
 
-        // Define input action
-        string inputId = InvokeAzureAgentExecutor.Steps.Input(action.Id);
-        RequestPortAction inputPort = new(RequestPort.Create<AgentToolRequest, AgentToolResponse>(inputId));
-        this._workflowModel.AddNode(inputPort, action.ParentId);
-        this._workflowModel.AddLink(action.Id, inputId, InvokeAzureAgentExecutor.RequiresInput);
+        // Define request-port for function calling action
+        string functionCallingPortId = InvokeAzureAgentExecutor.Steps.FunctionTool(action.Id);
+        RequestPortAction functionCallingPort = new(RequestPort.Create<AgentFunctionToolRequest, AgentFunctionToolResponse>(functionCallingPortId));
+        this._workflowModel.AddNode(functionCallingPort, action.ParentId);
+        this._workflowModel.AddLink(action.Id, functionCallingPort.Id, InvokeAzureAgentExecutor.RequiresFunctionCall);
+
+        // Define request-port for user input, such as: mcp tool & function tool approval
+        string userInputPortId = InvokeAzureAgentExecutor.Steps.UserInput(action.Id);
+        RequestPortAction userInputPort = new(RequestPort.Create<UserInputRequest, UserInputResponse>(userInputPortId));
+        this._workflowModel.AddNode(userInputPort, action.ParentId);
+        this._workflowModel.AddLink(action.Id, userInputPortId, InvokeAzureAgentExecutor.RequiresUserInput);
 
-        // Input port always transitions to resume
+        // Request ports always transitions to resume
         string resumeId = InvokeAzureAgentExecutor.Steps.Resume(action.Id);
-        this._workflowModel.AddNode(new DelegateActionExecutor<AgentToolResponse>(resumeId, this._workflowState, action.ResumeAsync), action.ParentId);
-        this._workflowModel.AddLink(inputId, resumeId);
-        // Transition to request port if more input is required
-        this._workflowModel.AddLink(resumeId, inputId, InvokeAzureAgentExecutor.RequiresInput);
+        this._workflowModel.AddNode(new DelegateActionExecutor<AgentFunctionToolResponse>(resumeId, this._workflowState, action.ResumeAsync), action.ParentId);
+        this._workflowModel.AddLink(functionCallingPortId, resumeId);
+        this._workflowModel.AddLink(userInputPortId, resumeId);
+        // Transition to appropriate request port if more function calling is requested
+        this._workflowModel.AddLink(resumeId, functionCallingPortId, InvokeAzureAgentExecutor.RequiresFunctionCall);
+        // Transition to appropriate request port if more user input is requested
+        this._workflowModel.AddLink(resumeId, userInputPortId, InvokeAzureAgentExecutor.RequiresUserInput);
         // Transition to post action if complete
-        this._workflowModel.AddLink(resumeId, postId, result => !InvokeAzureAgentExecutor.RequiresInput(result));
+        this._workflowModel.AddLink(resumeId, postId, InvokeAzureAgentExecutor.RequiresNothing);
 
         // Define post action
         this._workflowModel.AddNode(new DelegateActionExecutor(postId, this._workflowState, action.CompleteAsync), action.ParentId);

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowActionVisitor.cs

@@ -4,6 +4,7 @@
     <TargetFrameworks>$(ProjectsTargetFrameworks)</TargetFrameworks>
     <TargetFrameworks Condition="'$(Configuration)' == 'Debug'">$(ProjectsDebugTargetFrameworks)</TargetFrameworks>
     <VersionSuffix>preview</VersionSuffix>
+    <NoWarn>$(NoWarn);MEAI001</NoWarn>
   </PropertyGroup>
 
   <PropertyGroup>