Pedidos de confirmação para plug-ins de API para Microsoft 365 Copilot

Importante

Os plug-ins de API só são suportados como ações dentro de agentes declarativos. Não estão ativados no Microsoft 365 Copilot.

Por predefinição, Microsoft 365 Copilot pede ao utilizador para confirmar o envio de dados para um plug-in antes de os enviar para evitar consequências indesejadas em sistemas externos. O utilizador consegue ver os dados a enviar e é-lhe dada a opção de permitir ou recusar. Para algumas operações de API, é dada aos utilizadores a opção de permitir sempre o envio de dados, o que impede futuros pedidos de confirmação para essa operação específica.

Normalmente, Microsoft 365 Copilot mostra ao utilizador a opção permitir sempre operações HTTP GET e não mostra a opção POST, PATCH, PUT e DELETE. Os programadores de plug-ins de API podem alterar este comportamento para operações individuais na sua API. Os programadores também podem personalizar o texto que o Copilot apresenta ao utilizador como parte do pedido de confirmação.

Comportamento do pedido de substituição

Os programadores podem controlar se Microsoft 365 Copilot mostra a opção permitir sempre uma operação específica ao adicionar a x-openai-isConsequential propriedade no documento OpenAPI para a respetiva API. Definir esta propriedade para true desativar a opção permitir sempre e defini-la para a false ativar. Regra regra, qualquer ação com efeitos colaterais no sistema externo deve ser marcada com true para garantir que o utilizador está no controlo e evitar consequências indesejadas para ações com efeitos colaterais no sistema externo.

Por exemplo, considere uma API que cria um lembrete: POST /reminders. Uma vez que se trata de uma operação POST, Microsoft 365 Copilot pede ao utilizador para confirmar sempre que esta API é utilizada e não dá ao utilizador a opção de permitir sempre esta operação.

Para ativar a opção permitir sempre, adicione a x-openai-isConsequential propriedade definida como falso, conforme mostrado no exemplo seguinte.

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

Agora, imagine uma API relacionada que obtém lembretes existentes: GET /reminders. Uma vez que é um GET, Microsoft 365 Copilot mostra ao utilizador a opção permitir sempre.

Este comportamento pode ser alterado ao adicionar x-openai-isConsequential o conjunto como verdadeiro.

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

Personalizar texto de confirmação

Os programadores podem especificar o texto de confirmação ao definir a body propriedade no objeto Confirmação no objeto Capacidades de função da função no manifesto do plug-in. O valor de body deve ser indicativo do que a função faz. Se esta propriedade não estiver presente no manifesto, é utilizada a description propriedade no objeto Função .

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