Erstellen Ihres ersten Add-Ins als Copilot-Skill

In diesem Artikel erfahren Sie, wie Sie einen einfachen Excel Copilot-Agent erstellen, der Aktionen für den Inhalt einer Excel-Arbeitsmappe ausführen kann. Die App enthält auch ein Excel-Aufgabenbereich-Add-In.

Wissensvoraussetzungen

Grundlegendes Verständnis von deklarativen Agents in Microsoft 365 Copilot. Wenn Sie noch nicht mit ihnen vertraut sind, empfehlen wir die folgenden Aktionen.
- Lesen Sie deklarative Agents für Microsoft 365 Copilot Übersicht.
- Schließen Sie das Tutorial ab, das unter Erstellen deklarativer Agents mit dem Microsoft 365 Agent Toolkit beginnt.

Softwarevoraussetzungen

Alle Voraussetzungen, die unter Erstellen deklarativer Agents mithilfe des Microsoft 365 Agent Toolkits aufgeführt sind.
Das Microsoft 365 Agent Toolkit.

Beginnen mit einem Office-Add-In

Erstellen Sie mit den folgenden Schritten ein einfaches Excel-Add-In.

Erstellen Sie ein Office-Add-In im Microsoft 365 Agent Toolkit, indem Sie die Anweisungen unter Erstellen von Office-Add-In-Projekten mit dem Microsoft 365-Agent-Toolkit befolgen. Beenden Sie, nachdem das Projekt erstellt wurde. Führen Sie nicht die Schritte im Abschnitt zum Querladen aus.

Hinweis

Wenn Sie aufgefordert werden, das Add-In zu benennen, verwenden Sie "Excel-Add-In + Agent".
Das Projekt wird in einem neuen Visual Studio Code-Fenster geöffnet. Schließen Sie das ursprüngliche Visual Studio Code-Fenster.
Führen Sie in einer Eingabeaufforderung oder im Visual Studio Code-TERMINAL im Stammverzeichnis des Projekts aus npm install.

Querladen und Testen des Add-Ins

Testen Sie, dass das Add-In funktioniert, indem Sie die folgenden Schritte ausführen.
1. Wählen Sie Ansicht | Führen Sie in Visual Studio Code aus. Wählen Sie im Dropdownmenü AUSFÜHREN UND DEBUGGENdie Option Excel Desktop (Edge Chromium) aus.
2. Drücken Sie F5. Das Projekt wird erstellt, und ein Node dev-server-Fenster wird geöffnet. Dieser Vorgang kann einige Minuten dauern. Schließlich wird Excel geöffnet.
Hinweis

Wenn Sie zum ersten Mal ein Office-Add-In quer auf Ihren Computer geladen haben (oder das erste Mal seit mehr als einem Monat), werden Sie möglicherweise aufgefordert, ein altes Zertifikat zu löschen und/oder ein neues zu installieren. Stimmen Sie beiden Eingabeaufforderungen zu.
1. Wählen Sie im Menüband Start die Schaltfläche Add-Ins aus, und wählen Sie dann im daraufhin geöffneten Flyout Ihr Add-In aus.
2. Eine Contoso-Add-In-Gruppe mit der Schaltfläche Aufgabenbereich anzeigen wird auf dem Menüband Start angezeigt. Verwenden Sie die Schaltfläche, um den Aufgabenbereich des Add-Ins zu öffnen.
Hinweis

Wenn eine WebView-Aufforderung Beim Laden beenden angezeigt wird, wählen Sie OK aus.
1. Wenn der Aufgabenbereich geöffnet wurde, wählen Sie Ausführen aus. Eine Zelle im Arbeitsblatt ändert sich in Gelb.
2. Beenden Sie das Debuggen, und deinstallieren Sie das Add-In, indem Sie Excel herunterfahren und in einer Eingabeaufforderung oder visual Studio Code TERMINAL im Stammverzeichnis des Projekts ausführennpm run stop.
  
  Wichtig
  
  Das Beenden des Debuggens auf der Benutzeroberfläche von Visual Studio Code funktioniert aufgrund eines Fehlers derzeit nicht. Außerdem wird der Server weder durch das Schließen von Excel noch durch manuelles Schließen des Entwicklungsserverfensters zuverlässig heruntergefahren, oder excel bewirkt, dass das Add-In nicht mehr erfüllt wird. Sie müssen ausführen npm run stop.

Hinzufügen eines deklarativen Copilot-Agents

Fügen Sie den Agent mit den folgenden Schritten hinzu.

Nehmen Sie in der Manifestdatei die folgenden Änderungen vor.
1. Fügen Sie dem Stamm das folgende -Objekt hinzu. Gemäß Konvention wird sie direkt unter der Eigenschaft "validDomains" platziert. Sie erstellen die Datei "declarativeAgent.json" in einem späteren Schritt.
```
"copilotAgents": {
  "declarativeAgents": [
    {
      "id": "ContosoCopilotAgent",
      "file": "declarativeAgent.json"
    }
  ]
},
```
2. Das Array enthält mehrere Objekte "extensions.runtimes" . Suchen Sie das Objekt mit "id" dem Wert "CommandsRuntime", und kopieren Sie ihn als zusätzliches Laufzeitobjekt in das Array.
3. Nehmen Sie die folgenden Änderungen an diesem zusätzlichen Laufzeitobjekt vor.
  1. Ändern Sie die "id" von "CommandsRuntime" in "CopilotAgentActionsRuntime".
  2. Ändern Sie die "actions.id" -Eigenschaft in "fillcolor". Dies ist die ID einer Funktion, die Sie in einem späteren Schritt hinzufügen.
  3. Ändern Sie die "actions.type" Eigenschaft in "executeDataFunction".
Erstellen Sie im Ordner appPackage eine Datei mit dem Namen declarativeAgent.json.

Fügen Sie den folgenden Inhalt in die Datei ein. (Sie erstellen die Excel-API-local-plugin.json-Datei , die in diesem JSON-Code in einem späteren Schritt erwähnt wird.)

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

Erstellen Sie im Ordner appPackage eine Datei mit dem Namen Excel-API-local-plugin.json.

Fügen Sie den folgenden Inhalt in die Datei ein.

{
     "$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 pass 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"
             }
         }
     ]
 }

Öffnen Sie die Datei \src\commands\commands.ts , und fügen Sie den folgenden Code am Ende hinzu.

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.";
     });
});

Aktualisieren von Projektkonfigurationsdateien für ein kombiniertes Add-In und einen Copilot-Agent

Im Stammverzeichnis des Projekts befindet sich eine Datei namens teamsapp.yaml oder m365agents.yaml . Ersetzen Sie den Inhalt durch Folgendes:

# yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
# Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
# Visit https://aka.ms/teamsfx-actions for details on actions
version: v1.7

environmentFolderPath: ./env

# Triggered when 'teamsapp provision' is executed
provision:
# Creates a Teams app
  - uses: teamsApp/create
    with:
     # Teams app name
     name: Contoso Agent ${{APP_NAME_SUFFIX}}
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     teamsAppId: TEAMS_APP_ID

# Build Teams app package with latest env value
  - uses: teamsApp/zipAppPackage
    with:
     # Path to manifest template
     manifestPath: ./appPackage/manifest.json
     outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
     outputFolder: ./appPackage/build
# Validate app package using validation rules
  - uses: teamsApp/validateAppPackage
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Extend your Teams app to Outlook and the Microsoft 365 app
  - uses: teamsApp/extendToM365
    with:
     # Relative path to the build app package.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     titleId: M365_TITLE_ID
     appId: M365_APP_ID

# Triggered when 'teamsapp publish' is executed
publish:
# Build Teams app package with latest env value
  - uses: teamsApp/zipAppPackage
    with:
     # Path to manifest template
     manifestPath: ./appPackage/manifest.json
     outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
     outputFolder: ./appPackage/build
# Validate app package using validation rules
  - uses: teamsApp/validateAppPackage
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Apply the Teams app manifest to an existing Teams app in
# Teams Developer Portal.
# Will use the app id in manifest file to determine which Teams app to update.
  - uses: teamsApp/update
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Publish the app to
# Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
# for review and approval
  - uses: teamsApp/publishAppPackage
    with:
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     publishedAppId: TEAMS_APP_PUBLISHED_APP_ID
projectId: da53b0a2-1561-415e-919a-5b870bcd2f49

Ersetzen Sie den Wert von projectId in der letzten Inhaltszeile, die Sie im vorherigen Schritt eingefügt haben, durch eine neue zufällig generierte GUID.
Öffnen Sie die Datei \env.env.dev , und fügen Sie die folgenden Zeilen am Ende der Datei hinzu, direkt nach der Zeile "ADDIN_ENDPOINT=".
```
TEAMS_APP_ID=
TEAMS_APP_TENANT_ID=
M365_TITLE_ID=
M365_APP_ID=
```

Testen des Add-Ins und des Agents

Schließen Sie alle Office-Anwendungen.
Öffnen Sie das Microsoft 365 Agent Toolkit.
Wählen Sie im Bereich Lebenszyklus die Option Bereitstellen aus. Bei der Bereitstellung werden unter anderem folgende Aktionen ausgeführt:
- Legen Sie Werte für die vier Zeilen fest, die Sie der ENV.DEV-Datei hinzugefügt haben.
- Erstellen Sie einen /build-Ordner im Ordner /appPackage mit der ZIP-Paketdatei. Die Datei enthält die Manifest- und JSON-Dateien für den Agent und das Plug-In.
Führen Sie in einer Eingabeaufforderung oder im Visual Studio Code-TERMINAL im Stammverzeichnis des Projekts aus npm run dev-server , um den Server auf localhost zu starten. Warten Sie, bis im Serverfenster eine Zeile angezeigt wird, die die App erfolgreich kompiliert hat. Dies bedeutet, dass der Server ausgeführt wird und die Dateien verarbeitet.

Hinweis

Wenn Sie zum ersten Mal seit mehr als einem Monat einen lokalen Server für ein Office-Add-In auf Ihrem Computer ausführen, werden Sie möglicherweise aufgefordert, ein altes Zertifikat zu löschen und ein neues zu installieren. Stimmen Sie beiden Eingabeaufforderungen zu.
Der erste Schritt beim Testen hängt von der Plattform ab.
- Um in Office unter Windows zu testen, öffnen Sie Excel. In wenigen Augenblicken wird die Schaltfläche Aufgabenbereich anzeigen auf dem Menüband Start in der Gruppe Contoso-Add-In angezeigt. (Wenn sie nicht im Menüband angezeigt wird, wählen Sie im Menüband die Schaltfläche Add-Ins aus, und wählen Sie dann im geöffneten Flyout die Excel-App Add-In + Agent aus.)
- Navigieren Sie zum Testen in Office im Web in einem Browser zu https://excel.cloud.microsoft.com/, und erstellen Sie dann eine neue Arbeitsmappe.
Der Prozess zum Öffnen Ihres Agents hängt von der Benutzeroberfläche für Copilot in Office-Anwendungen ab, die sich im Übergang befindet.
- Wenn im Menüband eine Copilot-Schaltfläche vorhanden ist (kein Dro-Down-Menü), wählen Sie die Schaltfläche Copilot aus, um den Copilot-Bereich zu öffnen.
- Wenn ein Copilot-Dropdownmenü vorhanden ist, öffnen Sie das Menü, und wählen Sie App-Skills aus, um den Bereich Copilot zu öffnen.
Wählen Sie im Bereich Copilot das Hamburger-Steuerelement aus.
Im Bereich sollte excel-Add-In + Agent in der Liste der Agents enthalten sein. (Möglicherweise müssen Sie Mehr anzeigen auswählen, um sicherzustellen, dass alle Agents aufgelistet sind.) Wenn der Agent dies nicht ist, probieren Sie eine oder beide der folgenden Aktionen aus.
- Warten Sie einige Minuten, und laden Sie Copilot erneut.
- Wenn Copilot für die Liste der Agents geöffnet ist, klicken Sie auf den Cursor im Bereich Copilot , und drücken Sie STRG+R.
Wenn der Agent aufgelistet ist, wählen Sie ihn aus. Der Bereich Excel-Add-In + Agent wird geöffnet.
Wählen Sie den Starter Zellenfarbe unterhaltung ändern aus, und drücken Sie dann das Steuerelement Senden im Feld Unterhaltung am unteren Rand des Bereichs. Wählen Sie Bestätigen als Antwort auf die Bestätigungsaufforderung aus. Die Farbe der Zelle sollte sich ändern.

Tipp

Wenn Copilot einen Fehler meldet, wiederholen Sie Ihre Eingabeaufforderung, fügen Sie der Eingabeaufforderung jedoch den folgenden Satz hinzu: "Wenn Sie einen Fehler erhalten, melden Sie mir den vollständigen Text des Fehlers."
Versuchen Sie, andere Kombinationen aus Zelle und Farbe in das Konversationsfeld einzugeben, z. B. "Legen Sie Zelle G5 auf die Farbe des Himmels fest".

Vornehmen von Änderungen im Add-In oder Agent

Live Reloading und Hot Reloading für ein kombiniertes Add-In und Einen Agent werden im Vorschauzeitraum nicht unterstützt. Um Änderungen vorzunehmen, fahren Sie zuerst den Server herunter, und deinstallieren Sie die Erweiterung mit den folgenden Schritten.

Das Herunterfahren des Servers hängt davon ab, in welchem Fenster er ausgeführt wird.
- Wenn der Webserver in derselben Eingabeaufforderung oder in Visual Studio Code TERMINAL ausgeführt wird, in der Sie ausgeführt haben npm run dev-server, geben Sie dem Fenster den Fokus, und drücken Sie STRG+C. Wählen Sie als Antwort auf die Aufforderung zum Beenden des Prozesses "Y" aus.
- Wenn der Webserver in einem separaten Fenster ausgeführt wird, führen Sie in einer Eingabeaufforderung oder visual Studio Code TERMINAL im Stammverzeichnis des Projekts aus npm run stop.
Löschen Sie den Office-Cache gemäß den Anweisungen unter Manuelles Löschen des Caches.
Öffnen Sie Teams, wählen Sie Apps in der App-Leiste aus, und wählen Sie dann Apps verwalten unten im Bereich Apps aus.
Suchen Sie excel-Add-In + Agent in der Liste der Apps, und wählen Sie die Pfeilspitze links neben dem Namen aus, um die Zeile zu erweitern.
Wählen Sie das Papierkorbsymbol am rechten Ende der Zeile aus, und wählen Sie dann in der Eingabeaufforderung Entfernen aus.

Nehmen Sie Ihre Änderungen vor, und wiederholen Sie dann die Schritte unter Testen des Add-Ins und Agents.

Problembehandlung

Weitere Informationen finden Sie unter Problembehandlung bei kombinierten Add-Ins und Agents.

Nächste Schritte

Hinzufügen eines Copilot-Agents zu einem vorhandenen Add-In

Siehe auch

Feedback

War diese Seite hilfreich?

Last updated on 2025-11-11