Publier un agent dans les canaux Azure Bot Service

Article
12/31/2024

Vous pouvez connecter votre agent aux canaux Azure Bot Service existants, ce qui peut être utile si vous souhaitez connecter votre agent aux utilisateurs sur les canaux Azure Bot Service.

L’ajout de votre agent aux canaux Azure Bot Service nécessite une expertise considérable des développeurs. 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 agent 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 agent 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 SDK .NET Core version 2.1.
Package Nuget Microsoft.Bot.Connector.DirectLine.
Un agent créé dans Copilot Studio que vous souhaitez connecter à un canal Azure Bot Service.
Publiez un agent dans les 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 de ce document font référence aux documents suivants :

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

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 agent 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 du 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 devez ajouter du code et l’optimiser 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 agent Copilot Studio

Pour vous connecter à l’agent que vous avez créé avec Copilot Studio, vous devez récupérer le nom de votre agent et le point de terminaison du jeton.

Copiez le nom de votre agent 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 agent au canal Azure Bot Service.

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

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

Votre bot Azure Bot Service doit mapper et relayer la conversation du canal Azure Bot Service vers la conversation Direct Line avec l’agent Copilot Studio et vice versa.

Exemple de code

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

À chaque nouveau démarrage de conversation du canal Azure Bot Service externe, démarrez une conversation avec l’agent Copilot Studio. Consultez Obtenir un jeton Direct Line et Utiliser Direct Line pour communiquer avec l’agent 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 de l’agent Copilot Studio correspondantes. Une conversation de l’agent 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 l’agent Copilot Studio pour prendre en charge l’actualisation des jetons Direct Line est définie comme suit :

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

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

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

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 vers votre agent 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 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;
}

Consultez Utiliser Direct Line pour communiquer avec l’agent pour savoir comment obtenir la réponse de l’agent Copilot Studio. Quand la réponse de l’agent Copilot Studio est reçue, reportez-vous à Analyser la charge utile de conversation de l’agent 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.

Partage via