Publier un copilote sur les canaux Azure Bot Service

Article
09/27/2024

Vous pouvez pointer votre copilote sur des canaux Azure existants , ce qui peut être utile si vous souhaitez pointer votre copilote sur des utilisateurs finaux sur des canaux Azure.

L’ajout de votre copilote aux canaux Azure Bot Service nécessite une expertise de développeur considérable. Cet article est destiné aux administrateurs informatiques ou aux développeurs qui ont de l’expérience dans le développement et l’écriture de code.

Astuce

Vous n’avez pas besoin de suivre ce document pour ajouter votre copilote Copilot Studio à votre site Internet, Facebook ou Microsoft Teams. Si votre objectif est de vous connecter à une application Web ou native personnalisée, vos développeurs peuvent en savoir plus dans la section Publier un copilote dans les applications mobiles ou personnalisées.

Important

Les instructions de cette section nécessitent un développement logiciel de votre part ou de la part de vos développeurs. Elles sont destinées aux professionnels de l’informatique expérimentés, tels que les administrateurs informatiques ou les développeurs qui ont une solide compréhension des outils de développement, des utilitaires et des IDE.

Conditions préalables

Un Abonnement à Azure Bot Service.
Un bot Azure Bot Service utilisant le kit de développement logiciel v4.
Kit de développement logiciel .NET Core version 2.1.
Package Nuget Microsoft.Bot.Connector.DirectLine.
Un copilote créé dans Copilot Studio que vous souhaitez connecter à un canal Azure Bot Service.
Publiez un copilote sur des applications mobiles ou personnalisées.

Exemples de code

Les extraits de code utilisés dans ce document proviennent de l’exemple de code de bot de relais.

Références

Les instructions contenues dans ce document font référence aux documents suivants :

Déployez votre bot sur Azure pour obtenir des instructions sur le déploiement du bot Azure Connecter.
Canaux Azure Connecter vers Connecter vers n’importe quel canal pris en charge par Azure Bot Service.
Débogage Azure Connecter avec l’émulateur pour obtenir des instructions sur le débogage du bot Azure Connecter.

Créer ou utiliser un bot Azure Bot Service existant

Vous avez besoin d’un bot Azure Bot Service capable de relayer les conversations entre votre copilote Copilot Studio et les canaux Azure Bot Service.

Schéma du bot de relais.

L’exemple de code du bot relais est un bon point de départ si vous n’avez pas de bot Azure existant. ... Il est construit à partir d’un Microsoft Bot Framework bot exemple de code qui peut être compilé et déployé sur Azure Bot Service. Cet exemple de code est destiné à être utilisé comme point de départ et n’est pas destiné à être utilisé directement en production. Vous devez ajouter du code et des optimisations pour répondre aux besoins de votre entreprise.

Si vous avez déjà un bot Azure Bot Service, vous devez ajouter un connecteur Copilot Studio et du code pour gérer les sessions de conversation. Vous pouvez ensuite déployer le bot sur Azure Bot Service et le connecter aux canaux avec le portail Azure.

Récupérer les paramètres de votre copilote Copilot Studio

Pour accéder au copilote avec lequel vous avez construit Copilot Studio, vous devez récupérer le nom et le jeton de votre copilote point de terminaison.

Copiez le nom de votre copilote dans Copilot Studio.
Dans le menu de navigation, sous Paramètres, sélectionnez Canaux.
Sélectionnez le canal auquel vous voulez vous connecter. Ce scénario utilise Slack comme exemple.
Pour copier et enregistrer la valeur Point de terminaison du token, sélectionnez Copier. Vous avez besoin de votre point de terminaison pour Connecter votre copilote sur le canal Azure Bot Service.

Gérer les sessions de conversation avec votre copilote Copilot Studio

Il peut y avoir plusieurs conversations entre les canaux Azure Bot Service et la connexion Direct Line avec votre copilote Copilot Studio.

Votre bot Azure Bot Service doit mapper et relayer la conversation du canal Azure Bot Service à la conversation avec le copilote et vice versa. Direct Line Copilot Studio

Exemple de code

L’exemple suivant utilise des extraits de l’exemple de code de bot de relais.

À chaque nouveau démarrage de conversation de canal Azure Bot Service externe, démarrez une conversation avec le copilote Copilot Studio. Consultez Obtenir un jeton Direct Line et Utiliser Direct Line pour communiquer avec le copilote pour savoir comment démarrer une nouvelle conversation avec le 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;
 }

Pour gérer plusieurs sessions, vous devez maintenir un mappage entre les conversations externes du canal Azure Bot Service et les conversations avec le copilote Copilot Studio correspondantes. Une conversation avec le copilote Copilot Studio peut être identifiée et connectée avec deux propriétés : ConversationtId et Token.

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

Pour gérer le cycle de vie des conversations, actualisez les jetons Direct Line ou nettoyez les conversations inactives. En savoir plus sur l’actualisation des jetons sur Actualiser le jeton Direct Line. Une conversation copilote pour prendre en charge l’actualisation des jetons est définie comme suit : Copilot Studio Direct Line

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

Quand une nouvelle conversation avec le copilote Copilot Studio démarre, ajoutez une paire clé/valeur (external_Azure_Bot_Service_channel_conversationID,PowerVirtualAgentsConversation) à la table de mappage.

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

Pour poursuivre une conversation existante, lors de la réception d’un nouveau message du canal Azure Bot Service externe, récupérez la conversation existante dans la table de mappage, relayez l’activité de conversation externe à votre copilote Copilot Studio, puis recevez une réponse.

L’exemple suivant montre comment relayer une conversation en annulant la méthode 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;
}

Consultez Utiliser Direct Line pour communiquer avec le copilote pour savoir comment obtenir la réponse du copilote Copilot Studio. Quand la réponse du copilote Copilot Studio est reçue, reportez-vous à Analyser la charge utile de la conversation du copilote pour savoir comment analyser la réponse à la réponse du canal Azure Bot Service externe.

Un exemple d’analyse de réponse se trouve dans l’exemple de code de bot de relais ResponseConverter.cs.

Déployer sur Azure Bot Service

Une fois votre bot de relais Azure Bot Service prêt, vous devez déployer le bot sur votre Azure Bot Service.

Configurer les canaux Azure Bot Service

Vous pouvez configurer les canaux sur lesquels vous souhaitez vous connecter en vous connectant au portail Azure et en sélectionnant le groupe de ressources Azure sur lequel vous avez effectué le déploiement. Consultez les instructions spécifiques à chaque canal dans la section Canaux Azure Bot Service.

Partager via