Esquema de agente declarativo 1.2 para Microsoft 365 Copilot

En este artículo se describe el esquema 1.2 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 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 de esquema presenta los siguientes cambios de la versión 1.0.

• La sites propiedad se agrega al objeto de búsqueda web. Esta propiedad permite que la funcionalidad de búsqueda web se limite a los sitios permitidos.
• Se agregó la funcionalidad de arte gráfico . Esta funcionalidad permite al agente declarativo generar imágenes y arte en función de la entrada del usuario.
• Se agregó la funcionalidad del intérprete de código . Esta funcionalidad permite al agente declarativo generar y ejecutar código de Python.

Esquema JSON

Puede encontrar el esquema descrito en este documento 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, limite todas las propiedades de cadena a 4000 caracteres. Esta longitud de cadena no establece un tamaño aceptable para todas las propiedades de cadena del documento. Las implementaciones pueden establecer sus propios límites prácticos en 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 hacen 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

En el código siguiente se muestra un ejemplo de los campos necesarios en 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"
}

@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 Capabilities

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

• Objeto de búsqueda web
• OneDrive y el objeto de SharePoint
• Copilot connectors (objeto)
• Objeto de arte gráfico
• Objeto de intérprete de código

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

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

Objeto del sitio

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

El objeto de sitio contiene la siguiente propiedad.

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.

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.

Elementos por objeto URL

Los elementos por objeto URL contienen la siguiente propiedad.

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.

Connection (objeto)

Identifica un conector copilot.

El objeto de conexión contiene la siguiente propiedad.

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 la siguiente propiedad.

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 la siguiente propiedad.

Objeto Conversation Starters

El objeto starters de conversación es opcional en el manifiesto. Contiene sugerencias que el agente muestra al usuario para mostrar cómo puede empezar a trabajar con 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?"
    }
  ]
}

@conversationStarter(#{
  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úan como entrada del desarrollador y se pueden considerar como complementos.

El objeto action contiene las siguientes propiedades.

Ejemplo de objeto Actions

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

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

Contenido relacionado

• Escribir instrucciones eficaces para agentes declarativos
• Referencia del manifiesto de aplicación de Microsoft 365