Publicar um agente em aplicações móveis ou personalizadas

Pode ligar o seu agente a uma aplicação personalizada para que os utilizadores da aplicação possam interagir diretamente com o agente dentro da sua aplicação.

Na maioria dos casos, a sua aplicação personalizada é uma aplicação para dispositivos móveis que é uma aplicação baseada na Web ou uma aplicação nativa ou adaptador para outros serviços que o seu negócio necessita.

Existem diferentes procedimentos para a ligação à sua aplicação móvel, dependendo se a sua aplicação é uma aplicação baseada na Web ou uma aplicação nativa.

Ligar o seu agente a uma aplicação baseada na Web é relativamente simples, uma vez que envolve copiar um fragmento de código para a sua aplicação. No entanto, tanto as aplicações baseadas na Web como as aplicações nativas ou personalizadas ainda requerem uma experiência considerável de programador para integrar totalmente o agente na sua aplicação. Ambos os procedimentos estão descritos neste artigo.

Pré-requisitos

• SDK de .NET Core versão 2.1.
• Pacote NuGet Microsoft.Bot.Connector.DirectLine.
• Um agente criado no Copilot Studio que pretende ligar à sua aplicação.

Ligue o seu agente a uma aplicação baseada na Web

1. No Copilot Studio, no menu de navegação, selecione Canais.

2. Selecione o mosaico Aplicação móvel para abrir a janela de configuração.

3. Copie o código na secção Aplicações baseadas na Web e forneça-o aos seus programadores de aplicações para adicionar à sua aplicação baseada na Web.

   

Ligue o seu agente a uma aplicação nativa ou personalizada

Se o seu objetivo é ligar-se aos canais do Azure Bot Service, além de seguir as instruções aqui, os seus programadores podem saber mais em Publicar um agente nos canais do Azure Bot Service.

Referências

As instruções deste documento fazem referência ao seguinte material de origem:

• Direct Line API do Bot Framework
• Autenticação da DIrect Line
• Variáveis de contexto disponíveis no momento da entrega
• Atividade do Microsoft Bot Framework

Obtenha os parâmetros do seu agente do Copilot Studio

Para se ligar ao agente que criou, é necessário obter o nome do agente e o ponto final de token para o identificar.

1. No Copilot Studio, navegue até à página Descrição geral do seu agente e copie o nome do seu agente.

2. Selecione Canais>Aplicação móvel.

3. Na página Aplicação móvel, ao lado de Ponto final de token, selecione Copiar. Vai precisar deste ponto final no passo Obter token Direct Line.

   

Obter token Direct Line

Para começar uma conversa com o seu agente, precisa de um token Direct Line. Este token pode ser obtido através de um pedido GET ao ponto final indicado no ecrã do Copilot Studio. Este token deve então ser utilizado como cabeçalho para chamadas subsequentes à Direct Line API.

Exemplo:

GET <BOT TOKEN ENDPOINT>

Se o pedido for bem-sucedido, o ponto final devolve um token Direct Line, o tempo de expiração e um conversationId para o agente pedido.

Exemplo:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

Exemplo de código para obter token Direct Line

O exemplo seguinte obtém um token Direct Line para um agente do Copilot Studio.

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

O objeto de resposta é o mesmo que o pedido GET que vimos anteriormente.

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

Utilize a Direct Line para comunicar com o agente

Depois de obter o token Direct Line, está pronto para ter uma conversa com o seu agente do Copilot Studio com a Direct Line. Para iniciar uma conversa e enviar e receber mensagens, siga as instruções em Direct Line API do Bot Framework para iniciar uma conversa e enviar e receber mensagens.

O exemplo seguinte inicia uma conversa e envia e recebe mensagens de um agente do Copilot Studio.

1. Inicialize uma instância DirectLineClient com o token Direct Line e inicie uma conversa:

      // 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. Uma vez iniciada, cada conversa pode ser identificada e ligada usando a combinação de token e conversationtId. Envie uma mensagem de utilizador para uma conversa existente:

      // Use the retrieved token to create a DirectLineClient instance
      // Use the conversationId from above step
      // endConversationMessage is your predefined message indicating that user wants to quit the chat
      while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
      {
          using (var directLineClient = new DirectLineClient(token))
          {
              // Send user message using directlineClient
              // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
              await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
              {
                  Type = ActivityTypes.Message,
                  From = new ChannelAccount { Id = "userId", Name = "userName" },
                  Text = inputMessage,
                  TextFormat = "plain",
                  Locale = "en-Us",
              });
          }
      }
   

3. Obtenha a resposta do agente utilizando os mesmos token e conversationId. As atividades de resposta da Direct Line obtidas contêm mensagens tanto do utilizador como do agente. Pode filtrar as atividades de resposta pelo nome do seu agente para obter apenas a mensagem de resposta do agente.

      // Use the same token to create a directLineClient
      using (var directLineClient = new DirectLineClient(token))
      {
          // To get the first response set string watermark = null
          // More information about watermark is available at
          // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0
   
          // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
          ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);
   
          // update watermark from response
          watermark = response?.Watermark;
   
          // response contains set of Activity from both user and bot
          // To display bot response only, filter Activity.From.Name equals to your bot name
          List<Activity> botResponses = response?.Activities?.Where(x =>
                    x.Type == ActivityTypes.Message &&
                      string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();
   
          // Display botResponses
      }
   

Atualizar token Direct Line

Poderá ser necessário adicionar código para atualizar o token Direct Line se a sua aplicação tiver uma longa conversa com o agente. O token expira mas pode ser atualizado antes de expirar; saiba mais em Autenticação da Direct Line.

O exemplo seguinte atualiza o token para uma conversa existente do Copilot Studio:

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

Analisar payload de conversação do agente

Após iniciar uma conversa com o agente, o payload JSON da conversa utiliza a atividade padrão da Direct Line do Microsoft Bot Framework. Pode saber mais em Direct Line API do Bot Framework.

Processar atividade de entrega

Se a sua aplicação precisar de ser entregue a um fornecedor de agente em direto, terá de processar a atividade de entrega. A atividade de entrega é enviada quando o nó "Transferir para agente" é atingido. Pode saber mais sobre o payload da atividade de entrega.

Acionar uma mensagem de boas-vindas

Se quiser que o seu agente envie o tópico de sistema Saudação automaticamente quando um utilizador inicia uma conversa, pode enviar uma atividade com Type=event e Name=startConversation.