Publiez un agent sur des applications mobiles ou personnalisées

Vous pouvez Connecter votre agent dans une application personnalisée afin que les utilisateurs de l’application puissent interagir avec le agent 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.

Connecter votre agent à une application Web est relativement simple car cela implique de copier un code extrait dans votre application. Cependant, les applications Web et les applications natives ou personnalisées nécessitent toujours une expertise considérable des développeurs pour intégrer pleinement agent dans votre application. Les deux procédures sont décrites dans cet article.

Conditions préalables

• kit SDK .NET Core version 2.1.
• Package Nuget Microsoft.Bot.Connector.DirectLine.
• Un agent créé dans Copilot Studio que vous souhaitez ajouter à votre application.

Connecter votre agent vers une application Web

1. Dans Copilot Studio, dans le menu de navigation, 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.

   

Connecter votre agent vers une application native ou personnalisée

Si votre objectif est de publier un Connecter sur les chaînes Azure Connecter, en plus de suivre les instructions ici, vos développeurs peuvent en savoir plus sur Publier un agent sur les chaînes Azure Connecter.

Exemples de code

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

• Exemple de code de connecteur

Références

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

• Bot Framework Direct Line API
• Authentification Direct Line
• Variables contextuelles disponibles lors du transfert
• Activité Microsoft Bot Framework

Récupérez vos Copilot Studio paramètres agent

Pour accéder au agent que vous avez construit, vous devez récupérer le nom et le jeton de votre agent point de terminaison pour l’identifier.

1. Dans Copilot Studio, accédez à la page Présentation de votre agent et copiez le nom de votre agent.

2. Sélectionnez Canaux>Application mobile.

3. Sur la page Application mobile, en regard de Point de terminaison du jeton, sélectionnez Copier. Vous avez besoin de ce point de terminaison pour passer à l’étape Obtenir un jeton Direct Line.

   

Obtenir un jeton Direct Line

Pour démarrer une conversation avec votre agent, vous avez besoin d’un Direct Line token. 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 réussit, un jeton, une heure d’expiration et un identifiant de conversation pour le agent demandé seront renvoyés. Direct Line Exemple :

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

Exemple de code

L’exemple suivant utilise des échantillons de l’ exemple de code de connecteur pour obtenir un Direct Line jeton pour un Copilot Studio agent.

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

Utilisez Direct Line pour communiquer avec le agent

Après avoir récupéré le Direct Line jeton, vous êtes prêt à avoir une conversation avec votre Copilot Studio agent 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 l’ exemple de code du connecteur pour démarrer une conversation et envoyer et recevoir des messages à partir d’un Copilot Studio agent.

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 le agent’s réponse en utilisant le même token et conversationId. Les activités récupérées Direct Line réponse contiennent à la fois les messages de l’utilisateur et de agent. Vous pouvez filtrer les activités réponse par le nom de votre agent pour obtenir uniquement le message agent’s réponse.

      // 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 si votre application a une longue conversation avec agent. Direct Line 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 la conversation à partir de agent

Une fois que vous avez démarré une conversation avec agent, la charge utile JSON de la 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 agent envoie automatiquement le message d’accueil rubrique système lorsqu’un utilisateur démarre une conversation, vous pouvez envoyer une activité avec Type=event et Name=startConversation.