Partilhar via

Publicar um agente nos canais do Serviço de Bot do Azure

Você pode conectar seu agente aos canais existentes do Serviço de Bot do Azure, o que pode ser útil se você quiser conectar seu agente aos clientes nos canais do Serviço de Bot do Azure.

Adicionar seu agente aos canais do Serviço de Bot do Azure requer experiência considerável do desenvolvedor. Este artigo foi escrito para administradores de TI ou desenvolvedores que têm experiência em desenvolver e escrever código.

Sugestão

Não é necessário seguir este documento para adicionar seu agente do Copilot Studio ao seu site, Facebook ou Microsoft Teams. Se o seu objetivo for conectar-se a um aplicativo nativo ou baseado na Web personalizado, seus desenvolvedores podem saber mais em Publicar um agente em aplicativos móveis ou personalizados.

Importante

As instruções nesta seção exigem desenvolvimento de software de você ou de seus desenvolvedores. Destina-se a profissionais de TI experientes, como administradores de TI ou desenvolvedores que tenham uma sólida compreensão de ferramentas de desenvolvedor, utilitários e IDEs.

Pré-requisitos

Exemplos de código

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

Referências

As instruções neste documento referem-se aos seguintes documentos:

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

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

Diagrama de bot de retransmissão.

O código de exemplo do bot de retransmissão é um bom ponto de partida se você não tiver um bot existente do Serviço de Bot do Azure. Ele é criado a partir do código de exemplo de bot do Microsoft Bot Framework que pode ser compilado e implantado no Serviço de Bot do Azure. O código de exemplo destina-se a ser usado como ponto de partida e não se destina a 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á tiver um bot do Serviço de Bot do Azure, precisará adicionar um conector e um código do Copilot Studio para gerenciar sessões de conversa. Em seguida, você pode implantar o bot no Serviço de Bot do Azure e conectar-se a canais com o portal do Azure.

Obtenha os parâmetros do agente do Copilot Studio

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

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

    Obtenha o nome do bot.

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

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

    Canal Slack.

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

    Obtenha parâmetros de bot.

Gerencie sessões de conversa com seu agente do Copilot Studio

Pode haver várias conversas entre os canais do Serviço de Bot do Azure e a conexão de Linha Direta com seu agente do Copilot Studio.

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

Exemplo de código de exemplo

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

  1. Em cada nova conversa externa do canal do Serviço de Bot do Azure, inicie uma conversa com o agente do Copilot Studio. Consulte Obter token de Linha Direta e Usar Linha Direta 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 externas do canal do Serviço de Bot do Azure para conversas correspondentes do agente do Copilot Studio. Uma conversa do agente do Copilot Studio 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 da Linha Direta ou limpe conversas ociosas. Saiba mais sobre a atualização de token em Atualizar token de linha direta. Uma conversa do agente do Copilot Studio para oferecer suporte à atualização de tokens de Linha Direta é 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 conversa do agente do Copilot Studio for iniciada, adicione um par de valores de chave (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) à tabela de 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 em uma conversa existente, após uma nova mensagem de canal externo do Serviço de Bot do Azure recebida, recupere a conversa existente da tabela de mapeamento, retransmita a atividade de conversa externa para seu agente do Copilot Studio e obtenha uma resposta.

    O exemplo a seguir mostra a retransmissão de 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 linha direta para se comunicar com o agente para saber como obter a resposta do agente do Copilot Studio. Quando a resposta do agente do Copilot Studio for recebida, consulte Analisar carga útil de conversação do agente para saber como analisar a resposta à resposta externa do canal do Serviço de Bot do Azure.

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

Implantar no Serviço de Bot do Azure

Depois de ter o bot de retransmissão do Serviço de Bot do Azure pronto, você precisa 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 entrando no 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 de Serviço de Bot do Azure.

  • Last updated on