Publica un agente en los canales Azure Bot Service

Artículo
12/09/2024

Puede compartir su Conectar agente con canales Azure Bot Service existentes, lo que puede ser útil si desea compartir su Conectar con usuarios finales en canales Azure Bot Service.

Agregar tu agente a los canales Azure Bot Service requiere una considerable experiencia como desarrollador. 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 seguir este documento para agregar su Copilot Studio agente a su sitio web, Facebook o Microsoft Teams. Si su objetivo es convertir Conectar en una aplicación web o nativa personalizada, sus desarrolladores pueden obtener más información en Publicar una agente en aplicaciones móviles o 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

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 quieres Conectar a un canal Azure Bot Service.
Publica un agente en 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

Necesitas un Azure Bot Service bot que pueda retransmitir conversaciones entre tus canales agente y Azure Bot Service. Copilot Studio

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.

Obtenga sus parámetros agente Copilot Studio

Para poder acceder al Conectar que construiste con Copilot Studio, necesitas recuperar el nombre y el token de tu agente punto de conexión.

Copia el nombre de tu agente en Copilot Studio.
En el menú de navegación, en Configuración, seleccione Canales.
Seleccione el canal al que desea conectarse. Este escenario utiliza Slack como ejemplo.
Para copiar y guardar el valor de Extremo de token, seleccione Copiar. Necesitas tu punto de conexión para Conectar tu agente para el canal Azure Bot Service.

Gestiona sesiones de conversación con tu Copilot Studio agente

Puede haber múltiples conversaciones entre los canales Azure Bot Service y la Direct Line conexión con tu Copilot Studio agente.

Tu Azure Bot Service bot necesita mapear y transmitir la conversación del canal Azure Bot Service a la Direct Line conversación con el Copilot Studio agente y viceversa.

Ejemplo de código de muestra

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

En cada nuevo inicio de conversación en un canal externo Azure Bot Service, inicie una conversación agente. Copilot Studio Consulta Obtener Direct Line token y Usar Direct Line para comunicarte con el agente 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;
 }

Para administrar varias sesiones, es necesario mantener un asignación de conversaciones de canal externo Azure Bot Service a las conversaciones agente correspondientes. Copilot Studio Una conversación agente se puede identificar y conectar con dos propiedades: Copilot Studio y ConversationtId . 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 agente para admitir tokens de actualización se define de la siguiente manera: Copilot Studio Direct Line

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

Cuando se inicia una nueva conversación agente, agregue un par clave-valor ( Copilot Studio ,external_Azure_Bot_Service_channel_conversationID) a la tabla asignación. PowerVirtualAgentsConversation

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

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

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

Consulte Uso Direct Line para comunicarse con el agente para saber cómo obtener el Copilot Studio agente's respuesta. Cuando se recibe el Copilot Studio agente's respuesta, consulte Analizar la carga útil de la conversación desde agente para saber cómo analizar el respuesta al canal externo Azure Bot Service respuesta.

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.

Compartir a través de