Publique um agente nos canais Azure Serviço de Bot

Você pode conectar seu agente a canais Azure Serviço de Bot existentes, o que pode ser útil se você quiser conectar seu agente a usuários finais em canais Azure Serviço de Bot.

Adicionar seus canais agente aos Azure Serviço de Bot requer considerável experiência do desenvolvedor. Este artigo foi escrito para administradores ou desenvolvedores de TI com experiência no desenvolvimento e gravação de código.

Dica

Você não precisa seguir este documento para adicionar seu Copilot Studio agente ao seu site, Facebook ou Microsoft Teams. Se seu objetivo é se conectar a um aplicativo nativo ou baseado na web personalizado, seus desenvolvedores podem aprender mais em Publicar um agente em aplicativos móveis ou personalizados.

Importante

De acordo com as instruções nesta seção, seus desenvolvedores ou você precisam desenvolver um software. Elas são direcionadas a profissionais de TI experientes, como administradores ou desenvolvedores de TI que tenham um sólido entendimento de utilitários, IDEs e ferramentas para desenvolvedores.

Pré-requisitos

• Uma assinatura do Serviço de Bot do Azure.
• Um bot do Serviço de Bot do Azure usando o SDK v4.
• SDK do .NET Core versão 2.1.
• Pacote de NuGet Microsoft.Bot.Connector.DirectLine.
• Um agente criado em Copilot Studio que você deseja conectar a um canal Azure Serviço de Bot.
• Publique um agente em aplicativos móveis ou personalizados.

Exemplos de códigos

Os trechos de código usados neste documento são do exemplo de código do bot de retransmissão.

Referências

As instruções neste documento fazem referência aos seguintes documentos:

• Implantar seu bot no Azure para obter instruções sobre a implantação do Serviço de Bot do Azure.
• Canais do Serviço de Bot do Azure para conectar-se a qualquer canal com suporte pelo Serviço de Bot do Azure.
• Depuração do Serviço de Bot do Azure com o emulador para obter instruções sobre depuração do bot do Serviço de Bot do Azure.

Criar ou usar um bot existente do Serviço de Bot do Azure

Você precisa de um Azure Serviço de Bot bot que possa retransmitir conversas entre seus canais Copilot Studio agente e Azure Serviço de Bot.

O exemplo de código do bot de retransmissão é um bom ponto de partida se você não tem um bot existente do Serviço de Bot do Azure. Ele é criado por meio do bot exemplo de código do Microsoft Bot Framework que pode ser compilado e implementado no Serviço de Bot do Azure. A intenção é usar o exemplo de código como ponto de partida, e não deve ser usado diretamente na produção. Você precisa adicionar código e otimização para atender às suas necessidades de negócios.

Se você já possui um bot do Serviço de Bot do Azure, precisará adicionar um conector do Copilot Studio e código para gerenciar sessões de conversa. Em seguida, você pode implantar o bot no Serviço de Bot do Azure e conectar-se aos canais com o portal do Azure.

Obtenha seus parâmetros Copilot Studio agente

Para se conectar ao agente que você criou com Copilot Studio, você precisa recuperar o nome e o ponto de extremidade do token do seu agente.

1. Copie o nome do seu agente em Copilot Studio.

   

2. No menu de navegação, em Configurações, selecione Canais.

3. Selecione o canal ao qual você deseja se conectar. Este cenário usa Slack como um exemplo.

   

4. Para copiar e salvar o valor Ponto de Extremidade do Token, selecione Copiar. Você precisa do seu endpoint para conectar seu agente ao canal Azure Serviço de Bot.

   

Gerencie sessões de conversação com seu Copilot Studio agente

There pode ser múltiplas conversas entre os canais Azure Serviço de Bot e a Direct Line conexão com seu Copilot Studio agente.

Seu Azure Serviço de Bot bot precisa mapear e retransmitir a conversa do canal Azure Serviço de Bot para a Direct Line conversa com o Copilot Studio agente e vice-versa.

Exemplo de código

O exemplo a seguir usa partes do exemplo de código do bot de retransmissão.

1. Em cada novo início de conversa em canal externo Azure Serviço de Bot, inicie uma Copilot Studio conversa agente. Consulte Obter Direct Line token e Usar Direct Line para se comunicar com o agente para obter instruções sobre como iniciar uma nova conversa com o 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. Para gerenciar várias sessões, você precisa manter um mapeamento de conversas de canal Azure Serviço de Bot externas para conversas Copilot Studio agente correspondentes. Uma conversa Copilot Studio agente pode ser identificada e conectada com duas propriedades: ConversationtId e Token.

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

   Para gerenciar o ciclo de vida da conversa, atualize os tokens do Direct Line ou limpe as conversas inativas. Saiba mais sobre a atualização de token em Atualizar o token do Direct Line. Uma conversa Copilot Studio agente para dar suporte à atualização de Direct Line tokens é definida da seguinte forma:

   /// <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. Quando uma nova Copilot Studio conversa agente começar, adicione um par de valores-chave (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) à tabela mapeamento.

   // 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. Para continuar uma conversa existente, após receber uma nova mensagem de canal externo Azure Serviço de Bot, recupere a conversa existente da tabela mapeamento, retransmita a atividade da conversa externa para seu Copilot Studio agente e obtenha um resposta.

   O exemplo a seguir mostra a retransmissão da conversa, substituindo o método ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken)

   // 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. Consulte Usar Direct Line para se comunicar com o agente para saber como obter o Copilot Studio agente's resposta. Quando o Copilot Studio agente's resposta for recebido, consulte Analisar carga útil da conversa do agente para saber como analisar o resposta para o canal externo Azure Serviço de Bot resposta.

Um exemplo de análise de resposta pode ser encontrado em ResponseConverter.cs do exemplo de código do bot de retransmissão.

Implantar no Serviço de Bot do Azure

Quando o bot de retransmissão do Serviço de Bot do Azure estiver pronto, você precisará implantar o bot no seu Serviço de Bot do Azure.

Configurar canais do Serviço de Bot do Azure

Você pode configurar os canais aos quais deseja se conectar se conectando ao portal do Azure e selecionando o grupo de recursos do Serviço de Bot do Azure no qual você implantou. Veja as instruções específicas para cada canal em Canais do Serviço de Bot do Azure.