Esquema do agente declarativo 1.2 para Microsoft 365 Copilot

Artigo
11/19/2024

Este artigo descreve o esquema 1.2 utilizado pelo manifesto do agente declarativo. O manifesto é um documento legível por computador que fornece um Modelo de Linguagem Grande (LLM) com as instruções, conhecimentos e ações necessários para se especializar na resolução de um conjunto selecionado de problemas de utilizador.

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

Alterações da versão anterior

Esta versão de esquema apresenta as seguintes alterações da versão 1.0.

A sites propriedade é adicionada ao objeto de pesquisa na Web. Isto permite que a capacidade de pesquisa na Web seja limitada a sites permitidos.
A capacidade de arte gráfica foi adicionada. Esta capacidade permite que o agente declarativo gere imagens e imagens com base na entrada do utilizador.

Esquema JSON

O esquema descrito neste documento pode ser encontrado no formato de Esquema JSON aqui.

Convenções

Referências relativas em URLs

Salvo especificação em contrário, todas as propriedades que são URLs poderão ser referências relativas. As referências relativas no documento de manifesto são relativas à localização do documento de manifesto.

Comprimento da cadeia

Salvo especificação em contrário, todas as propriedades de cadeia devem estar limitadas a 4K carateres. Este comprimento de cadeia não confere qualquer tamanho aceitável para todo o documento. As implementações são livres de impor os seus próprios limites práticos ao comprimento do manifesto.

Propriedades não reconhecidas

Os objetos JSON definidos neste documento suportam apenas as propriedades descritas. Propriedades não reconhecidas ou desnecessárias em qualquer objeto JSON DEVEM tornar todo o documento inválido.

Localização de cadeias

As cadeias localizáveis podem utilizar uma chave de localização em vez de um valor literal. A sintaxe é [[key_name]], em key_name que é o nome da chave na localizationKeys propriedade nos ficheiros de localização. Para obter detalhes sobre a localização, veja Localizar o agente.

Objeto de manifesto do agente declarativo

A raiz do documento de manifesto é um objeto JSON que abrange os campos, capacidades, inícios de conversação e ações necessários.

O objeto de manifesto do agente declarativo contém as seguintes propriedades.

Propriedade	Tipo	Descrição
`version`	Cadeia de caracteres	Obrigatório. A versão do esquema. Deve ser definida como `v1.2`.
`id`	String	Opcional.
`name`	Cadeia de caracteres	Obrigatório. Localizável. O nome do agente declarativo. Tem de conter, pelo menos, um caráter não branco e TEM de ter 100 carateres ou menos.
`description`	Cadeia de caracteres	Obrigatório. Localizável. A descrição do agente declarativo. Tem de conter, pelo menos, um caráter não branco e TEM de ter 1000 carateres ou menos.
`instructions`	Cadeia de caracteres	Obrigatório. As instruções detalhadas ou diretrizes sobre o comportamento do agente declarativo, as suas funções e quaisquer comportamentos a evitar. TEM de conter, pelo menos, um caráter não branco e TEM de ter 8000 carateres ou menos.
`capabilities`	Matriz do objeto Capacidades	Opcional. Contém uma matriz de objetos que definem as capacidades do agente declarativo. NÃO PODE haver mais do que um de cada tipo derivado de objeto Capacidades na matriz.
`conversation_starters`	Matriz do objeto inicial de Conversação	Opcional. O Título e o Texto são localizáveis. Uma lista de exemplos de perguntas às quais o agente declarativo pode responder. NÃO PODE haver mais de seis objetos na matriz.
`actions`	Matriz do objeto Ação	Opcional. Uma lista de objetos que identificam plug-ins de API que fornecem ações acessíveis ao agente declarativo.

Exemplo de objeto de manifesto de agente declarativo

O seguinte JSON é um exemplo de campos necessários num manifesto de agente declarativo.

{
  "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 Capacidades

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

Objeto de pesquisa na Web
Objeto oneDrive e SharePoint
Objeto Conectores do Microsoft Graph
Objeto de arte gráfica

Exemplo de capacidades

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

Objeto de pesquisa na Web

Indica que o agente declarativo pode procurar na Web informações de ligação à terra.

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

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 identificam sites que o agente tem permissão para pesquisar. Se esta propriedade for omitida, todo o agente tem permissão para procurar em todos os sites. A matriz NÃO PODE conter mais do que quatro itens.

Objeto de site

Indica um site onde um agente declarativo pode procurar conteúdo.

O objeto do site contém as seguintes propriedades.

Propriedade	Tipo	Descrição
`url`	Cadeia de caracteres	Obrigatório. Um URL absoluto para um site a procurar conteúdo. O URL NÃO PODE conter mais de 2 segmentos de caminho (por exemplo, `https://contoso.com/projects/mark-8` é válido, `https://contoso.com/projects/mark-8/beta-program` não é válido). O URL NÃO PODE conter parâmetros de consulta.

Objeto oneDrive e SharePoint

Indica que o agente declarativo pode procurar informações de base no SharePoint e no OneDrive de um utilizador.

O objeto OneDrive e SharePoint contém as seguintes propriedades.

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 IDs do SharePoint	Opcional. Uma matriz de objetos que identificam origens do SharePoint ou do OneDrive com IDs. Se as `items_by_sharepoint_ids` propriedades e `items_by_url` forem omitidas, todas as origens do OneDrive e do Sharepoint na organização estão disponíveis para o agente declarativo.
`items_by_url`	Matriz de Itens por objeto de URL	Opcional. Uma matriz de objetos que identificam origens do SharePoint ou do OneDrive por URL. Se as `items_by_sharepoint_ids` propriedades e `items_by_url` forem omitidas, todas as origens do OneDrive e do Sharepoint na organização estão disponíveis para o agente declarativo.

Objeto Itens por IDs do SharePoint

O objeto Itens por IDs do SharePoint contém as seguintes propriedades.

Propriedade	Tipo	Descrição
`site_id`	String	Opcional. Um identificador GUID exclusivo para um site do SharePoint ou do OneDrive.
`web_id`	String	Opcional. Um identificador GUID exclusivo para uma Web específica num site do SharePoint ou do OneDrive.
`list_id`	String	Opcional. Um identificador GUID exclusivo para uma lista num site do SharePoint ou do OneDrive.
`unique_id`	String	Opcional. Um identificador GUID exclusivo utilizado para representar uma entidade ou recurso específico.

Dica

Para obter instruções sobre como obter os identificadores exclusivos de um recurso do SharePoint ou do OneDrive, veja Obter IDs de capacidades para o manifesto declarativo do agente.

Itens por objeto de URL

O objeto Itens por URL contém as seguintes propriedades.

Propriedade	Tipo	Descrição
`url`	String	Opcional. Um URL absoluto para um recurso do SharePoint ou do OneDrive.

Objeto de conectores do Microsoft Graph

Indica que o agente declarativo pode procurar informações de terra nos conectores selecionados do Microsoft Graph.

O objeto conectores do Microsoft Graph contém as seguintes propriedades.

Propriedade	Tipo	Descrição
`name`	Cadeia de caracteres	Obrigatório. Tem que ser definida como `GraphConnectors`.
`connections`	Matriz do objeto Ligação	Opcional. Uma matriz de objetos que identificam os conectores do Microsoft Graph disponíveis para o agente declarativo. Se esta propriedade for omitida, todos os conectores do Microsoft Graph na organização estão disponíveis para o agente declarativo.

Objeto Connection

Identifica um conector do Microsoft Graph.

O objeto de ligação contém as seguintes propriedades.

Propriedade	Tipo	Descrição
`connection_id`	Cadeia de caracteres	Obrigatório. O identificador exclusivo do conector do Microsoft Graph.

Dica

Para obter instruções sobre como obter o identificador exclusivo para um conector do Microsoft Graph, veja Obter IDs de capacidades para o manifesto declarativo do agente.

Objeto de arte gráfica

Indica que o agente declarativo pode criar imagens e imagens com base na entrada de texto do utilizador. Para obter mais informações, veja Gerador de imagens.

O objeto de arte gráfica contém as seguintes propriedades.

Propriedade	Tipo	Descrição
`name`	Cadeia de caracteres	Obrigatório. Tem que ser definida como `GraphicArt`.

Objeto de iniciadores de conversação

O objeto de iniciadores de conversação é opcional no manifesto. Contém sugestões que são apresentadas ao utilizador para demonstrar como podem começar a utilizar o agente declarativo.

O objeto inicial da conversação contém as seguintes propriedades:

Propriedade	Tipo	Descrição
`text`	Cadeia de caracteres	Obrigatório. Localizável. Uma sugestão que o utilizador pode utilizar para obter o resultado pretendido do agente declarativo. Tem de conter, pelo menos, um caráter não branco.
`title`	String	Opcional. Localizável. Um título exclusivo para o arranque da conversação. Tem de conter, pelo menos, um caráter não branco.

Exemplo de objeto de iniciadores de conversação

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

Objeto Actions

As ações são um objeto JSON opcional no manifesto. Funciona como uma entrada de programador e pode ser considerada como plug-ins.

O objeto de ação contém as seguintes propriedades.

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.

Exemplo de objeto de ações

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

Exemplo de manifesto do agente declarativo

Eis um exemplo de um ficheiro de manifesto de agente declarativo que utiliza a maioria das propriedades do manifesto descritas neste artigo.

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.2/schema.json",
  "version": "v1.2",
  "name": "Teams Toolkit declarative copilot",
  "description": "Declarative copilot created with Teams Toolkit",
  "instructions": "You are a repairs expert copilot. 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?"
    }
  ],
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "repairs-hub-api-plugin.json"
    }
  ],
  "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"
    }
  ]
}

Escrever instruções efetivas para agentes declarativos

Partilhar via

Esquema do agente declarativo 1.2 para Microsoft 365 Copilot

Alterações da versão anterior

Esquema JSON

Convenções

Referências relativas em URLs

Comprimento da cadeia

Propriedades não reconhecidas

Localização de cadeias

Objeto de manifesto do agente declarativo

Exemplo de objeto de manifesto de agente declarativo

Objeto Capacidades

Exemplo de capacidades

Objeto de pesquisa na Web

Objeto de site

Objeto oneDrive e SharePoint

Objeto Itens por IDs do SharePoint

Itens por objeto de URL

Objeto de conectores do Microsoft Graph

Objeto Connection

Objeto de arte gráfica

Objeto de iniciadores de conversação

Exemplo de objeto de iniciadores de conversação

Objeto Actions

Exemplo de objeto de ações

Exemplo de manifesto do agente declarativo

Comentários

Recursos adicionais

Partilhar via

Esquema do agente declarativo 1.2 para Microsoft 365 Copilot

Alterações da versão anterior

Esquema JSON

Convenções

Referências relativas em URLs

Comprimento da cadeia

Propriedades não reconhecidas

Localização de cadeias

Objeto de manifesto do agente declarativo

Exemplo de objeto de manifesto de agente declarativo

Objeto Capacidades

Exemplo de capacidades

Objeto de pesquisa na Web

Objeto de site

Objeto oneDrive e SharePoint

Objeto Itens por IDs do SharePoint

Itens por objeto de URL

Objeto de conectores do Microsoft Graph

Objeto Connection

Objeto de arte gráfica

Objeto de iniciadores de conversação

Exemplo de objeto de iniciadores de conversação

Objeto Actions

Exemplo de objeto de ações

Exemplo de manifesto do agente declarativo

Conteúdo relacionado

Comentários

Recursos adicionais