Publiez un agent sur les chaînes Azure Bot Service

Article
12/09/2024

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

L’ajout de vos chaînes agent aux chaînes Azure Bot Service nécessite une expertise considérable en tant que développeur. 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 Copilot Studio agent à votre site Web, Facebook ou Microsoft Teams. Si votre objectif est de Connecter vers une application Web ou native personnalisée, vos développeurs peuvent en savoir plus sur Publier un agent sur des 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 sur un canal Azure Connecter.
Publiez un agent 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 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 qui peut relayer les conversations entre vos chaînes Copilot Studio agent et 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.

Obtenez vos paramètres Copilot Studio agent

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

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 sur le canal Azure Bot Service.

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

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

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

Exemple de code

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

À chaque démarrage d’une nouvelle conversation sur un canal externe Azure Bot Service, démarrez une Copilot Studio conversation agent. Consultez Obtenir Direct Line un jeton et Utiliser Direct Line pour communiquer avec agent pour obtenir des instructions sur le démarrage d’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 de conversations de canal Azure Bot Service externes correspondant à Copilot Studio agent conversations. Une Copilot Studio conversation agent peut être identifiée et connectée à 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 agent pour prendre en charge l’actualisation des jetons est définie comme suit : 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
}

Lorsqu’une nouvelle Copilot Studio conversation agent démarre, ajoutez une paire clé-valeur (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) à la table 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 continuer une conversation existante, lors de la réception d’un nouveau message de canal externe Azure Bot Service, récupérez la conversation existante dans la table mappage, relayez l’activité de conversation externe à votre Copilot Studio agent et obtenez un 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 le agent pour savoir comment obtenir le Copilot Studio agent’s réponse. Lorsque le Copilot Studio agent’s réponse est reçu, reportez-vous à Analyser la charge utile de conversation du agent pour savoir comment analyser le réponse vers le canal Azure Bot Service externe réponse.

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.

Partager via