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. Das Microsoft 365-App-Manifest verweist auf deklarative Agent-Manifeste innerhalb eines App-Pakets. Weitere Informationen finden Sie in der Referenz zum Microsoft 365-App-Manifest.

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 Funktionen 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. Mit dieser Eigenschaft 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.
• Die Funktion "Codeinterpreter " wurde hinzugefügt. Diese Funktion ermöglicht es dem deklarativen Agent, Python-Code zu generieren und auszuführen.

JSON-Schema

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

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 zum Speicherort des Manifestdokuments.

Zeichenfolgenlänge

Sofern nicht anders angegeben, beschränken Sie alle Zeichenfolgeneigenschaften auf 4.000 Zeichen. Diese Zeichenfolgenlänge legt keine akzeptable Größe für alle Zeichenfolgeneigenschaften im Dokument fest. Implementierungen können ihre eigenen praktischen Grenzwerte für die Manifestlänge festlegen.

Nicht erkannte Eigenschaften

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

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.

Beispiel für ein Manifestobjekt des deklarativen Agents

Der folgende Code zeigt ein Beispiel für die erforderlichen Felder in einem deklarativen Agentmanifest.

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

}

Capabilities-Objekt

Das Capabilities-Objekt ist der Basistyp für Objekte in der capabilities -Eigenschaft des Manifestobjekts des deklarativen Agents. Mögliche Objekttypen sind:

• Websuchobjekt
• OneDrive- und SharePoint-Objekt
• Copilot-Connectors-Objekt
• Grafikobjekt
• Codeinterpreterobjekt

Beispiel für ein Capabilities-Objekt

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

Websuchobjekt

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

Das Websuchobjekt enthält die folgenden Eigenschaften.

Websiteobjekt

Gibt eine Website an, die ein deklarativer Agent nach Inhalten suchen kann.

Das Websiteobjekt enthält die folgende Eigenschaft.

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.

Informationen zum Optimieren von SharePoint-Inhalten für Copilot finden Sie unter Optimieren des Abrufs von SharePoint-Inhalten.

Elemente nach SharePoint-IDs-Objekt

Das Element nach SharePoint-IDs-Objekt enthält die folgenden Eigenschaften.

Elemente nach URL-Objekt

Das Element nach URL-Objekt enthält die folgende Eigenschaft.

Copilot-Connectors-Objekt

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

Das Copilot Connectors-Objekt enthält die folgenden Eigenschaften.

Connection-Objekt

Identifiziert einen Copilot-Connector.

Das Verbindungsobjekt enthält die folgende Eigenschaft.

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

Codeinterpreterobjekt

Gibt an, dass der deklarative Agent Python-Code generieren und ausführen kann, um komplexe mathematische Probleme zu lösen, Daten zu analysieren, Visualisierungen zu generieren und vieles mehr. Weitere Informationen finden Sie unter Codeinterpreter.

Das Codeinterpreterobjekt enthält die folgende Eigenschaft.

Unterhaltungsstarter-Objekt

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

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

Conversation Starters-Objekt (Beispiel)

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

Aktionen sind ein optionales JSON-Objekt im Manifest. Sie dienen als Entwicklereingabe und können als Plug-Ins betrachtet werden.

Das Aktionsobjekt enthält die folgenden Eigenschaften.

Actions-Objektbeispiel

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

Beispiel für das Manifest des deklarativen Agents

Das folgende Beispiel zeigt 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": "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"
    }
  ]
}

Verwandte Inhalte

• Schreiben effektiver Anweisungen für deklarative Agents
• Referenz zum Microsoft 365-App-Manifest