Publicar un agente a aplicaciones móviles o personalizadas

Puede conectar su agente a una aplicación personalizada para que los usuarios de la aplicación puedan interactuar con el agente directamente desde su aplicación.

En la mayoría de los casos, su aplicación personalizada será una aplicación para dispositivos móviles nativa o basada en web o bien un adaptador para otros servicios que su empresa requiera.

Existen diferentes procedimientos para conectarse a su aplicación móvil, dependiendo de si su aplicación es una aplicación basada en la web o una aplicación nativa.

Conectar su agente a una aplicación web es relativamente sencillo, ya que implica copiar un fragmento de código en su aplicación. Sin embargo, tanto las aplicaciones basadas en la web como las aplicaciones nativas o personalizadas aún requieren una considerable experiencia de desarrollador para integrar completamente el agente en su aplicación. Ambos procedimientos se describen en este artículo.

Requisitos previos

• .NET Core SDK versión 2.1.
• Paquete Nuget Microsoft.Bot.Connector.DirectLine.
• Un agente creado en Copilot Studio que desea conectar a su aplicación.

Conectar su agente a una aplicación basada en web

1. En Copilot Studio, en el menú de navegación, seleccione Canales.

2. Seleccione el icono de Aplicación móvil para abrir la ventana de configuración.

3. Copie el código debajo de la sección Aplicaciones basadas en la web y proporcióneselo a sus desarrolladores de aplicaciones para que lo agreguen a su aplicación basada en la web.

   

Conectar su agente a una aplicación nativa o personalizada

Si su objetivo es conectarse a los canales de Azure Bot Service, además de seguir las instrucciones que se proporcionan aquí, sus desarrolladores pueden obtener más información en Publicar un agente en los canales de Azure Bot Service.

Referencias

Las instrucciones de este documento hacen referencia al material de origen siguiente:

• Direct Line API de Bot Framework
• Autenticación de Direct Line
• Variables contextuales disponibles tras la transferencia
• Actividad de Microsoft Bot Framework

Recuperar los parámetros del agente de Copilot Studio

Para conectarse al agente que ha creado, debe recuperar el nombre y el punto final del token de su agente para identificarlo.

1. En Copilot Studio, vaya a la página Descripción general de su agente y copie el nombre de su agente.

2. Seleccione Canales>Aplicación móvil.

3. En la página Aplicación móvil, junto a Token de punto de conexión, seleccione Copiar. Lo necesitará en el punto de conexión para el paso Obtener token de Direct Line.

   

Obtener símbolo de Direct Line

Para iniciar una conversación con su agente, necesita un token de Direct Line. Este token se puede obtener realizando una solicitud GET al punto de conexión indicado en la pantalla Copilot Studio. Este símbolo (token) debe usarse como encabezado para las llamadas posteriores a la API de línea directa.

Ejemplo:

GET <BOT TOKEN ENDPOINT>

Si la solicitud se realiza correctamente, el punto de conexión devuelve un token Direct Line, una hora de expiración y un conversationId para el agente solicitado.

Ejemplo:

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

Ejemplo de código de token de Direct Line

En el ejemplo siguiente se obtiene un token de Direct Line para un agente de 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; }
}

El objeto de respuesta es el mismo que el de la solicitud GET que vimos anteriormente.

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

Usar Direct Line para comunicarse con el agente

Después de recuperar el token de Direct Line, estará listo para mantener una conversación con su agente de Copilot Studio con Direct Line. Para iniciar una conversación y enviar y recibir mensajes, siga las instrucciones en Direct Line API de Bot Framework para iniciar una conversación y enviar y recibir mensajes.

En el ejemplo siguiente se inicia una conversación y se envían y reciben mensajes de un agente de Copilot Studio.

1. Inicie una instancia de DirectLineClient con el token de Direct Line y empiece una conversación:

      // 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. Una vez iniciada, cada conversación se puede identificar y conectar mediante la combinación de token y conversationtId. Envíe un mensaje de usuario a una conversación 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 la respuesta del agente usando el mismo token y conversationId. Las actividades de respuesta de Direct Line recuperadas contienen mensajes tanto del usuario como del agente. Puede filtrar las actividades de respuesta por el nombre de su agente para obtener solo el mensaje de respuesta del 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
      }
   

Actualizar el símbolo de Direct Line

Es posible que tenga que agregar código para actualizar el token de Direct Line si su aplicación tiene una larga conversación con el agente. El símbolo expira, pero puede actualizarlo antes de que expire; obtenga más información en Autenticación de Direct Line.

En el ejemplo siguiente se actualiza el token de una conversación existente de 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

Analizar la carga de la conversación del agente

Tras iniciar una conversación con el bot, la carga JSON de la conversación utiliza la actividad estándar de Direct Line de Microsoft Bot Framework. Puede obtener más información en la API de Direct Line de Bot Framework.

Gestionar la actividad de transferencia

Si su aplicación debe transferirse a un proveedor de agente por chat, deberá gestionar la actividad de transferencia. La actividad de transferencia se envía cuando se introduce el nodo "Transferir a agente". Puede obtener más información sobre la carga de la actividad de transferencia.

Desencadenar un mensaje de bienvenida

Si desea que su agente envíe automáticamente el tema del saludo del sistema cuando un usuario inicia una conversación, puede enviar una actividad con Type=event y Name=startConversation.