Invite de confirmation pour les plug-ins d’API pour Microsoft 365 Copilot

Importante

Les plug-ins d’API sont uniquement pris en charge en tant qu’actions au sein d’agents déclaratifs. Ils ne sont pas activés dans Microsoft 365 Copilot.

Par défaut, Microsoft 365 Copilot demande à l’utilisateur de confirmer l’envoi de données à un plug-in avant de les envoyer afin d’éviter des conséquences inattendues dans des systèmes externes. L’utilisateur peut voir les données à envoyer et a le choix d’autoriser ou de refuser. Pour certaines opérations d’API, les utilisateurs ont la possibilité de toujours autoriser l’envoi de données, ce qui empêche les invites de confirmation ultérieures pour cette opération particulière.

Normalement, Microsoft 365 Copilot affiche à l’utilisateur l’option toujours autoriser pour les opérations HTTP GET, et n’affiche pas l’option post, PATCH, PUT et DELETE. Les développeurs de plug-ins d’API peuvent modifier ce comportement pour des opérations individuelles dans leur API. Les développeurs peuvent également personnaliser le texte que Copilot affiche à l’utilisateur dans le cadre de l’invite de confirmation.

Remplacement du comportement d’invite

Les développeurs peuvent contrôler si Microsoft 365 Copilot affiche l’option toujours autoriser pour une opération spécifique en ajoutant la x-openai-isConsequential propriété dans le document OpenAPI pour leur API. La définition de cette propriété sur true désactive l’option always allow et sa définition sur false l’active. En règle générale, toute action avec des effets secondaires dans le système externe doit être marquée avec true pour s’assurer que l’utilisateur est en contrôle et éviter les conséquences involontaires pour les actions avec des effets secondaires dans le système externe.

Prenons l’exemple d’une API qui crée un rappel : POST /reminders. Comme il s’agit d’une opération POST, Microsoft 365 Copilot demande à l’utilisateur de confirmer chaque fois que cette API est utilisée et ne lui donne pas la possibilité de toujours autoriser cette opération.

Pour activer l’option always allow, ajoutez la x-openai-isConsequential propriété définie sur false, comme indiqué dans l’exemple suivant.

post:
  x-openai-isConsequential: false
  summary: Create a new reminder
  description: Create a new budget with a specified name and due date
  operationId: CreateReminder
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Reminder'
    required: true

Imaginez maintenant une API associée qui récupère les rappels existants : GET /reminders. Étant donné qu’il s’agit d’un GET, Microsoft 365 Copilot montre à l’utilisateur l’option toujours autoriser.

Ce comportement peut être modifié en ajoutant x-openai-isConsequential défini sur true.

get:
  x-openai-isConsequential: true
  summary: Get existing reminders
  description: Gets a list of existing reminders
  operationId: GetReminders

Personnalisation du texte de confirmation

Les développeurs peuvent spécifier le texte de confirmation en définissant la body propriété dans l’objet Confirmation dans l’objet Function capabilities de la fonction dans le manifeste du plug-in. La valeur de body doit indiquer ce que fait la fonction. Si cette propriété n’est pas présente dans le manifeste, la description propriété dans l’objet Function est utilisée à la place.

{
  "name": "GetBudgets",
  "description": "Returns details including name and available funds of budgets, optionally filtered by budget name",
  "capabilities": {
    "confirmation": {
      "type": "AdaptiveCard",
      "title": "Search budgets",
      "body": "Do you want to allow searching for budgets?"
    }
  }
}