Créer une expérience de configuration d’agent dans Teams

Une expérience de configuration d’agent permet aux utilisateurs de configurer et de reconfigurer les paramètres de leurs agents directement dans l’étendue de conversation de canal ou de groupe après l’installation. Cela améliore l’efficacité opérationnelle de l’agent dès le début. L’expérience de configuration de l’agent élimine la nécessité d’interventions utilisateur répétées qui entravaient auparavant les avantages des applications en temps opportun, affectant l’expérience utilisateur.

Avec l’expérience de configuration de l’agent, vous pouvez vous assurer de la pertinence et de la valeur continues de l’agent, car les utilisateurs peuvent :

• Personnalisez l’agent en fonction de leurs flux de travail et préférences spécifiques lors de l’installation.
• Reconfigurez les paramètres pour vous adapter à l’évolution des exigences après l’installation.

Par exemple, un agent qui suit et partage des rubriques d’actualités ou surveille les dépôts GitHub peut initialement être configuré pour correspondre aux flux de travail des utilisateurs. Par la suite, il peut être facilement reconfiguré pour répondre aux nouvelles rubriques ou référentiels directement à partir de la conversation de groupe, ce qui simplifie la gestion du contenu et l’interaction sans quitter l’environnement Teams. Cette expérience de configuration flexible améliore considérablement l’expérience utilisateur et la productivité en intégrant les agents en toute transparence dans les opérations quotidiennes.

Voici un exemple où un utilisateur ajoute l’agent à une conversation de groupe, puis le configure pour qu’il s’aligne sur ses exigences spécifiques. L’utilisateur reconfigure ensuite l’agent pour modifier le status.

Configurer

Reconfigurer

Pour configurer l’agent comme fonctionnalité d’atterrissage par défaut pour une application qui prend en charge les fonctionnalités de bot et d’onglet, consultez Configurer la fonctionnalité d’atterrissage par défaut.

Expérience de configuration de l’agent de génération

Lorsque vous générez l’expérience de configuration de l’agent, vous devez vous assurer que l’utilisateur doit être en mesure de configurer un agent lors de la première installation et de le reconfigurer à tout moment.

Pour générer l’expérience de configuration de l’agent, procédez comme suit :

1. Mettre à jour le manifeste de l’application

2. Configurer votre bot

Mettre à jour le manifeste de l’application

Dans le fichier manifeste de l’application (précédemment appelé manifeste d’application Teams), mettez à jour la fetchTask propriété sous l’objet bots.configuration comme suit :

"bots": [
    {
      "botId": "${{AAD_APP_CLIENT_ID}}",
     "needsChannelSelector": false,
      "scopes": [
        "personal",
        "team",
        "groupChat"
      ],
      "configuration":{
        "groupChat":{
          "fetchTask": true
        },
        "team":{
          "fetchTask": true
        }
      },
      "isNotificationOnly": false
    }
  ],

Pour plus d’informations, consultez Schéma de manifeste d’application.

Configurer votre agent

Lorsqu’un utilisateur installe l’agent dans une conversation de canal ou de groupe, la fetchTask propriété dans le fichier manifeste de l’application lance config.fetch ou config.submit.

Si vous définissez la fetchTask propriété dans le manifeste de l’application sur :

• false : l’agent ne récupère pas de boîte de dialogue ou de carte adaptative. Au lieu de cela, l’agent doit fournir une boîte de dialogue statique ou une carte qui est utilisée lorsque l’agent est appelé. Pour plus d’informations, consultez boîtes de dialogue.

• true : l’agent lance config.fetch ou config.submit comme défini. Lorsque l’agent est appelé, vous pouvez renvoyer une carte adaptative ou une boîte de dialogue en fonction du contexte fourni dans channelData et userdata.

Le tableau suivant répertorie le type de réponse associé aux demandes d’appel :

• type: "continue": type: "continue" est utilisé pour définir une continuation d’un dialogue ou d’une carte adaptative dans une configuration d’agent. Lorsque le type est défini sur continue, cela indique que l’agent attend une interaction supplémentaire de l’utilisateur pour poursuivre le processus de configuration.

  Lorsque l’utilisateur envoie la configuration, l’appel config.submit est déclenché. Il lit l’entrée de l’utilisateur et retourne une autre carte adaptative. Vous pouvez également mettre à jour la configuration de l’agent pour retourner une boîte de dialogue.

app.OnConfigFetch(async (context) =>
{
 var card = new AdaptiveCard
 {
     Body = new List<CardElement>
     {
         new TextBlock("Configure your agent")
         {
             Weight = TextWeight.Bolder
         }
     },
     Actions = new List<Action>
     {
         new SubmitAction
         {
             Title = "Submit"
         }
     }
 };
 var taskInfo = new TaskInfo
 {
     Title = "test card",
     Width = new Union<int, Size>(600),
     Height = new Union<int, Size>(500),
     Card = new Attachment
     {
         ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
         Content = card
     }
 };
 return new ConfigTaskResponse(
     new ContinueTask(taskInfo)
 );
});

app.on('config.fetch', async ({ activity }) => {
const card = new AdaptiveCard(
 {
   type: 'TextBlock',
   text: 'Configure your agent',
   weight: 'Bolder',
 }
).withActions(
 new SubmitAction().withTitle('Submit')
);
return {
 config: {
   type: 'continue',
   value: {
     card: cardAttachment('adaptive', card),
     height: 500,
     width: 600,
     title: 'test card',
   },
 },
};
});

@app.on_config_open
async def handle_config_open(
 ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
 card = AdaptiveCard(
     body=[
         TextBlock(text="Configure your agent", weight="Bolder")
     ],
     actions=[
         SubmitAction(title="Submit")
     ]
 )

 return ConfigResponse(
     config=TaskModuleContinueResponse(
         value=CardTaskModuleTaskInfo(
             card=card_attachment(AdaptiveCardAttachment(content=card)),
             height=500,
             width=600,
             title="test card",
         )
     )
 )

• type: "auth": vous pouvez également demander à l’utilisateur de s’authentifier en réponse à la config.fetch demande. La type: "auth" configuration invite l’utilisateur à se connecter via une URL spécifiée, qui doit être liée à une page d’authentification valide qui peut être ouverte dans un navigateur. L’authentification est essentielle pour les scénarios où l’agent nécessite l’authentification de l’utilisateur. Il garantit que l’identité de l’utilisateur est vérifiée, en maintenant la sécurité et les expériences personnalisées au sein des fonctionnalités de l’agent.

  Remarque

  Pour type: "auth" l’authentification tierce uniquement est prise en charge. L’authentification unique (SSO) n’est pas prise en charge. Pour plus d’informations sur l’authentification tierce, consultez Ajouter une authentification.

app.OnConfigFetch(async (context) =>
{
 return new ConfigAuthResponse(
     new ConfigAuth
     {
         SuggestedActions = new SuggestedActions
         {
             Actions = new List<CardAction>
             {
                 new CardAction
                 {
                     Type = "openUrl",
                     Value = "https://example.com/auth",
                     Title = "Sign in to this app"
                 }
             }
         }
     }
 );
});

app.on('config.fetch', async ({ activity }) => {
return {
 config: {
   type: 'auth',
   suggestedActions: {
     actions: [
       {
         type: 'openUrl',
         value: 'https://example.com/auth',
         title: 'Sign in to this app',
       },
     ],
   },
 },
};
});

@app.on_config_open
async def handle_config_open(
 ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
 return ConfigResponse(
     config=ConfigAuth(
         suggested_actions=SuggestedActions(
             to=[],
             actions=[
                 CardAction(
                     type="openUrl",
                     value="https://example.com/auth",
                     title="Sign in to this app",
                 )
             ],
         )
     )
 )

• type="message": lorsque le type est défini sur message, il indique que l’agent renvoie un message simple à l’utilisateur, indiquant la fin de l’interaction ou fournissant des informations sans nécessiter d’autres entrées.

app.OnConfigSubmit(async (context) =>
{
 return new ConfigTaskResponse(
     new MessageTask("You have chosen to finish setting up agent")
 );
});

app.on('config.submit', async ({ activity, send }) => {
return {
 config: {
   type: 'message',
   value: 'You have chosen to finish setting up agent',
 },
};
});

@app.on_config_submit
async def handle_config_submit(
 ctx: ActivityContext[ConfigSubmitInvokeActivity]
) -> ConfigInvokeResponse:
 return ConfigResponse(
     config=TaskModuleMessageResponse(
         value="You have chosen to finish setting up agent",
     )
 )

Lorsqu’un utilisateur reconfigure l’agent, la fetchTask propriété dans le fichier manifeste de l’application démarre config.fetch dans la logique de l’agent. L’utilisateur peut reconfigurer les paramètres de l’agent après l’installation de deux manières :

• @mention agent dans la zone de composition des messages. Sélectionnez l’option Paramètres qui apparaît au-dessus de la zone de composition des messages. Une boîte de dialogue s’affiche, met à jour ou modifie les paramètres de configuration de l’agent dans la boîte de dialogue.

  

• Pointez sur l’agent, le profil d’agent carte s’affiche. Pour mettre à jour ou modifier les paramètres de configuration de l’agent, sélectionnez l’icône paramètres dans le profil d’agent carte.

  

Meilleures pratiques

• Si vous souhaitez avoir une configuration individuelle au niveau du canal de votre agent, veillez à suivre la configuration en fonction du canal. Les données de configuration ne sont pas stockées et la charge utile d’appel inclut le nombre suffisant de channelData.

• Fournissez une boîte de dialogue claire et conviviale qui invite l’utilisateur à entrer les informations requises pour que l’agent fonctionne correctement, telles qu’une URL, un chemin d’accès à une zone ou un lien de tableau de bord.

• Évitez d’envoyer plusieurs notifications ou demandes de configuration après l’installation, car cela risque de perturber les utilisateurs.

Exemple de code

Voir aussi

• Générer des agents pour Teams
• Cartes adaptatives