Publicar un agente a aplicaciones móviles o personalizadas

2025-06-20

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

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 su 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 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.

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.

Referencias

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

Recuperar sus parámetros de agente de Copilot Studio

Para conectarse al agente que creó, debe recuperar el nombre y el punto de conexión del token de su agente para identificarlo.

En Copilot Studio, navegue a la página Descripción general de su agente y copie el nombre de su 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 su agente, 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 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 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 agente

Una vez obtenido el símbolo de Direct Line, está preparado para tener una conversación con su agente 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.

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

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 la respuesta del agente usando el mismo token y conversationId. Las actividades de respuesta de Direct Line obtenidas contienen los mensajes del usuario y 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 símbolo de Direct Line si su aplicación tiene una conversación larga 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

Después de iniciar una conversación con el agente, 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 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.