Schéma d’agent déclaratif 1.2 pour Microsoft 365 Copilot

Article
11/19/2024

Cet article décrit le schéma 1.2 utilisé par le manifeste de l’agent déclaratif. Le manifeste est un document lisible par ordinateur qui fournit un modèle LLM (Large Language Model) avec les instructions, les connaissances et les actions nécessaires pour se spécialiser dans la résolution d’un ensemble sélectionné de problèmes utilisateur.

Les agents déclaratifs sont utiles pour comprendre et générer du texte de type humain, ce qui les rend polyvalents pour des tâches telles que l’écriture et la réponse à des questions. Cette spécification est axée sur le manifeste d’agent déclaratif qui agit comme une infrastructure structurée pour se spécialiser et améliorer les fonctionnalités dont un utilisateur spécifique a besoin.

Modifications par rapport à la version précédente

Cette version de schéma introduit les modifications suivantes à partir de la version 1.0.

La sites propriété est ajoutée à l’objet de recherche web. Cela permet de limiter la fonctionnalité de recherche web aux sites autorisés.
La fonctionnalité d’illustration graphique a été ajoutée. Cette fonctionnalité permet à l’agent déclaratif de générer des images et des illustrations en fonction des entrées utilisateur.

Schéma JSON

Le schéma décrit dans ce document se trouve au format de schéma JSON ici.

Conventions

Références relatives dans les URL

Sauf indication contraire, toutes les propriétés qui sont des URL PEUVENT être des références relatives. Les références relatives dans le document manifeste sont relatives à l’emplacement du document manifeste.

Longueur de chaîne

Sauf indication contraire, toutes les propriétés de chaîne DOIVENT être limitées à 4 000 caractères. Cette longueur de chaîne ne confère aucune taille acceptable pour l’ensemble du document. Les implémentations sont libres d’imposer leurs propres limites pratiques sur la longueur du manifeste.

Propriétés non reconnues

Les objets JSON définis dans ce document prennent uniquement en charge les propriétés décrites. Les propriétés non reconnues ou superflues dans un objet JSON DOIVENT rendre l’intégralité du document non valide.

Localisation de chaîne

Les chaînes localisables peuvent utiliser une clé de localisation au lieu d’une valeur littérale. La syntaxe est [[key_name]], où key_name est le nom de clé dans la localizationKeys propriété dans vos fichiers de localisation. Pour plus d’informations sur la localisation, consultez Localiser votre agent.

Objet manifeste de l’agent déclaratif

La racine du document manifeste est un objet JSON qui couvre les champs, les fonctionnalités, les démarrages de conversation et les actions requis.

L’objet manifeste de l’agent déclaratif contient les propriétés suivantes.

Propriété	Type	Description
`version`	String	Obligatoire. Version du schéma. Doit être défini sur `v1.2`.
`id`	String	Facultatif.
`name`	String	Obligatoire. Localisables. Nom de l’agent déclaratif. Il DOIT contenir au moins un caractère nonwhitespace et doit comporter 100 caractères ou moins.
`description`	String	Obligatoire. Localisables. Description de l’agent déclaratif. Il DOIT contenir au moins un caractère nonwhitespace et doit comporter 1 000 caractères ou moins.
`instructions`	String	Obligatoire. Instructions détaillées ou instructions sur le comportement de l’agent déclaratif, ses fonctions et tous les comportements à éviter. Il DOIT contenir au moins un caractère nonwhitespace et doit contenir au maximum 8 000 caractères.
`capabilities`	Tableau de l’objet Capabilities	Optional. Contient un tableau d’objets qui définissent les fonctionnalités de l’agent déclaratif. Il NE DOIT PAS y avoir plus d’un de chaque type dérivé d’objet Capabilities dans le tableau.
`conversation_starters`	Tableau de l’objet de démarrage de conversation	Optional. Title et Text sont localisables. Liste d’exemples de questions auxquelles l’agent déclaratif peut répondre. Il NE DOIT PAS y avoir plus de six objets dans le tableau.
`actions`	Tableau de l’objet Action	Optional. Liste d’objets qui identifient les plug-ins d’API qui fournissent des actions accessibles à l’agent déclaratif.

Exemple d’objet manifeste d’agent déclaratif

Le code JSON suivant est un exemple de champs obligatoires dans un manifeste d’agent déclaratif.

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

Objet Capabilities

L’objet capabilities est le type de base des objets dans la capabilities propriété dans l’objet manifeste de l’agent déclaratif. Les types d’objets possibles sont les suivants :

Objet de recherche web
OneDrive et objet SharePoint
Objet Connecteurs Microsoft Graph
Objet d’illustration graphique

Exemple de fonctionnalités

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

Objet de recherche web

Indique que l’agent déclaratif peut rechercher des informations de base sur le web.

L’objet de recherche web contient les propriétés suivantes.

Propriété	Type	Description
`name`	String	Obligatoire. Doit être défini sur `WebSearch`.
`sites`	Tableau de l’objet Site	Optional. Tableau d’objets qui identifient les sites que l’agent est autorisé à rechercher. Si cette propriété est omise, tout l’agent est autorisé à effectuer des recherches sur tous les sites. Le tableau NE DOIT PAS contenir plus de quatre éléments.

Objet de site

Indique un site qu’un agent déclaratif peut rechercher du contenu.

L’objet site contient les propriétés suivantes.

Propriété	Type	Description
`url`	String	Obligatoire. URL absolue d’un site à rechercher. L’URL NE DOIT PAS contenir plus de 2 segments de chemin d’accès (par exemple, `https://contoso.com/projects/mark-8` est valide, `https://contoso.com/projects/mark-8/beta-program` n’est pas valide). L’URL NE DOIT pas contenir de paramètres de requête.

OneDrive et objet SharePoint

Indique que l’agent déclaratif peut rechercher des informations de base dans SharePoint et OneDrive d’un utilisateur.

L’objet OneDrive et SharePoint contient les propriétés suivantes.

Propriété	Type	Description
`name`	String	Obligatoire. Doit être défini sur `OneDriveAndSharePoint`.
`items_by_sharepoint_ids`	Tableau de l’objet Items by SharePoint IDs	Optional. Tableau d’objets qui identifient les sources SharePoint ou OneDrive à l’aide d’ID. Si les `items_by_sharepoint_ids` propriétés et `items_by_url` sont omises, toutes les sources OneDrive et Sharepoint dans le organization sont disponibles pour l’agent déclaratif.
`items_by_url`	Tableau d’éléments par objet URL	Optional. Tableau d’objets qui identifient les sources SharePoint ou OneDrive par URL. Si les `items_by_sharepoint_ids` propriétés et `items_by_url` sont omises, toutes les sources OneDrive et Sharepoint dans le organization sont disponibles pour l’agent déclaratif.

Items by SharePoint IDs object

L’objet Items by SharePoint IDs contient les propriétés suivantes.

Propriété	Type	Description
`site_id`	String	Facultatif. Identificateur GUID unique pour un site SharePoint ou OneDrive.
`web_id`	String	Facultatif. Identificateur GUID unique pour un site web spécifique au sein d’un site SharePoint ou OneDrive.
`list_id`	String	Facultatif. Identificateur GUID unique pour une liste au sein d’un site SharePoint ou OneDrive.
`unique_id`	String	Facultatif. Identificateur GUID unique utilisé pour représenter une entité ou une ressource spécifique.

Conseil

Pour obtenir des instructions sur l’obtention des identificateurs uniques d’une ressource SharePoint ou OneDrive, voir Récupération d’ID de fonctionnalités pour le manifeste d’agent déclaratif.

Items by URL object

L’objet Items by URL contient les propriétés suivantes.

Propriété	Type	Description
`url`	String	Facultatif. URL absolue d’une ressource SharePoint ou OneDrive.

Objet connecteurs Microsoft Graph

Indique que l’agent déclaratif peut rechercher des informations sur les connecteurs Microsoft Graph sélectionnés.

L’objet connecteurs Microsoft Graph contient les propriétés suivantes.

Propriété	Type	Description
`name`	String	Obligatoire. Doit être défini sur `GraphConnectors`.
`connections`	Tableau de l’objet Connection	Optional. Tableau d’objets qui identifient les connecteurs Microsoft Graph disponibles pour l’agent déclaratif. Si cette propriété est omise, tous les connecteurs Microsoft Graph dans le organization sont disponibles pour l’agent déclaratif.

Connection, objet

Identifie un connecteur Microsoft Graph.

L’objet connection contient les propriétés suivantes.

Propriété	Type	Description
`connection_id`	String	Obligatoire. Identificateur unique du connecteur Microsoft Graph.

Conseil

Pour obtenir des instructions sur l’obtention de l’identificateur unique d’un connecteur Microsoft Graph, consultez Récupération des ID de fonctionnalités pour le manifeste de l’agent déclaratif.

Objet d’illustration graphique

Indique que l’agent déclaratif peut créer des images et des illustrations en fonction de l’entrée de texte de l’utilisateur. Pour plus d’informations, consultez Générateur d’images.

L’objet graphique contient les propriétés suivantes.

Propriété	Type	Description
`name`	String	Obligatoire. Doit être défini sur `GraphicArt`.

Objet De démarrage de conversation

L’objet conversation starters est facultatif dans le manifeste. Il contient des indicateurs qui sont affichés à l’utilisateur pour montrer comment il peut commencer à utiliser l’agent déclaratif.

L’objet de démarrage de conversation contient les propriétés suivantes :

Propriété	Type	Description
`text`	String	Obligatoire. Localisables. Suggestion que l’utilisateur peut utiliser pour obtenir le résultat souhaité à partir de l’agent déclaratif. Il DOIT contenir au moins un caractère nonwhitespace.
`title`	String	Facultatif. Localisables. Titre unique pour le démarrage de conversation. Il DOIT contenir au moins un caractère nonwhitespace.

Exemple d’objet Conversation Starters

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

Objet Actions

Les actions sont un objet JSON facultatif dans le manifeste. Il agit comme une entrée de développeur et peut être considéré comme des plug-ins.

L’objet action contient les propriétés suivantes.

Propriété	Type	Description
`id`	String	Obligatoire. Identificateur unique de l’action. Il peut s’agir d’un GUID.
`file`	String	Obligatoire. Chemin d’accès au manifeste du plug-in d’API pour cette action.

Exemple d’objet Actions

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

Exemple de manifeste d’agent déclaratif

Voici un exemple de fichier manifeste d’agent déclaratif qui utilise la plupart des propriétés de manifeste décrites dans cet article.

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.2/schema.json",
  "version": "v1.2",
  "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",
      "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"
    }
  ]
}

Écrire des instructions efficaces pour les agents déclaratifs

Partager via

Schéma d’agent déclaratif 1.2 pour Microsoft 365 Copilot

Modifications par rapport à la version précédente

Schéma JSON

Conventions

Références relatives dans les URL

Longueur de chaîne

Propriétés non reconnues

Localisation de chaîne

Objet manifeste de l’agent déclaratif

Exemple d’objet manifeste d’agent déclaratif

Objet Capabilities

Exemple de fonctionnalités

Objet de recherche web

Objet de site

OneDrive et objet SharePoint

Items by SharePoint IDs object

Items by URL object

Objet connecteurs Microsoft Graph

Connection, objet

Objet d’illustration graphique

Objet De démarrage de conversation

Exemple d’objet Conversation Starters

Objet Actions

Exemple d’objet Actions

Exemple de manifeste d’agent déclaratif

Commentaires

Ressources supplémentaires

Partager via

Schéma d’agent déclaratif 1.2 pour Microsoft 365 Copilot

Modifications par rapport à la version précédente

Schéma JSON

Conventions

Références relatives dans les URL

Longueur de chaîne

Propriétés non reconnues

Localisation de chaîne

Objet manifeste de l’agent déclaratif

Exemple d’objet manifeste d’agent déclaratif

Objet Capabilities

Exemple de fonctionnalités

Objet de recherche web

Objet de site

OneDrive et objet SharePoint

Items by SharePoint IDs object

Items by URL object

Objet connecteurs Microsoft Graph

Connection, objet

Objet d’illustration graphique

Objet De démarrage de conversation

Exemple d’objet Conversation Starters

Objet Actions

Exemple d’objet Actions

Exemple de manifeste d’agent déclaratif

Contenu connexe

Commentaires

Ressources supplémentaires