Plug-ins de API para Microsoft 365 Copilot
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.
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.
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.