Tornar um agente disponível em aplicativos móveis ou personalizados

Você pode conectar seu agente a um aplicativo personalizado para que os usuários do aplicativo possam interagir com o agente diretamente do aplicativo.

Na maioria dos casos, seu aplicativo personalizado é um aplicativo de dispositivo móvel que é um aplicativo baseado na Web ou um aplicativo nativo. Ele também pode ser um adaptador para outros serviços que sua empresa exige.

Existem procedimentos diferentes para se conectar ao seu aplicativo móvel, dependendo se seu aplicativo é um aplicativo baseado na Web ou um aplicativo nativo.

A conexão do seu agente a um aplicativo baseado na Web é relativamente simples, pois envolve a cópia de um trecho de código no seu aplicativo. No entanto, aplicativos baseados na Web e aplicativos nativos ou personalizados ainda exigem considerável conhecimento de desenvolvedor para integrar totalmente o agente ao seu aplicativo. Este artigo descreve ambos os procedimentos.

Pré-requisitos

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

Conectar o 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 seção Aplicativos baseados na Web e o forneça aos desenvolvedores do aplicativo para adicionar ao seu aplicativo baseado na Web.

   

Conecte seu agente a um aplicativo nativo ou personalizado

Se você quiser se conectar aos canais do Azure Serviço de Bot, consulte Publicar um agente nos canais do Azure Serviço de Bot.

Referências

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

• Direct Line API do Bot Framework
• Autenticação do Direct Line
• Variáveis contextuais disponíveis mediante a transferência
• Atividade do Microsoft Bot Framework

Recuperar os parâmetros de agente do Copilot Studio

Para se conectar ao agente que você construiu, recupere o nome do agente e o endpoint de token para identificá-lo.

1. Em Copilot Studio, vá para a página Overview do agente e copie o nome do agente.

2. Selecione Canais>Aplicativo móvel.

3. Na página Aplicativo móvel, ao lado de Ponto de extremidade do Token, selecione Copiar. Você precisa desse endpoint para a etapa Obter token do Direct Line.

   

Obter token da Direct Line

Para iniciar uma conversa com o agente, você precisa de um token do Direct Line. Obtenha esse token enviando uma solicitação GET para o endpoint mostrado na tela do Copilot Studio. Use esse token como o cabeçalho para as próximas chamadas para a API de linha direta.

Exemplo:

GET <BOT TOKEN ENDPOINT>

Se a solicitação for bem-sucedida, o endpoint retornará um token Direct Line, um tempo de expiração e uma conversaId para o agente solicitado.

Exemplo:

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

Obter exemplo de código de token do Direct Line

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 que a solicitação GET que você viu anteriormente.

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

Usar o Direct Line para se comunicar com o agente

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

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

1. Inicialize uma instância DirectLineClient com o token da 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, você 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 o mesmo token e conversationId. As atividades de resposta do Direct Line recuperadas contêm as mensagens do usuário e do agente. Você 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 da Direct Line

Talvez você precise adicionar código para atualizar o token do Direct Line caso o aplicativo tenha uma conversa longa com o agente. O token expira, mas pode ser atualizado antes de expirar. Para saber mais, consulte Direct Line Authentication.

O exemplo a seguir 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 o conteúdo da conversa do agente

Depois que você inicia uma conversa com o agente, o conteúdo JSON da conversa usará a atividade do Direct Line do Microsoft Bot Framework padrão. Para saber mais, consulte Bot Framework Direct Line API.

Tratar a atividade de transferência

Se seu aplicativo precisar transferir a atividade para um provedor de agentes ao vivo, será necessário gerenciar a transferência. A atividade de transferência é enviada quando o nó de transferência para o agente é atingido. Você pode saber mais sobre o conteúdo da atividade de entrega.

Disparar uma mensagem de boas-vindas

Para que seu agente envie automaticamente o tópico do sistema de saudação quando um usuário iniciar uma conversa, envie uma atividade com Type=event e Name=startConversation.