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

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/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 @@
 
 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 @@
 
 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 @@
 
 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 @@
 
 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 @@
 
 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 @@
 
 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 @@
 
 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 @@
 
 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/WorkflowAgentProvider.cs → dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ResponseAgentProvider.cs

@@ -11,9 +11,15 @@
 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/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/DeclarativeWorkflowContextTest.cs

@@ -14,7 +14,7 @@ public class DeclarativeWorkflowContextTests
     public void InitializeDefaultValues()
     {
         // Act
-        Mock<WorkflowAgentProvider> mockProvider = new(MockBehavior.Strict);
+        Mock<ResponseAgentProvider> mockProvider = new(MockBehavior.Strict);
         DeclarativeWorkflowOptions context = new(mockProvider.Object);
 
         // Assert
@@ -34,7 +34,7 @@ public void InitializeExplicitValues()
         ILoggerFactory loggerFactory = LoggerFactory.Create(builder => { });
 
         // Act
-        Mock<WorkflowAgentProvider> mockProvider = new(MockBehavior.Strict);
+        Mock<ResponseAgentProvider> mockProvider = new(MockBehavior.Strict);
         DeclarativeWorkflowOptions context = new(mockProvider.Object)
         {
             MaximumCallDepth = MaxCallDepth,

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/DeclarativeWorkflowOptionsTest.cs

@@ -65,7 +65,7 @@ public void Dispose()
     public void ConfigureTelemetry_DefaultIsNull()
     {
         // Arrange
-        Mock<WorkflowAgentProvider> mockProvider = CreateMockProvider();
+        Mock<ResponseAgentProvider> mockProvider = CreateMockProvider();
 
         // Act
         DeclarativeWorkflowOptions options = new(mockProvider.Object);
@@ -78,7 +78,7 @@ public void ConfigureTelemetry_DefaultIsNull()
     public void ConfigureTelemetry_CanBeSet()
     {
         // Arrange
-        Mock<WorkflowAgentProvider> mockProvider = CreateMockProvider();
+        Mock<ResponseAgentProvider> mockProvider = CreateMockProvider();
         bool callbackInvoked = false;
 
         // Act
@@ -103,7 +103,7 @@ public void ConfigureTelemetry_CanBeSet()
     public void TelemetryActivitySource_DefaultIsNull()
     {
         // Arrange
-        Mock<WorkflowAgentProvider> mockProvider = CreateMockProvider();
+        Mock<ResponseAgentProvider> mockProvider = CreateMockProvider();
 
         // Act
         DeclarativeWorkflowOptions options = new(mockProvider.Object);
@@ -116,7 +116,7 @@ public void TelemetryActivitySource_DefaultIsNull()
     public void TelemetryActivitySource_CanBeSet()
     {
         // Arrange
-        Mock<WorkflowAgentProvider> mockProvider = CreateMockProvider();
+        Mock<ResponseAgentProvider> mockProvider = CreateMockProvider();
 
         // Act
         DeclarativeWorkflowOptions options = new(mockProvider.Object)
@@ -133,7 +133,7 @@ public async Task BuildWorkflow_WithDefaultTelemetry_AppliesTelemetryAsync()
     {
         // Arrange
         using Activity testActivity = new Activity("DefaultTelemetryTest").Start()!;
-        Mock<WorkflowAgentProvider> mockProvider = CreateMockProvider();
+        Mock<ResponseAgentProvider> mockProvider = CreateMockProvider();
         DeclarativeWorkflowOptions options = new(mockProvider.Object)
         {
             ConfigureTelemetry = _ => { },
@@ -161,7 +161,7 @@ public async Task BuildWorkflow_WithTelemetryActivitySource_AppliesTelemetryAsyn
     {
         // Arrange
         using Activity testActivity = new Activity("TelemetryActivitySourceTest").Start()!;
-        Mock<WorkflowAgentProvider> mockProvider = CreateMockProvider();
+        Mock<ResponseAgentProvider> mockProvider = CreateMockProvider();
         DeclarativeWorkflowOptions options = new(mockProvider.Object)
         {
             TelemetryActivitySource = this._activitySource,
@@ -188,7 +188,7 @@ public async Task BuildWorkflow_WithConfigureTelemetry_AppliesConfigurationAsync
     {
         // Arrange
         using Activity testActivity = new Activity("ConfigureTelemetryTest").Start()!;
-        Mock<WorkflowAgentProvider> mockProvider = CreateMockProvider();
+        Mock<ResponseAgentProvider> mockProvider = CreateMockProvider();
         bool configureInvoked = false;
         DeclarativeWorkflowOptions options = new(mockProvider.Object)
         {
@@ -223,7 +223,7 @@ public async Task BuildWorkflow_WithoutTelemetry_DoesNotCreateActivitiesAsync()
     {
         // Arrange
         using Activity testActivity = new Activity("NoTelemetryTest").Start()!;
-        Mock<WorkflowAgentProvider> mockProvider = CreateMockProvider();
+        Mock<ResponseAgentProvider> mockProvider = CreateMockProvider();
         DeclarativeWorkflowOptions options = new(mockProvider.Object)
         {
             LoggerFactory = NullLoggerFactory.Instance
@@ -245,9 +245,9 @@ public async Task BuildWorkflow_WithoutTelemetry_DoesNotCreateActivitiesAsync()
         Assert.Empty(capturedActivities);
     }
 
-    private static Mock<WorkflowAgentProvider> CreateMockProvider()
+    private static Mock<ResponseAgentProvider> CreateMockProvider()
     {
-        Mock<WorkflowAgentProvider> mockAgentProvider = new(MockBehavior.Strict);
+        Mock<ResponseAgentProvider> mockAgentProvider = new(MockBehavior.Strict);
         mockAgentProvider
             .Setup(provider => provider.CreateConversationAsync(It.IsAny<CancellationToken>()))
             .Returns(() => Task.FromResult(Guid.NewGuid().ToString("N")));

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/DeclarativeWorkflowTest.cs

@@ -239,7 +239,7 @@ public void UnsupportedAction(Type type)
         AdaptiveDialog dialog = dialogBuilder.Build();
 
         WorkflowFormulaState state = new(RecalcEngineFactory.Create());
-        Mock<WorkflowAgentProvider> mockAgentProvider = CreateMockProvider("1");
+        Mock<ResponseAgentProvider> mockAgentProvider = CreateMockProvider("1");
         DeclarativeWorkflowOptions options = new(mockAgentProvider.Object);
         WorkflowActionVisitor visitor = new(new DeclarativeWorkflowExecutor<string>(WorkflowActionVisitor.Steps.Root("anything"), options, state, (message) => DeclarativeWorkflowBuilder.DefaultTransform(message)), state, options);
         WorkflowElementWalker walker = new(visitor);
@@ -374,14 +374,14 @@ private async Task RunWorkflowAsync<TInput>(string workflowPath, TInput workflow
     private Workflow CreateWorkflow<TInput>(string workflowPath, TInput workflowInput) where TInput : notnull
     {
         using StreamReader yamlReader = File.OpenText(Path.Combine("Workflows", workflowPath));
-        Mock<WorkflowAgentProvider> mockAgentProvider = CreateMockProvider($"{workflowInput}");
+        Mock<ResponseAgentProvider> mockAgentProvider = CreateMockProvider($"{workflowInput}");
         DeclarativeWorkflowOptions workflowContext = new(mockAgentProvider.Object) { LoggerFactory = this.Output };
         return DeclarativeWorkflowBuilder.Build<TInput>(yamlReader, workflowContext);
     }
 
-    private static Mock<WorkflowAgentProvider> CreateMockProvider(string input)
+    private static Mock<ResponseAgentProvider> CreateMockProvider(string input)
     {
-        Mock<WorkflowAgentProvider> mockAgentProvider = new(MockBehavior.Strict);
+        Mock<ResponseAgentProvider> mockAgentProvider = new(MockBehavior.Strict);
         mockAgentProvider.Setup(provider => provider.CreateConversationAsync(It.IsAny<CancellationToken>())).Returns(() => Task.FromResult(Guid.NewGuid().ToString("N")));
         mockAgentProvider.Setup(provider => provider.CreateMessageAsync(It.IsAny<string>(), It.IsAny<ChatMessage>(), It.IsAny<CancellationToken>())).Returns(Task.FromResult(new ChatMessage(ChatRole.Assistant, input)));
         return mockAgentProvider;

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Extensions/DeclarativeWorkflowOptionsExtensionsTests.cs

@@ -58,7 +58,7 @@ private static DeclarativeWorkflowOptions CreateOptions(
         int? maximumExpressionLength = null,
         int? maximumCallDepth = null)
     {
-        Mock<WorkflowAgentProvider> providerMock = new(MockBehavior.Strict);
+        Mock<ResponseAgentProvider> providerMock = new(MockBehavior.Strict);
         return
             new(providerMock.Object)
             {

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/MockAgentProvider.cs

@@ -11,9 +11,9 @@
 namespace Microsoft.Agents.AI.Workflows.Declarative.UnitTests;
 
 /// <summary>
-/// Mock implementation of <see cref="WorkflowAgentProvider"/> for unit testing purposes.
+/// Mock implementation of <see cref="ResponseAgentProvider"/> for unit testing purposes.
 /// </summary>
-internal sealed class MockAgentProvider : Mock<WorkflowAgentProvider>
+internal sealed class MockAgentProvider : Mock<ResponseAgentProvider>
 {
     public IList<string> ExistingConversationIds { get; } = [];