Plug-ins do Microsoft 365 Copilot

Os plug-ins permitem que agentes declarativos no Microsoft 365 Copilot interajam com servidores MCP (Protocolo de Contexto de Modelo) ou APIs REST que tenham uma descrição de OpenAPI. Usando um plug-in, os usuários podem pedir a um agente declarativo não apenas para consultar um servidor MCP ou API REST para obter informações, mas também para criar, atualizar e excluir dados e objetos. Tudo o que o servidor MCP ou a API REST pode fazer é acessível por meio de prompts de linguagem natural.

Um plug-in fornece um manifesto de plug-in que o Copilot usa para conhecer os recursos do servidor MCP ou da API do plug-in. O Copilot pode então decidir quando um plug-in instalado e habilitado é adequado para responder a qualquer prompt. Para saber mais sobre o arquivo de manifesto que um plug-in requer, consulte Esquema de manifesto do plug-in para o Microsoft 365 Copilot.

Como o Copilot descobre ferramentas de servidor MCP

Para plug-ins baseados em um servidor MCP, o Copilot resolve as ferramentas do servidor dinamicamente em runtime por padrão, diretamente do servidor MCP. A descoberta dinâmica de ferramentas significa que os usuários obtêm as ferramentas mais recentes que o servidor MCP expõe sem esperar que o agente seja reempacotado e republicado. Ao criar o agente, um desenvolvedor pode, opcionalmente, fixar um conjunto fixo de ferramentas no manifesto do plug-in. Os plug-ins da API REST sempre usam as ferramentas definidas no manifesto do plug-in. Para obter mais informações, consulte Criar plug-ins de um servidor MCP para o Microsoft 365 Copilot e Descoberta de ferramentas dinâmicas para plug-ins MCP no Microsoft 365 Copilot.

Exemplo de plugin

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 usuário pergunta ao agente "Quanto resta no orçamento de renovação do lobby do Fourth Coffee?"

2. Para um plug-in MCP que usa descoberta dinâmica de ferramentas, o agente busca as definições de ferramenta atuais do servidor MCP do plug-in em tempo de execução e valida todas as ferramentas novas ou alteradas antes de usá-las. Para um plug-in com um conjunto de ferramentas fixado ou para um plug-in de API REST, o agente usa as ferramentas definidas no manifesto do plug-in.

3. O agente identifica um plug-in relacionado ao orçamento a partir de seus plug-ins disponíveis que tem uma ferramenta de servidor MCP ou API GetBudget para obter detalhes do orçamento. Ele mapeia partes da pergunta do usuário para os parâmetros da função: budgetName="".

4. O agente pede ao usuário para permitir que ele envie Fourth Coffee lobby renovation para o plug-in.

5. O usuário opta por permitir que os dados sejam compartilhados com o plug-in uma vez ou opta por sempre permitir que os dados sejam compartilhados para essa função.

6. Se o servidor MCP ou a API do plug-in exigir autenticação, o plug-in solicitará um token ou chave de API do armazenamento de tokens.

7. O repositório de tokens retorna um token ou chave. Se necessário, o repositório de tokens faz com que o agente solicite que o usuário entre.

8. O agente envia uma solicitação para o servidor MCP ou API do plug-in, que está hospedado fora do Microsoft 365.

9. O servidor MCP ou a API retorna uma resposta.

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

10. O agente gera uma resposta com base na resposta do servidor MCP ou da API.

11. O agente envia a resposta: "Os fundos disponíveis deixados no orçamento de renovação do saguão do Fourth Coffee são de US $ 5.000".

Confirmando ações

O Copilot pergunta ao usuário antes de enviar dados pela primeira vez para um plug-in.

Depois que o usuário confirma a conexão, as ferramentas e APIs do servidor MCP que apenas recuperam dados não exigem confirmação, enquanto as ferramentas e APIs que modificam dados exigem. Os desenvolvedores de plug-ins podem substituir esses padrões. Para obter detalhes, consulte Prompts de confirmação para plug-ins de MCP e API para o Microsoft 365 Copilot.

Personalizando apresentação de resposta

O Copilot gera respostas de conversa usando dados do servidor MCP ou respostas da API. Os plug-ins podem personalizar como esses dados são apresentados, e o mecanismo depende do tipo de plug-in.

• Os plug-ins MCP podem fornecer respostas ricas e interativas usando aplicativos MCP - widgets de interface do usuário que o servidor MCP retorna junto com o resultado da ferramenta em tempo de execução. Como o widget é entregue com a resposta da ferramenta em vez de definido no manifesto, os aplicativos MCP funcionam se o plug-in usa um conjunto fixado de ferramentas ou a descoberta dinâmica de ferramentas.

• Os plug-ins de API podem fornecer modelos de Cartão Adaptável no manifesto do plug-in para exibir dados de maneira estruturada. Como os modelos são definidos em relação às operações declaradas no manifesto, essa abordagem se aplica a plug-ins de API e a plug-ins MCP que usam um conjunto fixado de ferramentas.

Para citações vinculadas à origem em qualquer tipo de plug-in, o Copilot usa semântica de resposta e pode inferir metadados de citação automaticamente da resposta da ferramenta ou da API. A inferência automática é especialmente útil para plug-ins MCP que usam a descoberta dinâmica de ferramentas, em que as ferramentas são resolvidas em runtime e não há definição de ferramenta de manifesto para configurar. Para obter mais informações, consulte Mostrar citações com semântica de resposta.

Tratamento de URL em respostas de ação

A experiência de chat do Microsoft 365 Copilot pode renderizar URLs retornadas como parte de respostas de ação, seja de plug-ins de MCP, plug-ins de API, conectores ou fluxos, como links clicáveis. O runtime do Copilot controla esse comportamento e não o avalia em relação a nenhum domínio declarado pelo plug-in (como a servers seção da descrição do OpenAPI de um plug-in de API).

As regras de segurança, confiança e política da plataforma regem o comportamento de renderização de URL para respostas de ação e podem mudar ao longo do tempo. Não confie em URLs clicáveis em respostas de ação para cenários críticos de produção.

Ajude o orquestrador do Copilot a escolher seu plug-in

O Microsoft 365 Copilot pode escolher exclusivamente a habilidade certa entre as muitas habilidades em seu repertório. Mas como você pode garantir que o Copilot escolha seu plug-in para fornecer a habilidade certa?

A resposta está em como você descreve seu plugin, suas habilidades e os parâmetros para o início das habilidades. Especifique descrições concisas e precisas no manifesto do plug-in para garantir que o orquestrador do Copilot saiba quando e como invocar seu plug-in.

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

Criar um plug-in de agente declarativo

Os desenvolvedores podem usar duas ferramentas para gerar pacotes de plug-ins de API:

• O Kit de Ferramentas de Agentes do Microsoft 365 no Visual Studio ou no Visual Studio Code cria pacotes de plug-ins com base em um servidor MCP existente ou na descrição de OpenAPI. O Agents Toolkit também tem projetos iniciais com uma API de exemplo e o pacote de plug-ins correspondente.
• Kiota é uma ferramenta de linha de comando e uma extensão do Visual Studio Code que gera pacotes de plug-ins com base em uma descrição existente do OpenAPI.

Limitações

Quando um agente declarativo inclui até cinco plug-ins definidos no manifesto do agente declarativo, o agente sempre injeta os plug-ins no prompt. Quando o agente inclui mais de cinco plug-ins, ele usa correspondência semântica. A correspondência semântica é baseada na descrição do plug-in, não em nenhuma das funções ou ferramentas individuais dentro do próprio plug-in.

Um plug-in pode incluir um número ilimitado de funções ou ferramentas MCP. Todas as funções ou ferramentas de um plug-in correspondente são retornadas, mesmo que apenas uma corresponda. Para um plug-in MCP que usa a descoberta dinâmica de ferramentas, as ferramentas resolvidas do servidor MCP em runtime contam para esse total. Devido aos limites da janela de token, a qualidade das respostas poderá ser prejudicada se mais de 10 funções ou ferramentas forem incluídas.

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 dependendo de qualquer sobrecarga do sistema. Otimize para pequenos comprimentos de token ou opte por opções de extensibilidade que permitem o streaming de conteúdo grande, se necessário.

Conteúdo relacionado

• Criar plug-ins de um servidor MCP para o Microsoft 365 Copilot
• Adicionar aplicativos MCP a agentes declarativos no Microsoft 365 Copilot
• Descoberta dinâmica de ferramentas para plug-ins MCP no Microsoft 365 Copilot
• Crie plug-ins de API de uma API existente para o Microsoft 365 Copilot
• Crie plug-ins de API com uma nova API para o Microsoft 365 Copilot
• Esquema de manifesto de plug-in para Microsoft 365 Copilot
• Escreva instruções eficazes para agentes declarativos com plug-ins de API