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 é ou uma aplicação baseada na web ou uma aplicação nativa. Também pode ser um adaptador a outros serviços que o seu negócio necessita.

Existem diferentes procedimentos para se ligar à sua aplicação móvel, dependendo se a sua aplicação é baseada na web ou 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. Este artigo descreve ambos os procedimentos.

Pré-requisitos

• SDK de .NET Core versão 2.1.
• Pacote NuGet Microsoft.Bot.Connector.DirectLine.
• Um agente criado no Copilot Studio que você deseja conectar ao seu aplicativo.

Conecte seu agente a um aplicativo baseado na Web

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

2. Selecione o bloco Aplicativo 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.

   

Conecte seu agente a um aplicativo nativo ou personalizado

Se quiser conectar-se aos canais do Azure Bot Service, veja Publicar um agente nos canais do Azure Bot Service.

References

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

• API de Linha Direta do Bot Framework
• Autenticação de linha direta
• Variáveis de contexto disponíveis após a transferência
• Atividade do Microsoft Bot Framework

Obtenha os parâmetros do seu agente do Copilot Studio

Para te ligares ao agente que criaste, recupera o nome do teu agente e o endpoint do token para o identificar.

1. No Copilot Studio, vai à página Visão Geral do teu agente e copia o nome do teu 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 de Linha Direta

Para começar uma conversa com o seu agente, precisa de um token Direct Line. Obtenha este token enviando um pedido GET ao endpoint mostrado no ecrã do Copilot Studio. Use este token como cabeçalho para as próximas chamadas à API de linha direta.

Exemplo:

GET <BOT TOKEN ENDPOINT>

Se o pedido for bem-sucedido, o endpoint retorna um token Direct Line, o tempo de expiração e um conversationId para o agente solicitado.

Exemplo:

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

Obter exemplo de código de token de Linha Direta

O exemplo a seguir obtém um token de 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 do GET pedido que viste antes.

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

Utilize a Direct Line para comunicar com o agente

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

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 iniciado, pode identificar e conectar-se a cada conversa usando a combinação de token e conversationtId. Envie uma mensagem de usuário 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. Recupere a resposta do agente usando os mesmos token e conversationId. As atividades de resposta da Linha Direta recuperadas contêm as mensagens do usuário e 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. Para saber mais, consulte Direct Line Autenticação.

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. Para saber mais, consulte Bot Framework Direct Line API.

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 transferência é enviada quando o nó Transferir para o agente é atingido. Pode saber mais sobre o payload da atividade de entrega.

Acionar uma mensagem de boas-vindas

Para que o seu agente envie automaticamente o tópico do sistema de saudações quando um utilizador inicia uma conversa, envie uma atividade com Type=event e Name=startConversation.