Plug-ins de API para Microsoft 365 Copilot

  • Artigo

Os plug-ins de API permitem que os agentes declarativos no Microsoft 365 Copilot interajam com APIs REST que têm uma descrição openAPI. Com um plug-in de API, os utilizadores podem pedir a um agente declarativo que consulte não só uma API REST para obter informações, mas também para criar, atualizar e eliminar dados e objetos. Tudo o que a API REST pode fazer é acessível através de pedidos de linguagem natural.

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.

Um plug-in de API fornece um documento de descrição openAPI e um manifesto de plug-in que o Copilot utiliza para conhecer as capacidades da API. Em seguida, o Copilot pode decidir quando é que uma API de plug-in instalada e ativada é adequada para responder a qualquer pedido. Para saber mais sobre o ficheiro de manifesto necessário para um plug-in de API, veja Esquema de manifesto de plug-in da API para Microsoft 365 Copilot.

Por exemplo, considere uma API de orçamentos que permita consultar e criar orçamentos, cobrar despesas ou adicionar fundos a orçamentos existentes. O pedido "Quanto falta no orçamento de viagem da Contoso" pode acionar um plug-in de orçamento, efetuando a seguinte chamada à API.

GET /budgets?name=contoso%20travel

A Copilot utiliza a resposta da chamada à API para gerar a sua resposta: "O orçamento de viagens da Contoso tem atualmente 5 000 $ em fundos disponíveis. Se precisar de alocar fundos a categorias específicas ou controlar as despesas, também o posso ajudar. Deixe-me saber como posso ajudar!"

O pedido "Cobrar 500 dólares ao orçamento de viagem da Contoso para o bilhete de avião da Megan" pode ser traduzido para a seguinte chamada à API.

POST /budgets/charge
Content-Type: application/json

{
  "budgetName": "Contoso travel",
  "amount": 500,
  "description": "Megan's airline ticket"
}

Copilot responde ao utilizador, usando as informações devolvidas: "O custo de 500 dólares para o bilhete de avião da Megan foi processado com sucesso. O orçamento de viagens da Contoso tem agora $4.500 restantes em fundos disponíveis. Se precisar de efetuar mais transações ou precisar de mais assistência com o seu orçamento, informe-me!"

Confirmar ações

O Copilot pergunta ao utilizador antes de enviar dados para um plug-in da API.

Uma captura de ecrã de uma caixa de diálogo de confirmação de plug-in.

Por predefinição, as APIs que só obtêm dados dão ao utilizador uma opção "Permitir sempre", enquanto as APIs que modificam os dados não. Os programadores de plug-in podem substituir estas predefinições. Para obter detalhes, veja Pedidos de confirmação para plug-ins de API para Microsoft 365 Copilot.

Personalizar a apresentação de resposta

O Copilot gera respostas de conversação com dados de respostas de API. Os plug-ins podem personalizar estas respostas ao fornecer modelos de Cartão Ajustável para apresentar dados de forma estruturada.

Uma captura de ecrã de uma resposta de Cartão Ajustável a partir de um plug-in da API

Gerar pacotes de plug-in da API

Existem duas ferramentas que os programadores podem utilizar para gerar pacotes de plug-ins de API.

  • O Toolkit do Teams no Visual Studio ou Visual Studio Code pode criar pacotes de plug-in com base numa descrição openAPI existente. Se não tiver uma API existente, o Teams Toolkit também tem projetos de arranque com uma API de exemplo e um pacote de plug-in correspondente.
  • O Kiota é uma ferramenta de linha de comandos e uma extensão de Visual Studio Code que pode gerar pacotes de plug-in com base numa descrição openAPI existente.

Limitações

Os URLs nas respostas da API são redigidos

Para proteger a privacidade do utilizador, o Copilot redigi todos os URLs contidos nas respostas da API. A única exceção a este comportamento é qualquer URL numa propriedade especificada pela url propriedade no objeto Propriedades da semântica de resposta.

Confira também