Esquema de agente declarativo para Microsoft 365 Copilot

En este artículo se describe una especificación que establece 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.

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.

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.

Ejemplo de objeto de manifiesto de agente declarativo

El siguiente JSON 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:

• Objeto de búsqueda web
• OneDrive y el objeto de SharePoint
• Microsoft Graph Connectors (objeto)

Ejemplo de funcionalidades

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

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.

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

El objeto Items by SharePoint IDs contiene las siguientes propiedades.

Elementos por objeto URL

El objeto Items by URL contiene las siguientes propiedades.

Objeto de conectores de Microsoft Graph

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

El objeto conectores de Microsoft Graph contiene las siguientes propiedades.

Connection (objeto)

Identifica un conector de Microsoft Graph.

El objeto de conexión contiene las siguientes propiedades.

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:

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.

Ejemplo de objeto Actions

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

Ejemplo de manifiesto de agente declarativo

Este es un ejemplo de 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.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"
                }
            ]
        }
    ]
}

Contenido relacionado

• Escribir instrucciones eficaces para agentes declarativos