Agregar un copiloto a aplicaciones móviles y personalizadas

  • Artículo

Importante

Las capacidades y características de Power Virtual Agents son ahora parte de Microsoft Copilot Studio tras importantes inversiones en IA generativa e integraciones mejoradas en Microsoft Copilot.

Algunos artículos y capturas de pantalla pueden hacer referencia a Power Virtual Agents mientras actualizamos la documentación y el contenido de capacitación.

Puede conectar su copiloto a una aplicación personalizada para que los usuarios de la aplicación puedan interactuar con el copiloto 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 copiloto 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 copiloto en su aplicación. Ambos procedimientos se describen en este artículo.

Requisitos previos

Conectar su copiloto a una aplicación basada en web

  1. En Copilot Studio, en el menú de navegación en Configuració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.

    Agregar copiloto a una aplicación basada en web.

Conectar su copiloto a una aplicación nativa o personalizada

Propina

Aunque esta sección describe cómo conectarse a una aplicación móvil, podría aplicarse el mismo proceso para aplicaciones personalizadas o nativas, como aplicaciones IoT (Internet de las cosas).

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 Conectar su bot a los canales de Azure Bot Service.

Importante

Las instrucciones de esta sección requieren que usted o sus desarrolladores realicen tareas de desarrollo de software. Está destinado a profesionales de TI con experiencia, como administradores de TI o desarrolladores que tienen una sólida comprensión de las herramientas de desarrollo, las utilidades y los IDE.

Ejemplos de código

Los fragmentos de código utilizados en este documento son de:

Referencias

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

Recuperar sus parámetros de copiloto de Copilot Studio

Para conectarse al copiloto que ha creado, deberá recuperar el nombre de su copiloto y punto de conexión de token para identificarlo.

  1. Copie el nombre de su copiloto en Copilot Studio.

    Obtener el nombre del copiloto.

  2. En el menú de navegación, en Configuración, seleccione Canales.

  3. Seleccione Aplicación móvil.

    Canal de aplicación móvil.

  4. Junto a Extremo de token, seleccione Copiar. Necesitará este punto de conexión para el paso Obtener símbolo de Direct Line.

    Obtener parámetros de copiloto.

Obtener símbolo de Direct Line

Para iniciar una conversación con su copiloto, necesita un símbolo de Direct Line. Este token se puede obtener realizando una solicitud GET al punto de conexión indicado en la pantalla de 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 es correcta, se devolverá un token de Direct Line, tiempo de vencimiento y un conversationId para el copiloto solicitado. Ejemplo:

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

Ejemplo de código de muestra

El siguiente ejemplo utiliza muestras del Código de ejemplo de conector para obtener un símbolo de Direct Line para un copiloto 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"
}

Utilizar Direct Line para comunicarse con el copiloto

Una vez obtenido el símbolo de Direct Line, está preparado para tener una conversación con su copiloto de Copilot Studio mediante Direct Line. Para iniciar una conversación y enviar y recibir mensajes, siga las instrucciones de la API de Direct Line de Bot Framework.

El siguiente ejemplo utiliza muestras de Código de ejemplo de conector para iniciar una conversación y enviar y recibir mensajes de un copiloto 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 copiloto usando el mismo token y conversationId. Las actividades de respuesta de Direct Line obtenidas contienen los mensajes del usuario y del copiloto. Puede filtrar las actividades de respuesta por el nombre de su copiloto para obtener solo el mensaje de respuesta del copiloto.

       // 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 símbolo de Direct Line si su aplicación tiene una conversación larga con el copiloto. El símbolo expira, pero puede actualizarlo antes de que expire; obtenga más información en Autenticación de Direct Line.

El siguiente ejemplo utiliza muestras del Código de ejemplo de conector para actualizar el token para una conversación de Copilot Studio existente:

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

Después de iniciar una conversación con el copiloto, la carga útil JSON de la conversación utiliza la actividad de Direct Line estándar 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 copiloto 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.