.NET Workflows - Rename agent-provider and add comments (Declarative Workflows) (#3895)

* Renamed with comments

* Fix rename arcs

* Integration tests

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative.AzureAI/AzureAgentProvider.cs

@@ -25,7 +25,7 @@ namespace Microsoft.Agents.AI.Workflows.Declarative;
 /// project endpoint and credentials to authenticate requests.</remarks>
 /// <param name="projectEndpoint">A <see cref="Uri"/> instance representing the endpoint URL of the Foundry project. This must be a valid, non-null URI pointing to the project.</param>
 /// <param name="projectCredentials">The credentials used to authenticate with the Foundry project. This must be a valid instance of <see cref="TokenCredential"/>.</param>
-public sealed class AzureAgentProvider(Uri projectEndpoint, TokenCredential projectCredentials) : WorkflowAgentProvider
+public sealed class AzureAgentProvider(Uri projectEndpoint, TokenCredential projectCredentials) : ResponseAgentProvider
 {
     private readonly Dictionary<string, AgentVersion> _versionCache = [];
     private readonly Dictionary<string, AIAgent> _agentCache = [];

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/AddConversationMessageTemplate.cs

@@ -35,7 +35,7 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.CodeGen
             this.Write("\n/// <summary>\n/// Adds a new message to the specified agent conversation\n/// </s" +
                     "ummary>\ninternal sealed class ");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Name));
-            this.Write("Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : ActionExe" +
+            this.Write("Executor(FormulaSession session, ResponseAgentProvider agentProvider) : ActionExe" +
                     "cutor(id: \"");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Id));
             this.Write("\", session)\n{\n    // <inheritdoc />\n    protected override async ValueTask<object" +

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/AddConversationMessageTemplate.tt

@@ -10,7 +10,7 @@
 /// <summary>
 /// Adds a new message to the specified agent conversation
 /// </summary>
-internal sealed class <#= this.Name #>Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : ActionExecutor(id: "<#= this.Id #>", session)
+internal sealed class <#= this.Name #>Executor(FormulaSession session, ResponseAgentProvider agentProvider) : ActionExecutor(id: "<#= this.Id #>", session)
 {
     // <inheritdoc />
     protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/CopyConversationMessagesTemplate.cs

@@ -34,7 +34,7 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.CodeGen
             this.Write("\n/// <summary>\n/// Copies one or more messages into the specified agent conversat" +
                     "ion.\n/// </summary>\ninternal sealed class ");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Name));
-            this.Write("Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : ActionExe" +
+            this.Write("Executor(FormulaSession session, ResponseAgentProvider agentProvider) : ActionExe" +
                     "cutor(id: \"");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Id));
             this.Write("\", session)\n{\n    // <inheritdoc />\n    protected override async ValueTask<object" +

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/CopyConversationMessagesTemplate.tt

@@ -9,7 +9,7 @@
 /// <summary>
 /// Copies one or more messages into the specified agent conversation.
 /// </summary>
-internal sealed class <#= this.Name #>Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : ActionExecutor(id: "<#= this.Id #>", session)
+internal sealed class <#= this.Name #>Executor(FormulaSession session, ResponseAgentProvider agentProvider) : ActionExecutor(id: "<#= this.Id #>", session)
 {
     // <inheritdoc />
     protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/CreateConversationTemplate.cs

@@ -32,7 +32,7 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.CodeGen
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Model.ConversationId));
             this.Write("\" variable.\n/// </summary>\ninternal sealed class ");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Name));
-            this.Write("Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : ActionExe" +
+            this.Write("Executor(FormulaSession session, ResponseAgentProvider agentProvider) : ActionExe" +
                     "cutor(id: \"");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Id));
             this.Write(@""", session)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/CreateConversationTemplate.tt

@@ -6,7 +6,7 @@
 /// <summary>
 /// Creates a new conversation and stores the identifier value to the "<#= this.Model.ConversationId #>" variable.
 /// </summary>
-internal sealed class <#= this.Name #>Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : ActionExecutor(id: "<#= this.Id #>", session)
+internal sealed class <#= this.Name #>Executor(FormulaSession session, ResponseAgentProvider agentProvider) : ActionExecutor(id: "<#= this.Id #>", session)
 {
     protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken)
     {

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/InvokeAzureAgentTemplate.cs

@@ -39,7 +39,7 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.CodeGen
             this.Write("\n/// <summary>\n/// Invokes an agent to process messages and return a response wit" +
                     "hin a conversation context.\n/// </summary>\ninternal sealed class ");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Name));
-            this.Write("Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : AgentExec" +
+            this.Write("Executor(FormulaSession session, ResponseAgentProvider agentProvider) : AgentExec" +
                     "utor(id: \"");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Id));
             this.Write("\", session, agentProvider)\n{\n    // <inheritdoc />\n    protected override async V" +

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/InvokeAzureAgentTemplate.tt

@@ -12,7 +12,7 @@
 /// <summary>
 /// Invokes an agent to process messages and return a response within a conversation context.
 /// </summary>
-internal sealed class <#= this.Name #>Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : AgentExecutor(id: "<#= this.Id #>", session, agentProvider)
+internal sealed class <#= this.Name #>Executor(FormulaSession session, ResponseAgentProvider agentProvider) : AgentExecutor(id: "<#= this.Id #>", session, agentProvider)
 {
     // <inheritdoc />
     protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/RetrieveConversationMessageTemplate.cs

@@ -32,7 +32,7 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.CodeGen
             this.Write("\n/// <summary>\n/// Retrieves a list of messages from an agent conversation.\n/// <" +
                     "/summary>\ninternal sealed class ");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Name));
-            this.Write("Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : ActionExe" +
+            this.Write("Executor(FormulaSession session, ResponseAgentProvider agentProvider) : ActionExe" +
                     "cutor(id: \"");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Id));
             this.Write("\", session)\n{\n    // <inheritdoc />\n    protected override async ValueTask<object" +

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/RetrieveConversationMessageTemplate.tt

@@ -8,7 +8,7 @@
 /// <summary>
 /// Retrieves a list of messages from an agent conversation.
 /// </summary>
-internal sealed class <#= this.Name #>Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : ActionExecutor(id: "<#= this.Id #>", session)
+internal sealed class <#= this.Name #>Executor(FormulaSession session, ResponseAgentProvider agentProvider) : ActionExecutor(id: "<#= this.Id #>", session)
 {
     // <inheritdoc />
     protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/RetrieveConversationMessagesTemplate.cs

@@ -38,7 +38,7 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.CodeGen
             this.Write("\n/// <summary>\n/// Retrieves a specific message from an agent conversation.\n/// <" +
                     "/summary>\ninternal sealed class ");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Name));
-            this.Write("Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : ActionExe" +
+            this.Write("Executor(FormulaSession session, ResponseAgentProvider agentProvider) : ActionExe" +
                     "cutor(id: \"");
             this.Write(this.ToStringHelper.ToStringWithCulture(this.Id));
             this.Write("\", session)\n{\n    // <inheritdoc />\n    protected override async ValueTask<object" +

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/RetrieveConversationMessagesTemplate.tt

@@ -12,7 +12,7 @@
 /// <summary>
 /// Retrieves a specific message from an agent conversation.
 /// </summary>
-internal sealed class <#= this.Name #>Executor(FormulaSession session, WorkflowAgentProvider agentProvider) : ActionExecutor(id: "<#= this.Id #>", session)
+internal sealed class <#= this.Name #>Executor(FormulaSession session, ResponseAgentProvider agentProvider) : ActionExecutor(id: "<#= this.Id #>", session)
 {
     // <inheritdoc />
     protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowOptions.cs

@@ -13,12 +13,12 @@ namespace Microsoft.Agents.AI.Workflows.Declarative;
 /// <summary>
 /// Configuration options for workflow execution.
 /// </summary>
-public sealed class DeclarativeWorkflowOptions(WorkflowAgentProvider agentProvider)
+public sealed class DeclarativeWorkflowOptions(ResponseAgentProvider agentProvider)
 {
     /// <summary>
     /// Defines the agent provider.
     /// </summary>
-    public WorkflowAgentProvider AgentProvider { get; } = Throw.IfNull(agentProvider);
+    public ResponseAgentProvider AgentProvider { get; } = Throw.IfNull(agentProvider);
 
     /// <summary>
     /// Defines the configuration settings for the workflow.

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Extensions/AgentProviderExtensions.cs

@@ -10,7 +10,7 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.Extensions;
 internal static class AgentProviderExtensions
 {
     public static async ValueTask<AgentResponse> InvokeAgentAsync(
-        this WorkflowAgentProvider agentProvider,
+        this ResponseAgentProvider agentProvider,
         string executorId,
         IWorkflowContext context,
         string agentName,

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Kit/AgentExecutor.cs

@@ -14,10 +14,10 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.Kit;
 /// <param name="id">The executor id</param>
 /// <param name="session">Session to support formula expressions.</param>
 /// <param name="agentProvider">Provider for accessing and manipulating agents and conversations.</param>
-public abstract class AgentExecutor(string id, FormulaSession session, WorkflowAgentProvider agentProvider) : ActionExecutor(id, session)
+public abstract class AgentExecutor(string id, FormulaSession session, ResponseAgentProvider agentProvider) : ActionExecutor(id, session)
 {
     /// <summary>
-    /// Invokes an agent using the provided <see cref="WorkflowAgentProvider"/>.
+    /// Invokes an agent using the provided <see cref="ResponseAgentProvider"/>.
     /// </summary>
     /// <param name="context">The workflow execution context providing messaging and state services.</param>
     /// <param name="agentName">The name or identifier of the agent.</param>

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Kit/RootExecutor.cs

@@ -18,7 +18,7 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.Kit;
 public abstract class RootExecutor<TInput> : Executor<TInput>, IResettableExecutor where TInput : notnull
 {
     private readonly IConfiguration? _configuration;
-    private readonly WorkflowAgentProvider _agentProvider;
+    private readonly ResponseAgentProvider _agentProvider;
     private readonly WorkflowFormulaState _state;
     private readonly Func<TInput, ChatMessage>? _inputTransform;
 

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/AddConversationMessageExecutor.cs

@@ -12,7 +12,7 @@ using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
 
-internal sealed class AddConversationMessageExecutor(AddConversationMessage model, WorkflowAgentProvider agentProvider, WorkflowFormulaState state) :
+internal sealed class AddConversationMessageExecutor(AddConversationMessage model, ResponseAgentProvider agentProvider, WorkflowFormulaState state) :
     DeclarativeActionExecutor<AddConversationMessage>(model, state)
 {
     protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken = default)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/CopyConversationMessagesExecutor.cs

@@ -13,7 +13,7 @@ using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
 
-internal sealed class CopyConversationMessagesExecutor(CopyConversationMessages model, WorkflowAgentProvider agentProvider, WorkflowFormulaState state) :
+internal sealed class CopyConversationMessagesExecutor(CopyConversationMessages model, ResponseAgentProvider agentProvider, WorkflowFormulaState state) :
     DeclarativeActionExecutor<CopyConversationMessages>(model, state)
 {
     protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken = default)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/CreateConversationExecutor.cs

@@ -11,7 +11,7 @@ using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
 
-internal sealed class CreateConversationExecutor(CreateConversation model, WorkflowAgentProvider agentProvider, WorkflowFormulaState state) :
+internal sealed class CreateConversationExecutor(CreateConversation model, ResponseAgentProvider agentProvider, WorkflowFormulaState state) :
     DeclarativeActionExecutor<CreateConversation>(model, state)
 {
     protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken = default)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/InvokeAzureAgentExecutor.cs

@@ -17,7 +17,7 @@ using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
 
-internal sealed class InvokeAzureAgentExecutor(InvokeAzureAgent model, WorkflowAgentProvider agentProvider, WorkflowFormulaState state) :
+internal sealed class InvokeAzureAgentExecutor(InvokeAzureAgent model, ResponseAgentProvider agentProvider, WorkflowFormulaState state) :
     DeclarativeActionExecutor<InvokeAzureAgent>(model, state)
 {
     public static class Steps

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/QuestionExecutor.cs

@@ -16,7 +16,7 @@ using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
 
-internal sealed class QuestionExecutor(Question model, WorkflowAgentProvider agentProvider, WorkflowFormulaState state) :
+internal sealed class QuestionExecutor(Question model, ResponseAgentProvider agentProvider, WorkflowFormulaState state) :
     DeclarativeActionExecutor<Question>(model, state)
 {
     public static class Steps

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/RequestExternalInputExecutor.cs

@@ -12,7 +12,7 @@ using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
 
-internal sealed class RequestExternalInputExecutor(RequestExternalInput model, WorkflowAgentProvider agentProvider, WorkflowFormulaState state)
+internal sealed class RequestExternalInputExecutor(RequestExternalInput model, ResponseAgentProvider agentProvider, WorkflowFormulaState state)
     : DeclarativeActionExecutor<RequestExternalInput>(model, state)
 {
     public static class Steps

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/RetrieveConversationMessageExecutor.cs

@@ -11,7 +11,7 @@ using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
 
-internal sealed class RetrieveConversationMessageExecutor(RetrieveConversationMessage model, WorkflowAgentProvider agentProvider, WorkflowFormulaState state) :
+internal sealed class RetrieveConversationMessageExecutor(RetrieveConversationMessage model, ResponseAgentProvider agentProvider, WorkflowFormulaState state) :
     DeclarativeActionExecutor<RetrieveConversationMessage>(model, state)
 {
     protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken = default)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/RetrieveConversationMessagesExecutor.cs

@@ -13,7 +13,7 @@ using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
 
-internal sealed class RetrieveConversationMessagesExecutor(RetrieveConversationMessages model, WorkflowAgentProvider agentProvider, WorkflowFormulaState state) :
+internal sealed class RetrieveConversationMessagesExecutor(RetrieveConversationMessages model, ResponseAgentProvider agentProvider, WorkflowFormulaState state) :
     DeclarativeActionExecutor<RetrieveConversationMessages>(model, state)
 {
     protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken = default)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ResponseAgentProvider.cs

@@ -11,9 +11,15 @@ using Microsoft.Extensions.AI;
 namespace Microsoft.Agents.AI.Workflows.Declarative;
 
 /// <summary>
-/// Base class for workflow agent providers.
+/// Defines contract used by declarative workflow actions to invoke and manipulate agents and conversations.
 /// </summary>
-public abstract class WorkflowAgentProvider
+/// <remarks>
+/// The shape of this provider contract is very much opinionated around patterns that exist in the Open AI Responses API.
+/// In addition to direct usage of the Responses API, Foundry V2 agents are supported as they are fundamentally based on
+/// the Open AI Responses API.  Using other <see cref="AIAgent"/> or <see cref="ChatClientAgent"/> patterns that are not
+/// based on the Response API is currently not supported.
+/// </remarks>
+public abstract class ResponseAgentProvider
 {
     /// <summary>
     /// Gets or sets a collection of additional tools an agent is able to automatically invoke.

dotnet/src/Shared/Workflows/Execution/WorkflowFactory.cs

@@ -24,7 +24,7 @@ internal sealed class WorkflowFactory(string workflowFile, Uri foundryEndpoint)
 
     /// <summary>
     /// Create the workflow from the declarative YAML.  Includes definition of the
-    /// <see cref="DeclarativeWorkflowOptions" /> and the associated <see cref="WorkflowAgentProvider"/>.
+    /// <see cref="DeclarativeWorkflowOptions" /> and the associated <see cref="ResponseAgentProvider"/>.
     /// </summary>
     public Workflow CreateWorkflow()
     {