Publicar un agente en aplicaciones móviles o personalizadas

Artículo
12/09/2024

Puedes Conectar tu agente en una aplicación personalizada para que los usuarios de la aplicación puedan interactuar con el agente directamente desde tu 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 basada en web es relativamente sencillo, ya que implica copiar un código fragmento de código en su aplicación. Sin embargo, tanto las aplicaciones basadas en web como las aplicaciones nativas o personalizadas aún requieren una considerable experiencia del desarrollador para integrar completamente 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 quieres Conectar en tu aplicación.

Conectar tu agente a una aplicación basada en web

En Copilot Studio, seleccione Canales en el menú de navegación.
Seleccione el icono de Aplicación móvil para abrir la ventana de configuración.
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 tu agente 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 enviar un Conectar a canales Azure Bot Service, además de seguir las instrucciones aquí, sus desarrolladores pueden obtener más información en Publicar un agente en canales 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:

Código de ejemplo de conector

Referencias

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

Recupera tus parámetros agente Copilot Studio

Para Conectar al agente que construiste, necesitas recuperar el nombre de tu agente y el token punto de conexión para identificarlo.

En Copilot Studio, navega a la página Descripción general de tu agente y copia el nombre de tu agente.
Seleccione Canales>Aplicación móvil.
En la página Aplicación móvil, junto a Token de punto de conexión, seleccione Copiar. Necesitará este punto de conexión para el paso Obtener símbolo de Direct Line.

Obtener símbolo de Direct Line

Para iniciar una conversación con tu agente, necesitas un token. 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 exitosa, se devolverá un token, un tiempo de expiración y un conversationId para el agente solicitado. Direct Line 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 muestra del conector para obtener un Direct Line token para un 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; }
}

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

Utilice Direct Line para comunicarse con agente

Después de recuperar el token, estás listo para tener una conversación con tu agente con Direct Line Copilot Studio 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 del código de muestra del conector para iniciar una conversación y enviar y recibir mensajes desde un Copilot Studio agente.

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

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",
           });
       }
   }

Recupere el agente's respuesta usando el mismo token y conversationId. Las actividades respuesta recuperadas contienen mensajes tanto del usuario como de agente. Direct Line Puedes filtrar las actividades respuesta por el nombre de tu agente para recibir solo el mensaje agente's respuesta.

   // 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 necesites agregar código para actualizar el token si tu aplicación tiene una conversación larga con agente. Direct Line 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 útil de la conversación desde agente

Después de iniciar una conversación con agente, la carga útil JSON de la conversación utiliza la actividad estándar. Microsoft Bot Framework Direct Line 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 quieres que tu agente envíe el saludo tema del sistema automáticamente cuando un usuario inicia una conversación, puedes enviar una actividad con Type=event y Name=startConversation.

Compartir a través de