Esquema de agente declarativo para Microsoft 365 Copilot

Este artigo descreve uma especificação que estabelece o 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.

Esquema JSON

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

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.

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

Exemplo de capacidades

{
  "capabilities": [
    {
      "name": "WebSearch"
    },
    {
      "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"
        }
      ]
    }
  ]
}

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.

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.

Objeto Itens por IDs do SharePoint

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

Itens por objeto de URL

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

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.

Objeto Connection

Identifica um conector do Microsoft Graph.

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

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:

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.

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.0/schema.json",
    "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"
        },
        {
            "name": "OneDriveAndSharePoint",
            "items_by_url": [
                {
                    "url": "https://contoso.sharepoint.com/sites/ProductSupport"
                }
            ]
        },
        {
            "name": "GraphConnectors",
            "connections": [
                {
                    "connection_id": "foodStore"
                }
            ]
        }
    ]
}

Conteúdo relacionado

• Escrever instruções efetivas para agentes declarativos