Publicar un agente en los canales de Azure Bot Service

Puede conectar su agente a los canales de Azure Bot Service existentes que pueden resultar útiles si desea conectar su agente a clientes en canales de Azure Bot Service.

Para agregar su agente a los canales de Azure Bot Service se requiere una experiencia de desarrollador considerable. Este artículo está dirigido a los administradores de TI o desarrolladores que cuentan con experiencia desarrollando y escribiendo código.

Requisitos previos

• Una suscripción a Azure Bot Service.
• Un bot de Azure Bot Service con SDK v4.
• .NET Core SDK versión 2.1.
• Paquete Nuget Microsoft.Bot.Connector.DirectLine.
• Un agente creado en Copilot Studio que desea conectarse a un canal de Azure Bot Service.
• Publicar un agente a aplicaciones móviles o personalizadas.

Ejemplos de código

Los fragmentos de código que se utilizan en este documento son de un código de ejemplo de bot de retransmisión.

Referencias

Las instrucciones de este documento hacen referencia a los documentos siguientes:

• Implementar su bot en Azure para obtener instrucciones sobre cómo implementar el bot de Azure Bot Service.
• Canales de Azure Bot Service para conectarse a cualquier canal compatible con Azure Bot Service.
• Depuración de Azure Bot Service con el emulador para obtener instrucciones sobre cómo depurar el bot de Azure Bot Service.

Crear o usar un bot de Azure Bot Service existente

Necesita un bot de Azure Bot Service que pueda retransmitir conversaciones entre su agente de Copilot Studio y los canales de Azure Bot Service.

El código de ejemplo del bot de retransmisión es un buen punto de partida si no tiene un bot de Azure Bot Service existente. Se ha creado a partir de un código de ejemplo de un bot de Microsoft Bot Framework que se puede compilar e implementar en Azure Bot Service. El código de ejemplo está pensado para usarse como punto de partida y no directamente en la producción. Deberá agregar código y optimización para ajustarse a sus necesidades de negocio.

Si ya tiene un bot de Azure Bot Service, debe agregar un conector y un código de Copilot Studio para administrar sesiones de conversación. A continuación, puede implementar el bot en Azure Bot Service y conectarse a canales con Azure Portal.

Obtener sus parámetros de agente de Copilot Studio

Para conectarse al agente que ha creado con Copilot Studio, deberá recuperar el nombre de su agente y punto de conexión de token.

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

   

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

3. Seleccione el canal al que desea conectarse. Este escenario utiliza Slack como ejemplo.

   

4. Para copiar y guardar el valor de Extremo de token, seleccione Copiar. Necesitará su punto de conexión para conectar su agente al canal de Azure Bot Service.

   

Administrar sesiones de conversación con su agente de Copilot Studio

Puede haber varias conversaciones entre los canales de Azure Bot Service y la conexión Direct Line con su agente de Copilot Studio.

Su bot de Azure Bot Service tiene que asignar y retransmitir la conversación desde el canal de Azure Bot Service a la conversación de Direct Line con el agente de Copilot Studio y viceversa.

Ejemplo de código de muestra

El siguiente ejemplo utiliza ejemplos del código de ejemplo de un bot de retransmisión.

1. En cada nuevo inicio de conversación de canal de Azure Bot Service externo, inicie una conversación de agente de Copilot Studio. Consulte Obtener token de Direct Line y Utilizar Direct Line para comunicarse con el bot para obtener instrucciones sobre cómo iniciar una nueva conversación con el bot.

   using (var httpRequest = new HttpRequestMessage())
   {   
       httpRequest.Method = HttpMethod.Get;
       UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
       httpRequest.RequestUri = uriBuilder.Uri;
       using (var response = await s_httpClient.SendAsync(httpRequest))
       {
           var responseString = await response.Content.ReadAsStringAsync();
           string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
       }
   }
   
   /// <summary>
   /// class for serialization/deserialization DirectLineToken
   /// </summary>
   public class DirectLineToken
   {
       public string Token { get; set; }
   }
   

    // 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. Para administrar varias sesiones, debe mantener una asignación de las conversaciones de canal externas de Azure Bot Service con las correspondientes conversaciones de agente de Copilot Studio. Una conversación de agente de Copilot Studio se puede identificar y conectar con dos propiedades: ConversationtId y Token.

   Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();  
   

   Para administrar el ciclo de vida de la conversación, actualice los tokens Direct Line o limpie conversaciones inactivas. Obtenga más información sobre la actualización de tokens en Actualizar token Direct Line. Una conversación de agente de Copilot Studio para admitir tokens de actualización Direct Line se define de la siguiente manera:

   /// <summary>
   /// Data model class for Copilot Studio agent conversation
   /// </summary>
   public class PowerVirtualAgentsConversation
   {
       public string ConversationtId { get; set; } // The Copilot Studio agent conversation ID retrieved from step 1
   
       public string Token { get; set; } // The DirectLine token retrieved from step 1
   
       public string WaterMark { get; set; } // Identify turn in a conversation
   
       public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh
   
       public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to agent
   }
   

3. Cuando comienza una nueva conversación de agente de Copilot Studio, agregue un par de valores clave (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) a la tabla de asignación.

   // After new Copilot Studio agent conversation starts
   ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
     {
       Token = token,
       ConversationtId = conversationId,
       WaterMark = null,
       LastConversationUpdateTime = DateTime.Now,
       LastTokenRefreshTime = DateTime.Now,
     }; 
   

4. Para continuar en una conversación existente, tras recibir un nuevo mensaje de canal externo de Azure Bot Service, recupere la conversación existente de la tabla de asignación, retransmita la actividad de conversación externa a su agente de Copilot Studio y obtenga una respuesta.

   El siguiente ejemplo muestra una conversación de retransmisión anulando el método ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken)

   // Invoked when a message activity is received from the user
   // Send the user message to Copilot Studio agent and get response
   protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
   {
       // Retrieve agent conversation from mapping table
       // If not exists for the given external conversation ID, start a new Copilot Studio agent conversation
       ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
               currentConversation : /*await StartBotConversationAsync(externalCID)*/;
   
       // Create DirectLine client with the token associated to current conversation
       DirectLineClient client = new DirectLineClient(currentConversation.Token);
   
       // Send user message using directlineClient
       await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
       {
         Type = DirectLineActivityTypes.Message,
         From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
         Text = turnContext.Activity.Text,
         TextFormat = turnContext.Activity.TextFormat,
         Locale = turnContext.Activity.Locale,
       });
   
       // Update LastConversationUpdateTime for session management
       currentConversation.LastConversationUpdateTime = DateTime.Now;
   }  
   

5. Consulte Utilizar Direct Line para comunicarse con el agente para ver cómo se obtiene la respuesta del agente de Copilot Studio. Cuando se reciba la respuesta del agente de Copilot Studio, consulte Analizar la carga de la conversación del agente para saber cómo analizar la respuesta a la respuesta del canal de Azure Bot Service externo.

Un ejemplo de análisis de respuesta se puede encontrar en el código de ejemplo de bot de retransmisión ResponseConverter.cs.

Implementar en Azure Bot Service

Una vez que tenga listo su bot de retransmisión de Azure Bot Service, debe implementar el bot en su Azure Bot Service.

Configurar canales de Azure Bot Service

Puede configurar los canales a los que desea conectarse iniciando sesión en Azure Portal y seleccionando el grupo de recursos de Azure Bot Service en el que se ha implementado. Vea las instrucciones concretas para cada canal en Canales de Azure Bot Service.