Diretrizes para criar ou atualizar extensões do Copilot
Importante
- Os plug-ins do Microsoft Copilot para Microsoft 365 estão em pré-visualização e só funcionam no Chat do Microsoft 365 no Microsoft Teams.
- Certifique-se de que o Copilot para Microsoft 365 está disponível para a sua organização. Tem duas formas de obter um ambiente de programador para o Copilot:
- Um inquilino do Microsoft 365 de sandbox com o Copilot (disponível em pré-visualização limitada através da associação tap).
- Um ambiente de produção de clientes empresariais com o Microsoft Copilot para licenças do Microsoft 365.
Os plug-ins do Microsoft 365 fornecem integração com vários produtos do Microsoft 365, como o Teams e o Outlook. A integração ajuda os utilizadores a procurar ou criar conteúdos em sistemas externos. Os plug-ins de extensão de mensagens permitem que o Microsoft Copilot para Microsoft 365 interaja com APIs de outro software e serviços através de um bot. Com o Copilot para Microsoft 365, pode:
- Procure as informações ou registos mais recentes. Por exemplo, os resultados mais recentes do pedido de incidente ou do inquérito.
- Resumir informações com base em vários registos. Por exemplo, resuma todos os pedidos de incidente relacionados com o projeto Northwind.
Recomendamos que crie ou atualize as extensões de mensagens existentes para maximizar a sua utilidade e capacidade de utilização no Copilot para Microsoft 365. As extensões de mensagens têm de suportar um ou mais comandos de pesquisa, uma vez que o Copilot para Microsoft 365 os reconhece como competências que pode executar em nome do utilizador. Além disso, as suas extensões têm de cumprir as normas de conformidade, desempenho, segurança e experiência de utilizador descritas neste artigo.
Observação
Se quiser configurar um conector personalizado do Graph para o Copilot para o Microsoft 365, certifique-se de que cumpre as diretrizes para criar ou atualizar conectores do Graph.
Requisitos obrigatórios
Os requisitos para criar plug-ins de extensão de mensagens para o Copilot para o Microsoft 365 incluem:
Definir descrições
Uma boa descrição oferece um resumo claro e conciso das funcionalidades da aplicação e permite que o Copilot para Microsoft 365 descubra e execute operações de pesquisa de forma eficiente. Quando um utilizador introduz o nome da aplicação juntamente com um verbo, por exemplo, Localizar permissões da Contoso, o plug-in da extensão de mensagem tem de ser invocado a partir do Copilot para Microsoft 365.
Certifique-se de que cumpre as diretrizes de descrição listadas na tabela seguinte:
| Ação | Reason |
|---|---|
|
Anti-Compete: evite utilizar o nome de qualquer outro plug-in em descrições curtas e longas. |
|
|
IA Responsável: evite utilizar palavras-chave inadequadas ou ofensivas. |
|
|
Injeções de pedidos: certifique-se de que as descrições não orientam o Copilot para efetuar ações que ignorem o funcionamento normal da aplicação. Além disso, a descrição não pode conter símbolos ou texto que indiquem que pode ser utilizado como código para injeção de pedidos. Evite utilizar expressões, funções e código que chamem uma aplicação em simultâneo. |
Descrição do aplicativo
As descrições de aplicações longas e curtas têm de ser claras e definir o âmbito da aplicação. Para compor uma aplicação como um plug-in no Copilot para Microsoft 365, modifique a descrição da aplicação de acordo com os seguintes requisitos de plug-in:
- A descrição longa tem de explicar claramente a funcionalidade e a utilização do plug-in da extensão de mensagens no Copilot para o Microsoft 365. Por exemplo, utilize a cloud da Contoso no Copilot para Microsoft 365 para procurar e resumir as suas tarefas.
- A breve descrição tem de descrever brevemente a funcionalidade da aplicação numa linguagem natural e pode incluir o nome da aplicação.
A tabela seguinte lista os breves exemplos de descrição para cada categoria:
Descrição: crie, pesquise, veja pedidos de suporte, erros e projetos.
Exemplo de descrição da aplicação:
{
"$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 de pesquisa
A descrição do comando mapeia a intenção e a expressão do utilizador para o comando de pesquisa dentro de um plug-in e tem de ser criada com base na análise da intenção do utilizador e das palavras-chave. As descrições dos comandos de pesquisa têm de:
- Concentre-se no que e como o comando procura (lista detalhada) em linguagem natural.
- Inclua verbos e sinónimos, se aplicável.
- Concentre-se em palavras-chave que provavelmente serão utilizadas na função de pesquisa das suas aplicações nativas.
Descrição semântica
A propriedade semanticDescription é utilizada para fornecer uma descrição detalhada de um comando para Copilot para Microsoft 365. A descrição semântica para comandos suporta até 5000 carateres e não é apresentada na interface de utilizador. Se a semanticDescription propriedade for deixada vazia, Copilot para Microsoft 365 utiliza as informações no description campo. Ao escrever um semanticDescription, tem de incluir informações sobre valores, limites e intervalos esperados para o comando .
A semanticDescription propriedade não é um campo obrigatório. No entanto, se adicionar semanticDescription um manifesto de aplicação, as verificações de validação existentes para descrições curtas, de parâmetros e de comandos também são aplicáveis para descrições semânticas.
Recomendamos que reveja as seguintes diretrizes para a descrição semântica para aumentar as hipóteses de a sua aplicação passar no processo de submissão da Microsoft Teams Store:
- Evite expressões instrutivas como "se o utilizador disser X", "ignorar", "eliminar", "repor", "novas instruções", "Responder a Negrito" ou "Não imprimir nada". [Correção obrigatória]
- Evite URLs, emojis ou carateres ocultos, como símbolos hexadecimais, 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 afirmações superlativas como "#1", "incrível" ou "melhor". [Correção sugerida]
A tabela seguinte lista os exemplos de descrição semântica e de comando para cada categoria:
Descrição: procure tarefas de alta prioridade relacionadas com a Northwind que serão concluídas amanhã.
Exemplo de descrição do 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 suportado tem uma propriedade "parâmetros" correspondente, que suporta até cinco parâmetros e o primeiro parâmetro tem de estar visível na barra de pesquisa da extensão de mensagem. Um parâmetro tem de ter uma boa descrição, que tem de conter uma combinação de parâmetros aceitáveis, enumerações, acrónimos e formato de saída.
A propriedade semanticDescription é utilizada para fornecer uma descrição detalhada de um comando para o Microsoft Copilot. A descrição semântica para parâmetros suporta até 2000 carateres e não é apresentada na interface de utilizador. Se a semanticDescription propriedade for deixada vazia, Copilot utiliza as informações no description campo. Ao escrever um semanticDescription, tem de incluir informações sobre valores, limites e intervalos esperados para o comando .
Uma boa descrição do parâmetro explica os requisitos do sistema numa linguagem natural com formato de saída. Seguem-se alguns exemplos de pedidos de pesquisa básicos e avançados para cada categoria:
Pesquisa básica: procure tarefas relacionadas com a Northwind. Pesquisa avançada: procure tarefas de alta prioridade relacionadas com a Northwind que serão concluídas 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"
}]
Expressões compostas
Observação
A caixa de diálogo De pesquisa (referida como módulo de tarefas no TeamsJS v1.x) não é suportada no Copilot para Microsoft 365.
Para o Copilot para o Microsoft 365, uma extensão de mensagem baseada em pesquisa tem de suportar mais de três expressões compostas exclusivas para efetuar a obtenção aprofundada de informações precisas. Para ativar expressões compostas, tem de expandir o âmbito da pesquisa para processar três ou mais parâmetros de pesquisa ao atualizar o manifesto da aplicação (anteriormente denominado manifesto da aplicação Teams) e garantir o seguinte:
Atualize o serviço Web para suportar a pesquisa com base em vários parâmetros. Para obter mais informações sobre como responder a pedidos de utilizador, veja Responder ao comando de pesquisa.
O Copilot para o Microsoft 365 pode transmitir uma cadeia vazia ou um valor nulo para parâmetros, que não fazem parte da expressão do utilizador, atualizar o serviço Web para processar os parâmetros.
Uma extensão de mensagem suporta até 10 comandos (9 utilizáveis) e cada comando tem uma propriedade correspondente
parameters, que suporta até cinco parâmetros.
O código seguinte é um exemplo de vários parâmetros definidos no manifesto da aplicação:
"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 têm de ter boas descrições com parâmetros aceitáveis, enumerações, acrónimos e formato de saída. Para obter mais informações e exemplos, veja Descrição do parâmetro.
Pedidos de exemplo
A samplePrompts propriedade orienta os utilizadores sobre como utilizar os vários plug-ins no Copilot. O Copilot utiliza os pedidos de exemplo para apresentar os pedidos do utilizador. As linhas de comandos têm de ser adaptáveis a diferentes regiões e desmarcadas em diferentes comandos. Os pedidos de exemplo estão disponíveis nas seguintes áreas no Copilot para Microsoft 365:
- Experiência de Primeira Execução (FRE): quando um utilizador instala ou ativa um plug-in pela primeira vez.
- Biblioteca de pedidos ou Laboratório Copilot: quando um utilizador procura ajuda com pedidos.
- Sugestões de plug-in: para orientar os utilizadores para melhores expressões.
Observação
- Se o manifesto da aplicação não especificar a
samplePromptspropriedade, os pedidos não são apresentados. - A
samplePromptspropriedade é obrigatória para a validação da aplicação durante o processo de submissão da aplicação. - Se definir vários comandos para a sua aplicação, são apresentadas ao utilizador um máximo de três pedidos (um de cada um dos três comandos principais). Os pedidos giram para fornecer ao utilizador um conjunto diversificado de pedidos em diferentes comandos.
Recomendamos que siga estas diretrizes para aumentar as hipóteses de a sua aplicação passar no processo de submissão da Microsoft Teams Store:
- Um plug-in tem de ter, pelo menos, três linhas de comandos e um máximo de cinco pedidos para cada comando.
- Cada pedido não pode exceder 128 carateres.
- Dois comandos no mesmo plug-in não podem ter pedidos idênticos.
- Os pedidos de exemplo têm de ser genéricos por natureza e não incluir referências personalizadas. Por exemplo, nomes de projeto e nome da tarefa.
- Todos os pedidos de exemplo têm de ser funcionais e devolver respostas.
- A linha de comandos tem de ser relevante para os comandos.
O código seguinte é um exemplo da propriedade no manifesto da samplePrompts aplicação:
"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 Ajustável
As extensões de mensagens respondem a uma entrada de utilizador com um Cartão Ajustável. Um Cartão Ajustável para um plug-in de extensão de mensagem tem de funcionar eficazmente, parecer formatado e cumprir os seguintes requisitos:
A resposta do Cartão Ajustável tem de incluir conteúdo de Cartão Ajustável e informações do cartão de pré-visualização como parte do mesmo modelo. [Obrigatório]
Exemplo de modelo de resposta de Cartão Ajustá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}" } } }Para além do logótipo da aplicação, do título, da miniatura e do título das informações, os dados no Cartão Adaptável têm de representar, pelo menos, duas informações. Pode identificar os campos dos atributos mais frequentemente pesquisados, como, por exemplo, dados modificados, autor, estado e sinalizadores. [Obrigatório]
O Cartão Adaptável tem de ser apresentável no ambiente de trabalho, na Web e no dispositivo móvel (iOS e Android). [Obrigatório]
Um Cartão Ajustável tem de conter, pelo menos, um botão de ação, mas não mais do que quatro botões de ação. [Obrigatório]
Observação
Os tipos de
imBackação ,messageBacknão são suportados num objeto de dados.São recomendados os seguintes tipos de ação:
Action.OpenUrl: abre um URL especificado a partir do Cartão.Action.ToggleVisibility: apresenta ou oculta um ou mais elementos no cartão.Action.Execute: recolhe os campos de entrada e envia-os como um pedido para o serviço de bot.Action.Submit: abre uma caixa de diálogo ou o Stageview com o tipo invocar no objeto de dados.
Se um utilizador puder alterar qualquer informação no cartão através da caixa de diálogo, Descrição geral ou diretamente a partir do cartão, recomendamos que o Cartão Ajustável suporte ações universais e atualização automática. [Recomendado]
Os Cartões Ajustáveis têm de incluir um URL como parte dos metadados, o que permite que os cartões sejam facilmente copiados de um hub para outro. [Recomendado]
Para além das miniaturas, qualquer imagem num Cartão Ajustável tem de ter um texto alternativo. [Recomendado]
Requisitos técnicos
Para que um plug-in seja validado, invocado e funcione de forma totalmente integrada, certifique-se de que cumpre os seguintes critérios:
| Critérios | Cumprimento |
|---|---|
| Versão do manifesto | A versão do manifesto da aplicação tem de ser a 1.13 ou posterior. [Obrigatório] |
| Canal do Microsoft 365 | Para que os utilizadores interajam com a sua extensão de mensagem a partir do Outlook, tem de adicionar o canal do Microsoft 365 ao seu bot. Para obter mais informações, consulte Adicionar canal do Microsoft 365. [Obrigatório] |
| Tempo de Resposta | O tempo de resposta não pode exceder 9 segundos para 99 por cento, 5 Segundos para 75% e 2 Segundos para 50 por cento. [Obrigatório] |
| Confiabilidade | As aplicações têm de manter 99,9% de disponibilidade. Por exemplo, se o Chat do Microsoft 365 chamar um plug-in 1000 vezes, terá de fornecer uma resposta significativa 999 vezes. [Obrigatório] |
| Zero Regressões | Se precisar de submeter novamente a sua aplicação para validação, a funcionalidade de extensão de mensagem existente que estava a funcionar anteriormente não pode ser interrupda. Este requisito só é aplicável a aplicações independentes de fornecedores de software (ISV) e não a aplicações criadas para a sua organização. [Obrigatório] |
| SSO (logon único) | Se aplicável, atualize o registo da aplicação 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 os cabeçalhos Configurar 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 da Northwind | Este exemplo demonstra como utilizar 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