Schema des deklarativen Agents 1.2 für Microsoft 365 Copilot
In diesem Artikel wird das 1.2-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.
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.
Änderungen gegenüber der vorherigen Version
Mit dieser Schemaversion werden die folgenden Änderungen gegenüber Version 1.0 eingeführt.
- Die
sites
-Eigenschaft wird dem Websuchobjekt hinzugefügt. Dadurch kann die Websuchfunktion auf zulässige Websites beschränkt werden. - Die Grafikfunktion wurde hinzugefügt. Diese Funktion ermöglicht es dem deklarativen Agent, Bilder und Grafiken basierend auf Benutzereingaben zu generieren.
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.2 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:
Beispiel für Funktionen
{
"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"
}
]
}
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. |
sites |
Array des Site-Objekts | Optional. Ein Array von -Objekten, die Websites identifizieren, die der Agent durchsuchen darf. Wenn diese Eigenschaft nicht angegeben wird, darf der gesamte Agent alle Websites durchsuchen. Das Array DARF NICHT mehr als vier Elemente enthalten. |
Websiteobjekt
Gibt eine Website an, die ein deklarativer Agent nach Inhalten suchen kann.
Das Websiteobjekt enthält die folgenden Eigenschaften.
Eigenschaft | Typ | Beschreibung |
---|---|---|
url |
String | Erforderlich. Eine absolute URL zu einer Website, die nach Inhalten gesucht werden soll. Die URL DARF NICHT mehr als 2 Pfadsegmente enthalten (z. B https://contoso.com/projects/mark-8 . ist gültig, https://contoso.com/projects/mark-8/beta-program ungültig). Die URL DARF KEINE Abfrageparameter enthalten. |
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.
Grafikobjekt
Gibt an, dass der deklarative Agent Bilder und Grafiken basierend auf der Texteingabe des Benutzers erstellen kann. Weitere Informationen finden Sie unter Imagegenerator.
Das Grafikobjekt enthält die folgenden Eigenschaften.
Eigenschaft | Typ | Beschreibung |
---|---|---|
name |
String | Erforderlich. Muss auf GraphicArt festgelegt werden. |
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.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"
}
]
}