Esquema do agente declarativo 1.8 para o Microsoft 365 Copilot

Este artigo descreve o esquema 1.8 usado pelo manifesto do agente declarativo. O manifesto é um documento legível por máquina que fornece a um Large Language Model (LLM) as instruções, o conhecimento e as ações necessários para se especializar na resolução de um conjunto seleto de problemas do usuário. O manifesto do aplicativo Microsoft 365 faz referência a manifestos de agentes declarativos dentro de um pacote do aplicativo. Para obter detalhes, consulte a referência do manifesto do aplicativo Microsoft 365.

Os agentes declarativos são valiosos na compreensão e geração de texto humano, tornando-os versáteis para tarefas como escrever e responder a perguntas. Esta especificação se concentra no manifesto do agente declarativo que atua como uma estrutura estruturada para especializar e aprimorar as funcionalidades de que um usuário específico precisa.

Alterações da versão anterior

Esta versão do esquema introduz as seguintes alterações da versão 1.7:

  • Foi adicionado o novo EmailActions recurso para habilitar operações de gravação no email, como triagem, envio supervisionado, exclusão, regras de caixa de entrada, resposta automática e gerenciamento de pastas. Consulte Objeto de ações de Email.
  • Foi adicionado o novo MeetingActions recurso para habilitar ações de reunião e calendário, como agendar eventos, criar pesquisas de localização de tempo e exibir insights de tempo. Consulte Objeto de ações da reunião.

Esquema JSON

Você pode encontrar o esquema descrito neste documento no formato JSON Schemaaqui.

Convenções

Referências relativas em URLs

A menos que especificado de outra forma, todas as propriedades que são URLs podem ser referências relativas. As referências relativas no documento de manifesto são relativas ao local do documento de manifesto.

Comprimento da cadeia de caracteres

A menos que especificado de outra forma, limite todas as propriedades da cadeia de caracteres a 4.000 caracteres. Esse comprimento de cadeia de caracteres não define um tamanho aceitável para todas as propriedades de cadeia de caracteres no documento. As implementações podem definir seus próprios limites práticos sobre o comprimento do manifesto.

Propriedades não reconhecidas

Os objetos JSON definidos neste documento dão suporte apenas às propriedades descritas. Propriedades não reconhecidas ou estranhas em qualquer objeto JSON tornam todo o documento inválido.

Localização de cadeia de caracteres

Cadeias de caracteres localizáveis podem usar uma chave de localização em vez de um valor literal. A sintaxe é [[key_name]], onde key_name está o nome da localizationKeys chave na propriedade em seus arquivos de localização. Para obter detalhes sobre localização, consulte Localizar seu agente.

Dica

Work IQ Dev Tools (versão prévia) — Como esse esquema é grande e muda com o tempo, a validação em relação à versão de remessa atual é importante. wiqd agent validate executa a Camada de Validação da Microsoft — o mesmo mecanismo que a plataforma usa para aceitar um manifesto — offline e em menos de um segundo, capturando campos obrigatórios ausentes, tipos errados, valores de enumeração inválidos, referências entre arquivos não resolvidas e restrições que o esquema JSON sozinho não pode expressar, como o número máximo de iniciadores de conversa. A extensão do Visual Studio Code exibe o mesmo diagnóstico embutido enquanto você digita. Para obter mais informações, consulte a documentação do Work IQ Dev Tools.

Objeto de manifesto do agente declarativo

A raiz do documento de manifesto é um objeto JSON que abrange campos obrigatórios, funcionalidades, iniciadores de conversa e ações.

O objeto manifesto do agente declarativo contém as propriedades a seguir.

Propriedade Tipo Descrição
version Cadeia de caracteres Obrigatório. A versão do esquema. Definido como v1.8
id String Opcional. Um identificador para o manifesto.
name Cadeia de caracteres Obrigatório. Localizável. O nome do agente declarativo. Deve conter pelo menos um caractere que não seja espaço em branco e ter 100 caracteres ou menos.
description Cadeia de caracteres Obrigatório. Localizável. A descrição do agente declarativo. Deve conter pelo menos um caractere que não seja um espaço em branco e ter 1.000 caracteres ou menos.
instructions Cadeia de caracteres Obrigatório. As instruções detalhadas ou diretrizes sobre como o agente declarativo deve se comportar, suas funções e quaisquer comportamentos a serem evitados. Deve conter pelo menos um caractere que não seja espaço em branco e ter 8.000 caracteres ou menos.
capabilities Objeto Matriz de Recursos Opcional. Contém uma matriz de objetos que definem os recursos do agente declarativo. A matriz não pode conter mais de um de cada tipo derivado de objeto Capabilities.
conversation_starters Matriz de objeto inicial de conversa Opcional. Título e Texto são localizáveis. Uma lista de exemplos de perguntas que o agente declarativo pode responder. A matriz não pode conter mais de 12 objetos.
actions Matriz de objeto de ação Opcional. Uma lista de 1 a 10 objetos que identificam plug-ins que fornecem ações acessíveis ao agente declarativo.
behavior_overrides O comportamento substitui o objeto Opcional. Contém definições de configuração que modificam o comportamento do agente.
disclaimer Objeto de aviso de isenção de responsabilidade Opcional. Texto de aviso de isenção de responsabilidade que é exibido para o usuário no início de uma conversa.
sensitivity_label objeto de rótulo de confidencialidade Opcional. Especifica um rótulo de confidencialidade do Microsoft Purview para o agente.
editorial_answers Objeto de respostas editoriais Opcional. Contém pares de pergunta e resposta predefinidos que o agente pode usar para responder às consultas do usuário com base na similaridade semântica.
worker_agents Matriz do objeto de agente de trabalho Opcional. Especifica outros agentes declarativos que podem ser usados por esse agente.
user_overrides Matriz de objeto de substituição de usuário Opcional. Especifica recursos na capabilities propriedade que o usuário pode modificar.

Exemplo de objeto de manifesto de agente declarativo

O código a seguir mostra um exemplo dos campos obrigatórios em um manifesto de agente declarativo.

{
  "version": "v1.8",
  "name": "Repairs agent",
  "description": "This declarative agent is meant to help track any tickets and repairs",
  "instructions": "This declarative agent needs to look at my Service Now and Jira tickets/instances to help me keep track of open items"
}

Objeto de capacidades

O objeto capabilities é o tipo base para objetos na propriedade do objeto de manifesto capabilities do agente declarativo. Os tipos de objeto possíveis são:

Observação

Os usuários podem acessar agentes declarativos com qualquer recurso diferente da pesquisa na Web somente se seus locatários permitirem o uso limitado ou se tiverem uma licença do Microsoft 365 Copilot.

Exemplo de objeto de recursos

{
  "capabilities": [
    {
      "name": "WebSearch",
      "sites": [
        {
          "url": "https://contoso.com"
        }
      ]
    },
    {
      "name": "OneDriveAndSharePoint",
      "items_by_sharepoint_ids": [
        {
          "site_id": "bc54a8cc-8c2e-4e62-99cf-660b3594bbfd",
          "web_id": "a5377427-f041-49b5-a2e9-0d58f4343939",
          "list_id": "78A4158C-D2E0-4708-A07D-EE751111E462",
          "unique_id": "304fcfdf-8842-434d-a56f-44a1e54fbed2"
        }
      ],
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/teams/admins/Documents/Folders1"
        }
      ]
    },
    {
      "name": "GraphConnectors",
      "connections": [
        {
          "connection_id": "jiraTickets"
        }
      ]
    },
    {
      "name": "GraphicArt"
    },
    {
      "name": "CodeInterpreter"
    },
    {
      "name": "Dataverse",
      "knowledge_sources": [
        {
          "host_name": "organization.crm.dynamics.com",
          "skill": "DVCopilotSkillName",
          "tables": [
            {
              "table_name": "account"
            },
            {
              "table_name": "opportunity"
            }
          ]
        }
      ]
    },
    {
      "name": "TeamsMessages",
      "urls": [
        {
          "url": "https://teams.microsoft.com/l/channel/19%3ApO0102YGEBRSH6RziXCxEgB4mtb7-5hIlDzAjtxs_dg1%40thread.tacv2/G%C3%A9n%C3%A9ral?groupId=2670cf94-acf5-48f4-96d4-c58dd8937afc&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
      ]
    },
    {
      "name": "People"
    },
    {
      "name": "EmailActions"
    },
    {
      "name": "ScenarioModels",
      "models": [
        {
          "id": "model_id"
        }
      ]
    },
    {
      "name": "Meetings",
      "items_by_id": [
        {
          "id": "010000002300A00045B6C7890D12E0030000000040056F7GH890IJ01000000000000000020000000J3L45M6A7NO8PQ9R0S12TUV340XY5Z00",
          "is_series": true
        }
      ]
    }
  ]
}

Objeto de pesquisa na Web

Indica que o agente declarativo pode pesquisar na web por informações básicas.

O objeto de pesquisa na Web contém as propriedades a seguir.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Tem que ser definida como WebSearch.
sites Matriz do objeto Site Opcional. Uma matriz de objetos que identifica sites que o agente tem permissão para pesquisar. Se você omitir essa propriedade, o agente poderá pesquisar todos os sites. A matriz não pode conter mais de quatro itens.

Observação

Para obter detalhes sobre dados, privacidade e segurança para pesquisa na Web no Microsoft 365 Copilot Chat e no Microsoft 365 Copilot, consulte Dados, privacidade e segurança para pesquisa na Web.

Objeto do site

Indica um site que um agente declarativo pode pesquisar conteúdo.

O objeto do site contém a propriedade a seguir.

Propriedade Tipo Descrição
url Cadeia de caracteres Obrigatório. Uma URL absoluta para um site a ser pesquisado em busca de conteúdo. A URL não pode conter mais de dois segmentos de caminho (por exemplo, https://contoso.com/projects/mark-8 é válido, mas https://contoso.com/projects/mark-8/beta-program não é válido). A URL não pode conter nenhum parâmetro de consulta.

Objeto do OneDrive e do SharePoint

Indica que o agente declarativo pode pesquisar o SharePoint e o OneDrive de um usuário para obter informações básicas.

O objeto do OneDrive e do SharePoint contém as propriedades a seguir.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Tem que ser definida como OneDriveAndSharePoint.
items_by_sharepoint_ids Matriz de itens por objeto de IDs do SharePoint Opcional. Uma matriz de objetos que identificam fontes do SharePoint ou do OneDrive usando IDs. Se você omitir as propriedades e as items_by_url , o agente declarativo poderá acessar todas as fontes do items_by_sharepoint_ids OneDrive e do SharePoint na organização.
items_by_url Matriz de itens por objeto de URL Opcional. Uma matriz de objetos que identifica as fontes do SharePoint ou do OneDrive por URL. Se você omitir as propriedades e as items_by_url , o agente declarativo poderá acessar todas as fontes do items_by_sharepoint_ids OneDrive e do SharePoint na organização.

Para obter informações sobre como otimizar o conteúdo do SharePoint para o Copilot, consulte Otimizar a recuperação de conteúdo.

Itens por objeto de IDs do SharePoint

O objeto itens por IDs do SharePoint contém as propriedades a seguir.

Propriedade Tipo Descrição
site_id String Opcional. Um identificador GUID exclusivo para um site do SharePoint ou OneDrive.
web_id String Opcional. Um identificador GUID exclusivo para uma Web específica em um site do SharePoint ou OneDrive.
list_id String Opcional. Um identificador GUID exclusivo para uma biblioteca de documentos dentro de um site do SharePoint.
unique_id String Opcional. Um identificador GUID exclusivo usado para definir o escopo de uma pasta ou arquivo na biblioteca de documentos especificado pela list_id propriedade.
search_associated_sites Booleano Opcional. Indica se a pesquisa de sites associados deve ser habilitada. Esse valor só é aplicável quando o valor faz referência a site_id um SharePoint HubSite.
part_type String Opcional. Indica o tipo de peça part_id a que se refere. Esse valor só é aplicável quando o part_id valor está presente. Os valores possíveis são: OneNotePart.
part_id String Opcional. Um identificador GUID exclusivo usado para representar parte de um item do SharePoint, como uma página do OneNote.

Dica

Para obter informações sobre como obter os identificadores exclusivos de um recurso do SharePoint ou do OneDrive, consulte Recuperando IDs de recursos para o manifesto de agente declarativo.

Itens por objeto de URL

O objeto itens por URL contém a propriedade a seguir.

Propriedade Tipo Descrição
url String Opcional. Uma URL absoluta para um recurso do SharePoint ou do OneDrive.

Objeto de conectores do Copilot

Indica que o agente declarativo pode pesquisar conectores Copilot selecionados para obter informações de aterramento.

O objeto conectores do Copilot contém as propriedades a seguir.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Tem que ser definida como GraphConnectors.
connections Matriz de objeto de conexão Opcional. Uma matriz de objetos que identificam os conectores do Copilot disponíveis para o agente declarativo. Se você omitir essa propriedade, o agente declarativo poderá acessar todos os conectores do Copilot na organização.
Objeto Connection

Identifica um conector Copilot.

O objeto de conexão contém as propriedades a seguir.

Propriedade Tipo Descrição
connection_id Cadeia de caracteres Obrigatório. O identificador exclusivo do conector do Copilot.
additional_search_terms String Opcional. Uma consulta de QL por palavra-chave (KQL) para filtrar itens com base nos campos no esquema da conexão.
items_by_external_id Matriz de objeto identificador de item Opcional. Especifica itens específicos por ID no conector do Copilot que estão disponíveis para o agente.
items_by_external_url Matriz de objeto de URL Externa Opcional. Especifica itens específicos por URL no conector do Copilot que estão disponíveis para o agente.
items_by_path Matriz de objeto Caminho Opcional. Filtra os itens disponíveis para o agente por caminhos de item (o itemPathrótulo semântico nos itens).
items_by_container_name Matriz de objeto de nome de contêiner Opcional. Filtra os itens disponíveis para o agente por nome do contêiner (o containerName rótulo semântico nos itens).
items_by_container_url Matriz de objeto de URL de Contêiner Opcional. Filtra os itens disponíveis para o agente por URL do contêiner (o containerUrl rótulo semântico dos itens).

Dica

Para obter instruções sobre como obter o identificador exclusivo para um conector Copilot, consulte Recuperando IDs de recursos para manifesto de agente declarativo.

Objeto identificador de item

Identifica um item externo por sua ID.

O objeto identificador de item contém as propriedades a seguir.

Propriedade Tipo Descrição
item_id Cadeia de caracteres Obrigatório. O identificador exclusivo do item externo.
Objeto de URL externa

Identifica um item externo por sua URL.

O objeto de URL externo contém a propriedade a seguir.

Propriedade Tipo Descrição
url Cadeia de caracteres Obrigatório. A URL do item externo.
Objeto Path

Identifica um item externo por seu caminho.

O objeto path contém as propriedades a seguir.

Propriedade Tipo Descrição
path Cadeia de caracteres Obrigatório. O caminho (itemPath valor do rótulo semântico) do item externo.
Objeto de nome do contêiner

Identifica um contêiner pelo nome.

O objeto de nome do contêiner contém as seguintes propriedades.

Propriedade Tipo Descrição
container_name Cadeia de caracteres Obrigatório. O nome do contêiner (containerName valor do rótulo semântico) do item externo.
Objeto de URL do contêiner

Identifica um contêiner por sua URL.

O objeto de URL do contêiner contém as propriedades a seguir.

Propriedade Tipo Descrição
container_url Cadeia de caracteres Obrigatório. A URL do contêiner (containerUrl valor do rótulo semântico) do item externo.

Objeto de arte gráfica

Indica que o agente declarativo pode criar imagens e arte com base na entrada de texto do usuário. Para obter mais informações, consulte Gerador de imagens.

O objeto de arte gráfica contém a seguinte propriedade.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Definido como GraphicArt

Objeto interpretador de código

Indica que o agente declarativo pode gerar e executar código Python para resolver problemas matemáticos complexos, analisar dados, gerar visualizações e muito mais. Para obter mais informações, consulte Interpretador de código.

O objeto interpretador de código contém a seguinte propriedade.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Definido como CodeInterpreter

Objeto do Dataverse

Indica que o agente declarativo pode pesquisar dados de tabelas no Dataverse.

O objeto Dataverse contém as propriedades a seguir.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Definido como Dataverse
knowledge_sources Variedade de fontes de conhecimento Opcional. Uma matriz de objetos que contém os identificadores, habilidades e nomes de tabela para as instâncias do Dataverse a serem incluídas como conhecimento.
Objeto de fontes de conhecimento

Contém informações sobre as instâncias do Dataverse a serem incluídas como conhecimento.

O objeto fontes de conhecimento contém as propriedades a seguir.

Propriedade Tipo Descrição
host_name Cadeia de caracteres Obrigatório. Um identificador exclusivo para o host no Dataverse.
skill Cadeia de caracteres Um identificador exclusivo que define a configuração de como o agente interage com o conhecimento do Dataverse.
tables Matriz de tabelas Uma matriz de tabelas para definir o escopo do conhecimento do agente.

Para encontrar o identificador exclusivo skill das fontes de conhecimento do Dataverse, você deseja incluir:

  1. No Copilot Studio, no painel esquerdo, escolha Agents>Copilot for Microsoft 365 e selecione Adicionar para criar um novo agente.
  2. Siga as instruções em Adicionar uma fonte de conhecimento do Dataverse para adicionar conhecimento do Dataverse.
  3. Selecione Publicar e baixe o arquivo .zip.
  4. Descompacte e abra o arquivo declarativeAgent.json.
  5. O skill valor é incluído na knowledge_sources seção, conforme mostrado no exemplo a seguir.
{
  "name": "Dataverse",
  "knowledge_sources": [
    {
      "host_name": "org0f612cfc.crm.dynamics.com",
      "skill": "AIBuilderFileAttachedData_e7eTReDbkX_1t4X1oGoCF",
      "tables": [
        {
          "table_name": "msdyn_aibfileattacheddata"
        }
      ]
    }
  ]
}
Objeto Tables

Contém as tabelas para definir o escopo do conhecimento do agente.

O objeto tables contém a propriedade a seguir.

Propriedade Tipo Descrição
table_name Cadeia de caracteres Obrigatório. Um identificador exclusivo para a tabela.

Objeto de mensagens do Microsoft Teams

Indica que o agente declarativo pode pesquisar canais, equipes, reuniões, chats 1:1 e chats em grupo do Microsoft Teams.

O objeto de mensagens do Microsoft Teams contém as propriedades a seguir.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Definido como TeamsMessages
urls Matriz de URLs do Microsoft Teams Opcional. Uma matriz de objetos que identifica as URLs dos canais do Microsoft Teams, chats de reunião, chats em grupo ou chats 1:1 disponíveis para o agente declarativo. A matriz não pode conter mais de cinco objetos. Se você omitir essa propriedade, o agente declarativo poderá pesquisar em todos os canais, reuniões, chats 1:1 e chats em grupo.
Objeto de URL do Microsoft Teams

Identifica um canal, equipe ou chat de reunião do Microsoft Teams.

O objeto de URL do Microsoft Teams contém as propriedades a seguir.

Propriedade Tipo Descrição
url Cadeia de caracteres Obrigatório. Uma URL bem formatada do Microsoft Teams vinculada a um canal do Microsoft Teams, chat de reunião, chat em grupo ou chat 1:1.

Objeto Email

Indica que o agente declarativo pode pesquisar mensagens de email nas caixas de correio às quais o usuário tem acesso.

O objeto de email contém as propriedades a seguir.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Deve ser definido como Email.
shared_mailbox String Opcional. O endereço SMTP de uma caixa de correio compartilhada.
group_mailboxes Matriz de cadeias de caracteres Opcional. Uma matriz de endereços SMTP de Grupos do Microsoft 365 ou caixas de correio compartilhadas. Há suporte para no máximo 25 caixas de correio.
folders Matriz de pastas Opcional. Se estiver presente, somente os emails nas pastas especificadas estarão disponíveis para o agente.
Folders object

Contém as pastas para definir o escopo do conhecimento do agente.

O objeto folders contém a propriedade a seguir.

Propriedade Tipo Descrição
folder_id Cadeia de caracteres Obrigatório. O nome conhecido da pasta ou ID da pasta a ser referenciada.

Objeto de ações de Email

Indica que o agente declarativo pode executar operações de gravação no email nas caixas de correio às quais o usuário tem acesso. Esse recurso permite operações de gravação de email, como triagem (arquivar, sinalizar, marcar como lida, fixar, mover, copiar, relatar lixo eletrônico), envio supervisionado, exclusão, regras de caixa de entrada (criar/obter), resposta automática e gerenciamento de pastas (criar/listar). Essa funcionalidade é separada da Email funcionalidade, que é somente leitura (pesquisa). Os desenvolvedores que desejam acesso de gravação de e-mail devem usar EmailActions; aqueles que desejam apenas pesquisa por e-mail devem usar Email.

Observação

EmailActions opera independentemente da Email capacidade. Quaisquer restrições de escopo configuradas Email no recurso (como folders, shared_mailbox, ou group_mailboxes) não se aplicam ao EmailActions. Os dois recursos podem ser declarados em conjunto ou de forma independente.

O objeto de ações de email contém a seguinte propriedade.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Tem que ser definida como EmailActions.
Exemplo de objeto de ações de Email
{
  "capabilities": [
    {
      "name": "EmailActions"
    }
  ]
}

People object

Indica que o agente declarativo pode pesquisar informações sobre pessoas na organização. Consulte o People knowledge para obter mais detalhes sobre os dados retornados pelo recurso base do People.

O objeto people contém as propriedades a seguir.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Tem que ser definida como People.
include_related_content Booleano Opcional. Indica se deve incluir conteúdo relacionado ao pesquisar dados de pessoas. Quando definido como true, o DA incluirá documentos relacionados, emails e mensagens do Teams entre o usuário do agente e as pessoas referenciadas (ou seja, o que eles têm em comum). Quando definido como falso ou omitido, somente as informações organizacionais básicas, como organogramas, nomes, endereços de email e habilidades, serão incluídas. O valor padrão é falso.

Objeto de modelos de cenário

Indica que o agente declarativo pode usar modelos específicos de tarefa.

O objeto scenario models contém as propriedades a seguir.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Tem que ser definida como ScenarioModels.
models Matriz de objeto de modelo Obrigatório. Uma matriz de objetos que identifica os modelos específicos da tarefa disponíveis para o agente declarativo.
Model object

Identifica um modelo específico da tarefa.

O objeto de modelo contém a propriedade a seguir.

Propriedade Tipo Descrição
id Cadeia de caracteres Obrigatório. O identificador exclusivo do modelo.

Objeto de reuniões

Indica que o agente declarativo pode pesquisar informações sobre reuniões na organização.

O objeto meetings contém as propriedades a seguir.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Tem que ser definida como Meetings.
items_by_id Matriz de objeto identificador de reunião Opcional. Uma matriz de objetos que identifica as reuniões disponíveis para o agente declarativo. A matriz não pode conter mais de cinco objetos. Se você omitir essa propriedade, o agente declarativo poderá pesquisar todas as reuniões.
Objeto identificador de reunião

Identifica uma reunião.

O objeto identificador de reunião contém as propriedades a seguir.

Propriedade Tipo Descrição
id Cadeia de caracteres Obrigatório. O identificador exclusivo da reunião. Para obter instruções sobre como localizar a ID de uma reunião, consulte Obter a ID de uma reunião.
is_series Booliano Obrigatório. Indica se a reunião é uma série.

Objeto de ações de reunião

Indica que o agente declarativo pode executar ações de reunião e calendário, como agendar eventos, criar pesquisas de localização de tempo ou exibir insights de tempo. As ações específicas apoiadas podem evoluir ao longo do tempo.

O objeto de ações da reunião contém a seguinte propriedade.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Tem que ser definida como MeetingActions.
Exemplo de objeto de ações de reunião
{
  "capabilities": [
    {
      "name": "MeetingActions"
    }
  ]
}

Objeto de conhecimento inserido

Indica que o agente declarativo pode usar arquivos localmente no pacote do aplicativo.

Os arquivos de conhecimento inseridos têm um tamanho máximo de arquivo de 1 MB e devem ser um dos seguintes tipos de documento:

  • Word documento (.doc, .docx)
  • Apresentação do PowerPoint (.ppt, .pptx)
  • Pasta de trabalho do Excel (.xls, .xlsx)
  • Texto sem formatação (.txt)
  • Portable Document Format (.pdf)

O objeto de conhecimento inserido contém as seguintes propriedades:

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. Tem que ser definida como EmbeddedKnowledge.
files Matriz do objeto Arquivo Obrigatório. Lista de objetos que identificam arquivos que contêm conhecimento que o agente pode usar para aterramento. O tamanho máximo da matriz é 10.

Exemplo de objeto EmbeddedKnowledge

{
  "name": "EmbeddedKnowledge",
  "files": [
    { "file": "file1.docx" },
    { "file": "file2.csv" }
  ]
}

Objeto File

Propriedade Tipo Descrição
file Cadeia de caracteres Obrigatório. O caminho relativo do arquivo para o arquivo inserido.

Objeto de iniciação de conversa

O objeto de início de conversa é opcional no manifesto. Ele contém dicas que o agente exibe para o usuário para mostrar como ele pode começar a usar o agente declarativo.

O objeto inicial de conversa contém as seguintes propriedades:

Propriedade Tipo Descrição
text Cadeia de caracteres Obrigatório. Localizável. Uma sugestão que o usuário pode usar para obter o resultado desejado do agente declarativo. Deve conter pelo menos um caractere que não seja espaço em branco.
title String Opcional. Localizável. Um título exclusivo para o início da conversa. Deve conter pelo menos um caractere que não seja espaço em branco.
depends_on Matriz de Depende do objeto Opcional. Uma lista de objetos que especificam dependências de recursos para este iniciador de conversa. Os iniciadores de conversa com dependências só são exibidos para os usuários quando todos os recursos referenciados estão presentes no manifesto do agente declarativo.

Observação

A matriz não pode conter mais de 12 objetos.

Exemplo de objeto de iniciadores de conversa

{
  "conversation_starters": [
    {
      "title": "My Open Repairs",
      "text": "What open repairs are assigned to me?"
    }
  ]
}

Depende do objeto

Especifica uma dependência para um iniciador de conversa. Esse objeto identifica um elemento de manifesto que deve estar presente para que o iniciador de conversa seja exibido.

O objeto depends on contém as propriedades a seguir.

Propriedade Tipo Descrição
name Cadeia de caracteres Obrigatório. O nome do tipo de elemento de manifesto. Deve ser definida como capabilities.
id Cadeia de caracteres Obrigatório. O identificador do elemento específico. Por exemplo: Email ou WebSearch.
Depende do exemplo de objeto
{
  "conversation_starters": [
    {
      "title": "Project Update",
      "text": "Executive status report on [Project]",
      "depends_on": [
        {
          "name": "capabilities",
          "id": "Email"
        },
        {
          "name": "capabilities",
          "id": "WebSearch"
        }
      ]
    }
  ]
}

Objeto Actions

As ações são um objeto JSON opcional no manifesto. Eles atuam como entrada do desenvolvedor e podem ser considerados como plug-ins. Um objeto de ação pode ser especificado como uma referência a um arquivo de manifesto de plug-in usando as propriedades and file ou pode ser uma representação embutida do objeto de manifesto id do plug-in.

A tabela a seguir descreve as propriedades de um objeto de ação referenciado.

Propriedade Tipo Descrição
id Cadeia de caracteres Obrigatório. Um identificador exclusivo para a ação. Pode ser um GUID.
file Cadeia de caracteres Obrigatório. Um caminho para o manifesto do plug-in da API para esta ação.

Ao especificar uma ação como um manifesto de plug-in embutido, o objeto de ação deve estar em conformidade com a especificação do manifesto do plug-in .

Observação

A matriz deve conter pelo menos um e não mais do que 10 objetos.

Exemplo de objeto de ações

O exemplo a seguir mostra uma ação especificada como uma referência a um arquivo de manifesto de plug-in.

{
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "plugin.json"
    }
  ]
}

O exemplo a seguir mostra uma ação com um manifesto de plug-in embutido.

{
  "actions": [
    {
      "schema_version": "v2.4",
      "name_for_human": "GitHub Issues Plugin",
      "description_for_model": "Search for GitHub issues by author, keyword or state",
      "runtimes": [
        {
          "type": "OpenApi",
          "auth": { "type": "None" },
          "spec": { "url": "https://github.com/ai/plugins/issues/openapi.yaml" }
        }
      ]
    }
  ]
}

O comportamento substitui o objeto

Um objeto JSON opcional que contém definições de configuração que substituem o comportamento do agente.

O objeto behavior overrides contém as propriedades a seguir.

Propriedade Tipo Descrição
suggestions Objeto Sugestões Opcional. Contém definições de configuração para o recurso de sugestões.
special_instructions Objeto de instruções especiais Opcional. Contém configurações para injetar instruções especiais no prompt.
default_response_mode String Opcional. O modo de resposta padrão do agente. Essa propriedade é prefixada porque default_ os usuários sempre podem substituir esse valor por meio da IU do seletor de modelo. Para obter detalhes, consulte Valores do modo de resposta padrão. O valor padrão é Auto.

Valores do modo de resposta padrão

A default_response_mode propriedade permite que os autores de agentes configurem o modo padrão para seus agentes a partir dos modos disponíveis no seletor de modelos de usuário. O valor deve ser um dos seguintes.

  • Auto - O agente determina automaticamente o melhor modo de resposta com base no contexto da consulta do usuário, selecionando de forma inteligente entre respostas rápidas e raciocínio mais profundo. Esse será o valor padrão se não for especificado.
  • Quick response - O agente fornece respostas rápidas otimizadas para interações de baixa latência. Esse modo é apropriado para agentes em que a velocidade é priorizada em relação ao raciocínio complexo.
  • Think deeper - O agente usa o modo de raciocínio para fornecer respostas mais ponderadas e abrangentes. Esse modo envolve maior latência, mas é adequado para cenários complexos de resolução de problemas em que uma análise mais profunda é benéfica.

Os autores do agente devem considerar o caso de uso ao selecionar um modo. Por exemplo, o aumento da latência envolvido no modo de raciocínio pode não ser apropriado para todos os agentes, enquanto alguns autores podem querer sempre invocar o raciocínio para tarefas analíticas complexas.

O cliente respeita o modo padrão configurado no manifesto. Os usuários podem substituir este padrão por meio do seletor de modelo.

Objeto Sugestões

Um objeto JSON opcional que contém definições de configuração para o recurso de sugestões.

O objeto suggestions contém a propriedade a seguir.

Propriedade Tipo Descrição
disabled Booliano Obrigatório. Se definido como true, o recurso de sugestões será desabilitado. O valor padrão é false.

Objeto de instruções especiais

Um objeto JSON opcional que contém configurações para injetar instruções especiais no prompt.

O objeto de instruções especiais contém a propriedade a seguir.

Propriedade Tipo Descrição
discourage_model_knowledge Booliano Obrigatório. Se definido como true, o agente não usa o conhecimento do modelo ao gerar respostas. O valor padrão é false.

Para saber quando e como usar essa propriedade, consulte Respostas de solo para fontes de conhecimento configuradas.

Objeto de aviso de isenção de responsabilidade

Um aviso de isenção de responsabilidade é um objeto JSON opcional no manifesto que especifica o texto do aviso de isenção de responsabilidade. O agente exibe esse texto para o usuário no início de uma conversa.

O objeto de isenção de responsabilidade contém a propriedade a seguir.

Propriedade Tipo Descrição
text Cadeia de caracteres Obrigatório. O texto do aviso de isenção de responsabilidade. O valor deve conter pelo menos um caractere que não seja espaço em branco e não deve exceder 500 caracteres.

objeto de rótulo de confidencialidade

Observação

Os rótulos de confidencialidade são aplicados ao agente somente quando o agente possui Embedded Files. Esta propriedade ainda não está habilitada, uma vez que os Files incorporados ainda não estão habilitados.

Um objeto JSON opcional que especifica o rótulo de confidencialidade do Microsoft Purview para os arquivos inseridos no agente. Ele contém a mais alta proteção entre todos os arquivos incorporados aos agentes na propriedade Embedded Knowledge

Propriedade Tipo Descrição
id Cadeia de caracteres O GUID do rótulo de confidencialidade do Microsoft Purview.

Exemplo de objeto de rótulo de confidencialidade

{
  "sensitivity_label": {
    "id": "<guid>"
  }
}

Objeto de agente de trabalho

Identifica um agente declarativo que pode ser usado por esse agente. Consulte Conectar-se a outros agentes para obter as práticas recomendadas e de uso.

Observação

Essa funcionalidade está em versão prévia.

O objeto de agente de trabalho contém as propriedades a seguir.

Propriedade Tipo Descrição
id String Opcional. A ID do título do aplicativo que contém o agente declarativo. Isso é retornado ao publicar o aplicativo com o Kit de Ferramentas de Agentes do Microsoft 365 ou pode ser encontrado na seção de metadados do agente do card do modo de desenvolvedor. Você deve especificar um ou idfile, mas não ambos.

Objeto de substituição de usuário

Identifica os recursos configurados no objeto Capabilities que o usuário pode substituir por meio de um controle de interface do usuário no Microsoft 365 Copilot. A única ação com suporte é remove, que habilita um controle de alternância na interface do usuário, permitindo que o usuário habilite ou desabilite o recurso de ser usado para gerar respostas.

Observação

Quando você declara GraphConnectors no path, todos os conectores Copilot disponíveis podem ser ativados ou desativados. Não é possível ativar a alternância para conectores específicos. O sistema agrupa e exibe conectores fornecidos pela Microsoft usando um nome amigável e conectores personalizados usando o nome do conector (por exemplo, CB Insights). Esse comportamento garante que os usuários finais possam identificar e gerenciar facilmente as fontes de conectores ao configurar a sessão do agente. Para obter mais informações sobre conectores e editores, consulte Galeria de Conectores do Microsoft 365 Copilot.

O objeto de substituição de usuário contém as propriedades a seguir.

Propriedade Tipo Descrição
path Cadeia de caracteres Obrigatório. Uma expressão JSONPath que identifica o recurso que os usuários podem modificar. A expressão JSONPath permite direcionar recursos específicos somente por nome.
allowed_actions Array of String Obrigatório. Especifica que as ações podem ser tomadas para os recursos especificados. A única ação com suporte é remove.

Exemplo de objeto de substituição de usuário

O exemplo a seguir habilita controles de alternância para os recursos de pesquisa na Web e mensagens do Microsoft Teams , permitindo que o usuário ative ou desative os recursos.

{
  "user_overrides": [
    {
      "path": "$.capabilities[?(@.name == 'WebSearch')]",
      "allowed_actions": ["remove"]
    },
    {
      "path": "$.capabilities[?(@.name == 'TeamsMessages')]",
      "allowed_actions": ["remove"]
    }
  ]
}

Objeto de respostas editoriais

Um objeto JSON opcional que contém pares de pergunta e resposta predefinidos que o agente pode usar para responder às consultas do usuário com base na similaridade semântica. O objeto deve conter uma url propriedade ou uma answers propriedade, mas não ambas.

O objeto de respostas editoriais contém as propriedades a seguir.

Propriedade Tipo Descrição
url Cadeia de caracteres Uma URL que localiza um documento que contém a configuração de respostas editoriais. Você deve especificar um ou urlanswers, mas não ambos.
answers Matriz de objeto de resposta Uma matriz de objetos de pares de pergunta e resposta predefinidos. A matriz não pode conter mais de 300 objetos. Você deve especificar um ou urlanswers, mas não ambos.

Objeto de resposta

Um objeto JSON contendo um par pergunta-resposta predefinido.

O objeto de resposta contém as seguintes propriedades.

Propriedade Tipo Descrição
question Cadeia de caracteres Obrigatório. A pergunta predefinida que é usada para correspondência de similaridade semântica com consultas de usuário. Deve conter pelo menos um caractere que não seja espaço em branco.
answer Cadeia de caracteres Obrigatório. A resposta predefinida que é retornada quando a consulta do usuário corresponde à pergunta acima do limite de similaridade. Deve conter pelo menos um caractere que não seja espaço em branco.
similarity_thresholds Objeto de limites de similaridade Opcional. Define os limites de similaridade para corresponder as consultas de usuário a essa pergunta.

Objeto de limites de similaridade

Um objeto JSON que contém os valores mínimos e máximos de limite de similaridade para correspondência semântica.

O objeto de limites de similaridade contém as propriedades a seguir.

Propriedade Tipo Descrição
min Número Obrigatório. O limite mínimo de similaridade. O valor deve ser um número inteiro entre 0 e 10 inclusive.
max Número Obrigatório. O limite máximo de similaridade. O valor deve ser um número inteiro entre 0 e 10 inclusive.

Exemplo de objeto de respostas editoriais

{
  "editorial_answers": {
    "answers": [
      {
        "question": "What is the company's return policy?",
        "answer": "Our company offers a 30-day return policy for all products purchased in-store or online.",
        "similarity_thresholds": {
          "min": 3,
          "max": 8
        }
      },
      {
        "question": "How do I contact support?",
        "answer": "You can contact our support team by emailing support@contoso.com or calling 1-800-555-0199."
      }
    ]
  }
}

Exemplo de manifesto de agente declarativo

O exemplo a seguir mostra um arquivo de manifesto de agente declarativo que usa a maioria das propriedades de manifesto descritas neste artigo.

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.8/schema.json",
  "version": "v1.8",
  "name": "Teams Toolkit declarative agent",
  "description": "Declarative agent created with Teams Toolkit",
  "instructions": "You are a repairs expert agent. With the response from the listRepairs function, you **must** create a poem out of the repairs listed and always include their title and the assigned person. The poem **must** not use the quote markdown and use regular text. If the user is asking to create a new repair, use the createRepair function and do not add poems.",
  "conversation_starters": [
    {
      "title": "Getting Started",
      "text": "How can I get started with Teams Toolkit?"
    },
    {
      "title": "Getting Help",
      "text": "How can I get help with Teams Toolkit?",
      "depends_on": [
        {
          "name": "capabilities",
          "id": "WebSearch"
        }
      ]
    }
  ],
  "sensitivity_label": {
    "id": "00000000-0000-0000-0000-000000000000"
  },
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "repairs-hub-api-plugin.json"
    }
  ],
  "behavior_overrides": {
    "suggestions": {
      "disabled": true
    },
    "special_instructions": {
      "discourage_model_knowledge": true
    },
    "default_response_mode": "Auto"
  },
  "disclaimer": {
    "text": "This declarative agent is a fictional example. You should not take it seriously."
  },
  "editorial_answers": {
    "answers": [
      {
        "question": "What is the company's return policy?",
        "answer": "Our company offers a 30-day return policy for all products purchased in-store or online.",
        "similarity_thresholds": {
          "min": 3,
          "max": 8
        }
      }
    ]
  },
  "worker_agents": [
    {
      "id": "P_2c27ae89-1f78-4ef7-824c-7d83f77eda28"
    }
  ],
  "user_overrides": [
    {
      "path": "$.capabilities[?(@.name == 'OneDriveAndSharePoint')]",
      "allowed_actions": [
        "remove"
      ]
    }
  ],
  "capabilities": [
    {
      "name": "WebSearch",
      "sites": [
        {
          "url": "https://contoso.com/projects/mark-8"
        }
      ]
    },
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/sites/ProductSupport"
        }
      ]
    },
    {
      "name": "GraphConnectors",
      "connections": [
        {
          "connection_id": "foodStore"
        }
      ]
    },
    {
      "name": "GraphicArt"
    },
    {
      "name": "CodeInterpreter"
    },
    {
      "name": "Dataverse",
      "knowledge_sources": [
        {
          "host_name": "organization.crm.dynamics.com",
          "skill": "DVCopilotSkillName",
          "tables": [
            {
              "table_name": "account"
            },
            {
              "table_name": "opportunity"
            }
          ]
        }
      ]
    },
    {
      "name": "TeamsMessages",
      "urls": [
        {
          "url": "https://teams.microsoft.com/l/channel/19%3ApO0102YGEBRSH6RziXCxEgB4mtb7-5hIlDzAjtxs_dg1%40thread.tacv2/G%C3%A9n%C3%A9ral?groupId=2670cf94-acf5-48f4-96d4-c58dd8937afc&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
      ]
    },
    {
      "name": "Email",
      "shared_mailbox": "sample@service.microsoft.com",
      "folders": [
        {
          "folder_id": "inbox"
        }
      ]
    },
    {
      "name": "EmailActions"
    },
    {
      "name": "People"
    },
    {
      "name": "ScenarioModels",
      "models": [
        {
          "id": "model_id"
        }
      ]
    },
    {
      "name": "Meetings",
      "items_by_id": [
        {
          "id": "010000002300A00045B6C7890D12E0030000000040056F7GH890IJ01000000000000000020000000J3L45M6A7NO8PQ9R0S12TUV340XY5Z00",
          "is_series": true
        }
      ]
    },
    {
      "name": "MeetingActions"
    },
    {
      "name": "EmbeddedKnowledge",
      "files": [
        { "file": "file1.docx" },
        { "file": "file2.csv" }
      ]
    }
  ]
}