Diretrizes para criar e atualizar agentes

Observação

Os agentes fornecem uma experiência mais flexível, inteligente e pronta para o futuro que permite um raciocínio mais avançado, um desenvolvimento mais simples e um melhor alinhamento com o Teams em evolução e a plataforma Microsoft 365. Recomendamos que você explore e crie agentes.

Para obter mais informações, confira Criar agentes declarativos e Criar agentes no Teams.

Se você tiver uma extensão de mensagem baseada em bot existente, também poderá estendê-la como um agente .

Importante

  • Os agentes do Microsoft 365 Copilot estão em versão prévia e funcionam apenas no Microsoft 365 Copilot.
  • Os agentes de extensão de mensagem estão em versão prévia.
  • Os agentes de extensões de mensagem no Microsoft 365 Copilot estão na visualização pública para o Microsoft Word e o PowerPoint.
  • Certifique-se de que o Microsoft 365 Copilot esteja disponível para sua organização. Você tem duas maneiras de obter um ambiente de desenvolvedor para o Microsoft 365 Copilot:
    • Um locatário de área restrita do Microsoft 365 com o Microsoft 365 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 do Microsoft 365 Copilot. Para obter mais informações sobre as diretrizes de validação para os agentes aumentarem suas chances de serem listados na Team Store, consulte as diretrizes de validação para agentes.

Os agentes 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 agentes de extensão de mensagem permitem que o Microsoft 365 Copilot interaja com APIs de outros softwares e serviços por meio de um bot. Com o Microsoft 365 Copilot, você pode:

  • Procure as informações ou registros mais recentes. Por exemplo, o último tíquete de incidente ou resultados de pesquisa.
  • Resumir informações com base em vários registros. Por exemplo, resuma 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 no Microsoft 365 Copilot. As extensões de mensagem devem dar suporte a um ou mais comandos de pesquisa. Como o Microsoft 365 Copilot as reconhece como habilidades, ele pode executar comandos em nome do usuário.

O gráfico mostra a experiência do usuário entre o Microsoft Teams e o Microsoft 365 Copilot.

Definir descrições de aplicativo, comando e parâmetro

[Deve corrigir]

Uma boa descrição oferece um resumo claro e conciso dos recursos do aplicativo e permite que o Microsoft 365 Copilot 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, Encontrar tíquetes da Contoso, o agente de extensão de mensagem deve ser invocado no Microsoft 365 Copilot.

A captura de tela mostra um cenário aprovado com um exemplo de um prompt de exemplo para o agente de extensão de mensagem no Microsoft 365 Copilot.

A captura de tela mostra um cenário de falha sem um exemplo de prompt de exemplo para extensão de mensagem como um agente no Microsoft 365 Copilot.

Descrição do aplicativo

Descrições longas e curtas de aplicativos devem ser claras e definir o escopo do aplicativo. Para renderizar um aplicativo como agente no Microsoft 365 Copilot, modifique a descrição do aplicativo para atender aos seguintes requisitos de agente:

  • Uma descrição longa deve explicar claramente a funcionalidade e o uso do agente de extensão de mensagem no Microsoft 365 Copilot. Por exemplo, use a nuvem da Contoso no Microsoft 365 Copilot para pesquisar e resumir suas tarefas.
  • Uma breve descrição deve descrever brevemente a funcionalidade do aplicativo em um idioma natural e pode incluir o nome do aplicativo.

Os snippets de código a seguir mostram os exemplos de descrição resumida para cada categoria:

Descrição: crie, pesquise, visualize 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 de pesquisa

A descrição do comando mapeia a intenção e o enunciado do usuário para pesquisar o comando dentro de um agente e deve ser criado com base na análise da intenção do usuário e das palavras-chave. As descrições de comando de pesquisa devem:

  • Concentre-se no que e como o comando pesquisa (lista detalhada) em linguagem natural.
  • Inclua verbos e sinônimos, se aplicável.
  • Concentre-se nas palavras-chave que provavelmente serão usadas na função de pesquisa de seus aplicativos nativos.

Descrição semântica

[Bom para consertar]

A propriedade semanticDescription é usada para fornecer uma descrição detalhada de um comando para o Microsoft 365 Copilot. A descrição semântica dos comandos suporta até 5.000 caracteres e não é exibida na interface do usuário. Se a propriedade for deixada vazia, o semanticDescription Microsoft 365 Copilot usará as description informações no 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 o 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.

Os snippets de código a seguir mostram os exemplos de descrição semântica e de comando para cada categoria:

Descrição: Pesquise tarefas de alta prioridade relacionadas a Northwind que vencem 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"
          ],

Importante

Para ativar o link de entrada OAuth no agente, certifique-se de definir a initialRun propriedade como true para comandos de pesquisa no manifesto do aplicativo.

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 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 365 Copilot. A descrição semântica dos parâmetros dá suporte a até 2.000 caracteres e não é exibida na interface do usuário. Se a propriedade for deixada vazia, o semanticDescription Microsoft 365 Copilot usará as description informações no campo. Ao escrever um semanticDescription, você deve incluir informações sobre valores, limites e intervalos esperados para o comando.

Uma boa descrição de 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: pesquise tarefas relacionadas ao Northwind.
  • Pesquisa avançada: Pesquise tarefas de alta prioridade relacionadas à Northwind que vencem amanhã.

Exemplo de descrição de 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"
    }]

Estas são as práticas recomendadas que você pode adaptar ao definir os parâmetros:

  • Os parâmetros devem ser claramente definidos para garantir respostas precisas dos agentes. O Copilot usa essas descrições para selecionar o melhor comando e prever valores de parâmetro com base na consulta do usuário.
  • A descrição do parâmetro não deve conter erros gramaticais e de pontuação.
  • Os parâmetros definidos no manifesto não devem ser idênticos.

Aprimorar a extensão da mensagem para recuperar informações por meio de enunciados compostos

Observação

A pesquisa por meio da caixa de diálogo (referida como módulo de tarefa no TeamsJS v1.x) não tem suporte no Microsoft 365 Copilot.

Para o Microsoft 365 Copilot, 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 atualizando o [manifesto do aplicativo (anteriormente chamado de manifesto do aplicativo do Teams)]/microsoft-365/extensibility/schema/#composeextensionscommands) 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.

  • O Microsoft 365 Copilot 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 parameters , que dá suporte a até cinco 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"
                        }
                    ]
                }
            ]

A captura de tela mostra um exemplo de um cenário de passagem em que o aplicativo Northwind retorna uma resposta para parâmetros de frutos do mar e em estoque.

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 a descrição do parâmetro.

Definir prompts de exemplo

[Deve corrigir]

A samplePrompts propriedade orienta os usuários sobre como usar os vários agentes no Microsoft 365 Copilot. O Microsoft 365 Copilot usa os prompts de exemplo para exibir os prompts para o usuário. Os prompts devem ser adaptáveis a diferentes localidades e claros em diferentes comandos. Os prompts de exemplo estão disponíveis para a OOBE (FRE) no Microsoft 365 Copilot quando um usuário instala ou habilita um agente pela primeira vez.

A captura de tela mostra os prompts de exemplo exibidos quando o agente de extensão de mensagem está habilitado no Microsoft 365 Copilot.

Observação

  • Se o manifesto do aplicativo não especificar a samplePrompts propriedade, os prompts não serão exibidos.
  • A samplePrompts propriedade é obrigatória para a validação do aplicativo durante o processo de envio do aplicativo.
  • Se você definir vários comandos para seu aplicativo, no máximo três prompts (um de cada um dos três principais comandos) serão exibidos para o usuário. Os prompts são girados para fornecer ao usuário um conjunto diversificado de prompts em diferentes comandos.

O código a seguir é um exemplo da propriedade no manifesto samplePrompts do 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"
     }
    ]
   }
  ]
 }
]

Criar respostas avançadas do Cartão Adaptável

[Deve corrigir]

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 agente de extensão de mensagem deve funcionar efetivamente, parecer avançado e atender aos seguintes requisitos:

  • A resposta do Cartão Adaptável deve incluir o conteúdo do Cartão Adaptável e informações do card de visualização como parte do mesmo modelo. [Deve corrigir]

    A captura de tela mostra um exemplo de um aplicativo de exemplo mostrando que a resposta do aplicativo Microsoft 365 Copilot contém visualização e conteúdo na mesma resposta.


    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}"
      }
    }
  }

    Observação

    Tipos imBack de ação e messageBack nã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 card.
    • Action.ToggleVisibility: exibe ou oculta um ou mais elementos no card.
    • Action.Execute: coleta os campos de entrada e os envia como uma solicitação ao serviço de bot.
    • Action.Submit: Abre uma caixa de diálogo ou Stageview usando a invocação de tipo no objeto de dados.

    O gráfico mostra um exemplo dos botões de ação Atualizar Estoque, reabastecer e Cancelar reabastecimento em uma resposta do Cartão Adaptável no Microsoft 365 Copilot.

  • Se um usuário puder alterar as informações no card por meio de uma caixa de diálogo, do Stageview ou diretamente do card, recomendamos que o Cartão Adaptável dê 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 texto alt. [Recomendado]

Agentes de extensão de mensagem em aplicativos do Microsoft 365 Copilot

[Deve corrigir]

Os agentes personalizam e ampliam a experiência do Microsoft 365 Copilot trazendo mais habilidades e conhecimentos para o Microsoft 365 Copilot para uma experiência de usuário personalizada. Ao usar agentes, que são um subconjunto de agentes, os usuários podem integrar recursos adicionais ao Microsoft 365 Copilot interagindo com aplicativos de terceiros, seja para recuperar ou modificar informações nesses aplicativos. Por exemplo, os agentes de extensão de mensagem facilitam a pesquisa de dados em outros aplicativos para que o Microsoft 365 Copilot possa apresentá-los mediante solicitação quando o agente for ativado.

Se você desenvolveu um agente para Microsoft 365 Copilot no Teams ou no copilot.microsoft.com, já está ciente dos benefícios que ele oferece aos usuários em seu fluxo de trabalho.

Exemplos de código

Nome do exemplo Descrição TypeScript
Extensão de mensagem de inventário Northwind Este exemplo implementa uma extensão de mensagem do Teams que pode ser usada como um plug-in para o Microsoft 365 Copilot. A extensão de mensagem permite que os usuários consultem o banco de dados Northwind. Exibir

Confira também

  • Last updated on