Os agentes são aplicativos para o Microsoft 365

Ao criar um agente, você também está criando um aplicativo para o Microsoft 365. As aplicações para o Microsoft 365 partilham um esquema de manifesto comum e formato de empacotamento, bem como processos e ferramentas de gestão e distribuição unificados. O resultado final é que seus aplicativos e agentes atinjam o público mais amplo possível e apareçam contextualmente no fluxo de trabalho de seus usuários.

Este artigo descreve as principais partes do modelo de aplicativo do Microsoft 365 que se aplicam ao desenvolvimento de agentes.

Importante

  • Atualmente, os plug-ins de API só são suportados como ações em agentes declarativos. Eles não estão habilitados no Microsoft 365 Copilot. Para obter um exemplo que mostra como adicionar um plug-in de API a um agente declarativo, consulte Adicionar um plug-in de API como uma ação personalizada ao agente.
  • A funcionalidade está habilitada por padrão em todos os locatários licenciados pelo Microsoft 365 Copilot. Os administradores podem desabilitar essa funcionalidade em uma base de usuário e grupo e controlar como os plug-ins individuais são aprovados para uso e quais plug-ins são habilitados. Para obter mais informações, consulte Gerenciar agentes em aplicativos integrados.

Pacote do aplicativo

O pacote do aplicativo para Microsoft 365, incluindo agentes, é um arquivo zip que contém um ou mais arquivos de configuração (manifesto) e seus ícones de aplicativo. A lógica do aplicativo e o armazenamento de dados são hospedados em outro lugar e acessados pelo aplicativo host do Microsoft 365 via HTTPS. Você enviará o pacote do aplicativo ao administrador para publicar na sua organização ou ao Partner Center para publicar no Microsoft AppSource.

No mínimo, um pacote de aplicativo contém:

  • O manifesto do aplicativo (manifest.json), que descreve a configuração do aplicativo, os recursos, os recursos necessários e os atributos importantes
  • Um ícone colorido grande (color.png), um ícone colorido de 192x192 para exibir seu agente na interface do usuário e na loja do Microsoft 365 Copilot
  • Um pequeno ícone de estrutura de tópicos (outline.png), um ícone 32x32 com fundo transparente (não usado atualmente no Copilot, mas necessário para passar na validação)

O pacote do aplicativo também pode conter definições de agente declarativo e plug-in de API, bem como arquivos de localização para outros idiomas com suporte.

Diagrama mostrando a anatomia de um pacote do aplicativo Microsoft 365: manifesto do aplicativo (arquivo .json) + ícones (arquivos .png de cores e contornos) encapsulados em um arquivo .zip

Ícones do aplicativo

O pacote do aplicativo deve incluir uma versão colorida e de estrutura de tópicos do ícone do aplicativo, como arquivos .png. Esses ícones têm requisitos de tamanho específicos para passar na validação da loja.

Observação

Atualmente, apenas o ícone de cor é usado para representar agentes para os usuários (tanto na listagem da Store quanto na interface do usuário do Microsoft 365 Copilot), mas um ícone de estrutura de tópicos ainda é necessário quando você envia o pacote do aplicativo para o Microsoft AppSource.

Para obter diretrizes detalhadas de design para ícones de cores e contornos para o pacote de aplicativos do Microsoft 365, consulte Ícones de design para aquisição e gerenciamento de agentes.

Ícone de cor

O ícone de cor representa seu agente na interface do usuário do Microsoft 365 Copilot e nas lojas de aplicativos no produto (Teams, Office, Outlook, Microsoft 365).

Imagem de exemplo de um ícone de cor de aplicativo, mostrando 192x192 pixels como tamanho total do ícone com o plano de fundo incluído, com um espaço central de 120x120 pixels mostrando a

Seu ícone de cor:

  • Pode ser de qualquer cor
  • Deve ter uma resolução de 192 x 192 pixels
  • Deve conter um símbolo dentro de 120 x 120 pixels (para permitir 36 pixels de preenchimento para cenários de host onde ele é cortado)
  • Deve estar sobre um fundo quadrado totalmente sólido ou totalmente transparente

Ícone de contorno

O ícone de estrutura de tópicos é usado para representar aplicativos fixados e/ou ativos na barra de aplicativos do Teams. No momento, ele não é usado para agentes, mas ainda é necessário para que o pacote do aplicativo passe na validação.

Imagem de exemplo de um ícone de contorno de aplicativo, mostrando o tamanho de 32x32 pixels e o contorno do ícone branco com fundo transparente

Seu ícone de estrutura de tópicos:

  • Deve ter 32 x 32 pixels
  • Deve ser branco com um fundo transparente ou transparente com um fundo branco
  • Não deve conter preenchimento adicional ao redor do símbolo

Manifesto do aplicativo

O manifesto do aplicativo para Microsoft 365 é um arquivo JSON que descreve a funcionalidade e as características do seu aplicativo. Em sua essência, o manifesto do aplicativo para Microsoft 365 é o esquema para criar aplicativos do Teams; no entanto, a partir da versão 1.13, ele oferece suporte a aplicativos executados em hosts Microsoft 365, além do Teams.

Se você estiver usando o Copilot Studio para criar um agente declarativo, o manifesto do aplicativo será gerado para você com base nas informações fornecidas durante o processo de criação.

Todo manifesto do aplicativo deve incluir os campos a seguir.

Campo de manifesto Descrição
version O número da versão do aplicativo, no formato MAJOR. MENOR. PATCH (semver standard).
id O identificador exclusivo deste aplicativo, no formato GUID.
Desenvolvedor Informações sobre o desenvolvedor, incluindo nome, site e links para a política de privacidade e os termos de uso. Para aplicativos enviados ao AppSource, os valores devem corresponder ao valor fornecido no formulário de envio de aplicativo do Partner Center.
name O nome do seu aplicativo, conforme exibido para os usuários finais no host do aplicativo.
description Descrições curtas e longas do seu aplicativo para usuários. Para aplicativos enviados ao AppSource, esses valores devem corresponder às informações na entrada do AppSource.
Ícones Caminhos relativos para arquivos de ícones de cor e contorno.
accentColor Uma cor a ser usada com e como plano de fundo para seus ícones de contorno, em valor hexadecimal RGB, por exemplo #4464ee.
Definições para recursos específicos do aplicativo Uma definição para cada funcionalidade do aplicativo, como guias pessoais (staticTabs), extensões de mensagem (composeExtensions) ou bots. Agentes declarativos e plug-ins de API são definidos no nó copilotAgents .

O exemplo a seguir mostra um manifesto do aplicativo com seções de espaço reservado no final para extensão de mensagem e recursos do aplicativo de agente declarativo.

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.18/MicrosoftTeams.schema.json",
    "manifestVersion": "1.18",
    "version": "1.0.0",
    "id": "00000000-0000-0000-0000-000000000000",
    "developer": {
        "name": "Northwind Traders",
        "websiteUrl": "https://www.example.com",
        "privacyUrl": "https://www.example.com/privacy",
        "termsOfUseUrl": "https://www.example.com/termsofuse"
    },
    "icons": {
        "color": "Northwind-Logo-196.png",
        "outline": "Northwind-Logo-32.png"
    },
    "name": {
        "short": "Northwind Inventory",
        "full": "Northwind Inventory App"
    },
    "description": {
        "short": "App allows you to find and update product inventory information",
        "full": "Northwind Inventory is the ultimate tool for managing your product inventory. With its intuitive interface and powerful features, you'll be able to easily find your products by name, category, inventory status, and supplier city. You can also update inventory information with the app."
    },
    "accentColor": "#3690E9",
    "composeExtensions": {
        ...
    },
    "copilotAgents": {
        ...
    }
}

Para saber mais, consulte a referência do manifesto do aplicativo Microsoft 365.

copilotAgents definições

Os agentes declarativos e os plug-ins de API têm seus próprios esquemas de definição. O arquivo de definição para um agente declarativo é referenciado do objeto copilotAgents do manifesto do aplicativo.

O exemplo a seguir mostra como fazer referência a um agente declarativo:

    "copilotAgents": {
        "declarativeAgents": [
            {
                "id": "agent1",
                "file": "declarativeAgent1.json"
            }
        ]
    },

A definição de um plug-in de API é referenciada (em actions) a partir da definição de agente declarativo.

Diagrama mostrando o manifesto do aplicativo fazendo referência a um manifesto de agente declarativo e um manifesto de plug-in de API. O manifesto do agente declarativo faz referência a outro manifesto de plug-in de API

Observe o seguinte:

  • Atualmente, há suporte apenas para uma definição de agente declarativo por manifesto de aplicativo.

  • Quando você usa o Copilot Studio para criar agentes, um exclusivo id é gerado para cada um, como parte da geração geral do manifesto do aplicativo. Ao criar agentes com o Microsoft 365 Agents Toolkit ou seu próprio IDE, você atribui o id a si mesmo, de acordo com suas próprias convenções ou nome amigável.

Manifesto do agente declarativo

O manifesto do agente declarativo inclui instruções para respostas do Copilot, prompts de exemplo de início de conversa, fontes de dados usadas para fundamentação e uma lista de ações (habilidades de plug-in de API) que o agente pode executar.

Para saber mais, confira Esquema de manifesto do agente declarativo para o Microsoft 365 Copilot.

Manifesto do plugin de API

O manifesto do plug-in da API descreve os recursos do plug-in, incluindo as APIs compatíveis e as operações que ele pode executar. Ele também inclui metadados como nome, descrição, versão e uma referência à definição de OpenAPI das APIs REST com as quais ele interage. Os plug-ins de API podem ser referenciados a partir de um manifesto de agente declarativo a ser usado na experiência do agente declarativo.

Para saber mais, consulte Esquema de manifesto de plug-in para o Microsoft 365 Copilot.

Conteúdo relacionado

  • Last updated on