Compartir a través de

Esquema de agente declarativo 1.4 para Microsoft 365 Copilot

En este artículo se describe el esquema 1.4 usado por el manifiesto del agente declarativo. El manifiesto es un documento legible por máquina que proporciona un modelo de lenguaje grande (LLM) con las instrucciones, conocimientos y acciones necesarios para especializarse en solucionar un conjunto selecto de problemas de usuario. El manifiesto de aplicación de Microsoft 365 hace referencia a los manifiestos de agente declarativo dentro de un paquete de aplicación. Para obtener más información, consulte la referencia del manifiesto de aplicación de Microsoft 365.

Los agentes declarativos son valiosos para comprender y generar texto similar a humano, lo que los hace versátiles para tareas como escribir y responder preguntas. Esta especificación se centra en el manifiesto del agente declarativo que actúa como un marco estructurado para especializar y mejorar las funcionalidades que necesita un usuario específico.

Cambios de la versión anterior

Esta versión del esquema presenta los siguientes cambios de la versión 1.3:

Esquema JSON

El esquema descrito en este documento se puede encontrar en formato de esquema JSONaquí.

Convenios

Referencias relativas en direcciones URL

A menos que se especifique lo contrario, todas las propiedades que son direcciones URL PUEDEN ser referencias relativas. Las referencias relativas en el documento de manifiesto son relativas a la ubicación del documento de manifiesto.

Longitud de cadena

A menos que se especifique lo contrario, todas las propiedades de cadena DEBEN estar limitadas a 4 000 caracteres. Esta longitud de cadena no confiere ningún tamaño aceptable para todo el documento. Las implementaciones pueden imponer sus propios límites prácticos sobre la longitud del manifiesto.

Propiedades no reconocidas

Los objetos JSON definidos en este documento solo admiten las propiedades descritas. Las propiedades no reconocidas o extrañas en cualquier objeto JSON DEBEN hacer que todo el documento no sea válido.

Localización de cadenas

Las cadenas localizables pueden usar una clave de localización en lugar de un valor literal. La sintaxis es [[key_name]], donde key_name es el nombre clave de la localizationKeys propiedad de los archivos de localización. Para obtener más información sobre la localización, consulte Localización del agente.

Objeto de manifiesto del agente declarativo

La raíz del documento de manifiesto es un objeto JSON que cubre los campos, funcionalidades, inicios de conversación y acciones necesarios.

El objeto de manifiesto del agente declarativo contiene las siguientes propiedades.

Propiedad Tipo Descripción
version Cadena Obligatorio. Versión del esquema. Se debe configurar como v1.4.
id Cadena Opcional.
name Cadena Obligatorio. Localizable. Nombre del agente declarativo. DEBE contener al menos un carácter nowhitespace y DEBE tener 100 caracteres o menos.
description Cadena Obligatorio. Localizable. Descripción del agente declarativo. DEBE contener al menos un carácter nowhitespace y DEBE tener 1000 caracteres o menos.
instructions Cadena Obligatorio. Instrucciones detalladas o instrucciones sobre cómo debe comportarse el agente declarativo, sus funciones y cualquier comportamiento que se evite. DEBE contener al menos un carácter nowhitespace y DEBE tener 8000 caracteres o menos.
capabilities Matriz del objeto Capabilities Opcional. Contiene una matriz de objetos que definen las funcionalidades del agente declarativo. NO DEBE haber más de uno de cada tipo derivado de objeto Capabilities en la matriz.
conversation_starters Matriz del objeto de inicio de conversación Opcional. Título y texto son localizables. Una lista de ejemplos de preguntas que el agente declarativo puede responder. NO DEBE haber más de 12 objetos en la matriz.
actions Matriz del objeto Action Opcional. Lista de objetos que identifican complementos de API que proporcionan acciones accesibles para el agente declarativo.
behavior_overrides El comportamiento invalida el objeto Opcional. Contiene valores de configuración que modifican el comportamiento del agente.

Ejemplo de objeto de manifiesto de agente declarativo

El código siguiente es un ejemplo de campos obligatorios dentro de un manifiesto 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 Capabilities

El objeto capabilities es el tipo base de objetos de la capabilities propiedad en el objeto de manifiesto del agente declarativo. Los posibles tipos de objeto son:

Nota:

Los agentes declarativos con cualquier funcionalidad que no sea la búsqueda web solo están disponibles para los usuarios de los inquilinos que permiten el uso medido o los inquilinos que tienen una licencia de Microsoft 365 Copilot.

Ejemplo de objeto Capabilities

{
  "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": "ScenarioModels",
      "models": [
        {
          "id": "model_id"
        }
      ]
    }
  ]
}

Objeto de búsqueda web

Indica que el agente declarativo puede buscar información de conexión a tierra en la web.

El objeto de búsqueda web contiene las siguientes propiedades.

Propiedad Tipo Descripción
name Cadena Obligatorio. Se debe establecer en WebSearch.
sites Matriz del objeto Site Opcional. Matriz de objetos que identifican sitios en los que el agente puede buscar. Si se omite esta propiedad, todo el agente puede buscar en todos los sitios. La matriz NO DEBE contener más de cuatro elementos.

Nota:

Para obtener más información sobre los datos, la privacidad y la seguridad de la búsqueda web en Microsoft 365 Copilot Chat y Microsoft 365 Copilot, consulte Datos, privacidad y seguridad para la búsqueda web.

Objeto del sitio

Indica un sitio en el que un agente declarativo puede buscar contenido.

El objeto de sitio contiene las siguientes propiedades.

Propiedad Tipo Descripción
url Cadena Obligatorio. Dirección URL absoluta a un sitio en el que se va a buscar contenido. La dirección URL NO DEBE contener más de dos segmentos de ruta de acceso (por ejemplo, https://contoso.com/projects/mark-8 es válido, https://contoso.com/projects/mark-8/beta-program no es válido). La dirección URL NO DEBE contener ningún parámetro de consulta.

OneDrive y el objeto de SharePoint

Indica que el agente declarativo puede buscar información de base en SharePoint y OneDrive de un usuario.

El objeto OneDrive y SharePoint contiene las siguientes propiedades.

Propiedad Tipo Descripción
name Cadena Obligatorio. Se debe establecer en OneDriveAndSharePoint.
items_by_sharepoint_ids Matriz de elementos por objeto de identificadores de SharePoint Opcional. Matriz de objetos que identifican orígenes de SharePoint o OneDrive mediante identificadores. Si se omiten las items_by_sharepoint_idsitems_by_url propiedades y , todos los orígenes de OneDrive y SharePoint de la organización están disponibles para el agente declarativo.
items_by_url Matriz de elementos por objeto URL Opcional. Matriz de objetos que identifican orígenes de SharePoint o OneDrive por dirección URL. Si se omiten las items_by_sharepoint_idsitems_by_url propiedades y , todos los orígenes de OneDrive y SharePoint de la organización están disponibles para el agente declarativo.

Para obtener información sobre cómo optimizar el contenido de SharePoint para Copilot, vea Optimizar la recuperación de contenido de SharePoint.

Objeto Items by SharePoint IDs (Elementos por identificadores de SharePoint)

El objeto items by SharePoint IDs contiene las siguientes propiedades.

Propiedad Tipo Descripción
site_id Cadena Opcional. Identificador GUID único para un sitio de SharePoint o OneDrive.
web_id Cadena Opcional. Identificador GUID único para una web específica dentro de un sitio de SharePoint o OneDrive.
list_id Cadena Opcional. Identificador GUID único para una lista dentro de un sitio de SharePoint o OneDrive.
unique_id Cadena Opcional. Identificador GUID único que se usa para representar una entidad o recurso específico.
search_associated_sites Booleano Opcional. Indica si se va a habilitar la búsqueda de sitios asociados. Este valor solo es aplicable cuando el site_id valor hace referencia a una instancia de SharePoint HubSite.
part_type Cadena Opcional. Indica el tipo de elemento part_id al que hace referencia. Este valor solo es aplicable cuando el part_id valor está presente. Los valores posibles son: OneNotePart.
part_id Cadena Opcional. Identificador GUID único que se usa para representar parte de un elemento de SharePoint, como una página de OneNote.

Sugerencia

Para obtener información sobre cómo obtener los identificadores únicos de un recurso de SharePoint o OneDrive, vea Recuperación de identificadores de funcionalidades para el manifiesto de agente declarativo.

Elementos por objeto URL

Los elementos por objeto URL contienen las siguientes propiedades.

Propiedad Tipo Descripción
url Cadena Opcional. Dirección URL absoluta a un recurso de SharePoint o OneDrive.

Copilot connectors (objeto)

Indica que el agente declarativo puede buscar información de puesta a tierra en los conectores copilot seleccionados.

El objeto de conectores de Copilot contiene las siguientes propiedades.

Propiedad Tipo Descripción
name Cadena Obligatorio. Se debe establecer en GraphConnectors.
connections Matriz del objeto Connection Opcional. Matriz de objetos que identifican los conectores de Copilot disponibles para el agente declarativo. Si se omite esta propiedad, todos los conectores de Copilot de la organización están disponibles para el agente declarativo.
Connection (objeto)

Identifica un conector copilot.

El objeto de conexión contiene las siguientes propiedades.

Propiedad Tipo Descripción
connection_id Cadena Obligatorio. Identificador único del conector de Copilot.
additional_search_terms Cadena Opcional. Una consulta de lenguaje de consulta de palabras clave (KQL) para filtrar elementos en función de los campos del esquema de la conexión.
items_by_external_id Matriz del objeto de identificador de elemento Opcional. Especifica elementos específicos por identificador en el conector de Copilot que están disponibles para el agente.
items_by_path Matriz del objeto Path Opcional. Filtra los elementos disponibles para el agente por rutas de acceso de elementos (la itemPathetiqueta semántica en los elementos).
items_by_container_name Matriz del objeto Nombre de contenedor Opcional. Filtra los elementos disponibles para el agente por nombre de contenedor (la containerName etiqueta semántica en los elementos).
items_by_container_url Matriz del objeto de dirección URL del contenedor Opcional. Filtra los elementos disponibles para el agente por dirección URL del contenedor (la containerUrl etiqueta semántica en los elementos).

Sugerencia

Para obtener instrucciones sobre cómo obtener el identificador único de un conector de Copilot, consulte Recuperación de identificadores de funcionalidades para el manifiesto de agente declarativo.

Objeto de identificador de elemento

Identifica un elemento externo por su identificador.

El objeto de identificador de elemento contiene las siguientes propiedades.

Propiedad Tipo Descripción
item_id Cadena Obligatorio. Identificador único del elemento externo.
Path (objeto)

Identifica un elemento externo por su ruta de acceso.

El objeto path contiene las siguientes propiedades.

Propiedad Tipo Descripción
path Cadena Obligatorio. Ruta de acceso (itemPath valor de etiqueta semántica) del elemento externo.
Objeto de nombre de contenedor

Identifica un contenedor por su nombre.

El objeto de nombre de contenedor contiene las siguientes propiedades.

Propiedad Tipo Descripción
container_name Cadena Obligatorio. Nombre del contenedor (containerName valor de etiqueta semántica) del elemento externo.
Objeto de dirección URL del contenedor

Identifica un contenedor por su dirección URL.

El objeto de dirección URL del contenedor contiene las siguientes propiedades.

Propiedad Tipo Descripción
container_url Cadena Obligatorio. Dirección URL del contenedor (containerUrl valor de etiqueta semántica) del elemento externo.

Objeto de arte gráfico

Indica que el agente declarativo puede crear imágenes y arte en función de la entrada de texto del usuario. Para obtener más información, vea Generador de imágenes.

El objeto de arte gráfico contiene las siguientes propiedades.

Propiedad Tipo Descripción
name Cadena Obligatorio. Se debe establecer en GraphicArt.

Objeto de intérprete de código

Indica que el agente declarativo puede generar y ejecutar código de Python para resolver problemas matemáticos complejos, analizar datos, generar visualizaciones y mucho más. Para obtener más información, vea Intérprete de código.

El objeto de intérprete de código contiene las siguientes propiedades.

Propiedad Tipo Descripción
name Cadena Obligatorio. Se debe establecer en CodeInterpreter.

Dataverse (objeto)

Indica que el agente declarativo puede buscar datos de tablas en Microsoft Dataverse.

El objeto Dataverse contiene las siguientes propiedades.

Propiedad Tipo Descripción
name Cadena Obligatorio. Se debe establecer en Dataverse.
knowledge_sources Matriz de orígenes de conocimiento Opcional. Matriz de objetos que contienen los identificadores, aptitudes y nombres de tabla para que las instancias de Dataverse incluyan como conocimiento.
Objeto de orígenes de conocimiento

Contiene información sobre las instancias de Dataverse que se van a incluir como conocimiento.

El objeto de orígenes de conocimiento contiene las siguientes propiedades.

Propiedad Tipo Descripción
host_name Cadena Obligatorio. Identificador único para el host en Dataverse.
skill Cadena Identificador único que define la configuración de cómo interactúa el agente con el conocimiento de Dataverse.
tables Matriz de tablas Matriz de tablas para limitar el conocimiento del agente.
Tables (objeto)

Contiene las tablas para limitar el conocimiento del agente.

El objeto tables contiene la siguiente propiedad.

Propiedad Tipo Descripción
table Cadena Obligatorio. Identificador único de la tabla.

Objeto de mensajes de Teams

Indica que el agente declarativo puede buscar en canales de Teams, equipos, reuniones, chats 1:1 y chats de grupo.

El objeto de mensajes de Teams contiene las siguientes propiedades.

Propiedad Tipo Descripción
name Cadena Obligatorio. Se debe establecer en TeamsMessages.
urls Matriz de direcciones URL de Teams Opcional. Matriz de objetos que identifican las direcciones URL de los canales de Teams, los chats de reuniones, los chats de grupo o los chats 1:1 disponibles para el agente declarativo. NO DEBE haber más de cinco objetos en la matriz. La omisión de esta propiedad permite una búsqueda sin ámbito a través de todos los canales, reuniones, chats 1:1 y chats grupales.
Objeto URL de Teams

Identifica un canal, un equipo o un chat de reunión de Teams.

El objeto de dirección URL de Teams contiene las siguientes propiedades.

Propiedad Tipo Descripción
url Cadena Obligatorio. Una dirección URL de Teams bien formatada que se vincula a un canal de Teams, un chat de reunión, un chat de grupo o un chat 1:1.

Email (objeto)

Indica que el agente declarativo puede buscar mensajes de correo electrónico en los buzones a los que el usuario tiene acceso.

El objeto de correo electrónico contiene las siguientes propiedades.

Propiedad Tipo Descripción
name Cadena Obligatorio. Se debe establecer en Email.
shared_mailbox Cadena Opcional. Dirección SMTP de un buzón compartido.
folders Cadena Opcional. Matriz de objetos folder_id .
Folders (objeto)

Contiene las carpetas para limitar el conocimiento del agente.

El objeto folders contiene la siguiente propiedad.

Propiedad Tipo Descripción
folder_id Cadena Obligatorio. Nombre de carpeta conocido o identificador de carpeta de la carpeta a la que se va a hacer referencia.

Objeto de persona

Indica que el agente declarativo puede buscar información sobre las personas de la organización.

El objeto people contiene la siguiente propiedad.

Propiedad Tipo Descripción
name Cadena Obligatorio. Se debe establecer en People.

Objeto De modelos de escenario

Indica que el agente declarativo puede usar modelos específicos de la tarea.

El objeto de modelos de escenario contiene las siguientes propiedades.

Propiedad Tipo Descripción
name Cadena Obligatorio. Se debe establecer en ScenarioModels.
models Matriz del objeto Model Obligatorio. Matriz de objetos que identifica los modelos específicos de la tarea disponibles para el agente declarativo.
Model (objeto)

Identifica un modelo específico de la tarea.

El objeto de modelo contiene la siguiente propiedad.

Propiedad Tipo Descripción
id Cadena Obligatorio. Identificador único del modelo.

Objeto Conversation Starters

El objeto starters de conversación es opcional en el manifiesto. Contiene sugerencias que se muestran al usuario para demostrar cómo pueden empezar a usar el agente declarativo.

El objeto de inicio de conversación contiene las siguientes propiedades:

Propiedad Tipo Descripción
text Cadena Obligatorio. Localizable. Sugerencia que el usuario puede usar para obtener el resultado deseado del agente declarativo. DEBE contener al menos un carácter nowhitespace.
title Cadena Opcional. Localizable. Un título único para el inicio de la conversación. DEBE contener al menos un carácter nowhitespace.

Ejemplo de objeto conversation starters

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

Actions (objeto)

Las acciones son un objeto JSON opcional en el manifiesto. Actúa como una entrada del desarrollador y se puede considerar como complementos.

El objeto action contiene las siguientes propiedades.

Propiedad Tipo Descripción
id Cadena Obligatorio. Identificador único de la acción. PUEDE ser un GUID.
file Cadena Obligatorio. Ruta de acceso al manifiesto del complemento de API para esta acción.

Ejemplo de objeto Actions

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

El comportamiento invalida el objeto

Objeto JSON opcional que contiene valores de configuración que invalidan el comportamiento del agente.

El objeto de invalidación de comportamiento contiene las siguientes propiedades.

Propiedad Tipo Descripción
suggestions Objeto Suggestions Opcional. Contiene los valores de configuración de la característica de sugerencias.
special_instructions Objeto de instrucciones especiales Opcional. Contiene la configuración para insertar instrucciones especiales en el símbolo del sistema.

Objeto Suggestions

Objeto JSON opcional que contiene los valores de configuración de la característica de sugerencias.

El objeto suggestions contiene la siguiente propiedad.

Propiedad Tipo Descripción
disabled Booleano Obligatorio. Si se establece en true, la característica de sugerencias se deshabilitará. El valor predeterminado es false.

Objeto de instrucciones especiales

Un objeto JSON opcional que contiene la configuración para insertar instrucciones especiales en el símbolo del sistema.

El objeto de declinación de responsabilidades contiene la siguiente propiedad.

Propiedad Tipo Descripción
discourage_model_knowledge Booleano Obligatorio. Si se establece en true, se desaconseja que el agente use el conocimiento del modelo al generar respuestas. El valor predeterminado es false.

Ejemplo de manifiesto de agente declarativo

En el ejemplo siguiente se muestra un archivo de manifiesto de agente declarativo que usa la mayoría de las propiedades de manifiesto descritas en este artículo.

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
  "version": "v1.4",
  "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?"
    }
  ],
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "repairs-hub-api-plugin.json"
    }
  ],
  "behavior_overrides": {
    "suggestions": {
      "disabled": true
    },
    "special_instructions": {
      "discourage_model_knowledge": true
    }
  },
  "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": "People"
    },
    {
      "name": "ScenarioModels",
      "models": [
        {
          "id": "model_id"
        }
      ]
    }
  ]
}

Contenido relacionado