Partilhar via

Localizar o agente

  • Artigo

Os agentes são essencialmente aplicações para o Microsoft 365. Partilham um esquema de manifesto comum, empacotamento de aplicações e processo de distribuição e gestão. O manifesto da aplicação referencia o ficheiro de definição dos agentes declarativos no copilotAgents objeto.

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

Utiliza o mesmo ficheiro de localização (por idioma) para as capacidades e agentes da aplicação Teams. No entanto, enquanto todos os outros campos de manifesto da aplicação são referenciados através de expressões JSONPath nos ficheiros de idioma, os campos relacionados com o agente são 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 localizados necessitam de um ficheiro de idioma para o idioma predefinido e para cada idioma extra.

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

Este artigo descreve como adicionar suporte para outros idiomas (para além do idioma predefinido) aos agentes.

1. Atualize os manifestos do agente 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 têm de corresponder 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 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 localizationInfo secção num manifesto de aplicação.

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

Se o agente não suportar outros idiomas, 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 extra

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

O exemplo seguinte mostra um ficheiro de idioma, fr.json, com cadeias localizadas para um agente 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, 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. 4.000 caracteres ✔️
Pares chave/valor para cadeias localizadas em agentes Para agentes, 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 campos seguintes 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 não branco. 100 caracteres ✔️
description A descrição do agente declarativo. Tem de conter, pelo menos, um caráter não branco. 1000 carateres ✔️
conversation_starters Uma lista (matriz) de exemplos de perguntas às quais o agente declarativo pode responder, em que cada exemplo é um objeto com title e text, ambos localizáveis. Seis 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 campos seguintes 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 não 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.

Conteúdo relacionado