Ajouter un copilote à des applications mobiles et personnalisées

  • 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 à une application personnalisée afin que les utilisateurs de l’application puissent interagir avec le copilote directement depuis votre application.

Dans la plupart des cas, votre application personnalisée est une application pour appareil mobile qui est soit une application Web, soit une application native ou un adaptateur à d’autres services dont votre entreprise a besoin.

Il existe différentes procédures pour se connecter à votre application mobile, selon que votre application est une application Web ou une application native.

La connexion de votre copilote à une application Web est relativement simple, car elle implique la copie d’un extrait de code dans votre application. Cependant, les applications Web et les applications natives ou personnalisées nécessitent toujours un considérable travail de développeur pour intégrer pleinement le copilote dans votre application. Les deux procédures sont décrites dans cet article.

Conditions préalables

Connecter votre copilote à une application Web

  1. Dans Copilot Studio, dans le menu de navigation, sous Paramètres, sélectionnez Canaux.

  2. Sélectionnez la vignette Application mobile pour ouvrir la fenêtre de configuration.

  3. Copiez le code sous la section Applications Web et fournissez-le aux développeurs de votre application pour qu’ils l’ajoutent à votre application Web.

    Ajoutez un copilote à une application Web.

Connecter votre copilote à une application native ou personnalisée

Astuce

Bien que cette section explique comment se connecter à une application mobile, le même processus peut être appliqué aux applications personnalisées ou natives, telles que les applications IoT (Internet des objets).

Si votre objectif est de vous connecter aux canaux Azure Bot Service, en plus de suivre les instructions présentées ici, vos développeurs peuvent en savoir plus sur Connecter votre bot aux canaux Azure Bot Service.

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.

Exemples de code

Les extraits de code utilisés dans ce document proviennent de :

Références

Les instructions de ce document font référence au support source suivant :

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

Pour vous connecter au copilote que vous avez créé, vous devrez récupérer le nom de votre copilote et le point de terminaison du jeton pour l’identifier.

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

    Obtenez le nom du copilote.

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

  3. Sélectionnez Application mobile.

    Canal d’application mobile.

  4. En regard de Point de terminaison de jeton, sélectionnez Copier. Vous avez besoin de ce point de terminaison pour passer à l’étape Obtenir un jeton Direct Line.

    Récupérez les paramètres du copilote.

Obtenir un jeton Direct Line

Pour démarrer une conversation avec votre copilote, vous avez besoin d’un jeton Direct Line. Ce jeton peut être obtenu en effectuant une requête GET au point de terminaison indiqué sur l’écran Copilot Studio. Ce jeton doit ensuite être utilisé comme en-tête pour les appels ultérieurs à l’API Directline.

Exemple :

GET <BOT TOKEN ENDPOINT>

Si la demande aboutit, un jeton Direct Line, un délai d’expiration et un ID conversationnel seront retournés pour le copilote demandé. Exemple :

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

Exemple de code

L’exemple suivant utilise des exemples de Code de connecteur pour obtenir un jeton Direct Line pour un copilote Copilot Studio.

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

L’objet de réponse est le même que la requête GET que nous avons vue précédemment.

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

Utiliser Direct Line pour communiquer avec le copilote

Après avoir récupéré le jeton Direct Line, vous êtes prêt à avoir une conversation avec votre copilote Copilot Studio avec Direct Line. Pour lancer une conversation et envoyer et recevoir des messages, suivez les instructions sur API Bot Framework Direct Line.

L’exemple suivant utilise des échantillons de la section Exemple de code de connecteur pour démarrer une conversation et envoyer et recevoir des messages d’un copilote Copilot Studio.

  1. Initialisez une instance DirectLineClient avec le jeton Direct Line et démarrez une conversation :

       // 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. Une fois commencée, chaque conversation peut être identifiée et jointe en utilisant la combinaison de token et conversationtId. Envoyer un message utilisateur à une conversation existante :

       // Use the retrieved token to create a DirectLineClient instance
   // Use the conversationId from above step
   // endConversationMessage is your predefined message indicating that user wants to quit the chat
   while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
   {
       using (var directLineClient = new DirectLineClient(token))
       {
           // Send user message using directlineClient
           // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
           await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
           {
               Type = ActivityTypes.Message,
               From = new ChannelAccount { Id = "userId", Name = "userName" },
               Text = inputMessage,
               TextFormat = "plain",
               Locale = "en-Us",
           });
       }
   }

  3. Récupérez la réponse du copilote en utilisant les mêmes token et conversationId. Les activités de réponse Direct Line récupérées contiennent les messages de l’utilisateur et du copilote. Vous pouvez filtrer les activités de réponse par le nom de votre copilote pour n’obtenir que le message de réponse du copilote.

       // Use the same token to create a directLineClient
   using (var directLineClient = new DirectLineClient(token))
   {
       // To get the first response set string watermark = null
       // More information about watermark is available at
       // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0

       // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
       ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);

       // update watermark from response
       watermark = response?.Watermark;

       // response contains set of Activity from both user and bot
       // To display bot response only, filter Activity.From.Name equals to your bot name
       List<Activity> botResponses = response?.Activities?.Where(x =>
                 x.Type == ActivityTypes.Message &&
                   string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();

       // Display botResponses
   }

Actualiser le jeton Direct Line

Vous devrez peut-être ajouter du code pour actualiser le jeton Direct Line si votre application a une longue conversation avec le copilote. Le jeton expire, mais peut être actualisé avant son expiration ; en savoir plus sur Authentification Direct Line.

L’exemple suivant utilise des échantillons de la section Exemple de code de connecteur pour actualiser le jeton pour une conversation Copilot Studio existante :

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

Analyser la charge utile de conversation du copilote

Après avoir démarré une conversation avec le copilote, la charge utile JSON de conversation utilise l’activité standard Microsoft Bot Framework Direct Line. Pour en savoir plus, voir API Bot Framework Direct Line.

Gérer l’activité de transfert

Si votre application doit opérer un transfert à un conseiller, vous devez gérer l’activité de transfert. L’activité de transfert est envoyée lorsque le nœud « Transfert à l’agent » est atteint. Vous pouvez en savoir plus sur la charge utile de l’activité de transfert.

Déclencher un message d’accueil

Si vous souhaitez que votre copilote envoie automatiquement la rubrique système Bienvenue lorsqu’un utilisateur démarre une conversation, vous pouvez envoyer une activité avec Type=event et Name=startConversation.