Freigeben über

Copilot-Agents sind Apps für Microsoft 365

  • Artikel

Wichtig

  • API-Plug-Ins werden derzeit nur als Aktionen in deklarativen Agents unterstützt. Sie sind in Microsoft 365 Copilot nicht aktiviert. Ein Beispiel zum Hinzufügen eines API-Plug-Ins zu einem deklarativen Agent finden Sie unter Hinzufügen eines Plug-Ins.
  • Die Funktion ist standardmäßig in allen Microsoft 365 Copilot lizenzierten Mandanten aktiviert. Administratoren können diese Funktionalität auf Benutzer- und Gruppenbasis deaktivieren und steuern, wie einzelne Plug-Ins für die Verwendung genehmigt werden und welche Plug-Ins aktiviert sind. Weitere Informationen finden Sie unter Verwalten von Copilot-Agents in integrierten Apps.

Wenn Sie einen Copilot-Agent erstellen, erstellen Sie auch eine App für Microsoft 365. Apps für Microsoft 365 teilen sich ein gemeinsames Manifestschema- und Paketformat sowie einheitliche Verteilungs- und Verwaltungsprozesse und -tools. Das Endergebnis ist, dass Ihre Apps und Copilot-Agents eine möglichst breite Zielgruppe erreichen und kontextbezogen im Workflow Ihrer Benutzer angezeigt werden.

Dieser Artikel führt Sie durch die wichtigsten Teile des Microsoft 365-App-Modells für die Entwicklung von Copilot-Agents.

App-Modell für Microsoft 365

Das Microsoft 365-Ökosystem entwickelt sich zu einer integrierten App-Plattform, auf der Sie ein gemeinsames App-Modell verwenden können, um Ihre App zu definieren und zu packen. Was als Möglichkeit zum Erweitern von Teams-Apps für die Ausführung in anderen Microsoft 365-Anwendungen begann, wurde seitdem erweitert, um die Verteilung von Microsoft Graph-Connectors, Outlook-Add-Ins und jetzt Copilot-Agents zu unterstützen.

App-Paket

Das App-Paket für Microsoft 365, einschließlich Copilot-Agents, ist eine ZIP-Datei, die eine oder mehrere Konfigurationsdateien (Manifestdateien) und Ihre App-Symbole enthält. Ihre App-Logik und Der Datenspeicher werden an anderer Stelle gehostet und von der Microsoft 365-Hostanwendung über HTTPS aufgerufen. Sie übermitteln das App-Paket an Ihren Administrator, um es in Ihrem organization oder in Partner Center zu veröffentlichen, um es in Microsoft AppSource zu veröffentlichen.

Ein App-Paket enthält mindestens Folgendes:

  • das App-Manifest (manifest.json), das app-Konfiguration, Funktionen, erforderliche Ressourcen und wichtige Attribute beschreibt,
  • ein großes Farbsymbol (color.png), ein vollfarbiges 92x92-Symbol zum Anzeigen Ihres Agents in der Microsoft Copilot-Benutzeroberfläche und im Speicher und
  • ein kleines Kontursymbol (outline.png), ein 32x32-Symbol mit transparentem Hintergrund (derzeit nicht in Copilot verwendet, aber erforderlich, um die Überprüfung zu bestehen)

Das App-Paket kann auch deklarative Agent- und API-Plug-In-Definitionen sowie Lokalisierungsdateien für andere unterstützte Sprachen enthalten.

Diagramm, das die Anatomie eines Microsoft 365-App-Pakets zeigt: App-Manifest (.json-Datei) + Symbole (Farbe und Gliederung .png Dateien), die in eine .zip-Datei eingeschlossen sind

App-Symbole

Ihr App-Paket muss sowohl eine Farb- als auch eine Gliederungsversion Ihres App-Symbols enthalten, wie .png Dateien. Diese Symbole haben bestimmte Größenanforderungen, um die Speicherüberprüfung zu bestehen.

Hinweis

Derzeit wird nur das Farbsymbol verwendet, um Copilot-Agents für den Endbenutzer darzustellen (sowohl als Store-Eintrag als auch innerhalb Microsoft 365 Copilot Benutzeroberfläche), aber beim Übermitteln des App-Pakets an Microsoft AppSource ist weiterhin ein Gliederungssymbol erforderlich.

Weitere Entwurfsanleitungen zu Farb- und Kontursymbolen für das Microsoft 365-App-Paket, App-Symbole für Teams Store und App-Leiste.

Farbsymbol

Das Farbsymbol stellt Ihren Agent in den Microsoft Copilot Ui und in produktinternen App Stores (Teams, Outlook, Microsoft 365) dar.

Beispielbild eines App-Farbsymbols mit einer Gesamtsymbolgröße von 192 x 192 Pixeln mit enthaltenem Hintergrund und einem zentralen Bereich von 96 x 96 Pixeln mit dem

Ihr Farbsymbol:

  • Kann eine beliebige Farbe sein
  • Muss insgesamt 192 x 192 Pixel groß sein
  • Sollte für das Symbol selbst 96 x 96 Pixel groß sein (um 48 Pixel Abstand für Hostszenarien zu ermöglichen, in denen es zugeschnitten ist)
  • Muss auf einem voll durchgezogenen oder vollständig transparenten quadratischen Hintergrund sitzen

Kontursymbol

Das Gliederungssymbol wird verwendet, um angeheftete und/oder aktive Apps auf der Teams-App-Leiste darzustellen. Es wird derzeit nicht für Copilot-Agents verwendet, ist aber dennoch erforderlich, damit das App-Paket die Überprüfung bestehen kann.

Beispielbild eines App-Gliederungssymbols mit einer Größe von 32 x 32 Pixeln und einer weißen Symbolumrandung mit transparentem Hintergrund

Ihr Gliederungssymbol:

  • Muss 32 x 32 Pixel groß sein
  • Muss entweder weiß mit transparentem Hintergrund oder transparent mit weißem Hintergrund sein
  • Darf keine zusätzliche Auffüllung um das Symbol enthalten.

App-Manifest

Das App-Manifest für Microsoft 365 ist eine JSON-Datei, die die Funktionen und Merkmale Ihrer App beschreibt. Im Kern ist das App-Manifest für Microsoft 365 das Schema zum Erstellen von Teams-Apps, aber es wurde seitdem (seit Version 1.13) erweitert, um Apps zu definieren, die zusätzlich zu Teams auf Microsoft 365-Hosts ausgeführt werden.

Wenn Sie Microsoft Copilot Studio verwenden, um einen deklarativen Agent zu erstellen, wird das App-Manifest basierend auf den Informationen generiert, die Sie während des Erstellungsprozesses angeben.

Jedes App-Manifest muss die folgenden Informationen enthalten:

Manifestfeld Beschreibung
version Die Versionsnummer der App im Format MAJOR. KLEINER. PATCH (Semver-Standard ).
id Der eindeutige generierte Bezeichner für diese App im Microsoft Application Registration Portal (apps.dev.microsoft.com) in GUID-Form.
Entwickler Informationen zum Entwickler, einschließlich Name, Website und Links zu Datenschutzrichtlinien und Nutzungsbedingungen. Für Apps, die an AppSource übermittelt werden, müssen die Werte mit dem Wert übereinstimmen, der im Partner Center-App-Übermittlungsformular angegeben ist.
name Der Name Ihrer App, der endbenutzern auf dem Anwendungshost angezeigt wird.
description Kurze und lange Beschreibungen Ihrer App für Benutzer. Für Apps, die an AppSource übermittelt werden, müssen diese Werte mit den Informationen in Ihrem AppSource-Eintrag übereinstimmen.
Ikonen Relative Pfade zu Farb- und Gliederungssymboldateien.
accentColor Eine Farbe, die mit und als Hintergrund für Ihre Gliederungssymbole verwendet werden soll, im RGB-Hexadezimalwert, z. B #4464ee. .
Definitionen für bestimmte App-Funktionen Eine Definition für jede App-Funktion, z. B. persönliche Registerkarten (staticTabs), Nachrichtenerweiterungen (composeExtensions) oder Bots. Deklarative Agents und API-Plug-Ins werden unter dem Knoten copilotAgents definiert.

Das folgende Beispiel zeigt ein App-Manifest mit Platzhalterabschnitten am Ende für Nachrichtenerweiterungs- und deklarative Agent-App-Funktionen:

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.18/MicrosoftTeams.schema.json",
    "manifestVersion": "1.18",
    "version": "1.0.0",
    "id": "00000000-0000-0000-0000-000000000000",
    "developer": {
        "name": "Northwind Traders",
        "websiteUrl": "https://www.example.com",
        "privacyUrl": "https://www.example.com/termofuse",
        "termsOfUseUrl": "https://www.example.com/privacy"
    },
    "icons": {
        "color": "Northwind-Logo-196.png",
        "outline": "Northwind-Logo-32.png"
    },
    "name": {
        "short": "Northwind Inventory",
        "full": "Northwind Inventory App"
    },
    "description": {
        "short": "App allows you to find and update product inventory information",
        "full": "Northwind Inventory is the ultimate tool for managing your product inventory. With its intuitive interface and powerful features, you'll be able to easily find your products by name, category, inventory status, and supplier city. You can also update inventory information with the app."
    },
    "accentColor": "#3690E9",
    "composeExtensions": {
        ...
    },
    "copilotAgents": {
        ...
    }
}

Weitere Informationen finden Sie in der Schemareferenz zum App-Manifest für Entwicklervorschau.

copilotAgents Definitionen

Deklarative Agents und API-Plug-Ins verfügen jeweils über eigene Definitionsschemas. Auf die Definitionsdatei für einen deklarativen Agent wird vom copilotAgents -Objekt des App-Manifests verwiesen.

Das folgende Beispiel zeigt, wie auf einen deklarativen Agent verwiesen wird:

    "copilotAgents": {
        "declarativeAgents": [
            {
                "id": "agent1",
                "file": "declarativeAgent1.json"
            }
        ]
    },

Auf die Definition eines API-Plug-Ins wird in der deklarativen Agent-Definition verwiesen.

Diagramm: App-Manifest, das auf ein deklaratives Agent- und API-Plug-In-Manifest verweist. Das Manifest des deklarativen Agents verweist auf ein anderes API-Plug-In-Manifest.

Beachten Sie Folgendes:

  • Derzeit wird nur eine deklarative Agent-Definition pro App-Manifest unterstützt. Pro deklarativem Agent wird nur ein API-Plug-In unterstützt.

  • Wenn Sie Copilot Studio verwenden, um Copilot-Agents zu erstellen, wird für jeden als Teil der gesamten App-Manifestgenerierung eine eindeutige id generiert. Wenn Sie Agents mit dem Teams-Toolkit oder Ihrer eigenen IDE erstellen, weisen Sie den id selbst gemäß Ihren eigenen Konventionen oder Anzeigenamen zu.

Manifest des deklarativen Agents

Das Manifest des deklarativen Agents enthält Anweisungen für Copilot-Antworten, Beispieleingabeaufforderungen für Konversationsstarter, Datenquellen, die für das Grounding verwendet werden, und eine Liste der Aktionen (API-Plug-In-Skills), die der Agent ausführen kann.

Weitere Informationen finden Sie unter Manifestschema des deklarativen Agents für Microsoft 365 Copilot.

API-Plug-In-Manifest

Das API-Plug-In-Manifest beschreibt die Funktionen des Plug-Ins, einschließlich der unterstützten APIs und der Vorgänge, die es ausführen kann. Sie enthält auch Metadaten wie Name, Beschreibung, Version und einen Verweis auf die OpenAPI-Definition der REST-APIs, mit denen sie interagiert. Auf API-Plug-Ins kann aus einem deklarativen Agent-Manifest verwiesen werden, das in der deklarativen Agent-Benutzeroberfläche verwendet werden soll.

Weitere Informationen finden Sie unter API-Plug-In-Manifestschema für Microsoft 365 Copilot.

Lokalisieren Ihres Agents

Die Art und Weise, wie Sie einen Copilot-Agent lokalisieren, unterscheidet sich geringfügig von der Lokalisierung anderer Funktionen (z. B. Registerkarten, Bots und Nachrichtenerweiterungen) im App-Manifest.

Sie verwenden dieselbe Lokalisierungsdatei (pro Sprache) sowohl für die klassischen Teams-App-Funktionen als auch für den Copilot-Agent. Während auf alle anderen App-Manifestfelder mithilfe von JSONPath-Ausdrücken in den Sprachdateien verwiesen wird, wird auf Copilot-Agent-bezogene Felder einfach mithilfe von Wörterbuchschlüsseln verwiesen. Im Gegensatz zu klassischen Teams-App-Funktionen, die Standardsprachzeichenfolgen im App-Manifest selbst verwenden, benötigen lokalisierte Copilot-Agents eine Sprachdatei sowohl für die Standardsprache als auch für jede zusätzliche Sprache.

Diagramm: Beziehung zwischen App-Manifest, deklarativem Agent-Manifest und einer Sprachdatei zum Lokalisieren eines Copilot-Agents

Die folgenden Schritte zeigen, wie Sie zusätzliche Sprachen (über die Standardeinstellung hinaus) für Ihre Copilot-Agents unterstützen.

1. Aktualisieren Sie Ihre Copilot-Agent-Manifeste mit tokenisierten Schlüsseln.

Aktualisieren Sie Ihre Manifeste des deklarativen Agents und/oder API-Plug-Ins mit tokenisierten Schlüsseln (angegeben mit doppelten eckigen Klammern, z. B [[PLUGIN_NAME]]. ) für alle Feldwerte, die Sie lokalisieren möchten. Lokalisierungsschlüssel entsprechen diesem regulären Ausdruck: ^[a-zA-Z_][a-zA-Z0-9_]*$

Das folgende Beispiel zeigt ein deklaratives Agent-Manifest mit tokenisierten Werten für seinen Namen und seine Beschreibung:

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
    "name": "[[DA_Name]]",
    "description": "[[DA_Description]]",
    "instructions": "# You are an assistant..."
}

2. Hinzufügen localizationInfo zu Ihrem App-Manifest

Fügen Sie ihrem App-Manifest den localizationInfo Abschnitt mit Sprachtags und relativen Pfaden zu jeder unterstützten Sprachdatei in Ihrem App-Paket hinzu.

Wenn Ihr Copilot-Agent mehrere Sprachen unterstützt, müssen Sie eine eigenständige Sprachdatei für jede unterstützte Sprache angeben, einschließlich Ihrer Standardsprache.

Das folgende Beispiel zeigt den Abschnitt "Lokalisierungsinformationen" in einem App-Manifest:

"localizationInfo": {
    "defaultLanguageTag": "en",
    "defaultLanguageFile": "en.json",
    "additionalLanguages": [
        {
            "languageTag": "fr",
            "file": "fr.json"
        }
    ]
},

Wenn Ihr Copilot-Agent keine zusätzlichen Sprachen unterstützt, werden die Standardsprachzeichenfolgen in der App-Manifestdatei selbst dargestellt. (App-Pakete in einer sprache erfordern keine separate Sprachdatei für die Standardsprache.)

3. Erstellen einer Lokalisierungsdatei für jede zusätzliche Sprache

Erstellen Sie eine Lokalisierungsdatei für jede zusätzliche unterstützte Sprache mit Werten für die tokenisierten Schlüssel. Verwenden Sie dabei die Dateinamen (für defaultLanguageFile und file Eigenschaften), die im App-Manifest aus dem vorherigen Schritt angegeben wurden.

Das folgende Beispiel zeigt eine Sprachdatei mit fr.jsonlokalisierten Zeichenfolgen für einen Copilot-Agent und persönliche Registerkarten:

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json`",
    "name.short": "Agent de Communications",
    "name.full": "Agent pour les Communications",
    "description.short": "Outils pour les professionnels de la communication",
    "description.full": "Outils pour les professionnels de la communication Contoso, y compris la galerie de ressources et les assistants personnels",
    "localizationKeys": {
        "DA_Name": "Agent de Communications",
        "DA_Description": "Un assistant pour les professionnels de la communication et des relations publiques chez Contoso."
    },
    "staticTabs[0].name": "Accueil",
    "staticTabs[1].name": "Galerie de ressources",
    "staticTabs[2].name": "À propos de Contoso"
}

Lokalisierbare Felder im App-Manifest

Geben Sie für jede Sprachdatei die folgenden Eigenschaften aus dem App-Lokalisierungsschema an, die lokalisiert werden müssen:

Manifestfeld Beschreibung Maximale Länge Erforderlich
@schema Die URL zum Lokalisierungsschema. Verwenden Sie für Copilot-Agents devPreview: https://developer.microsoft.com/en-us/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json. Die Manifestschemaversion muss sowohl für App-Manifestdateien als auch für Lokalisierungsdateien identisch sein. ✔️
name.short Ersetzt den Kurznamen aus dem App-Manifest durch den angegebenen Wert. 30 Zeichen ✔️
name.full Ersetzt den vollständigen Namen aus dem App-Manifest durch den angegebenen Wert. 100 Zeichen ✔️
description.short Ersetzt die kurze Beschreibung aus dem App-Manifest durch den angegebenen Wert. 80 Zeichen ✔️
description.full Ersetzt die vollständige Beschreibung aus dem App-Manifest durch den angegebenen Wert. 4.000 Zeichen ✔️
Schlüssel-Wert-Paare für lokalisierte Zeichenfolgen in Copilot-Agents Verwenden Sie für Copilot-Agents tokenisierte Schlüssel (wie in der App manifest.jsonangegeben, aber ohne doppelte eckige Klammern) mit ihren lokalisierten Werten. Beispiel: "DA_Name": "Agent de Communications"
JSONPath/Wert-Paare für lokalisierte Zeichenfolgen anderer App-Komponenten Verwenden Sie für alle anderen (klassischen Teams)-App-Komponenten JSONPath-Ausdrücke als Schlüssel für die lokalisierten Werte. Beispiel: "staticTabs[0].name": "Accueil"

Weitere Informationen finden Sie unter Lokalisieren Ihrer App (Microsoft Teams) und lokalisierungsschemareferenz.

Lokalisierbare Felder im Manifest des deklarativen Agents

Die folgenden Felder können innerhalb des Manifests des deklarativen Agents lokalisiert werden:

Manifestfeld Beschreibung Maximale Länge Erforderlich
name Der Name des deklarativen Agents. Muss mindestens ein Zeichen ohne Leerzeichen enthalten. 100 Zeichen ✔️
description Die Beschreibung des deklarativen Agents. Muss mindestens ein Zeichen ohne Leerzeichen enthalten. 1.000 Zeichen ✔️
conversation_starters Eine Liste (Array) von Beispielen für Fragen, die der deklarative Agent beantworten kann, wobei jedes Beispiel durch ein -Objekt mit title und textdargestellt wird, die beide lokalisierbar sind. 6 Objekte im Array

Weitere Informationen finden Sie unter Manifestreferenz für deklarative Agents.

Lokalisierbare Felder im API-Plug-In-Manifest

Die folgenden Felder können innerhalb des API-Plug-In-Manifests lokalisiert werden:

Manifestfeld Beschreibung Maximale Länge Erforderlich
name_for_human Ein kurzer, für Menschen lesbarer Name für das Plug-In. Sie muss mindestens ein Zeichen ohne Leerzeichen enthalten. 20 Zeichen ✔️
description_for_model Die Beschreibung des Plug-Ins, das für das Modell bereitgestellt wird, einschließlich dessen, wofür das Plug-In vorgesehen ist und unter welchen Umständen seine Funktionen relevant sind. 2048 Zeichen
description_for_human Eine lesbare Beschreibung des Plug-Ins. 100 Zeichen ✔️
logo_url Eine URL, die zum Abrufen eines Logos verwendet wird, das vom Orchestrator verwendet werden kann.
legal_info_url Eine absolute URL, die ein Dokument mit den Nutzungsbedingungen für das Plug-In sucht.
privacy_policy_url Eine absolute URL, die ein Dokument mit der Datenschutzrichtlinie für das Plug-In sucht.

Weitere Informationen finden Sie unter API-Plug-In-Manifestreferenz.

Siehe auch