Freigeben über

Schema des deklarativen Agents für Microsoft 365 Copilot

  • Artikel

In diesem Artikel wird eine Spezifikation beschrieben, die das Manifest des deklarativen Agents festlegt. 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.

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
id Zeichenfolge Optional.
name Zeichenfolge Erforderlich. Lokalisierbar. Der Name des deklarativen Agents. Sie MUSS mindestens ein Zeichen ohne Leerzeichen enthalten und muss maximal 100 Zeichen umfassen.
description Zeichenfolge Erforderlich. Lokalisierbar. Die Beschreibung des deklarativen Agents. Sie MUSS mindestens ein Zeichen ohne Leerzeichen enthalten und darf maximal 1.000 Zeichen umfassen.
instructions Zeichenfolge 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"
    },
    {
      "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 Zeichenfolge 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 Zeichenfolge 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 Zeichenfolge 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 Zeichenfolge 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 Zeichenfolge 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 Zeichenfolge Erforderlich. Ein eindeutiger Bezeichner für die Aktion. Es kann eine GUID sein.
file Zeichenfolge 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",
    "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"
                }
            ]
        }
    ]
}

Verwandte Inhalte