Agent mit Aktionen aus einer REST-API erweitern (Vorschauversion)

Sie können REST-APIs (einschließlich OpenAI-APIs) verwenden, um einen von Ihnen erstellten Agenten mit externen Systemen zu verbinden und auf verfügbare Daten zur Verwendung in Ihrem Agenten zuzugreifen. Sie können Ihre Agent mit einer REST-API verbinden, indem Sie Copilot Studio drei Dinge bereitstellen:

• Eine OpenAPI-Spezifikation, welche die Funktionen und verfügbaren Aktionen der API bestimmt
• Details zur Art der erforderlichen Authentifizierung und die Authentifizierungsdetails, damit Benutzende eine Verbindung mit der API herstellen und auf das externe System zugreifen können
• Beschreibungen, anhand derer das Sprachmodell bestimmen kann, wann die API aufgerufen werden soll, um die Daten zu nutzen

REST-APIs können über Copilot Studio zu Copilot-Agenten und benutzerdefinierten Agenten hinzugefügt werden.

Copilot-Agenten ermöglichen es einem Erstellenden, mehrere Datenquellen wie Connectors, APIs, Prompts und Wissensquellen in mehreren Agenten zu kombinieren. Sie können diesen Agenten verwenden, um Agentenerfahrungen mit Microsoft-Branding, z. B. Microsoft 365 Copilot, zu erweitern.

Benutzerdefinierte Agenten sind eigenständige Agenten, die Connectors, APIs, Prompts und Wissensquellen enthalten. Sie können benutzerdefinierte Agenten direkt verwenden, indem Sie sie in Websites oder andere Kanäle integrieren.

Anmerkung

API-Aktionen müssen auf der Grundlage einer OpenAPI v2-Spezifikation erstellt werden. Diese Anforderung besteht aufgrund des Verhaltens von Power Platform bei der Verarbeitung von API-Spezifikationen. Wenn eine v3-Spezifikation übermittelt wird, wird sie während des Erstellungsprozesses automatisch in eine v2-Spezifikation übersetzt.

Anforderungen

Es sind einige Voraussetzungen erforderlich, um Agent-Erfahrungen mit Microsoft-Branding mit Konnektor-Aktionen zu erweitern.

Für alle Agentenerfahrungstypen benötigen Sie Anmeldeinformationen auf Erstellendenebene und eine Copilot Studio-Lizenz.

Außerdem benötigen Sie eine Kopie der OpenAPI-Spezifikation, Kenntnisse über die Art der erforderlichen Authentifizierung und die Authentifizierungsdetails.

Einem Agenten eine REST-API-Aktion hinzufügen

Zum Hinzufügen einer REST-API zu Ihrem Agenten gehören einige Schritte. Die folgenden Abschnitte führen Sie durch diesen Vorgang.

Der Prozess zum Hinzufügen einer REST-API ist für benutzerdefinierte und Copilot-Agenten identisch.

Der Prozess besteht aus wenigen Schritten.

Einem Agenten eine Aktion hinzufügen

1. Beginnen Sie auf der Seite Übersicht Ihres Agenten.

   

2. Wählen Sie im Abschnitt Aktionen die Option Aktion hinzufügen aus. Sie können auch zur Registerkarte Aktionen wechseln und Aktion hinzufügen auswählen.

   

   Der Assistent zur Erstellung von Aktionen wird gestartet, wobei sofort die Seite Eine Aktion auswählen angezeigt wird.

API-Spezifikation, -Beschreibung und -Lösung angeben

1. Wählen Sie unten auf der Seite unter API für einen benutzerdefinierten Connector hinzufügen aus.

   

2. Laden Sie eine OpenAPI-Spezifikationsdatei für die REST-API hoch, mit der Sie eine Verbindung herstellen möchten. Sie können die Spezifikationsdatei entweder per Drag & Drop auf den Bildschirm REST-API hochladen ziehen oder Ihr System nach der gewünschten Datei durchsuchen.

   

   Anmerkung

   Die OpenAPI-Spezifikation muss eine JSON-Datei im v2-Format sein. Wenn eine v3-Spezifikation übermittelt wird, wird sie während des Erstellungsprozesses automatisch in eine v2-Spezifikation übersetzt.

   Nachdem Sie die Spezifikation hochgeladen haben, wird der Bildschirm aktualisiert, sodass der Name der Spezifikationsdatei und die Details angezeigt werden.

   

   In den folgenden Schritten verankern wir das Verfahren in einem spezifischen Beispiel von SunnyADO, einem ADO-Ticketverwaltungssystem. In dem Beispiel soll es den Benutzenden ermöglicht werden, ihre Tickets über den Agenten abzurufen und zu aktualisieren.

3. Überprüfen Sie die Details und wählen Sie dann Weiter aus.

   Sie sehen eine Seite mit den API-Plug-In-Details, auf der Sie zusätzliche Informationen zur API bereitstellen können.

   

   Das Beschreibungsfeld wird zunächst basierend auf der Beschreibung in der von Ihnen hochgeladenen API-Spezifikation ausgefüllt. Geben Sie eine ausführliche Beschreibung an, da Ihre Agentenorchestrierung die Beschreibung verwendet, um zu bestimmen, wann die bestimmte Aktion verwendet werden soll. Geben Sie Details, einschließlich Synonyme, an, um Ihren Agenten bei der Auswahl zu unterstützen.

   Die anfängliche Beschreibung lautet beispielsweise: „Ein einfacher Dienst zum Verwalten von Tickets.“

   Eine bessere Beschreibung ist: „Ein System, das verwendet wird, um bestehende Tickets von SunnyADO zu erhalten, abzurufen, zu finden und anzuzeigen. Es ermöglicht Benutzenden, Tickets zu aktualisieren, zu ändern und zu verwalten, um mehr Daten zur Verbesserung der Datensätze bereitzustellen.“

4. Geben Sie eine verbesserte Beschreibung im Feld Beschreibung ein.

5. In der Dropdownliste sind alle in der aktuellen Umgebung verfügbaren Lösungen aufgelistet. Wählen Sie die Lösung aus, die Sie nutzen möchten. Weitere Informationen dazu, was Lösungen sind, finden Sie unter Lösungskonzepte.

   

   Wenn Sie eine bevorzugte Lösung haben oder der ausgewählte Connector bereits in der Lösung enthalten ist, wird diese Lösung automatisch ausgewählt.

   Sie können entweder eine Lösung auswählen oder das Feld leer lassen. Wenn Sie die Lösung leer lassen, wird für Sie eine Lösung mit dem Aktionsnamen und dem Standardherausgeber erstellt. Wenn Sie Ihre Aktion in einer Lösung speichern, können Sie sie problemlos zwischen Umgebungen verschieben.

   Anmerkung

   Wenn Ihnen in diesem Fall die Standardlösung oder die CDS-Standardlösung nicht als Option angezeigt werden, empfehlen wir eine benutzerdefinierte Lösung für eine einfache Verwaltung. Weitere Informationen finden Sie unter Standardlösung vs. benutzerdefinierte Lösung.

6. Wählen Sie bei ausgewählter Lösung Weiter aus, um fortzufahren.

Authentifizierungsdetails bereitstellen

Die Seite Authentifizierung wird angezeigt, auf der Sie auswählen können, welche Art der Authentifizierung für die API verwendet werden soll.

Anmerkung

Derzeit sind die verfügbaren Optionen „Keine“, „Authentifizierung 2.0“ und „API“.

1. Wählen Sie eine Authentifizierungsmethode aus der Liste aus.

2. Füllen Sie die erforderlichen Felder für die Authentifizierungsmethode aus. Die Felder variieren je nach Authentifizierungsmethode.

   • Keine: Es sind keine weiteren Felder erforderlich.
   • API-Schlüssel:
     • Parameterbeschriftung: Eine Textbeschriftung für den API-Parameter.
     • Parametername: Ein Textname für den API-Parameter.
     • Position des Parameters: Die Position, an der der Parameter zu finden ist.
   • Authentifizierung 2.0:
     • Client-ID: Client-GUID für den Zieldienst.
     • Geheimer Clientschlüssel: Geheimniswert für den Client. Das Geheimnis wird nicht angezeigt, wenn der Benutzende anschließend das Bearbeitungsfenster öffnet. Bewahren Sie das Geheimnis jedoch auf, da Sie es benötigen, wenn Sie weitere Änderungen vornehmen möchten.
     • Autorisierungs-URL: URL, die zur Autorisierung des Quellsystems verwendet wird.
     • Token-URL: URL, unter der das Token abgerufen werden kann.
     • Aktualisierungs-URL: URL, zu der Sie bei einer Aktualisierung weitergeleitet werden.
     • Bereich: Die Bereichs-URL, die der API für Microsoft Entra-Apps zugewiesen ist.
     • Welche Microsoft 365-Organisation auf die Endpunkte zugreift: Dadurch wird der Zugriff auf die Quelle entweder auf die Organisation des Erstellenden oder auf alle Organisationen beschränkt.
     • Welche App (Client) die Endpunkte verwenden kann: GUID, die das Clientsystem bestimmt, das für den Zugriff auf diese Daten verwendet werden kann. Zu den Apps können Microsoft 365, Power Automate und andere Optionen zählen.

3. Sobald alle Felder ausgefüllt sind, wählen Sie Weiter aus.

   Es wird die Seite Plug-In-Aktion auswählen und konfigurieren angezeigt, auf der Sie Aktionen auswählen können, die für die API aktiviert werden sollen.

   

Aktionen für die API auswählen

Wählen Sie die zu aktivierenden API-unterstützten Aktionen aus. Im Allgemeinen bietet eine REST-API eine Reihe von Aktionen über die verschiedenen Kombinationen aus Endpunkt und HTTP-Methode (get, put, post, delete usw.), die in der API-Spezifikation festgelegt sind. In einigen Fällen möchten Sie möglicherweise nicht, dass die Benutzende des Agenten die Möglichkeit haben, jede der Aktionen auszuführen, welche die API grundsätzlich anbietet. Ihre API-Spezifikation könnte zum Beispiel Aktionen zum Aktualisieren und Löschen enthalten, aber Sie möchten, dass nur Benutzende Ihres Agenten Datensätze erstellen können.

1. Wählen Sie eine Aktion aus der Liste zum Konfigurieren aus.

   Die Seite Plug-Aktion konfigurieren wird angezeigt.

   

2. Konfigurieren Sie die ausgewählte Aktion. Wie bei der gesamten API werden Sie aufgefordert, einen Aktionsnamen und eine Aktionsbeschreibung anzugeben. Beschreibungen werden zunächst aus den Beschreibungen in der API-Spezifikation vorausgefüllt. Der Name muss nicht eindeutig sein, sollte aber für die Aktion selbst stehen. Die Beschreibung sollte, wie die allgemeine API-Beschreibung auch, spezifisch genug sein, um dem Sprachmodell Details zur Verfügung zu stellen, mit denen Sie besser erkennen können, ob Ihre Abfrage zu dieser spezifischen Aktion passt.

3. Sobald die Felder ausgefüllt sind, wählen Sie Weiter aus.

   Die Seite Parameter Ihrer Aktion überprüfen wird angezeigt.

   

   Auf dieser Seite werden die Werte angezeigt, die als Teil der möglichen Eingabe- und Ausgabewerte bereitgestellt werden. Diese Werte können nicht geändert werden. Die Beschreibungen der Ein- und Ausgaben können jedoch aktualisiert werden. Der gesamte Inhalt dieser Seite wird direkt aus der hochgeladenen API-Spezifikation abgerufen.

4. Füllen Sie die erforderlichen Werte für die Beschreibungen aus. Die Beschreibungen geben eine Definition dafür, wofür die Werte verwendet werden. Wenn eine der Beschreibungen leer ist, muss sie erst eingetragen werden, bevor Sie fortfahren können. Sie können den Namen kopieren und einfügen, wenn Ihnen keine bessere Beschreibung einfällt.

5. Wählen Sie nach Abschluss der Beschreibung Weiter aus.

   Die erste Aktion ist jetzt konfiguriert und erscheint in der Liste der Ausgewählten Aktionen auf der Seite Ihre Plug-In-Aktion auswählen und konfigurieren.

   

6. Fügen Sie alle anderen Aktionen hinzu, die Sie zu diesem Zeitpunkt einbeziehen möchten. Wenn Sie mit dem Hinzufügen von Aktionen fertig sind, die Ihr Agent unterstützen soll, wählen Sie Weiter aus.

   Die Seite Aktion überprüfen wird angezeigt. Die Seite enthält die Details der konfigurierten REST-API-Aktion.

   

Überprüfen und veröffentlichen

1. Wenn Sie Aktualisierungen vornehmen müssen, können Sie Zurück auswählen und Ihre Änderungen machen. Wählen Sie andernfalls Weiter aus.

   Es wird ein Bildschirm angezeigt, der anzeigt, dass Ihre Aktion veröffentlicht wird, während der Prozess noch abgeschlossen wird. Sie werden informiert, sobald die Veröffentlichung erledigt ist.

2. Nach Abschluss der Veröffentlichung kehren Sie zum Bildschirm Aktion auswählen zurück. Hier können Sie die neu konfigurierte REST-API in Ihren Copilot-Agenten oder benutzerdefinierten Agenten einfügen und die Konfiguration der Komponente abschließen.

   

Die REST-API-Aktion kann jetzt in Ihrem Agenten verwendet werden.

Tipp

Verwenden Sie die Suchleiste, um Ihre Aktion leichter zu finden.