Os agentes copilot são aplicações para o Microsoft 365

Artigo
10/22/2024

Importante

Atualmente, os plug-ins de API só são suportados como ações dentro de agentes declarativos. Não estão ativados no Microsoft 365 Copilot. Para obter um exemplo que mostra como adicionar um plug-in de API a um agente declarativo, veja Adicionar um plug-in.
A capacidade está ativada por predefinição em todos os inquilinos licenciados Microsoft 365 Copilot. Os administradores podem desativar esta funcionalidade numa base de utilizador e grupo e controlar a forma como os plug-ins individuais são aprovados para utilização e quais os plug-ins que estão ativados. Para obter mais informações, veja Manage Copilot agents in Integrated Apps (Gerir agentes copilot em Aplicações Integradas).

Quando cria um agente Copilot, também está a criar uma aplicação 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 as suas aplicações e agentes copilot atingem a audiência mais ampla possível e aparecem contextualmente no fluxo de trabalho dos seus utilizadores.

Este artigo explica-lhe as partes principais do modelo de aplicações do Microsoft 365 para desenvolvimento de agentes Copilot.

Modelo de aplicação para o Microsoft 365

O ecossistema do Microsoft 365 está a evoluir para uma plataforma de aplicações integrada, onde pode utilizar um modelo de aplicação comum para definir e empacotar a sua aplicação. O que começou como uma forma de expandir as aplicações do Teams a executar noutras aplicações do Microsoft 365 expandiu-se desde então para suportar a distribuição de conectores do Microsoft Graph, Suplementos do Outlook e agora agentes copilot.

Pacote do aplicativo

O pacote de aplicação para o Microsoft 365, incluindo agentes copilot, é um ficheiro zip que contém um ou mais ficheiros de configuração (manifesto) e os ícones da sua aplicação. A lógica da aplicação e o armazenamento de dados são alojados noutro local e acedidos pela aplicação anfitriã do Microsoft 365 através de HTTPS. Irá submeter o pacote de aplicação ao seu administrador para publicar na sua organização ou no Centro de Parceiros para publicar no Microsoft AppSource.

No mínimo, um pacote de aplicação contém:

o manifesto da aplicação (manifest.json), que descreve a configuração da aplicação, as capacidades, os recursos necessários e os atributos importantes,
um ícone de cor grande (color.png), um ícone de cor completa 92x92 para apresentar o agente no Microsoft Copilot IU e armazenar, e
um pequeno ícone de destaque (outline.png), um ícone 32x32 com fundo transparente (não atualmente utilizado no Copilot, mas necessário para passar a validação)

O pacote de aplicações também pode conter definições declarativas do agente e do plug-in da API, bem como ficheiros de localização para outros idiomas suportados.

Diagrama a mostrar a anatomia de um pacote de aplicações do Microsoft 365: manifesto de aplicação (ficheiro .json) + ícones (cor e destaque .png ficheiros) moldados num ficheiro de .zip

Ícones do aplicativo

O pacote de aplicação tem de incluir uma versão de cor e destaque do ícone da sua aplicação, como .png ficheiros. Estes ícones têm requisitos de tamanho específicos para passar a validação do arquivo.

Observação

Atualmente, apenas o ícone de cor é utilizado para representar agentes copilot para o utilizador final (tanto como a listagem da loja como dentro Microsoft 365 Copilot IU), mas ainda é necessário um ícone de destaque ao submeter o pacote de aplicações para o Microsoft AppSource.

Para obter mais orientações de conceção sobre ícones de cores e destaques para o pacote de aplicações do Microsoft 365, ícones de Aplicação para a Loja Teams e barra de aplicações.

Ícone de cor

O ícone de cor representa o seu agente nas lojas de aplicações Microsoft Copilot IU e no produto (Teams, Outlook, Microsoft 365).

O ícone de cor:

Pode ser qualquer cor
Tem de ter um total de 192 x 192 píxeis
Deve ter 96 x 96 píxeis para o símbolo em si (para permitir 48 píxeis de preenchimento para cenários anfitriões onde é recortado)
Tem de se sentar sobre um fundo quadrado totalmente sólido ou totalmente transparente

Ícone de contorno

O ícone de destaque é utilizado para representar aplicações afixadas e/ou ativas na barra de aplicações do Teams. Atualmente, não é utilizado para agentes copilot, mas ainda é necessário para que o pacote de aplicações passe na validação.

O ícone de destaque:

Tem de ter 32 x 32 píxeis
Tem de ser branco com um fundo transparente ou transparente com um fundo branco
Não pode conter preenchimento adicional à volta do símbolo

Manifesto do aplicativo

O manifesto da aplicação para o Microsoft 365 é um ficheiro JSON que descreve a funcionalidade e as características da sua aplicação. Na sua essência, o manifesto da aplicação para o Microsoft 365 é o esquema para criar aplicações do Teams, no entanto, desde então expandiu-se (desde a versão 1.13) para definir aplicações que são executadas em anfitriões do Microsoft 365, além do Teams.

Se estiver a utilizar Microsoft Copilot Studio para criar um agente declarativo, o manifesto da aplicação é gerado automaticamente com base nas informações que fornecer durante o processo de criação.

Cada manifesto de aplicação tem de incluir as seguintes informações:

Campo de manifesto	Descrição
version	O número da versão da aplicação, no formato MAJOR. MENOR. PATCH (semver standard).
id	O identificador gerado exclusivo para esta aplicação a partir do Portal de Registo de Aplicações da Microsoft (apps.dev.microsoft.com), no formato GUID.
programador	Informações sobre o programador, incluindo o nome, o site e as ligações para a política de privacidade e termos de utilização. Para aplicações submetidas para o AppSource, os valores têm de corresponder ao valor fornecido no formulário de submissão de aplicações do Centro de Parceiros.
name	O nome da sua aplicação, conforme apresentado aos utilizadores finais no anfitrião da aplicação.
description	Descrições curtas e longas da sua aplicação para utilizadores. Para aplicativos enviados ao AppSource, esses valores devem corresponder às informações na entrada do AppSource.
ícones	Caminhos relativos para ficheiros de ícones de cores e destaques.
accentColor	Uma cor a utilizar com e como fundo para os ícones de destaque, no valor hexadecimal RGB, por exemplo `#4464ee`.
Definições para capacidades de aplicações específicas	Uma definição para cada capacidade de aplicação, como separadores pessoais (staticTabs), extensões de mensagens (composeExtensions) ou bots. Os agentes declarativos e os plug-ins de API são definidos no nó copilotAgents .

O exemplo seguinte mostra um manifesto de aplicação com secções de marcador de posição no final para a extensão da mensagem e as capacidades da aplicação declarativa do agente:

{
    "$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/termofuse",
        "termsOfUseUrl": "https://www.example.com/privacy"
    },
    "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, veja Referência do esquema do manifesto da aplicação de pré-visualização do programador.

`copilotAgents` definições

Os agentes declarativos e os plug-ins de API têm cada um os seus próprios esquemas de definição. O ficheiro de definição de um agente declarativo é referenciado a copilotAgents partir do objeto do manifesto da aplicação.

O exemplo seguinte mostra como referenciar um agente declarativo:

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

A definição de um plug-in de API é referenciada a partir da definição do agente declarativo.

Diagrama a mostrar o manifesto da aplicação que referencia um manifesto de agente declarativo e um manifesto de plug-in da API. O manifesto do agente declarativo referencia outro manifesto de plug-in da API

Além disso, observe o seguinte:

Atualmente, só é suportada uma definição declarativa de agente por manifesto de aplicação. Apenas um plug-in de API é suportado por agente declarativo.
Quando utiliza Copilot Studio para criar agentes Copilot, é gerado um exclusivo id para cada um, como parte da geração geral de manifestos da aplicação. Ao criar agentes com o Teams Toolkit ou o seu próprio IDE, atribui-o a si próprio, de acordo com as id suas próprias convenções ou nome amigável.

Manifesto do agente declarativo

O manifesto do agente declarativo inclui instruções para respostas copilot, pedidos de exemplo de arranque de conversação, origens de dados utilizadas para a base e uma lista de ações (competências de plug-in da API) que o agente consegue executar.

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

Manifesto do plug-in da API

O manifesto do plug-in da API descreve as capacidades do plug-in, incluindo as APIs que suporta e as operações que pode realizar. Também inclui metadados como nome, descrição, versão e uma referência à definição openAPI das APIs REST com as quais interage. Os plug-ins de API podem ser referenciados a partir de um manifesto de agente declarativo para serem utilizados na experiência declarativa do agente.

Para saber mais, veja Esquema de manifesto de plug-in da API para Microsoft 365 Copilot.

Localizar o agente

A forma como localiza um agente copilot é ligeiramente diferente da forma como localiza outras capacidades (como separadores, bots e extensões de mensagens) no manifesto da aplicação.

Irá utilizar o mesmo ficheiro de localização (por idioma) para as capacidades da aplicação clássica do Teams e para o agente Copilot. No entanto, enquanto todos os outros campos de manifesto da aplicação são referenciados através de expressões JSONPath nos ficheiros de linguagem, os campos relacionados com o agente copilot são simplesmente referenciados através de chaves de dicionário. Ao contrário das funcionalidades clássicas da aplicação Teams, que utilizam cadeias de idioma predefinidas no próprio manifesto da aplicação, os agentes copilot localizados requerem um ficheiro de idioma para o idioma predefinido, bem como para cada idioma adicional.

Diagrama a mostrar a relação entre o manifesto da aplicação, o manifesto do agente declarativo e um ficheiro de idioma para fins de localização de um agente Copilot

Os passos seguintes mostram como suportar idiomas adicionais (para além da predefinição) para os agentes copilot.

1. Atualize os manifestos do agente Copilot com chaves com tokens

Atualize os manifestos declarativos do agente e/ou do plug-in da API com chaves com tokens (indicados com parênteses retos duplos, por exemplo [[PLUGIN_NAME]]) para quaisquer valores de campo que pretenda localizar. As chaves de localização correspondem muito a esta expressão regular: ^[a-zA-Z_][a-zA-Z0-9_]*$

O exemplo seguinte mostra um manifesto de agente declarativo com valores tokens para o respetivo nome e descrição:

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
    "name": "[[DA_Name]]",
    "description": "[[DA_Description]]",
    "instructions": "# You are an assistant..."
}

2. Adicionar `localizationInfo` ao manifesto da aplicação

Adicione a localizationInfo secção ao manifesto da aplicação, com etiquetas de idioma e caminhos relativos a cada ficheiro de idioma suportado no seu pacote de aplicação.

Se o seu agente Copilot suportar mais do que um idioma, tem de especificar um ficheiro de idioma autónomo para cada idioma suportado, incluindo o idioma predefinido.

O exemplo seguinte mostra a secção informações de localização num manifesto de aplicação:

"localizationInfo": {
    "defaultLanguageTag": "en",
    "defaultLanguageFile": "en.json",
    "additionalLanguages": [
        {
            "languageTag": "fr",
            "file": "fr.json"
        }
    ]
},

Se o agente Copilot não suportar idiomas adicionais, as cadeias de idioma predefinidas são representadas no próprio ficheiro de manifesto da aplicação. (Os pacotes de aplicações de idioma único não necessitam de um ficheiro de idioma separado para o idioma predefinido.)

3. Criar um ficheiro de localização para cada idioma adicional

Crie um ficheiro de localização para cada idioma suportado adicional com valores para as chaves com tokens, utilizando os nomes de ficheiro especificados (para defaultLanguageFile e file propriedades) no manifesto da aplicação do passo anterior.

O exemplo seguinte mostra um ficheiro de idioma, fr.json, com cadeias localizadas para um agente Copilot e separadores pessoais:

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json`",
    "name.short": "Agent de Communications",
    "name.full": "Agent pour les Communications",
    "description.short": "Outils pour les professionnels de la communication",
    "description.full": "Outils pour les professionnels de la communication Contoso, y compris la galerie de ressources et les assistants personnels",
    "localizationKeys": {
        "DA_Name": "Agent de Communications",
        "DA_Description": "Un assistant pour les professionnels de la communication et des relations publiques chez Contoso."
    },
    "staticTabs[0].name": "Accueil",
    "staticTabs[1].name": "Galerie de ressources",
    "staticTabs[2].name": "À propos de Contoso"
}

Campos localizáveis no manifesto da aplicação

Para cada ficheiro de idioma, especifique as seguintes propriedades do esquema de localização da aplicação que têm de ser localizadas:

Campo de manifesto	Descrição	Comprimento máximo	Obrigatório
`@schema`	O URL para o esquema de localização. Para agentes Copilot, utilize devPreview: `https://developer.microsoft.com/en-us/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json`. A versão do esquema de manifesto tem de ser a mesma para os ficheiros de manifesto da aplicação e de localização.		✔️
`name.short`	Substitui o nome abreviado do manifesto da aplicação pelo valor fornecido.	30 caracteres	✔️
`name.full`	Substitui o nome completo do manifesto da aplicação pelo valor fornecido	100 caracteres	✔️
`description.short`	Substitui a breve descrição do manifesto da aplicação pelo valor fornecido.	80 caracteres	✔️
`description.full`	Substitui a descrição completa do manifesto da aplicação pelo valor fornecido.	4000 caracteres	✔️
Pares chave/valor para cadeias localizadas em agentes Copilot	Para agentes Copilot, utilize chaves com tokens (conforme especificado na aplicação `manifest.json`, mas sem parênteses retos duplos) com os respetivos valores localizados. Por exemplo: `"DA_Name": "Agent de Communications"`
Pares JSONPath/valor para cadeias localizadas de quaisquer outros componentes da aplicação	Para todos os outros componentes da aplicação (Teams clássico), utilize expressões JSONPath como chaves para os valores localizados. Por exemplo: `"staticTabs[0].name": "Accueil"`

Para saber mais, consulte Localizar a sua aplicação (Microsoft Teams) e a Referência do esquema de Localização.

Campos localizáveis no manifesto do agente declarativo

Os seguintes campos são localizáveis no manifesto do agente declarativo:

Campo de manifesto	Descrição	Comprimento máximo	Obrigatório
`name`	O nome do agente declarativo. Tem de conter, pelo menos, um caráter de espaço em branco.	100 caracteres	✔️
`description`	A descrição do agente declarativo. Tem de conter, pelo menos, um caráter de espaço em branco.	1000 carateres	✔️
`conversation_starters`	Uma lista (matriz) de exemplos de perguntas às quais o agente declarativo pode responder, em que cada exemplo é representado por um objeto com `title` e `text`, ambos localizáveis.	6 objetos na matriz

Para saber mais, veja Referência de manifesto do agente declarativo.

Campos localizáveis no manifesto do plug-in da API

Os seguintes campos são localizáveis no manifesto do plug-in da API:

Campo de manifesto	Descrição	Comprimento máximo	Obrigatório
`name_for_human`	Um nome curto e legível por humanos para o plug-in. Tem de conter, pelo menos, um caráter que não seja de espaço em branco.	20 carateres	✔️
`description_for_model`	A descrição do plug-in que é fornecido ao modelo, incluindo para que serve o plug-in e em que circunstâncias as suas funções são relevantes.	2,048 caracteres
`description_for_human`	Uma descrição legível por humanos do plug-in.	100 caracteres	✔️
`logo_url`	Um URL utilizado para obter um logótipo que pode ser utilizado pelo orquestrador.
`legal_info_url`	Um URL absoluto que localiza um documento que contém os termos de serviço do plug-in.
`privacy_policy_url`	Um URL absoluto que localiza um documento que contém a política de privacidade do plug-in.

Para saber mais, veja Referência do manifesto do plug-in da API.

Compartilhar via

Os agentes copilot são aplicações para o Microsoft 365

Modelo de aplicação para o Microsoft 365

Pacote do aplicativo

Ícones do aplicativo

Ícone de cor

Ícone de contorno

Manifesto do aplicativo

`copilotAgents` definições

Manifesto do agente declarativo

Manifesto do plug-in da API

Localizar o agente

1. Atualize os manifestos do agente Copilot com chaves com tokens

2. Adicionar `localizationInfo` ao manifesto da aplicação

3. Criar um ficheiro de localização para cada idioma adicional

Campos localizáveis no manifesto da aplicação

Campos localizáveis no manifesto do agente declarativo

Campos localizáveis no manifesto do plug-in da API

Confira também

Comentários

Recursos adicionais

Compartilhar via

Os agentes copilot são aplicações para o Microsoft 365

Modelo de aplicação para o Microsoft 365

Pacote do aplicativo

Ícones do aplicativo

Ícone de cor

Ícone de contorno

Manifesto do aplicativo

copilotAgents definições

Manifesto do agente declarativo

Manifesto do plug-in da API

Localizar o agente

1. Atualize os manifestos do agente Copilot com chaves com tokens

2. Adicionar localizationInfo ao manifesto da aplicação

3. Criar um ficheiro de localização para cada idioma adicional

Campos localizáveis no manifesto da aplicação

Campos localizáveis no manifesto do agente declarativo

Campos localizáveis no manifesto do plug-in da API

Confira também

Comentários

Recursos adicionais

`copilotAgents` definições

2. Adicionar `localizationInfo` ao manifesto da aplicação