Solicitudes de confirmación de complementos de API para Microsoft 365 Copilot

Importante

Los complementos de API solo se admiten como acciones dentro de agentes declarativos. No se habilitan en Microsoft 365 Copilot.

De forma predeterminada, Microsoft 365 Copilot pide al usuario que confirme el envío de datos a un complemento antes de enviarlos para evitar consecuencias no deseadas en sistemas externos. El usuario puede ver los datos que se van a enviar y tiene la opción de permitir o rechazar. Para algunas operaciones de API, a los usuarios se les ofrece la opción de permitir siempre el envío de datos, lo que impide que se soliciten confirmaciones futuras para esa operación en particular.

Normalmente, Microsoft 365 Copilot muestra al usuario la opción always allow para las operaciones HTTP GET y no muestra la opción para POST, PATCH, PUT y DELETE. Los desarrolladores de complementos de API pueden cambiar este comportamiento para las operaciones individuales en su API. Los desarrolladores también pueden personalizar el texto que Copilot muestra al usuario como parte de la solicitud de confirmación.

Invalidar el comportamiento de la solicitud

Los desarrolladores pueden controlar si Microsoft 365 Copilot muestra la opción always allow para una operación específica agregando la x-openai-isConsequential propiedad en el documento de OpenAPI para su API. Al establecer esta propiedad true en , se deshabilita la opción always allow y se establece para false habilitarla. Por regla general, cualquier acción con efectos secundarios en el sistema externo debe marcarse con true para asegurarse de que el usuario está en control y evitar consecuencias no deseadas para las acciones con efectos secundarios en el sistema externo.

Por ejemplo, considere una API que crea un recordatorio: POST /reminders. Dado que se trata de una operación POST, Microsoft 365 Copilot pide al usuario que confirme cada vez que se usa esta API y no ofrece al usuario la opción de permitir siempre esta operación.

Para habilitar la opción always allow, agregue la x-openai-isConsequential propiedad establecida en false, como se muestra en el ejemplo siguiente.

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

Ahora imagine una API relacionada que recupere los avisos existentes: GET /reminders. Dado que es get, Microsoft 365 Copilot muestra al usuario la opción always allow.

Este comportamiento se puede cambiar agregando x-openai-isConsequential set a true.

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

Personalización del texto de confirmación

Los desarrolladores pueden especificar el texto de confirmación estableciendo la body propiedad en el objeto Confirmation del objeto Function capabilities de la función en el manifiesto del complemento. El valor de body debe indicar lo que hace la función. Si esta propiedad no está presente en el manifiesto, se usa la description propiedad en el objeto Function .

{
  "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?"
    }
  }
}