Diretrizes para criar e atualizar agentes copilot
Importante
- Os plug-ins para Microsoft 365 Copilot estão em pré-visualização e só funcionam no Microsoft 365 Copilot.
- Os plug-ins de extensão de mensagens estão em pré-visualização.
- Os plug-ins de extensões de mensagens no Microsoft 365 Copilot estão em pré-visualização pública para o Microsoft Word e o PowerPoint.
- Certifique-se de que Microsoft 365 Copilot está disponível para a sua organização. Tem duas formas de obter um ambiente de programador para Microsoft 365 Copilot:
- Um inquilino do Microsoft 365 de sandbox com Microsoft 365 Copilot (disponível em pré-visualização limitada através da associação TAP).
- Um ambiente de produção de clientes empresariais com licenças de Microsoft 365 Copilot. Para obter mais informações sobre as diretrizes de validação dos agentes copilot para aumentar a probabilidade de serem listados na Loja de Equipas, veja diretrizes de validação para agentes Copilot.
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 Microsoft 365 Copilot interagir com APIs de outro software e serviços através de um bot. Com Microsoft 365 Copilot, 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 Microsoft 365 Copilot. As extensões de mensagens têm de suportar um ou mais comandos de pesquisa. Uma vez que Microsoft 365 Copilot os reconhece como competências, pode executar comandos em nome do utilizador.
Definir descrições de aplicações, comandos e parâmetros
[Tem de corrigir]
Uma boa descrição oferece um resumo claro e conciso das funcionalidades da aplicação e permite que Microsoft 365 Copilot 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 da mensagem tem de ser invocado a partir de Microsoft 365 Copilot.
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 Microsoft 365 Copilot, 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 da mensagem no Microsoft 365 Copilot. Por exemplo, utilize a cloud da Contoso no Microsoft 365 Copilot 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.
Os fragmentos de código seguintes mostram 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
[Boa solução]
A propriedade semanticDescription é utilizada para fornecer uma descrição detalhada de um comando para Microsoft 365 Copilot. 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, Microsoft 365 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 .
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.
Os fragmentos de código seguintes mostram 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"
],
Importante
Para ativar a ligação de início de sessão do OAuth no plug-in, certifique-se de que define a initialRun propriedade para true para comandos de pesquisa no manifesto da aplicação.
Descrição do parâmetro
Cada comando de extensão de mensagem tem uma propriedade correspondente parameters , que suporta até cinco parâmetros. 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 Microsoft 365 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, Microsoft 365 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"
}]
Melhorar a extensão de mensagem para obter informações através de expressões compostas
[Tem de corrigir]
Observação
A caixa de diálogo De pesquisa (referida como módulo de tarefas no TeamsJS v1.x) não é suportada no Microsoft 365 Copilot.
Para Microsoft 365 Copilot, 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 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.
Microsoft 365 Copilot podem transmitir uma cadeia vazia ou um valor nulo para parâmetros, que não fazem parte da expressão do utilizador. Atualize 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 a descrição do parâmetro.
Definir pedidos de exemplo
[Tem de corrigir]
A samplePrompts propriedade orienta os utilizadores sobre como utilizar os vários plug-ins no Microsoft 365 Copilot. Microsoft 365 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 para a Experiência de Primeira Execução (FRE) no Microsoft 365 Copilot quando um utilizador instala ou ativa pela primeira vez um plug-in.
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.
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"
}
]
}
]
}
]
Criar respostas de Cartões Ajustáveis avançadas
[Tem de corrigir]
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 pré-visualizar card informações como parte do mesmo modelo. [Tem de corrigir]
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}" } } }Observação
Tipos de
imBackação emessageBacknã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 card. -
Action.ToggleVisibility: apresenta ou oculta um ou mais elementos no card. -
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 as informações no card através de uma caixa de diálogo, Deteção de Etapas ou diretamente a partir do card, recomendamos que o Cartão Adaptá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]
Plug-ins de extensão de mensagens em aplicações Microsoft 365 Copilot
[Tem de corrigir]
Importante
Os plug-ins de extensão de mensagens nas aplicações Microsoft 365 Copilot estão em pré-visualização privada limitada para Word e PowerPoint. Mais detalhes a publicar após o anúncio de uma pré-visualização pública.
Os agentes da Copilot personalizam e expandem a experiência de Microsoft 365 Copilot ao trazer mais competências e conhecimentos para Microsoft 365 Copilot para uma experiência de utilizador personalizada. Ao utilizar plug-ins, que são um subconjunto de agentes copilot, os utilizadores podem integrar capacidades adicionais no Microsoft 365 Copilot ao interagir com aplicações de terceiros, seja para obter ou modificar informações nessas aplicações. Por exemplo, os plug-ins de extensão de mensagens facilitam a pesquisa de dados noutras aplicações para que Microsoft 365 Copilot possam apresentá-lo a pedido quando o plug-in é ativado.
Se desenvolveu um plug-in para Microsoft 365 Copilot no Teams ou copilot.microsoft.com, já tem conhecimento dos benefícios que oferece aos utilizadores no fluxo de trabalho.
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 Microsoft 365 Copilot. | Exibir |