Plug-ins de API para Microsoft 365 Copilot

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

Observação

Além de chamar APIs REST ou servidores MCP, existe uma funcionalidade de pré-visualização que permite que um plug-in chame APIs numa biblioteca local. Recomendamos que experimente esta funcionalidade, mas não deve ser utilizada num plug-in de produção. Para obter mais informações, veja Build API plugins for Microsoft 365 Copilot with the Office JavaScript Library (Criar plug-ins de API para Microsoft 365 Copilot com a Biblioteca JavaScript do Office).

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 (ao utilizar uma API REST) 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

O utilizador pergunta ao agente "Quanto resta no orçamento de renovação do Quarto Café?"
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="".
O agente pede ao utilizador para permitir o envio Fourth Coffee lobby renovation para o plug-in.
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.
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.
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.
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
```
A API devolve uma resposta de API no formato especificado na respetiva especificação OpenAPI.
```
{
  "name": "Fourth Coffee lobby renovation",
  "availableFunds": 5000.00
}
```
O agente gera uma resposta com base na resposta da API.
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

Otimizar o plug-in para o orquestrador Copilot

Microsoft 365 Copilot pode escolher exclusivamente a competência certa a partir das muitas competências no seu repertório. Mas como pode certificar-se de que o Copilot escolhe o plug-in para fornecer a competência certa?

A resposta reside na forma como descreve o plug-in, as suas competências e os parâmetros de iniciação de competências. Especifique descrições concisas e precisas no manifesto do plug-in para garantir que o orquestrador copilot sabe quando e como invocar o plug-in.

A forma como descreve o plug-in para o orquestrador depende do tipo de plug-in que criar, conforme descrito na tabela seguinte.

Tipo de plug-in	Descrito por	Saiba mais
Plug-ins de API	Descrição de OpenAPI	Como tornar um documento OpenAPI eficaz na expansão do Copilot
Ações do Copilot Studio	Nomes e descrições no mapa de conversação Copilot Studio	Orquestrar tópicos e ações de copilot com IA geradora
Plug-ins de extensão de mensagem	Manifesto do aplicativo	Diretrizes para plug-ins de extensão de mensagens

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 de Agentes do Microsoft 365 no Visual Studio ou Visual Studio Code pode criar pacotes de plug-ins com base numa descrição openAPI existente. Se não tiver uma API existente, o Toolkit de Agentes 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

Plug-ins do agente declarativo

Quando um agente declarativo inclui até cinco plug-ins definidos no manifesto do agente declarativo, os plug-ins são sempre injetados no pedido. Quando são definidos mais de cinco plug-ins, o agente utiliza a correspondência semântica. A correspondência semântica baseia-se na descrição do plug-in e não em nenhuma das funções individuais dentro do próprio plug-in.

Um plug-in pode incluir um número ilimitado de funções. Todas as funções são devolvidas, mesmo que apenas uma função seja correspondida. No entanto, devido aos limites das janelas de tokens, a qualidade das respostas poderá degradar-se se forem incluídas mais de 10 funções.

A janela de token para entradas e saídas de um plug-in trunca conteúdo grande. O limite funcional está sujeito a alterações à medida que os modelos melhoram e consoante qualquer sobrecarga do sistema. Otimize para comprimentos de tokens pequenos ou opte por opções de extensibilidade que permitem a transmissão em fluxo de conteúdos grandes, se necessário.

Comentários

Esta página foi útil?

Last updated on 2025-11-19