Kombinieren von Copilot-Agents mit Office-Add-Ins (Vorschau)

Hinweis

In diesem Artikel wird davon ausgegangen, dass Sie mit deklarativen Copilot-Agents vertraut sind. Wenn Sie dies nicht sind, beginnen Sie mit Folgendem:

• Übersicht über deklarative Agents für Microsoft 365 Copilot.
• Agents sind Apps für Microsoft 365.

Das Einschließen eines Microsoft 365 Copilot-Agents in ein Office-Add-In bietet zwei Vorteile:

• Copilot wird zu einer Oberfläche in natürlicher Sprache für die Funktionalität des Add-Ins.
• Der Agent kann Parameter an das javaScript übergeben, das er aufruft. Dies ist nicht möglich, wenn ein Funktionsbefehl über eine Schaltfläche oder ein Menüelement aufgerufen wird.

Sie können sich ein Office-Add-In auch als Skill in einem Copilot-Agent vorstellen. Da Office-Add-Ins die Office JavaScript-Bibliothek zum Ausführen von Lese- und Schreibvorgängen für Office-Dokumente verwenden, werden diese Vorgänge zu Aktionen im Copilot-Agent.

Szenarien

Im Folgenden finden Sie einige ausgewählte Möglichkeiten, wie das Hinzufügen eines Copilot-Agents den Wert eines Add-Ins für Benutzer erhöht.

• Verwenden des Add-Ins: Wenn ein Benutzer mehrere Schritte oder Aufgaben mit dem Add-In ausführen muss, um ein Ziel zu erreichen, kann die Chatoberfläche von Copilot den Prozess der ersten Schritte mit dem Add-In vereinfachen. Stellen Sie sich beispielsweise eine Anwaltskanzlei vor, die über eine Liste von Fragen verfügen muss, die zu jedem von ihr vorbereiteten Lease beantwortet werden müssen. Das Erstellen dieser Liste von Fragen kann zeitaufwändig und arbeitsintensiv sein. Ein Copilot-Agent, der die Office JavaScript-Bibliothek verwendet, kann jedoch aufgefordert werden, eine erste Entwurfsliste mit Fragen zu erstellen und sie in ein Word Dokument einzufügen.

• Inhaltsanalyse: Ein Agent kann verwendet werden, um den Inhalt eines Dokuments oder einer Kalkulationstabelle zu analysieren und je nachdem, was er findet, Maßnahmen zu ergreifen. Es folgen einige Beispiele.

  • Ein Agent analysiert eine Anforderung für einen Vorschlag und ruft dann die Antworten auf Fragen im RFP von einem Back-End-System ab. Der Benutzer fordert den Agent einfach auf, "Die Antworten, die Sie kennen, auf die Fragen einzugeben".
  • Ein Agent analysiert ein Dokument oder eine Tabelle in einer Kalkulationstabelle auf Inhalte, die impliziert, dass bestimmte Aktionen ausgeführt werden müssen, entweder im Dokument selbst oder an anderer Stelle in den Geschäftssystemen des Kunden. Der Benutzer sagt möglicherweise" "Überprüfen Sie das Dokument auf elemente, die ich in der Überwachungsliste verpasst habe."

• Vertrauenswürdige Einfügung von Daten: Wenn Sie eine typische KI-Engine mit einer Frage auffordern, werden die gefundenen Informationen kombiniert und eine Antwort erstellt. ein Prozess, der zu Ungenauigkeiten führen kann. Ein Copilot-Agent, der auf einem Add-In basiert, kann jedoch Daten unverändert aus einer vertrauenswürdigen Quelle einfügen. Beispiele:

  • Stellen Sie sich ein Add-In vor, das das Einfügen rechtlicher Recherchen in Word ermöglicht, wo es dann bearbeitet werden kann. Ein Benutzer fragt den Agenten: "Unter welchen Umständen kann eine Vermietung von Wohnraum in Indiana einseitig vom Vermieter gebrochen werden?" Das Add-In ruft dann unveränderte Inhalte aus Präzedenzfällen und Statuten ab.
  • Stellen Sie sich ein Add-In vor, das den Bestand digitaler Ressourcen verwaltet. Im Copilot-Agent-Chat fordert ein Benutzer folgendes auf: "Fügen Sie eine Tabelle mit unseren Farbfotos mit dem Namen jedes Fotos ein, der Anzahl der Heruntergeladenen und der Größe in Megabyte, sortiert in der Reihenfolge der meisten heruntergeladenen Fotos." Das Add-In ruft diese Daten dann unverändert aus dem Datensatzsystem ab und fügt die Tabelle in ein Excel-Arbeitsblatt ein.

Die Beziehung von Copilot-Agents zum Add-In-Framework

Ein Copilot-Agent ist eine Schnittstelle in natürlicher Sprache für ein Add-In.

Ein Add-In kann nur als Skill in einem Copilot-Agent konfiguriert werden. Es muss keinen Aufgabenbereich, benutzerdefinierte Menübandschaltflächen oder benutzerdefinierte Menüs enthalten. Aber es kann jede dieser Möglichkeiten haben, zusätzlich zu einem Copilot-Skill. Der beste Ansatz hängt von den Benutzerszenarien ab, die das Add-In aktivieren sollte.

• Wenn das Add-In einfache, schnelle Aktionen bereitstellen soll, für die keine Parameter übergeben werden müssen, schließen Sie benutzerdefinierte Menübandschaltflächen oder Menüs, sogenannte Add-In-Befehle, in das Add-In ein.
• Wenn das Add-In eine Dashboard Erfahrung benötigt, der Benutzer Einstellungen konfigurieren muss, Metadaten zum Inhalt des Office-Dokuments anzeigen muss oder aus anderen Gründen eine seitenähnliche Oberfläche benötigt, fügen Sie einen Aufgabenbereich in das Add-In ein.
• Wenn das Add-In komplexe Aktionen bereitstellen muss, die parameter erfordern, die zur Laufzeit übergeben werden oder eine Schnittstelle in natürlicher Sprache benötigen, schließen Sie einen Copilot-Agent ein.

Hinweis

• Derzeit können nur Excel-, PowerPoint- und Word-Add-Ins als Skill in Copilot konfiguriert werden. Wir arbeiten daran, Outlook zu unterstützen.
• Copilot-Agents werden in Office für Mac derzeit nicht unterstützt.
• Ein Add-In muss das einheitliche Manifest verwenden, damit Microsoft 365 als Skill in Copilot konfiguriert wird.
• Ein Inhalts-Add-In kann kein Skill in Copilot sein.

Hauptaufgaben

Es gibt zwei Hauptaufgaben beim Konfigurieren eines Add-Ins als Copilot-Skill, die analog zu den beiden Aufgaben zum Konfigurieren von Funktionsbefehlen für ein Add-In sind.

• Erstellen Sie JavaScript-Funktionen, die die Aktionen des Agents implementieren.
• Verwenden Sie JSON, um für Office und die JavaScript-Runtimes die Namen dieser Funktionen anzugeben.

JSON-Konfiguration

Die Konfiguration eines Add-Ins als Copilot-Skill erfordert drei JSON-formatierte Dateien, die in den folgenden Unterabschnitten beschrieben werden.

Einheitliches Manifest für Microsoft 365

Es gibt zwei Teile des Manifests, die Sie konfigurieren. Erstellen Sie zunächst ein Aktionsobjekt, das die JavaScript-Funktion identifiziert, die von der Aktion aufgerufen wird. Es folgt ein Beispiel (ohne überflüssiges Markup). Beachten Sie die folgenden Aspekte in diesem Code.

• Die Eigenschaft "page" gibt die URL der Webseite an, die ein eingebettetes Skripttag enthält, das wiederum die URL der JavaScript-Datei angibt, in der die Funktion definiert ist. Dieselbe Datei enthält einen Aufruf der Office.actions.associate-Methode , um die Funktion einer Aktions-ID zuzuordnen.
• Die "actions.id" -Eigenschaft im Manifest ist dieselbe Aktions-ID, die an den Aufruf von associateübergeben wird.
• Die "actions.type" -Eigenschaft ist auf "executeDataFunction" festgelegt. Dies ist der Typ, der Parameter akzeptieren und von Copilot aufgerufen werden kann.

"extensions": [

    ...

    "runtimes": [
        {
            "id": "CommandsRuntime",
            "type": "general",
            "code": {
                "page": "https://localhost:3000/commands.html"
            },
            "lifetime": "short",
            "actions": [
                {
                    "id": "fillcolor",
                    "type": "executeDataFunction",
                }
            ]
        }
    ]
]

Erstellen Sie anschließend ein deklaratives Agent-Objekt, das die Datei identifiziert, die die detaillierte Konfiguration des Agents enthält. Es folgt ein Beispiel.

"copilotAgents": {
    "declarativeAgents": [
        {
        "id": "ContosoCopilotAgent",
        "file": "declarativeAgent.json"
        }
    ]
}

Die Referenzdokumentation für das MANIFEST-JSON finden Sie unter Microsoft 365 app manifest schema reference (Referenz zum Microsoft 365-App-Manifestschema).

Konfiguration des deklarativen Agents

Die Agent-Konfigurationsdatei enthält Anweisungen für den Agent und gibt eine oder mehrere API-Plug-In-Konfigurationsdateien an, die die detaillierte Konfiguration der Aktionen des Agents enthalten. Es folgt ein Beispiel. Beachten Sie Folgendes zu diesem JSON-Code.

• Der Unterhaltungsstarter wird im Chatbereich von Copilot angezeigt.
• Die "actions.id" -Eigenschaft in dieser Datei ist die Sammel-ID aller Funktionen in der datei, die in angegeben ist "actions.file". Es muss nicht mit im "actions.id" Manifest übereinstimmen.

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json",
    "version": "v1.5",
    "name": "Excel Add-in + Agent",
    "description": "Agent for working with Excel cells.",
    "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
    "conversation_starters": [
        {
            "title": "Change cell color",
            "text": "I want to change the color of cell B2 to orange"
        }
    ],
    "actions": [
        {
            "id": "localExcelPlugin",
            "file": "Excel-API-local-plugin.json"
        }
    ]
}

Die Referenzdokumentation für deklarative Agents finden Sie unter Deklarative Agent-Schema 1.5 für Microsoft 365 Copilot.

Konfiguration des Copilot-API-Plug-Ins

Die API-Plug-In-Konfigurationsdatei gibt die "Funktionen" des Plug-Ins im Sinne von Agentaktionen an, nicht javaScript-Funktionen, einschließlich der Anweisungen für die Aktion. Außerdem wird die JavaScript-Runtime für Copilot konfiguriert. Es folgt ein Beispiel. Beachten Sie zu diesem JSON-Code Folgendes:

• Der "functions.name" muss mit der "extensions.runtimes.actions.id" -Eigenschaft im Add-In-Manifest übereinstimmen.
• und "reasoning.description""reasoning.instructions" verweisen auf eine JavaScript-Funktion, nicht auf eine REST-API.
• Die "responding.instructions" -Eigenschaft stellt nur Anleitungen für Copilot zur Reaktion bereit. Es werden keine Grenzwerte oder strukturellen Anforderungen für die Antwort gesetzt.
• Das "runtimes.run_for_functions" Array muss entweder die gleiche Zeichenfolge wie "functions.name" oder eine entsprechende Zeichenfolge enthalten.
• Die "runtimes.spec.local_endpoint" -Eigenschaft gibt an, dass die JavaScript-Funktion, die der Zeichenfolge "fillcolor" zugeordnet ist, in einem Office-Add-In und nicht in einem REST-Endpunkt verfügbar ist.
• Die "runtimes.spec.allowed_host" -Eigenschaft gibt an, dass der Agent nur in Excel sichtbar sein soll.
• Die "runtimes.auth.type" -Eigenschaft ist für Office-Add-In-Agents immer "None".

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
    "schema_version": "v2.3",
    "name_for_human": "Excel Add-in + Agent",
    "description_for_human": "Add-in Actions in Agents",
    "namespace": "addinfunction",
    "functions": [
        {
            "name": "fillcolor",
            "description": "fillcolor changes a single cell location to a specific color.",
            "parameters": {
                "type": "object",
                "properties": {
                    "cell": {
                        "type": "string",
                        "description": "A cell location in the format of A1, B2, etc.",
                        "default" : "B2"
                    },
                    "color": {
                        "type": "string",
                        "description": "A color in hex format, e.g., #30d5c8",
                        "default" : "#30d5c8"
                    }
                },
                "required": ["cell", "color"]
            },
            "returns": {
                "type": "string",
                "description": "A string indicating the result of the action."
            },
            "states": {
                "reasoning": {
                    "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
                    "instructions": "The user will ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
                },
                "responding": {
                    "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
                    "instructions": "If there is no error present, tell the user the cell location and color that was set."
                }
            }
        }
    ],
    "runtimes": [
        {
            "type": "LocalPlugin",
            "spec": {
                "local_endpoint": "Microsoft.Office.Addin",
                "allowed_host": ["workbook"]
            },
            "run_for_functions": ["fillcolor"],
            "auth": {
                "type": "None"
            }
        }
    ]
}

Die Referenzdokumentation für API-Plug-Ins finden Sie unter API-Plug-In-Manifestschema 2.3 für Microsoft 365 Copilot.

Erstellen der JavaScript-Funktionen

Die JavaScript-Funktionen, die vom Copilot-Agent aufgerufen werden, werden genau so erstellt, wie Funktionsbefehle erstellt werden. Es folgt ein Beispiel. Beachten Sie die folgenden Aspekte in diesem Code.

• Im Gegensatz zu einem Funktionsbefehl kann eine Funktion, die einer Copilot-Aktion zugeordnet ist, Parameter annehmen.
• Der erste Parameter der associate Methode muss sowohl mit der "extensions.runtimes.actions.id" -Eigenschaft im Add-In-Manifest als auch mit der "functions.name" -Eigenschaft im JSON-Code des API-Plug-Ins übereinstimmen.

async function fillColor(cell, color) {
    await Excel.run(async (context) => {
        context.workbook.worksheets.getActiveWorksheet().getRange(cell).format.fill.color = color;
        await context.sync();
    })
}

Office.onReady((info) => {
    Office.actions.associate("fillcolor", async (message) => {
        const {cell, color} = JSON.parse(message);
        await fillColor(cell, color);
        return "Cell color changed.";
    });
});

Nachdem Ihre Funktionen erstellt wurden, erstellen Sie eine HTML-Datei ohne Benutzeroberfläche, die ein <script> Tag enthält, das die JavaScript-Datei mit den Funktionen lädt. Die URL dieser HTML-Datei muss mit dem Wert der "extensions.runtimes.code.page" Eigenschaft im Manifest übereinstimmen. Siehe Einheitliches Manifest für Microsoft 365 weiter oben in diesem Artikel.

Problembehandlung bei kombinierten Agents und Add-Ins

Im Folgenden finden Sie einige häufige Probleme und Lösungsvorschläge.

• Die Agentaktion schlägt mit einer Meldung fehl, die angibt, dass die Aktion im Add-In nicht gefunden wurde. Im Folgenden sind einige mögliche Ursachen aufgeführt.

  • Der "functions.name" Eigenschaftswert im JSON-Code des Plug-Ins stimmt nicht genau mit einer "extensions.runtimes.actions.id" Eigenschaft im Add-In-Manifest überein.
  • Es gibt einen Abgleich "actions.id" im Manifest, aber der gleichgeordnete "actions.type" Wert für dasselbe Aktionsobjekt ist nicht "executeDataFunction".

• Die Agentaktion schlägt mit einer Meldung fehl, die angibt, dass die Registrierung des Aktionshandlers nicht gefunden wurde. Dies ist eine mögliche Ursache.

  • Das JavaScript des Add-Ins verfügt nicht über einen Aufruf von Office.actions.associate mit dem ersten Parameter , der genau mit dem "functions.name" Eigenschaftswert im JSON-Code des Plug-Ins übereinstimmt.

Nächste Schritte

• Erstellen Ihres ersten Add-Ins als Copilot-Skill
• Hinzufügen eines Copilot-Agents zu einem Add-In