Publicar un agente en 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, la aplicación personalizada es una aplicación de dispositivo móvil que es una aplicación basada en web o una aplicación nativa. También puede ser un adaptador para otros servicios que requiere su empresa.

Existen diferentes procedimientos para conectarse a la aplicación móvil, en función de si la aplicación es una aplicación basada en 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. En este artículo se describen ambos procedimientos.

Prerrequisitos

• .NET Core SDK versión 2.1.
• Paquete NuGet Microsoft.Bot.Connector.DirectLine.
• Un agente creado en Copilot Studio que quieres conectar a tu 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 quiere conectarse a canales de Azure Bot Service, consulte Publish an agent to Azure Bot Service channels.

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 construido, recupere el nombre, el token y el punto de conexión del agente para identificarlo.

1. En Copilot Studio, vaya a la página Overview del agente y copie el nombre del 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. Necesita este punto final para el paso Obtener el token de Direct Line.

   

Obtener símbolo de Direct Line

Para iniciar una conversación con su agente, necesita un token de Direct Line. Para obtener este token, envíe una solicitud GET al punto de conexión que se muestra en la pantalla de Copilot Studio. Use este token como encabezado para las siguientes llamadas 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 para obtener el 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 la GET solicitud que vio 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, está listo para tener una conversación con el agente de Copilot Studio mediante 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 iniciado, puede identificar y conectarse a cada conversación 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 mediante 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 token expira, pero se puede actualizar antes de que expire. Para más información, consulte Direct Line Authentication.

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 útil 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. Para obtener más información, consulte Bot Framework Direct Line API.

Gestionar la actividad de traspaso

Si su aplicación necesita derivar a un proveedor de agentes en vivo, deberá gestionar la actividad de derivación. La actividad de traspaso se envía cuando se activa el nodo Transferir al agente. Puede obtener más información sobre el contenido de la actividad de traspaso.

Desencadenar un mensaje de bienvenida

Para que el agente envíe automáticamente el tema del sistema Greeting cuando un usuario inicia una conversación, envíe una actividad con Type=event y Name=startConversation.