Ajouter un copilote Copilot Studio aux canaux Azure Bot Service

  • Article

Important

Les capacités et les fonctionnalités de Power Virtual Agents font maintenant partie de Microsoft Copilot Studio, suite à des investissements significatifs dans l’IA générative et des intégrations améliorées dans Microsoft Copilot.

Certains articles et captures d’écran peuvent faire référence à Power Virtual Agents pendant que nous mettons à jour la documentation et le contenu de la formation.

Vous pouvez connecter votre copilote aux canaux Azure Bot Service existants. Cela peut être utile si vous souhaitez connecter votre copilote aux utilisateurs finaux sur les canaux Azure Bot Service.

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 Ajouter un copilote aux applications mobiles et 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

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 de ce document font référence aux éléments suivants :

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 de bot de relais est un bon point de départ si vous n’avez pas de bot Azure Bot Service existant. Il est construit à partir de l’exemple de code de bot Microsoft Bot Framework 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 devrez ajouter du code et l’optimiser pour qu’il réponde 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 vous connecter au copilote que vous avez créé avec Copilot Studio, vous devrez récupérer le nom de votre copilote et le point de terminaison du jeton.

  1. Copiez le nom de votre copilote dans Copilot Studio.

    Obtenir le nom du bot.

  2. Dans le menu de navigation, sous Paramètres, sélectionnez Canaux.

  3. Sélectionnez le canal auquel vous voulez vous connecter. Ce scénario utilise Slack comme exemple.

    Canal Slack.

  4. Pour copier et enregistrer la valeur Point de terminaison du token, sélectionnez Copier. Vous aurez besoin de votre point de terminaison pour connecter votre copilote au canal Azure Bot Service.

    Obtenir les paramètres du bot.

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 devra mapper et relayer la conversation du canal Azure Bot Service vers la conversation Direct Line avec le copilote Copilot Studio et vice versa.

Exemple de code

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

  1. À 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;
 }

  2. 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 avec le copilote Copilot Studio est définie comme suit pour cette prise en charge :

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

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

  5. 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 auxquels vous souhaitez vous connecter en vous connectant au portail Azure et en sélectionnant le groupe de ressources Azure Bot Service sur lequel vous avez opéré le déploiement. Consultez les instructions spécifiques à chaque canal dans la section Canaux Azure Bot Service.