Compartilhar via

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!"

Como funcionam os plug-ins de API

Um diagrama de sequência a mostrar como funciona um plug-in da API

  1. O utilizador pergunta ao agente "Quanto resta no orçamento de renovação do Quarto Café?"

  2. O agente identifica um plug-in relacionado com o orçamento dos plug-ins disponíveis que tem uma função GetBudget para obter detalhes orçamentais. Mapeia partes da pergunta do utilizador para os parâmetros da função: budgetName="".

  3. O agente pede ao utilizador para permitir o envio Fourth Coffee lobby renovation para o plug-in.

  4. O utilizador opta por permitir que os dados sejam partilhados com o plug-in uma vez ou opta por permitir sempre que os dados sejam partilhados para esta função.

  5. Se a API do plug-in necessitar de autenticação, o plug-in solicita um token ou uma chave de API a partir do arquivo de tokens.

  6. O arquivo de tokens devolve um token ou chave. Se necessário, o arquivo de tokens faz com que o agente contacte o utilizador para iniciar sessão.

  7. O agente envia um pedido para a API do plug-in, que está alojada fora do Microsoft 365.

    GET /budgets?budgetName=Fourth+Coffee+lobby+renovation

  8. A API devolve uma resposta de API no formato especificado na especificação OpenAPI.

    {
  "name": "Fourth Coffee lobby renovation",
  "availableFunds": 5000.00
}

  9. O agente gera uma resposta com base na resposta da API.

  10. O agente envia a resposta "Os fundos disponíveis deixados no orçamento de renovação do quarto café são $5.000."

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.

Conteúdo relacionado