Esquema do agente declarativo 1.2 para Microsoft 365 Copilot

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. O manifesto de aplicação do Microsoft 365 referencia manifestos de agente declarativos dentro de um pacote de aplicação. Para obter detalhes, veja a referência do manifesto da aplicação Microsoft 365.

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 do agente declarativo 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. Esta propriedade 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.
• A capacidade de intérprete de código foi adicionada. Esta capacidade permite ao agente declarativo gerar e executar código Python.

Esquema JSON

Pode encontrar o esquema descrito neste documento 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 podem 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, limite todas as propriedades de cadeia a 4000 carateres. Este comprimento de cadeia não define um tamanho aceitável para todas as propriedades de cadeia no documento. As implementações podem definir os seus próprios limites práticos no comprimento do manifesto.

Propriedades não reconhecidas

Os objetos JSON definidos neste documento suportam apenas as propriedades descritas. As propriedades não reconhecidas ou desnecessárias em qualquer objeto JSON tornam 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 do agente declarativo

O código seguinte mostra um exemplo dos 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"
}

@agent(
  "Repairs agent",
  "This declarative agent needs to look at my Service Now and Jira tickets/instances to help me keep track of open items"
)
@instructions(
  "This declarative agent needs to look at my Service Now and Jira tickets/instances to help me keep track of open items"
)
namespace MyAgent {

}

Objeto Capacidades

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

• Objeto de pesquisa na Web
• Objeto oneDrive e SharePoint
• Objeto de conectores Copilot
• Objeto de arte gráfica
• Objeto de interpretador de código

Exemplo de objeto 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"
    }
  ]
}

namespace MyAgent {
  op webSearch is AgentCapabilities.WebSearch<Sites = [
    {
        url: "https://contoso.com"
    }
  ]>;

  op od_sp is AgentCapabilities.OneDriveAndSharePoint<
    ItemsBySharePointIds = [
      {
        siteId: "bc54a8cc-8c2e-4e62-99cf-660b3594bbfd";
        webId: "a5377427-f041-49b5-a2e9-0d58f4343939";
        listId: "78A4158C-D2E0-4708-A07D-EE751111E462";
        itemId: "304fcfdf-8842-434d-a56f-44a1e54fbed2";
      }
    ],
    ItemsByUrl = [
      {
        url: "https://contoso.sharepoint.com/teams/admins/Documents/Folders1"
      }
    ]
  >;

  op copilotConnectors is AgentCapabilities.CopilotConnectors<Connections = [
    {
        connectionId: "jiraTickets"
    }
  ]>;

  op graphicArt is AgentCapabilities.GraphicArt;

  op codeInterpreter is AgentCapabilities.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.

Objeto de site

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

O objeto do site contém a seguinte propriedade.

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.

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

Objeto Itens por IDs do SharePoint

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

Itens por objeto de URL

Os itens por objeto URL contêm a seguinte propriedade.

Objeto de conectores Copilot

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

O objeto conectores Copilot contém as seguintes propriedades.

Objeto Connection

Identifica um conector Copilot.

O objeto de ligação contém a seguinte propriedade.

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 a seguinte propriedade.

Objeto de 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, veja Interpretador de código.

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

Objeto de iniciadores de conversação

O objeto de iniciadores de conversação é opcional no manifesto. Contém sugestões que o agente apresenta ao utilizador para mostrar como pode 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?"
    }
  ]
}

@conversationStarter(#{
  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. Atuam como entrada do programador e podem ser considerados plug-ins.

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

Exemplo de objeto de ações

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

@service
@server("https://jsonplaceholder.typicode.com")
@actions(#{
  nameForHuman: "Posts APIs",
  descriptionForHuman: "Manage blog post items on JSON Placeholder APIs.",
  descriptionForModel: "Read, create, update and delete blog post items on the JSON Placeholder APIs."
})
namespace PostsAPI {
  // All operations from the actions
}

Exemplo de manifesto do agente declarativo

O exemplo seguinte mostra 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": "Microsoft 365 Agents Toolkit declarative copilot",
  "description": "Declarative copilot created with Agents 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 Agents Toolkit?"
    },
    {
      "title": "Getting Help",
      "text": "How can I get help with Agents 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"
    }
  ]
}

Conteúdo relacionado

• Escrever instruções efetivas para agentes declarativos
• Referência do manifesto da aplicação Microsoft 365