Publish an agent to Azure Bot Service channels

You can connect your agent to existing Azure Bot Service channels. This connection is helpful if you want to connect your agent to customers on Azure Bot Service channels.

Adding your agent to Azure Bot Service channels requires considerable developer expertise. This article is written for IT admins or developers who have experience developing and writing code.

Prerequisites

• An Azure Bot Service subscription.
• An Azure Bot Service bot using v4 SDK.
• .NET SDK version 10.0.
• NuGet package Microsoft.Bot.Connector.DirectLine.
• An agent created in Copilot Studio that you want to connect to an Azure Bot Service channel.
• Publish an agent to mobile or custom apps.

Code samples

Code snippets used in this document are from relay bot sample code.

References

The instructions in this document reference the following documents:

• Deploy your bot to Azure for instructions on deploying the Azure Bot Service bot.
• Azure Bot Service Channels to connect to any Azure Bot Service-supported channel.
• Azure Bot Service debug with the emulator for instructions on debugging the Azure Bot Service bot.

Create or use an existing Azure Bot Service bot

You need an Azure Bot Service bot that can relay conversations between your Copilot Studio agent and Azure Bot Service channels.

The relay bot sample code is a good starting point if you don't have an existing Azure Bot Service bot. This sample code is built from Microsoft Bot Framework bot sample code that you can compile and deploy to the Azure Bot Service. Use the sample code as a starting point. The sample code is not intended for production use. You need to add code and optimization to match your business needs.

If you already have an Azure Bot Service bot, add a Copilot Studio connector and code to manage conversation sessions. You can then deploy the bot to the Azure Bot Service and connect to channels by using the Azure portal.

Get your Copilot Studio agent parameters

To connect to the agent you built with Copilot Studio, you need to retrieve your agent's name and token endpoint.

1. Copy your agent's name in Copilot Studio.

   

2. In the navigation menu under Settings, select Channels.

3. Select the channel you want to connect to. This scenario uses Slack as an example.

   

4. To copy and save the Token Endpoint value, select Copy. You need your endpoint to connect your agent to the Azure Bot Service channel.

   

Manage conversation sessions with your Copilot Studio agent

Multiple conversations can exist between the Azure Bot Service channels and the Direct Line connection with your Copilot Studio agent.

Your Azure Bot Service bot needs to map and relay the conversation from the Azure Bot Service channel to the Direct Line conversation with the Copilot Studio agent and vice versa.

Sample code example

The following example uses samples from the relay bot sample code.

1. On every new external Azure Bot Service channel conversation start, start a Copilot Studio agent conversation. Refer to Get Direct Line token and Use Direct Line to communicate with the agent for instructions on starting a new conversation with the bot.

   using (var httpRequest = new HttpRequestMessage())
   {   
       httpRequest.Method = HttpMethod.Get;
       UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
       httpRequest.RequestUri = uriBuilder.Uri;
       using (var response = await s_httpClient.SendAsync(httpRequest))
       {
           var responseString = await response.Content.ReadAsStringAsync();
           string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
       }
   }
   
   /// <summary>
   /// class for serialization/deserialization DirectLineToken
   /// </summary>
   public class DirectLineToken
   {
       public string Token { get; set; }
   }
   

    // Use the retrieved token to create a DirectLineClient instance
    using (var directLineClient = new DirectLineClient(token))
    {
        var conversation = await directLineClient.Conversations.StartConversationAsync();
        string conversationtId = conversation.ConversationId;
    }
   

2. To manage multiple sessions, maintain a mapping of external Azure Bot Service channel conversations to corresponding Copilot Studio agent conversations. Connect a Copilot Studio agent conversation by using two properties: ConversationtId and Token.

   Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();  
   

   To manage the conversation lifecycle, refresh the Direct Line tokens or clean up idled conversations. Learn more about token refresh at Refresh Direct Line token. A Copilot Studio agent conversation that supports refreshing Direct Line tokens is defined as follows:

   /// <summary>
   /// Data model class for Copilot Studio agent conversation
   /// </summary>
   public class PowerVirtualAgentsConversation
   {
       public string ConversationtId { get; set; } // The Copilot Studio agent conversation ID retrieved from step 1
   
       public string Token { get; set; } // The DirectLine token retrieved from step 1
   
       public string WaterMark { get; set; } // Identify turn in a conversation
   
       public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh
   
       public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to agent
   }
   

3. When a new Copilot Studio agent conversation starts, add a key value pair (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) to the mapping table.

   // After new Copilot Studio agent conversation starts
   ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
     {
       Token = token,
       ConversationtId = conversationId,
       WaterMark = null,
       LastConversationUpdateTime = DateTime.Now,
       LastTokenRefreshTime = DateTime.Now,
     }; 
   

4. To continue an existing conversation, retrieve the existing conversation from the mapping table when you receive a new external Azure Bot Service channel message. Relay the external conversation activity to your Copilot Studio agent, and get a response.

   The following sample shows relaying conversation by overriding the ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken) method

   // Invoked when a message activity is received from the user
   // Send the user message to Copilot Studio agent and get response
   protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
   {
       // Retrieve agent conversation from mapping table
       // If not exists for the given external conversation ID, start a new Copilot Studio agent conversation
       ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
               currentConversation : /*await StartBotConversationAsync(externalCID)*/;
   
       // Create DirectLine client with the token associated to current conversation
       DirectLineClient client = new DirectLineClient(currentConversation.Token);
   
       // Send user message using directlineClient
       await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
       {
         Type = DirectLineActivityTypes.Message,
         From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
         Text = turnContext.Activity.Text,
         TextFormat = turnContext.Activity.TextFormat,
         Locale = turnContext.Activity.Locale,
       });
   
       // Update LastConversationUpdateTime for session management
       currentConversation.LastConversationUpdateTime = DateTime.Now;
   }  
   

5. Refer to Use Direct Line to communicate with the agent for how to get the Copilot Studio agent's response. When you receive the Copilot Studio agent's response, refer to Parse conversation payload from the agent for how to parse the response to the external Azure Bot Service channel response.

An example of response parsing can be found in the relay bot sample code ResponseConverter.cs.

Deploy to Azure Bot Service

After you create your Azure Bot Service relay bot, deploy the bot to your Azure Bot Service.

Set up Azure Bot Service channels

To set up channels, sign in to the Azure portal and select the Azure Bot Service resource group you deployed to. For specific instructions, see Azure Bot Service Channels.