From c798cb7a2ecd675c898db84931fb700060bceb77 Mon Sep 17 00:00:00 2001 From: Jacob Alber Date: Thu, 2 Apr 2026 11:48:19 -0400 Subject: [PATCH] release: Mark Handoff Orchestrations Experimental (#5065) --- .../03_AgentWorkflowPatterns.csproj | 1 + .../AgentWorkflowBuilder.cs | 2 ++ ...ffsWorkflowBuilder.cs => HandoffWorkflowBuilder.cs} | 10 ++++++++++ .../Microsoft.Agents.AI.Workflows.csproj | 3 ++- .../Specialized/HandoffAgentExecutor.cs | 4 ++++ .../Microsoft.Agents.AI.Workflows.UnitTests.csproj | 2 +- 6 files changed, 20 insertions(+), 2 deletions(-) rename dotnet/src/Microsoft.Agents.AI.Workflows/{HandoffsWorkflowBuilder.cs => HandoffWorkflowBuilder.cs} (95%) diff --git a/dotnet/samples/03-workflows/_StartHere/03_AgentWorkflowPatterns/03_AgentWorkflowPatterns.csproj b/dotnet/samples/03-workflows/_StartHere/03_AgentWorkflowPatterns/03_AgentWorkflowPatterns.csproj index e926a8375a..f0b7858971 100644 --- a/dotnet/samples/03-workflows/_StartHere/03_AgentWorkflowPatterns/03_AgentWorkflowPatterns.csproj +++ b/dotnet/samples/03-workflows/_StartHere/03_AgentWorkflowPatterns/03_AgentWorkflowPatterns.csproj @@ -6,6 +6,7 @@ enable enable + $(NoWarn);MAAIW001 diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows/AgentWorkflowBuilder.cs b/dotnet/src/Microsoft.Agents.AI.Workflows/AgentWorkflowBuilder.cs index 22ee1b48eb..9d7aa5b8c7 100644 --- a/dotnet/src/Microsoft.Agents.AI.Workflows/AgentWorkflowBuilder.cs +++ b/dotnet/src/Microsoft.Agents.AI.Workflows/AgentWorkflowBuilder.cs @@ -2,6 +2,7 @@ using System; using System.Collections.Generic; +using System.Diagnostics.CodeAnalysis; using System.Linq; using System.Threading.Tasks; using Microsoft.Agents.AI.Workflows.Specialized; @@ -154,6 +155,7 @@ public static partial class AgentWorkflowBuilder /// The must be capable of understanding those provided. If the agent /// ignores the tools or is otherwise unable to advertize them to the underlying provider, handoffs will not occur. /// + [Experimental(DiagnosticConstants.ExperimentalFeatureDiagnostic)] public static HandoffWorkflowBuilder CreateHandoffBuilderWith(AIAgent initialAgent) { Throw.IfNull(initialAgent); diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows/HandoffsWorkflowBuilder.cs b/dotnet/src/Microsoft.Agents.AI.Workflows/HandoffWorkflowBuilder.cs similarity index 95% rename from dotnet/src/Microsoft.Agents.AI.Workflows/HandoffsWorkflowBuilder.cs rename to dotnet/src/Microsoft.Agents.AI.Workflows/HandoffWorkflowBuilder.cs index 8e5cee7ed5..4e9f201053 100644 --- a/dotnet/src/Microsoft.Agents.AI.Workflows/HandoffsWorkflowBuilder.cs +++ b/dotnet/src/Microsoft.Agents.AI.Workflows/HandoffWorkflowBuilder.cs @@ -2,6 +2,7 @@ using System; using System.Collections.Generic; +using System.Diagnostics.CodeAnalysis; using System.Linq; using Microsoft.Agents.AI.Workflows.Specialized; using Microsoft.Extensions.AI; @@ -9,13 +10,21 @@ using Microsoft.Shared.Diagnostics; namespace Microsoft.Agents.AI.Workflows; +internal static class DiagnosticConstants +{ + public const string ExperimentalFeatureDiagnostic = "MAAIW001"; +} + /// [Obsolete("Prefer HandoffWorkflowBuilder (no 's') instead, which has the same API but the preferred name. This will be removed in a future release before GA.")] +#pragma warning disable MAAIW001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. public sealed class HandoffsWorkflowBuilder(AIAgent initialAgent) : HandoffWorkflowBuilderCore(initialAgent) +#pragma warning restore MAAIW001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. { } /// +[Experimental(DiagnosticConstants.ExperimentalFeatureDiagnostic)] public sealed class HandoffWorkflowBuilder(AIAgent initialAgent) : HandoffWorkflowBuilderCore(initialAgent) { } @@ -23,6 +32,7 @@ public sealed class HandoffWorkflowBuilder(AIAgent initialAgent) : HandoffWorkfl /// /// Provides a builder for specifying the handoff relationships between agents and building the resulting workflow. /// +[Experimental(DiagnosticConstants.ExperimentalFeatureDiagnostic)] public class HandoffWorkflowBuilderCore where TBuilder : HandoffWorkflowBuilderCore { /// diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj b/dotnet/src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj index 321d279504..032314c657 100644 --- a/dotnet/src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj +++ b/dotnet/src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj @@ -1,4 +1,4 @@ - + true @@ -8,6 +8,7 @@ true true + true true diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffAgentExecutor.cs b/dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffAgentExecutor.cs index 98205a40c6..e885b894fd 100644 --- a/dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffAgentExecutor.cs +++ b/dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffAgentExecutor.cs @@ -4,6 +4,7 @@ using System; using System.Collections.Generic; using System.ComponentModel; using System.Diagnostics; +using System.Diagnostics.CodeAnalysis; using System.Linq; using System.Text.Json; using System.Threading; @@ -31,6 +32,7 @@ internal sealed class HandoffAgentExecutorOptions public HandoffToolCallFilteringBehavior ToolCallFilteringBehavior { get; set; } = HandoffToolCallFilteringBehavior.HandoffOnly; } +[Experimental(DiagnosticConstants.ExperimentalFeatureDiagnostic)] internal sealed class HandoffMessagesFilter { private readonly HandoffToolCallFilteringBehavior _filteringBehavior; @@ -40,6 +42,7 @@ internal sealed class HandoffMessagesFilter this._filteringBehavior = filteringBehavior; } + [Experimental(DiagnosticConstants.ExperimentalFeatureDiagnostic)] internal static bool IsHandoffFunctionName(string name) { return name.StartsWith(HandoffWorkflowBuilder.FunctionPrefix, StringComparison.Ordinal); @@ -164,6 +167,7 @@ internal sealed class HandoffMessagesFilter } /// Executor used to represent an agent in a handoffs workflow, responding to events. +[Experimental(DiagnosticConstants.ExperimentalFeatureDiagnostic)] internal sealed class HandoffAgentExecutor( AIAgent agent, HandoffAgentExecutorOptions options) : Executor(agent.GetDescriptiveId(), declareCrossRunShareable: true), IResettableExecutor diff --git a/dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj b/dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj index 58979a4f1b..22764bb163 100644 --- a/dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj +++ b/dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj @@ -1,7 +1,7 @@  - $(NoWarn);MEAI001 + $(NoWarn);MEAI001;MAAIW001