Publique um agente em aplicativos móveis ou personalizados

Artigo
12/09/2024

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

Na maioria dos casos, seu aplicativo personalizado é um aplicativo para dispositivo móvel baseado na Web ou aplicativo ou adaptador nativo para outros serviços exigidos por sua empresa.

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

Conectar seu agente a um aplicativo baseado na web é relativamente simples, pois envolve copiar um código trecho para seu aplicativo. No entanto, tanto aplicativos baseados na web quanto aplicativos nativos ou personalizados ainda exigem considerável experiência do desenvolvedor para integrar totalmente o agente ao seu aplicativo. Os dois procedimentos são descritos neste artigo.

Pré-requisitos

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 ao seu aplicativo.

Conecte seu agente a um aplicativo baseado na web

No Copilot Studio no menu de navegação, selecione Canais.
Selecione o bloco Aplicativo móvel para abrir a janela de configuração.
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

Dica

Embora esta seção descreva como se conectar a um aplicativo móvel, o mesmo processo pode ser aplicado a aplicativos personalizados ou nativos, como aplicativos IoT (Internet das Coisas).

Se seu objetivo é se conectar aos canais Azure Serviço de Bot, além de seguir as instruções Here, seus desenvolvedores podem aprender mais em Publicar um agente nos canais Azure Serviço de Bot.

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.

Exemplos de códigos

Origem dos trechos de código usados neste documento:

Exemplo do código de conector

Referências

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

Recupere seus parâmetros Copilot Studio agente

Para se conectar ao agente que você criou, você precisa recuperar o nome e o ponto de extremidade do token do seu agente para identificá-lo.

Em Copilot Studio, navegue até a página Visão geral do seu agente e copie o nome do seu agente.
Selecione Canais>Aplicativo móvel.
Na página Aplicativo móvel, ao lado de Ponto de extremidade do Token, selecione Copiar. Você precisa este ponto de extremidade para a etapa Obter token da Direct Line.

Obter token da Direct Line

Para iniciar uma conversa com seu agente, você precisa de um Direct Line token. Esse token pode ser obtido fazendo uma solicitação GET ao ponto de extremidade indicado na tela do Copilot Studio. Esse token deve então ser usado como cabeçalho para chamadas subsequentes à API do directline.

Exemplo:

GET <BOT TOKEN ENDPOINT>

Se a solicitação for bem-sucedida, será retornado um Direct Line token, um tempo de expiração e um conversationId para o agente solicitado. Exemplo:

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

Exemplo de código

O exemplo a seguir usa amostras do código de amostra do Connector para obter um Direct Line token para um Copilot Studio agente.

/// <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 da solicitação GET que vimos anteriormente.

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

Use Direct Line para se comunicar com agente

Após recuperar o Direct Line token, você está pronto para ter uma conversa com seu Copilot Studio agente com Direct Line. Para iniciar uma conversa e enviar e receber mensagens, siga as instruções em Bot Framework Direct Line API.

O exemplo a seguir usa amostras do código de exemplo do Connector para iniciar uma conversa e enviar e receber mensagens de um Copilot Studio agente.

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;
   }

Depois de iniciada, cada conversa pode ser identificada e conectada 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",
           });
       }
   }

Recupere o agente's resposta usando o mesmo token e conversationId. As atividades recuperadas Direct Line resposta contêm mensagens do usuário e de agente. Você pode filtrar as atividades resposta pelo nome do seu agente para obter apenas a mensagem agente's resposta.

   // 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

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

O exemplo a seguir usa partes do Exemplo de código do conector para atualizar o token de 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 carga útil da conversação do agente

Depois de iniciar uma conversa com agente, a carga JSON da conversa usa a atividade padrão. Microsoft Bot Framework Direct Line Saiba mais em Bot Framework Direct Line API.

Tratar a atividade de entrega

Se seu aplicativo tiver que transferir para um provedor de agente humano, você precisará tratar a atividade de entrega. A atividade de entrega é enviada quando chega no nó "Transferir para agente". Você pode saber mais sobre o conteúdo da atividade de entrega.

Disparar uma mensagem de boas-vindas

Se você quiser que seu agente envie a saudação tópico do sistema automaticamente quando um usuário iniciar uma conversa, você pode enviar uma atividade com Type=event e Name=startConversation.

Compartilhar via