Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Os plug-ins MCP e API são ações personalizadas que 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. Ao usar um desses plug-ins, os usuários podem pedir a um agente declarativo para consultar um servidor MCP ou API REST para obter informações e, quando suportado, criar, atualizar e excluir dados e objetos por meio de prompts de idioma natural.
Este artigo usa o plug-in para a ação personalizada técnica de MCP ou API usada por um agente declarativo. Para o produto, pacote, registro e ciclo de vida do plug-in voltado para o cliente, consulte Plug-ins do Microsoft 365 Copilot.
Durante a compilação ou reutilização, use este artigo para escolher uma ação MCP ou API e entender como o orquestrador a invoca. Você termina com o modelo de ação técnica e um procedimento de produto para implementá-lo. A ação resultante é uma dependência do agente, não uma promessa separada de distribuição pública.
Importante
Os plug-ins MCP e API fornecem ações em agentes declarativos. Eles não são pacotes de plug-in instaláveis autônomos: somente o agente contendo pode acessar suas funções e ferramentas. Para obter informações sobre o relacionamento de manifesto de ação e pacote, consulte Plug-ins e ações de agente declarativo.
Uma API ou plug-in MCP usa um manifesto de plug-in que o Copilot lê para saber mais sobre a API ou o servidor MCP disponível para o agente. O Copilot pode então decidir quando o agente deve usar essa integração para responder a um prompt. Para saber mais sobre esse manifesto, consulte API e esquema de manifesto do plug-in MCP. O pacote instalável usa um manifesto do aplicativo Microsoft 365 separado.
Como o Copilot descobre ferramentas de servidor MCP
Para plug-ins baseados em um servidor MCP, o Copilot resolve as ferramentas do plug-in dinamicamente em runtime por padrão, diretamente do servidor MCP. A descoberta dinâmica de ferramentas significa que você 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.
Esse padrão se aplica a plug-ins MCP usados como ações de agente declarativo. Para um plug-in que faz referência a um servidor MCP remoto por meio agentConnectors do manifesto do aplicativo Microsoft 365, a descoberta dinâmica de ferramentas requer o manifesto do aplicativo versão 1.29 ou posterior e um host que a permita. Para obter mais informações, consulte Configurar servidores MCP remotos para plug-ins do Microsoft 365 Copilot.
Exemplo de plugin
Considere um servidor MCP de orçamentos que permita consultar e criar orçamentos, cobrar despesas ou adicionar fundos a orçamentos existentes. O prompt "Quanto resta no orçamento de viagem da Contoso" pode disparar um plug-in de orçamento, invocando a get-budgets ferramenta.
POST /mcp
Content-Type: application/json
{
"method": "tools/call",
"params": {
"name": "get-budgets",
"arguments": {
"budgetName": "contoso travel"
}
}
}
O Copilot usa a resposta do resultado da ferramenta para gerar sua resposta: "O orçamento de viagem da Contoso tem atualmente US$ 5.000 em fundos disponíveis. Se você precisar alocar fundos para categorias específicas ou rastrear despesas, também posso ajudá-lo com isso. Apenas me diga como posso ajudar!"
O prompt "Cobrar US$ 500 do orçamento de viagem da Contoso para a passagem aérea de Megan" pode ser traduzido para a seguinte chamada de ferramenta MCP.
POST /mcp
Content-Type: application/json
{
"method": "tools/call",
"params": {
"name": "charge-budget",
"arguments": {
"budgetName": "contoso travel",
"amount": 500,
"description": "Megan's airline ticket"
}
}
}
O Copilot responde ao usuário usando as informações retornadas: "A cobrança de US$ 500 pela passagem aérea de Megan foi processada com êxito. O orçamento de viagem da Contoso agora tem US$ 4.500 restantes em fundos disponíveis. Se você precisar fazer mais transações ou precisar de mais ajuda com seu orçamento, por favor me avise!"
Como funcionam os plug-ins
O usuário pergunta ao agente "Quanto resta no orçamento de renovação do lobby do Fourth Coffee?"
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.
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
GetBudgetpara obter detalhes do orçamento. Ele mapeia partes da pergunta do usuário para os parâmetros da função:budgetName="".O agente pede ao usuário para permitir que ele envie
Fourth Coffee lobby renovationpara o plug-in.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.
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.
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.
O agente envia uma solicitação para o servidor MCP ou API do plug-in, que está hospedado fora do Microsoft 365.
O servidor MCP ou a API retorna uma resposta.
{ "name": "Fourth Coffee lobby renovation", "availableFunds": 5000.00 }O agente gera uma resposta com base na resposta do servidor MCP ou da API.
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 as ações do seu agente
Descreva a integração da API ou do MCP, suas funções ou ferramentas e suas entradas com precisão para que o orquestrador possa selecionar a ação certa para a solicitação do usuário. Essas descrições dizem respeito às ações do agente, não ao nome ou à descrição do repositório do pacote de plug-in externo.
| Integração de ações | Onde descrevê-lo | Saiba mais |
|---|---|---|
| Plugin de API | Manifesto de plug-in e operação OpenAPI e descrições de parâmetros | Criar descrições efetivas de OpenAPI |
| Plug-in MCP | Descrições do manifesto do plug-in e da ferramenta MCP; As definições de ferramenta vêm do servidor em tempo de execução ou são fixadas no manifesto | Descoberta dinâmica de ferramentas e ferramentas fixadas |
As funções e as ferramentas MCP não são iguais aos arquivos de instrução reutilizáveis descritos em Habilidades como recursos de plug-in.
Criar um agente declarativo com ações de API ou MCP
Para desenvolvimento profissional, comece com o Work IQ Dev Tools. Escolha um ambiente documentado primeiro e adicione uma ferramenta na lista a seguir quando precisar de seus recursos de geração ou integração de projetos:
-
O Work IQ Dev Tools é a ferramenta recomendada. Use
wiqd agent add actionpara adicionar uma ação OpenAPI ou MCP remota compatível a um projeto de agente declarativo. - As instruções passo a passo baseadas no Kit de Ferramentas existentes permanecem disponíveis para um servidor MCP, uma descrição de OpenAPI ou uma nova API REST. Siga esses procedimentos ao trabalhar com um projeto de Kit de Ferramentas.
- O Kiota pode gerar um manifesto de plugin de API a partir de uma descrição existente do OpenAPI.
O manifesto da API ou do plug-in MCP configura a integração da ação do agente. Empacotar e distribuir o agente contendo por meio de sua rota app-package com suporte; O manifesto de ação não é um pacote de plug-ins instalável de forma independente.
Dica
As Ferramentas de Desenvolvimento do Work IQ geralmente estão disponíveis.
wiqd agent add action Adiciona uma ação a um projeto de agente declarativo e wiqd agent validate --mode source executa verificações offline na origem do agente salvo. Uma marcação de origem aprovada não estabelece a acessibilidade do runtime ou do ponto de extremidade OpenAPI, a exatidão da autenticação ou a aceitação do pacote final. Se você omitir, --modeo padrão de validação será package, que carrega uma cópia de um ZIP existente e pode exigir entrada. Para modos de validação e cobertura, consulte a referência de comandos WIQD e Validação e MVL.
Limitações
Esses limites dizem respeito a plug-ins de API e MCP usados como ações de agente declarativo, não ao número de habilidades, agentes ou conectores em um pacote de plug-in instalável.
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.
Próxima etapa
Implemente aação MCP ou API selecionada. Depois que os componentes funcionarem individualmente, insira Pacote & teste com Integrar e teste seus componentes.
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
- API e esquema de manifesto do plug-in MCP para o Microsoft 365 Copilot
- Escreva instruções eficazes para agentes declarativos com plug-ins de API