Diretrizes para criar ou atualizar um plug-in de extensão de mensagem para Copilot para Microsoft 365
Importante
- Os plug-ins para Microsoft Copilot para Microsoft 365 estão em versão prévia e funcionam apenas em Microsoft 365 Chat no Microsoft Teams.
- Verifique se Copilot para Microsoft 365 está disponível para sua organização. Você tem duas maneiras de obter um ambiente de desenvolvedor para Copilot:
- Um locatário do Microsoft 365 com Copilot (disponível em versão prévia limitada por meio da associação TAP).
- Um ambiente de produção de cliente corporativo com licenças de Microsoft Copilot para Microsoft 365.
Os plug-ins do Microsoft 365 fornecem integração com vários produtos do Microsoft 365, como Teams e Outlook. A integração ajuda os usuários a pesquisar ou criar conteúdo em sistemas externos. Os plug-ins de extensão de mensagem permitem que Microsoft Copilot para Microsoft 365 interajam com APIs de outros softwares e serviços por meio de um bot. Com Copilot para Microsoft 365, você pode:
- Pesquisa para obter as informações ou o registro mais recentes. Por exemplo, o tíquete de incidente mais recente ou os resultados da pesquisa.
- Resumir informações com base em vários registros. Por exemplo, resumir todos os tíquetes de incidente relacionados ao projeto Northwind.
Recomendamos que você crie ou atualize suas extensões de mensagem existentes para maximizar sua utilidade e usabilidade em Copilot para Microsoft 365. As extensões de mensagem devem dar suporte a um ou mais comandos de pesquisa, pois Copilot para Microsoft 365 as reconhece como habilidades que podem ser executadas em nome do usuário. Além disso, suas extensões devem atender aos padrões de conformidade, desempenho, segurança e experiência do usuário descritos neste artigo.
Requisitos obrigatórios
Os requisitos para criar plug-ins de extensão de mensagem para Copilot para Microsoft 365 incluem:
Definir descrições
Uma boa descrição oferece um resumo claro e conciso dos recursos do aplicativo e permite que Copilot para Microsoft 365 descubra e execute operações de pesquisa com eficiência. Quando um usuário insere o nome do aplicativo junto com um verbo, por exemplo, Localizar tíquetes contoso, o plug-in de extensão de mensagem deve ser invocado de Copilot para Microsoft 365 (Chat M365).
Verifique se você segue as diretrizes de descrição listadas na seguinte tabela:
| Ação | Reason |
|---|---|
|
Anti-Compete: evite usar o nome de qualquer outro plug-in em descrições curtas e longas. |
|
|
IA responsável: evite usar palavras-chave inadequadas ou ofensivas. |
|
|
Injeções de prompt: verifique se as descrições não orientam Copilot a executar ações que ignorem o funcionamento normal do aplicativo. Além disso, a descrição não deve conter símbolos ou texto que indiquem que ele pode ser usado como código para injeção rápida. Evite usar frases, funções e código que chamem um aplicativo de forma recorrente. |
Descrição do aplicativo
Descrições de aplicativo longas e curtas devem ser claras e definir o escopo do aplicativo. Para renderizar um aplicativo como um plug-in no Copilot para Microsoft 365, modifique a descrição do aplicativo para atender aos seguintes requisitos de plug-in:
- A descrição longa deve explicar claramente a funcionalidade e o uso do plug-in de extensão de mensagem no Copilot para Microsoft 365. Por exemplo, use a nuvem contoso no Copilot para Microsoft 365 para pesquisar e resumir suas tarefas.
- A descrição curta deve descrever brevemente a funcionalidade do aplicativo em uma linguagem natural e pode incluir o nome do aplicativo.
A tabela a seguir lista os exemplos de descrição curta para cada categoria:
Descrição: criar, pesquisar, exibir tíquetes, bugs e projetos.
Exemplo de descrição do aplicativo:
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.13/MicrosoftTeams.schema.json",
"version": "1.0.0",
"manifestVersion": "1.13",
"id": "2bxxxxc5-5xxx-4xxx-aXXX-94xxxx8919e5",
"name": {
"short": "Tasks",
"full": "Contoso Tasks"
},
"description": {
"short": "Create, search, view tickets, bugs, and projects",
"full": "Contoso Tasks makes it easy to stay organized. Create, assign, and track tasks individually or collaboratively with your team, and see everything come together in one place."
},
descrição do comando Pesquisa
A descrição do comando mapeia a intenção e o enunciado do usuário para pesquisar o comando dentro de um plug-in e deve ser criado com base na análise da intenção e das palavras-chave do usuário. Pesquisa descrições de comando devem:
- Concentre-se no que e em como o comando pesquisa (lista detalhada) no idioma natural.
- Inclua verbos e sinônimos, se aplicável.
- Concentre-se em palavras-chave que provavelmente serão usadas na função de pesquisa de seus aplicativos nativos.
Descrição semântica
A propriedade semanticDescription é usada para fornecer uma descrição detalhada de um comando para Copilot para Microsoft 365. A descrição semântica para comandos dá suporte a até 5.000 caracteres e não é exibida na interface do usuário. Se a semanticDescription propriedade ficar vazia, Copilot para Microsoft 365 usará as informações no description campo. Ao escrever um semanticDescription, você deve incluir informações sobre valores, limites e intervalos esperados para o comando.
A semanticDescription propriedade não é um campo obrigatório. No entanto, se você adicionar semanticDescription no manifesto do aplicativo, as verificações de validação existentes para descrições curtas, de parâmetro e de comando também serão aplicáveis para descrições semânticas.
Recomendamos que você examine as seguintes diretrizes para descrição semântica para aumentar as chances de seu aplicativo passar o processo de envio da Microsoft Teams Store:
- Evite frases instrucionais como "se o usuário disser X", "ignorar", "excluir", "redefinir", "novas instruções", "Responder em negrito" ou "Não imprimir nada". [Correção obrigatória]
- Evite URLs, emojis ou caracteres ocultos, como símbolos hexadecimal, binários ou não convencionais. [Correção obrigatória]
- Evite erros de gramática e pontuação. [Correção obrigatória]
- Evite linguagem excessivamente verbosa, florida ou de marketing. [Correção sugerida]
- Evite declarações superlativas como "#1", "incrível" ou "melhor". [Correção sugerida]
A tabela a seguir lista os exemplos de descrição semântica e de comando para cada categoria:
Descrição: Pesquisa para tarefas de alta prioridade relacionadas ao Northwind que devem ser entregues amanhã.
Exemplo de descrição de comando:
"commands": [
{
"id": "Search",
"type": "query",
"title": "Tasks",
"description": "Search for high priority tasks related to Northwind that are due tomorrow.",
"SemanticDescription": "Search for issues, epics, stories, tasks, sub tasks, bugs + additional details."
"initialRun": true,
"fetchTask": false,
"context": [
"commandBox",
"compose",
"message"
],
Descrição do parâmetro
Cada comando de extensão de mensagem é compatível com uma propriedade "parâmetros" correspondente que dá suporte a até cinco parâmetros e o primeiro parâmetro deve estar visível na barra de pesquisa de extensão de mensagem. Um parâmetro deve ter uma boa descrição, que deve conter uma combinação de parâmetros, enumerações, acrônimos e formato de saída aceitáveis.
A propriedade semanticDescription é usada para fornecer uma descrição detalhada de um comando para o Microsoft Copilot. A descrição semântica para parâmetros dá suporte a até 2.000 caracteres e não é exibida na interface do usuário. Se a semanticDescription propriedade ficar vazia, Copilot usará as informações no description campo. Ao escrever um semanticDescription, você deve incluir informações sobre valores, limites e intervalos esperados para o comando.
Uma boa descrição do parâmetro explica os requisitos do sistema em uma linguagem natural com formato de saída. Veja a seguir alguns exemplos de solicitações de pesquisa básicas e avançadas para cada categoria:
Pesquisa básica: Pesquisa para tarefas relacionadas ao Northwind.Pesquisa avançada: Pesquisa para tarefas de alta prioridade relacionadas ao Northwind que devem ser entregues amanhã.
Exemplo de descrição do parâmetro:
"parameters": [
{
"name": "Name",
"title": "Project or Task Name",
"description": "Project name or task name as keyword.",
"inputType": "text"
},
{
"name": "Time",
"title": "Time",
"description": "Date or number of days for which you need tasks for.",
"semanticDescription": "Date or number of days for which you need tasks for. Output: Number",
"inputType": "text"
},
{
"name": "Priority",
"title": "Priority",
"description": "Priority of tasks.",
"semanticDescription": "Priority of tasks. Acceptable values are high, medium, low, NA",
"inputType": "text"
}]
Enunciados compostos
Observação
Pesquisa por meio da caixa de diálogo (conhecido como módulo de tarefa no TeamsJS v1.x) não tem suporte no Chat M365.
Para o Chat M365, uma extensão de mensagem baseada em pesquisa deve dar suporte a mais de três enunciados compostos exclusivos para executar a recuperação profunda de informações precisas. Para habilitar enunciados compostos, você deve expandir o escopo da pesquisa para lidar com três ou mais parâmetros de pesquisa atualizando o manifesto do aplicativo (anteriormente chamado de manifesto do aplicativo Teams) e garantir o seguinte:
Atualize seu serviço Web para dar suporte à pesquisa com base em vários parâmetros. Para obter mais informações sobre como responder às solicitações do usuário, consulte Responder ao comando de pesquisa.
Copilot para Microsoft 365 pode passar uma cadeia de caracteres vazia ou um valor nulo para parâmetros, que não fazem parte do enunciado do usuário, atualize seu serviço Web para lidar com os parâmetros.
Uma extensão de mensagem dá suporte a até 10 comandos (9 utilizáveis) e cada comando tem uma propriedade correspondente
parametersque dá suporte a até 5 parâmetros.
O código a seguir é um exemplo de vários parâmetros definidos no manifesto do aplicativo:
"commands": [
{
"id": "inventorySearch",
"context": [
"compose",
"commandBox"
],
"description": "Search products by name, category, inventory status, supplier location, stock level",
"title": "Product inventory",
"type": "query",
"parameters": [
{
"name": "productName",
"title": "Product name",
"description": "Enter a product name here",
"inputType": "text"
},
{
"name": "categoryName",
"title": "Category name",
"description": "Enter the category of the product",
"inputType": "text"
},
{
"name": "inventoryStatus",
"title": "Inventory status",
"description": "Enter what status of the product inventory. Possible values are 'in stock', 'low stock', 'on order', or 'out of stock'",
"inputType": "text"
},
{
"name": "supplierCity",
"title": "Supplier city",
"description": "Enter the supplier city of product",
"inputType": "text"
},
{
"name": "stockQuery",
"title": "Stock level",
"description": "Enter a range of integers such as 0-42 or 100- (for >100 items). Only use if you need an exact numeric range.",
"inputType": "text"
}
]
},
{
"id": "discountSearch",
"context": [
"compose",
"commandBox"
],
"description": "Search for discounted products by category",
"title": "Discounts",
"type": "query",
"parameters": [
{
"name": "categoryName",
"title": "Category name",
"description": "Enter the category to find discounted products",
"inputType": "text"
}
]
},
{
"id": "revenueSearch",
"context": [
"compose",
"commandBox"
],
"description": "Find products based on their revenue/period",
"title": "Revenue",
"type": "query",
"parameters": [
{
"name": "revenueRange",
"title": "Revenue range",
"description": "Enter 'high' or 'low' or enter a range of integers such as 0-10000 or 5000- using this exact format",
"inputType": "text"
}
]
}
]
Os parâmetros de pesquisa devem ter boas descrições com parâmetros, enumerações, acrônimos e formato de saída aceitáveis. Para obter mais informações e exemplos, consulte Descrição do parâmetro.
Prompts de exemplo
A samplePrompts propriedade orienta os usuários sobre como usar os vários plug-ins no Copilot. Copilot usa os prompts de exemplo para exibir os prompts para o usuário. Os prompts devem ser adaptáveis a diferentes localidades e desmarcar em diferentes comandos. Os prompts de exemplo estão disponíveis nas seguintes áreas em Copilot para Microsoft 365:
- Experiência de Primeira Execução (FRE): quando um usuário instala ou habilita um plug-in pela primeira vez.
- Biblioteca de prompts ou Copilot Lab: quando um usuário busca ajuda com prompts.
- Sugestões de plug-in: para orientar os usuários para melhores enunciados.
Observação
- Se o manifesto do aplicativo não especificar a
samplePromptspropriedade, os prompts não serão exibidos. - A
samplePromptspropriedade é obrigatória para validação de aplicativo durante o processo de envio do aplicativo. - Se você definir vários comandos para seu aplicativo, um máximo de três prompts (um de cada um dos três principais comandos) serão exibidos para o usuário. Os prompts giram para fornecer ao usuário um conjunto diversificado de prompts em diferentes comandos.
Recomendamos que você siga estas diretrizes para aumentar as chances de seu aplicativo passar pelo processo de envio da Microsoft Teams Store:
- Um plug-in deve ter pelo menos três prompts e no máximo cinco prompts para cada comando.
- Cada prompt não deve exceder 128 caracteres.
- Dois comandos no mesmo plug-in não devem ter prompts idênticos.
- Os prompts de exemplo devem ser genéricos por natureza e não incluir referências personalizadas. Por exemplo, nomes de projeto e nome da tarefa.
- Todos os prompts de exemplo devem ser funcionais e retornar respostas.
- Prompt deve ser relevante para os comandos.
O código a seguir é um exemplo da propriedade no manifesto do samplePrompts aplicativo:
"composeExtensions": [
{
"canUpdateConfiguration": true,
"botId": "bxxxxxx5-xxxx-xxxx-xxxx-4xxxxxx16599",
"commands": [
{
"id": "orders",
"title": "Orders",
"context": [
"Commandbox",
"Compose"
],
"description": "Search for orders",
"semanticDescription": "Search for orders",
"samplePrompts": [
{
"text": "Search for all orders"
},
{
"text": "Search for orders related to Contoso"
},
{
"text": "Search for all pending orders"
},
{
"text": "Search for all completed ordered for Fabrikam"
}
]
}
]
}
]
Resposta do Cartão Adaptável
As extensões de mensagem respondem a uma entrada do usuário com um Cartão Adaptável. Um cartão adaptável para um plug-in de extensão de mensagem deve funcionar efetivamente, parecer rico e atender aos seguintes requisitos:
A resposta do Cartão Adaptável deve incluir o conteúdo do Cartão Adaptável e as informações de cartão de visualização como parte do mesmo modelo. [Obrigatório]
Exemplo de modelo de resposta de cartão adaptável
{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [ { "type": "Container", "items": [ { "type": "TextBlock", "text": "${companyName}", "size": "Medium", "wrap": true, "style": "heading" }, { "type": "TextBlock", "text": "${stockExchange} ${stockSymbol}", "isSubtle": true, "spacing": "None", "wrap": true }, { "type": "TextBlock", "text": "${formattedDate} ${formattedTime}", "wrap": true } ] }, { "type": "Container", "spacing": "None", "items": [ { "type": "ColumnSet", "columns": [ { "type": "Column", "width": "stretch", "items": [ { "type": "TextBlock", "text": "${currentPrice} ", "size": "ExtraLarge", "wrap": true }, { "type": "TextBlock", "text": "${priceChange} ${percentChange}", "color": "${changeColor}", "spacing": "None", "wrap": true } ] }, { "type": "Column", "width": "auto", "items": [ { "type": "FactSet", "facts": [ { "title": "Open", "value": "${openPrice} " }, { "title": "High", "value": "${highPrice} " }, { "title": "Low", "value": "${lowPrice} " } ] } ] } ] } ] } ], "previewCard": { "contentType": "application/vnd.microsoft.card.hero", "content": { "title": "${companyName}", "text": "${stockSymbol}" } } }Além do logotipo do aplicativo, título, miniatura e título das informações, os dados no Cartão Adaptável devem representar pelo menos duas informações. Você pode identificar os campos dos atributos mais pesquisados, como, dados modificados, autor, status e sinalizadores. [Obrigatório]
O Cartão Adaptável deve ser apresentável na área de trabalho, na Web e no celular (iOS e Android). [Obrigatório]
Um Cartão Adaptável deve conter pelo menos um botão de ação, mas não mais de quatro botões de ação. [Obrigatório]
Observação
imBackTipos de ação ,messageBacknão têm suporte em um objeto de dados.Os seguintes tipos de ação são recomendados:
Action.OpenUrl: abre uma URL especificada do Cartão.Action.ToggleVisibility: exibe ou oculta um ou mais elementos no cartão.Action.Execute: coleta os campos de entrada e os envia como uma solicitação para o serviço de bot.Action.Submit: abre uma caixa de diálogo ou Stageview usando a invocação de tipo no objeto de dados.
Se um usuário puder alterar qualquer informação sobre o cartão por meio de caixa de diálogo, Stageview ou diretamente do cartão, recomendamos o Cartão Adaptável para dar suporte a ações universais e atualização automática. [Recomendado]
Os Cartões Adaptáveis devem incluir uma URL como parte dos metadados, o que permite que os cartões sejam facilmente copiados de um hub para outro. [Recomendado]
Além das miniaturas, qualquer imagem em um Cartão Adaptável deve ter um alt-text. [Recomendado]
Requisitos técnicos
Para que um plug-in seja validado, invocado e funcione perfeitamente, verifique se ele atende aos seguintes critérios:
| Critérios | Cumprimento |
|---|---|
| Versão do Manifesto | A versão do manifesto do aplicativo deve ser 1.13 ou posterior. [Obrigatório] |
| Canal do Microsoft 365 | Para que os usuários interajam com sua extensão de mensagem do Outlook, você precisa adicionar o canal do Microsoft 365 ao seu bot. Para obter mais informações, confira Adicionar canal do Microsoft 365. [Obrigatório] |
| Tempo de resposta | O tempo de resposta não deve exceder 9 segundos para 99%, 5 segundos para 75% e 2 segundos para 50%. [Obrigatório] |
| Confiabilidade | Os aplicativos devem manter 99,9% de disponibilidade. Por exemplo, se Microsoft 365 Chat chamar um plug-in 1.000 vezes, ele deverá fornecer uma resposta significativa 999 vezes. [Obrigatório] |
| Regressões zero | Se você precisar reenviar seu aplicativo para validação, a funcionalidade de extensão de mensagem existente que estava funcionando anteriormente não deverá ser interrompida. Esse requisito só é aplicável a aplicativos ISV (fornecedor de software) independentes e não a aplicativos criados para sua organização. [Obrigatório] |
| SSO (logon único) | Se aplicável, atualize seu registro de aplicativo Microsoft Entra ID para SSO. [Recomendado] |
| Política de Segurança de Conteúdo | Se aplicável, modifique os cabeçalhos da Política de Segurança de Conteúdo. [Recomendado] |
Importante
Se aplicável, atualize os cabeçalhos da Política de Segurança de Conteúdo e X-Frame-Options , de acordo com Configurar cabeçalhos da Política de Segurança de Conteúdo.
Exemplos de código
| Nome do exemplo | Descrição | TypeScript |
|---|---|---|
| Extensão de mensagem de inventário northwind | Este exemplo demonstra como usar uma extensão de mensagem do Teams como um plug-in no Microsoft Copilot para Microsoft 365. | Exibir |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de