Schema des deklarativen Agents 1.0 für Microsoft 365 Copilot

Artikel
11/19/2024

In diesem Artikel wird das 1.0-Schema beschrieben, das vom Manifest des deklarativen Agents verwendet wird. Das Manifest ist ein maschinenlesbares Dokument, das ein LLM (Large Language Model) mit den erforderlichen Anweisungen, Kenntnissen und Aktionen bereitstellt, um sich auf die Behandlung einer ausgewählten Gruppe von Benutzerproblemen zu spezialisieren.

Wichtig

Die neueste Version des Manifestschemas des deklarativen Agents ist Version 1.2. Es wird empfohlen, dass neue Agents die neueste Schemaversion verwenden.

Deklarative Agenten sind wertvoll beim Verstehen und Generieren von menschenähnlichem Text, sodass sie für Aufgaben wie das Schreiben und Beantworten von Fragen vielseitig sind. Diese Spezifikation konzentriert sich auf das deklarative Agent-Manifest, das als strukturiertes Framework fungiert, um Die Funktionalitäten eines bestimmten Benutzers zu spezialisieren und zu verbessern.

JSON-Schema

Das in diesem Dokument beschriebene Schema finden Sie hier im JSON-Schemaformat.

Konventionen

Relative Verweise in URLs

Sofern nicht anders angegeben, können alle Eigenschaften, die URLs sind, relative Verweise sein. Relative Verweise im Manifestdokument sind relativ zur Position des Manifestdokuments.

Zeichenfolgenlänge

Sofern nicht anders angegeben, SOLLTEN alle Zeichenfolgeneigenschaften auf 4.000 Zeichen beschränkt sein. Diese Zeichenfolgenlänge verleiht keine akzeptable Größe für das gesamte Dokument. Implementierungen können ihre eigenen praktischen Grenzen für die Manifestlänge auferlegen.

Nicht erkannte Eigenschaften

Json-Objekte, die in diesem Dokument definiert sind, unterstützen nur die beschriebenen Eigenschaften. Nicht erkannte oder überflüssige Eigenschaften in einem JSON-Objekt SOLLTEN das gesamte Dokument ungültig machen.

Lokalisierung von Zeichenfolgen

Lokalisierbare Zeichenfolgen können einen Lokalisierungsschlüssel anstelle eines Literalwerts verwenden. Die Syntax ist [[key_name]], wobei key_name der Schlüsselname in der localizationKeys -Eigenschaft in Ihren Lokalisierungsdateien ist. Ausführliche Informationen zur Lokalisierung finden Sie unter Lokalisieren Ihres Agents.

Manifestobjekt des deklarativen Agents

Der Stamm des Manifestdokuments ist ein JSON-Objekt, das erforderliche Felder, Funktionen, Konversationsstarter und Aktionen abdeckt.

Das Manifestobjekt des deklarativen Agents enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`version`	String	Erforderlich. Die Schemaversion. Muss auf `v1.0` festgelegt werden.
`id`	String	Optional.
`name`	String	Erforderlich. Lokalisierbar. Der Name des deklarativen Agents. Sie MUSS mindestens ein Zeichen ohne Leerzeichen enthalten und muss maximal 100 Zeichen umfassen.
`description`	String	Erforderlich. Lokalisierbar. Die Beschreibung des deklarativen Agents. Sie MUSS mindestens ein Zeichen ohne Leerzeichen enthalten und darf maximal 1.000 Zeichen umfassen.
`instructions`	String	Erforderlich. Die detaillierten Anweisungen oder Richtlinien zum Verhalten des deklarativen Agents, seiner Funktionen und zu vermeidenden Verhaltensweisen. Sie MUSS mindestens ein Zeichen ohne Leerzeichen enthalten und DARF maximal 8.000 Zeichen umfassen.
`capabilities`	Array von Capabilities-Objekt	Optional. Enthält ein Array von -Objekten, die Funktionen des deklarativen Agents definieren. Es DARF NICHT mehr als eines jedes abgeleiteten Capabilities-Objekts im Array vorhanden sein.
`conversation_starters`	Array des Conversation-Starterobjekts	Optional. Titel und Text können lokalisiert werden. Eine Liste mit Beispielen für Fragen, die der deklarative Agent beantworten kann. Das Array DARF NICHT mehr als sechs Objekte enthalten.
`actions`	Array des Action-Objekts	Optional. Eine Liste von Objekten, die API-Plug-Ins identifizieren, die Aktionen bereitstellen, auf die der deklarative Agent zugreifen kann.

Beispiel für ein Manifestobjekt des deklarativen Agents

Der folgende JSON-Code ist ein Beispiel für erforderliche Felder in einem deklarativen Agent-Manifest.

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

Capabilities-Objekt

Das Capabilities-Objekt ist der Basistyp von Objekten in der capabilities -Eigenschaft im Manifestobjekt des deklarativen Agents. Mögliche Objekttypen sind:

Websuchobjekt
OneDrive- und SharePoint-Objekt
Microsoft Graph Connectors-Objekt

Beispiel für Funktionen

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

Websuchobjekt

Gibt an, dass der deklarative Agent das Web nach Erdungsinformationen durchsuchen kann.

Das Websuchobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`name`	String	Erforderlich. Muss auf `WebSearch` festgelegt werden.

OneDrive- und SharePoint-Objekt

Gibt an, dass der deklarative Agent sharePoint und OneDrive eines Benutzers nach Erdungsinformationen durchsuchen kann.

Das OneDrive- und SharePoint-Objekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`name`	String	Erforderlich. Muss auf `OneDriveAndSharePoint` festgelegt werden.
`items_by_sharepoint_ids`	Array von Elementen nach SharePoint-IDs-Objekt	Optional. Ein Array von -Objekten, die SharePoint- oder OneDrive-Quellen mithilfe von IDs identifizieren. Wenn sowohl die `items_by_sharepoint_ids` -Eigenschaft als auch die `items_by_url` -Eigenschaft nicht angegeben werden, sind alle OneDrive- und SharePoint-Quellen im organization für den deklarativen Agent verfügbar.
`items_by_url`	Array von Elementen nach URL-Objekt	Optional. Ein Array von Objekten, die SharePoint- oder OneDrive-Quellen anhand der URL identifizieren. Wenn sowohl die `items_by_sharepoint_ids` -Eigenschaft als auch die `items_by_url` -Eigenschaft nicht angegeben werden, sind alle OneDrive- und SharePoint-Quellen im organization für den deklarativen Agent verfügbar.

Elemente nach SharePoint-IDs-Objekt

Das Objekt Items by SharePoint IDs enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`site_id`	Zeichenfolge	Optional. Ein eindeutiger GUID-Bezeichner für eine SharePoint- oder OneDrive-Website.
`web_id`	Zeichenfolge	Optional. Ein eindeutiger GUID-Bezeichner für ein bestimmtes Web innerhalb einer SharePoint- oder OneDrive-Website.
`list_id`	Zeichenfolge	Optional. Ein eindeutiger GUID-Bezeichner für eine Liste innerhalb einer SharePoint- oder OneDrive-Website.
`unique_id`	Zeichenfolge	Optional. Ein eindeutiger GUID-Bezeichner, der verwendet wird, um eine bestimmte Entität oder Ressource darzustellen.

Tipp

Anweisungen zum Abrufen der eindeutigen Bezeichner für eine SharePoint- oder OneDrive-Ressource finden Sie unter Abrufen von Funktions-IDs für das manifest des deklarativen Agents.

Elemente nach URL-Objekt

Das Objekt Items by URL enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`url`	Zeichenfolge	Optional. Eine absolute URL zu einer SharePoint- oder OneDrive-Ressource.

Microsoft Graph-Connectors-Objekt

Gibt an, dass der deklarative Agent ausgewählte Microsoft Graph-Connectors nach Erdungsinformationen durchsuchen kann.

Das Microsoft Graph-Connectors-Objekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`name`	String	Erforderlich. Muss auf `GraphConnectors` festgelegt werden.
`connections`	Array des Connection-Objekts	Optional. Ein Array von -Objekten, die die Microsoft Graph-Connectors identifizieren, die für den deklarativen Agent verfügbar sind. Wenn diese Eigenschaft nicht angegeben wird, sind alle Microsoft Graph-Connectors im organization für den deklarativen Agent verfügbar.

Connection-Objekt

Identifiziert einen Microsoft Graph-Connector.

Das Verbindungsobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`connection_id`	String	Erforderlich. Der eindeutige Bezeichner des Microsoft Graph-Connectors.

Tipp

Anweisungen zum Abrufen des eindeutigen Bezeichners für einen Microsoft Graph-Connector finden Sie unter Abrufen von Funktions-IDs für das manifest des deklarativen Agents.

Unterhaltungsstarter-Objekt

Das Unterhaltungsstarter-Objekt ist im Manifest optional. Sie enthält Hinweise, die dem Benutzer angezeigt werden, um zu veranschaulichen, wie er mit dem deklarativen Agent beginnen kann.

Das Conversation Starter-Objekt enthält die folgenden Eigenschaften:

Eigenschaft	Typ	Beschreibung
`text`	String	Erforderlich. Lokalisierbar. Ein Vorschlag, den der Benutzer verwenden kann, um das gewünschte Ergebnis vom deklarativen Agent zu erhalten. Es MUSS mindestens ein Zeichen enthalten, das nicht weiß ist.
`title`	Zeichenfolge	Optional. Lokalisierbar. Ein eindeutiger Titel für den Unterhaltungsstart. Es MUSS mindestens ein Zeichen enthalten, das nicht weiß ist.

Conversation Starters-Objekt (Beispiel)

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

Actions-Objekt

Aktionen sind ein optionales JSON-Objekt im Manifest. Es fungiert als Entwicklereingabe und kann als Plug-Ins betrachtet werden.

Das Aktionsobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`id`	String	Erforderlich. Ein eindeutiger Bezeichner für die Aktion. Es kann eine GUID sein.
`file`	String	Erforderlich. Ein Pfad zum API-Plug-In-Manifest für diese Aktion.

Actions-Objektbeispiel

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

Beispiel für das Manifest des deklarativen Agents

Hier sehen Sie ein Beispiel für eine Manifestdatei des deklarativen Agents, die die meisten der in diesem Artikel beschriebenen Manifesteigenschaften verwendet.

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

Schreiben effektiver Anweisungen für deklarative Agents

Freigeben über

Schema des deklarativen Agents 1.0 für Microsoft 365 Copilot

JSON-Schema

Konventionen

Relative Verweise in URLs

Zeichenfolgenlänge

Nicht erkannte Eigenschaften

Lokalisierung von Zeichenfolgen

Manifestobjekt des deklarativen Agents

Beispiel für ein Manifestobjekt des deklarativen Agents

Capabilities-Objekt

Beispiel für Funktionen

Websuchobjekt

OneDrive- und SharePoint-Objekt

Elemente nach SharePoint-IDs-Objekt

Elemente nach URL-Objekt

Microsoft Graph-Connectors-Objekt

Connection-Objekt

Unterhaltungsstarter-Objekt

Conversation Starters-Objekt (Beispiel)

Actions-Objekt

Actions-Objektbeispiel

Beispiel für das Manifest des deklarativen Agents

Feedback

Zusätzliche Ressourcen

Freigeben über

Schema des deklarativen Agents 1.0 für Microsoft 365 Copilot

JSON-Schema

Konventionen

Relative Verweise in URLs

Zeichenfolgenlänge

Nicht erkannte Eigenschaften

Lokalisierung von Zeichenfolgen

Manifestobjekt des deklarativen Agents

Beispiel für ein Manifestobjekt des deklarativen Agents

Capabilities-Objekt

Beispiel für Funktionen

Websuchobjekt

OneDrive- und SharePoint-Objekt

Elemente nach SharePoint-IDs-Objekt

Elemente nach URL-Objekt

Microsoft Graph-Connectors-Objekt

Connection-Objekt

Unterhaltungsstarter-Objekt

Conversation Starters-Objekt (Beispiel)

Actions-Objekt

Actions-Objektbeispiel

Beispiel für das Manifest des deklarativen Agents

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen