Plug-ins para Microsoft 365 Copilot

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

Um plug-in fornece um manifesto de plug-in que o Copilot utiliza para conhecer as capacidades do servidor MCP ou da API do plug-in. Em seguida, o Copilot pode decidir quando é que um plug-in instalado e ativado é adequado para responder a qualquer pedido. Para saber mais sobre o ficheiro de manifesto necessário para um plug-in, veja Plugin manifest schema for Microsoft 365 Copilot (Esquema de manifesto de plug-in para Microsoft 365 Copilot).

Exemplo de plug-in

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "get-budgets",
    "arguments": {
      "budgetName": "contoso travel"
    }
  }
}

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "get-budgets",
    "arguments": {
      "budgetName": "contoso travel"
    }
  }
}

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "charge-budget",
    "arguments": {
      "budgetName": "contoso travel",
      "amount": 500,
      "description": "Megan's airline ticket"
    }
  }
}

GET /budgets?name=contoso%20travel

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

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

Como funcionam os plug-ins

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 a partir dos plug-ins disponíveis que tem uma ferramenta de servidor MCP ou API GetBudget para obter detalhes do orçamento. 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 o servidor MCP ou a API do plug-in exigir autenticação, o plug-in solicita um token ou 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 o servidor MCP ou API do plug-in, que está alojado fora do Microsoft 365.

8. O servidor ou API MCP devolve uma resposta.

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

9. O agente gera uma resposta com base no servidor MCP ou 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 pela primeira vez para um plug-in.

Depois de o utilizador confirmar a ligação, as ferramentas do servidor MCP e as APIs que apenas obtêm dados não necessitam de confirmação, enquanto as ferramentas e APIs que modificam os dados o fazem. 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 do servidor MCP ou respostas de API. Os plug-ins podem personalizar estas respostas ao fornecer modelos de Cartão Ajustável para apresentar dados de forma estruturada.

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.

Gerar pacotes de plug-in

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 num servidor MCP existente ou numa descrição openAPI. 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.

Conteúdo relacionado

• Criar plug-ins de API a partir de uma API existente para Microsoft 365 Copilot
• Criar plug-ins de API com uma nova API para Microsoft 365 Copilot
• Criar plug-ins a partir de um servidor MCP para Microsoft 365 Copilot
• Esquema de manifesto de plug-in para Microsoft 365 Copilot
• Escrever instruções efetivas para agentes declarativos com plug-ins de API