Enhance README with detailed setup instructions and user authenticati…

src/Microsoft.Agents.SDK.sln

@@ -114,13 +114,21 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Agents.Storage.Tr
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Agents.Storage.Tests", "tests\Microsoft.Agents.Storage.Tests\Microsoft.Agents.Storage.Tests.csproj", "{23065AEC-4875-4CDC-A7E5-EE389C201534}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.Agents.BotBuilder.Tests", "tests\Microsoft.Agents.BotBuilder.Tests\Microsoft.Agents.BotBuilder.Tests.csproj", "{401F5548-D6EF-4497-B786-D2A6BA8CBF76}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Agents.BotBuilder.Tests", "tests\Microsoft.Agents.BotBuilder.Tests\Microsoft.Agents.BotBuilder.Tests.csproj", "{401F5548-D6EF-4497-B786-D2A6BA8CBF76}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.Agents.State.Tests", "tests\Microsoft.Agents.State.Tests\Microsoft.Agents.State.Tests.csproj", "{71813B2D-D6A8-4388-9541-9B1287C93F19}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Agents.State.Tests", "tests\Microsoft.Agents.State.Tests\Microsoft.Agents.State.Tests.csproj", "{71813B2D-D6A8-4388-9541-9B1287C93F19}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.Agents.State", "libraries\Core\Microsoft.Agents.State\Microsoft.Agents.State.csproj", "{6A27C156-842F-409C-86B7-D9CC0A38F02F}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Agents.State", "libraries\Core\Microsoft.Agents.State\Microsoft.Agents.State.csproj", "{6A27C156-842F-409C-86B7-D9CC0A38F02F}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "EvalClient", "samples\EvalClient\EvalClient.csproj", "{A839D635-0382-4E4C-8052-1F18B71434EE}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "EvalClient", "samples\EvalClient\EvalClient.csproj", "{A839D635-0382-4E4C-8052-1F18B71434EE}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.Agents.Hosting.AspNetCore.Tests", "tests\Microsoft.Agents.Hosting.AspNetCore\Microsoft.Agents.Hosting.AspNetCore.Tests.csproj", "{7D1A1CE5-6D9B-4D31-AC77-C3B1787F575D}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "InMeetingNotificationsBot", "samples\Teams\Meetings-Notification\InMeetingNotificationsBot.csproj", "{06E490F7-F0BB-E3C4-54FE-5210627292A1}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TagMentionBot", "samples\Teams\bot-tag-mention\TagMentionBot.csproj", "{BC5EFA6C-7EB5-4803-B7C5-093892E9DBB8}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.Agents.Authentication.Msal.Tests", "tests\Microsoft.Agents.Authentication.Msal.Tests\Microsoft.Agents.Authentication.Msal.Tests.csproj", "{B9AD64EF-EA22-4CAC-B89B-03CEE46CFF4F}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -312,6 +320,22 @@ Global
 		{A839D635-0382-4E4C-8052-1F18B71434EE}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{A839D635-0382-4E4C-8052-1F18B71434EE}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{A839D635-0382-4E4C-8052-1F18B71434EE}.Release|Any CPU.Build.0 = Release|Any CPU
+		{7D1A1CE5-6D9B-4D31-AC77-C3B1787F575D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{7D1A1CE5-6D9B-4D31-AC77-C3B1787F575D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{7D1A1CE5-6D9B-4D31-AC77-C3B1787F575D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{7D1A1CE5-6D9B-4D31-AC77-C3B1787F575D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{06E490F7-F0BB-E3C4-54FE-5210627292A1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{06E490F7-F0BB-E3C4-54FE-5210627292A1}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{06E490F7-F0BB-E3C4-54FE-5210627292A1}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{06E490F7-F0BB-E3C4-54FE-5210627292A1}.Release|Any CPU.Build.0 = Release|Any CPU
+		{BC5EFA6C-7EB5-4803-B7C5-093892E9DBB8}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{BC5EFA6C-7EB5-4803-B7C5-093892E9DBB8}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{BC5EFA6C-7EB5-4803-B7C5-093892E9DBB8}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{BC5EFA6C-7EB5-4803-B7C5-093892E9DBB8}.Release|Any CPU.Build.0 = Release|Any CPU
+    {B9AD64EF-EA22-4CAC-B89B-03CEE46CFF4F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B9AD64EF-EA22-4CAC-B89B-03CEE46CFF4F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B9AD64EF-EA22-4CAC-B89B-03CEE46CFF4F}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B9AD64EF-EA22-4CAC-B89B-03CEE46CFF4F}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -372,6 +396,10 @@ Global
 		{71813B2D-D6A8-4388-9541-9B1287C93F19} = {AD743B78-D61F-4FBF-B620-FA83CE599A50}
 		{6A27C156-842F-409C-86B7-D9CC0A38F02F} = {7A18F0C9-F8AF-4168-B954-6563BB2C1A90}
 		{A839D635-0382-4E4C-8052-1F18B71434EE} = {674A812C-7287-4883-97F9-697D83750648}
+		{7D1A1CE5-6D9B-4D31-AC77-C3B1787F575D} = {AD743B78-D61F-4FBF-B620-FA83CE599A50}
+		{06E490F7-F0BB-E3C4-54FE-5210627292A1} = {183D0E91-B84E-46D7-B653-6D85B4CCF804}
+		{BC5EFA6C-7EB5-4803-B7C5-093892E9DBB8} = {183D0E91-B84E-46D7-B653-6D85B4CCF804}
+    {B9AD64EF-EA22-4CAC-B89B-03CEE46CFF4F} = {AD743B78-D61F-4FBF-B620-FA83CE599A50}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {F1E8E538-309A-46F8-9CE7-AEC6589FAE60}

src/libraries/Authentication/Authentication.Msal/AssemblyInfo.cs

@@ -0,0 +1,7 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("Microsoft.Agents.Authentication.Msal.Tests, PublicKey=0024000004800000940000000602000000240000525341310004000001000100b5fc90e7027f67871e773a8fde8938c81dd402ba65b9201d60593e96c492651e889cc13f1415ebb53fac1131ae0bd333c5ee6021672d9718ea31a8aebd0da0072f25d87dba6fc90ffd598ed4da35e44c398c454307e8e33b8426143daec9f596836f97c8f74750e5975c64e2189f45def46b2a2b1247adc3652bf5c308055da9")]
+[assembly: InternalsVisibleTo("DynamicProxyGenAssembly2, PublicKey=0024000004800000940000000602000000240000525341310004000001000100c547cac37abd99c8db225ef2f6c8a3602f3b3606cc9891605d02baa56104f4cfc0734aa39b93bf7852f7d9266654753cc297e7d2edfe0bac1cdcf9f717241550e0a7b191195b7667bb4f64bcb8e2121380fd1d9d46ad2d92d2d15605093924cceaf74c4861eff62abf69b9291ed0a340e113be11e6a7d3113e92484cf7045cc7")]

src/libraries/Client/Microsoft.Agents.Connector/RestClients/ConversationsRestClient.cs

@@ -536,7 +536,7 @@ internal HttpRequestMessage CreateGetConversationPagedMembersRequest(string conv
             request.Method = HttpMethod.Get;
 
             request.RequestUri = new Uri(endpoint.EnsureTrailingSlash(), $"v3/conversations/{conversationId}/pagedmembers")
-                .AppendQuery("pageSize", pageSize.Value.ToString())
+                .AppendQuery("pageSize", pageSize.HasValue ? pageSize.Value.ToString() : null)
                 .AppendQuery("continuationToken", continuationToken);
 
             request.Headers.Add("Accept", "application/json");

src/libraries/Client/Microsoft.Agents.Connector/Teams/RestTeamsOperations.cs

@@ -269,7 +269,8 @@ private async Task<T> GetResponseAsync<T>(string operationName, string apiUrl, H
 
             if (body != null)
             {
-                request.Content = new StringContent(ProtocolJsonSerializer.ToJson(body), System.Text.Encoding.UTF8, "application/json");
+                var json = ProtocolJsonSerializer.ToJson(body);
+                request.Content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
             }
 
             if (customHeaders != null)
@@ -293,13 +294,21 @@ private async Task<T> GetResponseAsync<T>(string operationName, string apiUrl, H
                 {
                     case 200:
                     case 201:
+                    case 202:
                         {
                             if (typeof(T) == typeof(string))
                             {
                                 var responseContent = await httpResponse.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
                                 return ProtocolJsonSerializer.ToObject<T>(responseContent);
                             }
-                            return ProtocolJsonSerializer.ToObject<T>(httpResponse.Content.ReadAsStream(cancellationToken));
+
+                            var json = await httpResponse.Content.ReadAsStringAsync().ConfigureAwait(false);
+                            if (!string.IsNullOrWhiteSpace(json))
+                            {
+                                return ProtocolJsonSerializer.ToObject<T>(json);
+                            }
+
+                            return default(T);
                         }
                     case 429:
                         {

src/libraries/Client/Microsoft.Agents.CopilotStudio.Client/README.md

@@ -1,13 +1,103 @@
 # Microsoft.Agents.CopilotStudio.Client
 
-Provides a client to interact with agents built in Copilot Studio
+Provides a client to interact with agents built in Copilot Studio. This Library is intended to provide access to a given agent's conversational channel.
+
+## Instructions - Required Setup to use this library
+
+### Prerequisite
+
+To use this library, you will need the following:
+
+1. An Agent Created in Microsoft Copilot Studio.
+1. Ability to Create a Application Identity in Azure for a Public Client/Native App Registration Or access to an existing Public Client/Native App registration with the **CopilotStudio.Copilot.Invoke API Permission assigned**.
+
+### Create a Agent in Copilot Studio
+
+1. Create or open an Agent in [Copilot Studio](https://copilotstudio.microsoft.com)
+    1. Make sure that the Copilot is Published
+    1. Goto Settings => Advanced => Metadata and copy the following values, You will need them later:
+        1. Schema name - this is the 'unique name' of your agent inside this environment.
+        1. Environment Id - this is the ID of the environment that contains the agent.
+
+### Create an Application Registration in Entra ID to support user authentication to Copilot Studio
+
+This is used when you are creating an application soly for the purpose of user interactive login and will be using a client that will surface an Entra ID MultiFactor Authentication Prompt.    
+
+> [!IMPORTANT]
+> If you are using this client from a service, you will need to exchange the user token used to login to your service for a token for your agent hosted in copilot studio. This is called a On Behalf Of authentication token.  You can find more information about this authentication flow in [Entra Documentation](https://learn.microsoft.com/entra/msal/dotnet/acquiring-tokens/web-apps-apis/on-behalf-of-flow). 
+
+This step will require permissions to Create application identities in your Azure tenant. For user authentication, you will be creating a Native Client Application Identity, which does not have secrets.
+
+1. Open <https://portal.azure.com>
+1. Navigate to Entra Id
+1. Create an new App Registration in Entra ID
+    1. Provide an Name
+    1. Choose "Accounts in this organization directory only"
+    1. In the "Select a Platform" list, Choose "Public Client/native (mobile & desktop)
+    1. In the Redirect URI url box, type in `http://localhost` (**note: use HTTP, not HTTPS**)
+    1. Then click register.
+1. In your newly created application
+    1. On the Overview page, Note down for use later when configuring the example application:
+        1. the Application (client) ID
+        1. the Directory (tenant) ID
+    1. Goto Manage
+    1. Goto API Permissions
+    1. Click Add Permission
+        1. In the side pannel that appears, Click the tab `API's my organization uses`
+        1. Search for `Power Platform API`.
+            1. *If you do not see `Power Platform API` see the note at the bottom of this section.*
+        1. In the permissions list choose `CopilotStudio` and Check `CopilotStudio.Copilots.Invoke`
+        1. Click `Add Permissions`
+    1. (Optional) Click `Grant Admin consent for copilotsdk`
+    1. Close Azure Portal
+
+> [!TIP]
+> If you do not see `Power Platform API` in the list of API's your organization uses, you need to add the Power Platform API to your tenant. To do that, goto [Power Platform API Authentication](https://learn.microsoft.com/power-platform/admin/programmability-authentication-v2#step-2-configure-api-permissions) and follow the instructions on Step 2 to add the Power Platform Admin API to your Tenant
+
+### Add the CopilotStudio.Copilots.Invoke permissions to your Application Registration in Entra ID to support user authentication to Copilot Studio
 
 ## How-to use
 
+### User Based auth flows
+
+User based authentication flows are the only currently supported flow for this client.
+
+Your code will need to create a User Token ( via MSAL Public Client or an OBO flow for a User access token) to call this service.
+
+There are currently two ways to pass auth to the CopilotClient.
+
+#### 1. Create an HttpMessageRequest Handler that will populate the bearer token and assign it to the httpClient you create
+
+In this case, you would create an HttpMessageRequestHandler that creates the bearer header on the http request message,  In the example below, `AddTokenHandler` is responsible for adding the bearer header to the http request prior to the send:
+
+```cs
+// Create an http client for use by the DirectToEngine Client and add the token handler to the client.
+builder.Services.AddHttpClient("mcs").ConfigurePrimaryHttpMessageHandler(
+    () => new AddTokenHandler(settings));
+```
+
+Then create an instance the client and request to start a conversation:
+
 ```cs
 var copilotClient = new CopilotClient(settings, s.GetRequiredService<IHttpClientFactory>(), logger, "mcs");
 await foreach (Activity act in copilotClient.StartConversationAsync(emitStartConversationEvent:true, cancellationToken:cancellationToken))
 {
 
 }
-```
+```
+
+#### 2. Create a function that returns a user token and pass that to the constructor for the Copilot Client
+
+In this case, the `TokenService` is a class is responsible for managing the token acquire flow and returning the access token via the `GetToken API` call on the `TokenService` Class.
+> [!NOTE]
+> We do not cover how to create the TokenService Class in this document. The Copilot client is looking for a function that matches the signature `Func<string, Task<string>> tokenProviderFunction`
+
+```cs
+var tokenService = new TokenService(settings);
+var copilotClient = new CopilotClient(settings, s.GetRequiredService<IHttpClientFactory>(), tokenService.GetToken, logger, "mcs");
+
+await foreach (Activity act in copilotClient.StartConversationAsync(emitStartConversationEvent:true, cancellationToken:cancellationToken))
+{
+
+}
+```

src/libraries/Core/Microsoft.Agents.Core/Models/EntityTypes.cs

@@ -0,0 +1,14 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Microsoft.Agents.Core.Models
+{
+    public static class EntityTypes
+    {
+        public const string Mention = "mention";
+        public const string Place = "Place";
+        public const string Thing = "Thing";
+        public const string GeoCoordinates = "GeoCoordinates";
+        public const string StreamInfo = "streaminfo";
+    }
+}

src/libraries/Core/Microsoft.Agents.Core/Models/GeoCoordinates.cs

@@ -10,7 +10,7 @@ public class GeoCoordinates : Entity
     {
         /// <summary> Initializes a new instance of GeoCoordinates. </summary>
         public GeoCoordinates()
-            :this(type:  "GeoCoordinates")
+            :this(type: EntityTypes.GeoCoordinates)
         {
         }
 

src/libraries/Core/Microsoft.Agents.Core/Models/Mention.cs

@@ -9,15 +9,15 @@ namespace Microsoft.Agents.Core.Models
     public class Mention : Entity
     {
         /// <summary> Initializes a new instance of Mention. </summary>
-        public Mention() : base("mention")
+        public Mention() : base(EntityTypes.Mention)
         {
         }
 
         /// <summary> Initializes a new instance of Mention. </summary>
         /// <param name="type"> Type of this entity (RFC 3987 IRI). </param>
         /// <param name="mentioned"> Channel account information needed to route a message. </param>
         /// <param name="text"> Sub Text which represents the mention (can be null or empty). </param>
-        public Mention(ChannelAccount mentioned = default, string text = default, string type = default) : base(type ?? "mention")
+        public Mention(ChannelAccount mentioned = default, string text = default, string type = default) : base(type ?? EntityTypes.Mention)
         {
             Mentioned = mentioned;
             Text = text;

src/libraries/Core/Microsoft.Agents.Core/Models/Place.cs

@@ -9,7 +9,7 @@ namespace Microsoft.Agents.Core.Models
     public class Place : Entity
     {
         /// <summary> Initializes a new instance of Place. </summary>
-        public Place() : base("Place")
+        public Place() : base(EntityTypes.Place)
         {
         }
 
@@ -19,7 +19,7 @@ public Place() : base("Place")
         /// <param name="geo"> Geo coordinates of the place (may be complex object of type `GeoCoordinates` or `GeoShape`). </param>
         /// <param name="hasMap"> Map to the place (may be `string` (URL) or complex object of type `Map`). </param>
         /// <param name="name"> The name of the thing. </param>
-        public Place(object address = default, object geo = default, object hasMap = default, string type = "Place", string name = default)
+        public Place(object address = default, object geo = default, object hasMap = default, string type = EntityTypes.Place, string name = default)
         {
             Address = address;
             Geo = geo;

src/libraries/Core/Microsoft.Agents.Core/Models/StreamInfo.cs

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Microsoft.Agents.Core.Models
+{
+    /// <summary>
+    /// Stream information will be included in an Entity in the Activity.
+    /// </summary>
+    public class StreamInfo : Entity
+    {
+        public StreamInfo() : base(EntityTypes.StreamInfo)
+        {
+            StreamType = StreamType.Streaming;
+        }
+
+        /// <summary>
+        /// Required unique ID.  This remains the same for all subsequent Entities part of the stream operation.
+        /// </summary>
+        public string StreamId { get; set; }
+
+        public StreamType StreamType { get; set; }
+
+        /// <summary>
+        /// Required incrementing integer for each Typing Activity sent, and final Message.
+        /// </summary>
+        public int StreamSequence { get; set; }
+
+        /// <summary>
+        /// Optional stream result when StreamType is Final.
+        /// </summary>
+        public StreamResult StreamResult { get; set; }
+    }
+}

src/libraries/Core/Microsoft.Agents.Core/Models/StreamResult.cs

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Microsoft.Agents.Core.Models
+{
+    public enum StreamResult
+    {
+        Success,
+        Timeout,
+        Error
+    }
+}

src/libraries/Core/Microsoft.Agents.Core/Models/StreamType.cs

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Microsoft.Agents.Core.Models
+{
+    /// <summary>
+    /// The type of streaming message being sent.
+    /// </summary>
+    public enum StreamType
+    {
+        /// <summary>
+        /// An informative update.
+        /// </summary>
+        /// <remarks>
+        /// Informative messages
+        ///    Can be sent in any order
+        ///    Text is in Activity.Text
+        ///    TextFormat can be supplied
+        ///    Increments the streamSequence
+        /// </remarks>
+        Informative,
+
+        /// <summary>
+        /// A chunk of partial message text.
+        /// </summary>
+        Streaming,
+
+        /// <summary>
+        /// The final message.  Only on final "message" Activity.
+        /// </summary>
+        Final
+    }
+}