Agregar un copiloto de Copilot Studio a los canales de Azure Bot Service

  • 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 los canales de Azure Bot Service existentes. Esto puede resultar útil si desea conectar su copiloto a los usuarios finales en los canales de Azure Bot Service.

Para agregar su copiloto 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.

Propina

No es necesario que lea este documento para agregar su copiloto de Copilot Studio a su sitio web, Facebook o Microsoft Teams. Si su objetivo es conectarse a una aplicación nativa o basada en la web personalizada, sus desarrolladores pueden obtener más información en Agregar un copiloto a aplicaciones móviles y personalizadas.

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.

Requisitos previos

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 lo siguiente:

Crear o usar un bot de Azure Bot Service existente

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

Diagrama bot de retransmisión.

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 copiloto de Copilot Studio

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

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

    Obtener nombre del bot.

  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.

    Canal de Slack.

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

    Obtener parámetros de bot.

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

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

Su bot de Azure Bot Service tendrá que asignar y retransmitir la conversación desde el canal de Azure Bot Service a la conversación de Direct Line con el copiloto 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 copiloto de Copilot Studio. Consulte Obtener símbolo de Direct Line y Utilizar Direct Line para comunicarse con el copiloto 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 copiloto de Copilot Studio. Una conversación de copiloto 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 copiloto de Copilot Studio para respaldarlos se define de la siguiente manera:

    /// <summary>
/// Data model class for Copilot Studio copilot conversation
/// </summary>
public class PowerVirtualAgentsConversation
{
    public string ConversationtId { get; set; } // The Copilot Studio copilot 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 copilot
}

  3. Cuando comienza una conversación nueva de copiloto 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 copilot 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 copiloto 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 copilot and get response
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Retrieve copilot conversation from mapping table
    // If not exists for the given external conversation ID, start a new Copilot Studio copilot 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 copiloto para ver cómo se obtiene la respuesta del copiloto de Copilot Studio. Cuando se reciba la respuesta del copiloto de Copilot Studio, consulte Analizar la carga de la conversación del copiloto 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.