Erweitern Ihres Agents mit Tools aus einer REST-API (Vorschau)

[Dieser Artikel ist Teil der Dokumentation zur Vorabversion und kann geändert werden.]

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 Agent zuzugreifen. Sie können Ihren 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-Agents und benutzerdefinierten Agentshinzugefügt werden.

Von Bedeutung

Dieser Artikel enthält Dokumentation zur Vorschauversion von Microsoft Copilot Studio und kann noch geändert werden.

Vorschaufeatures sind nicht für die Produktionsverwendung vorgesehen und verfügen möglicherweise über eingeschränkte Funktionen. Diese Funktionen stehen vor dem offiziellen Release zur Verfügung, damit Sie früher Zugriff darauf erhalten und Feedback geben können.

Weitere Informationen zur Erstellung eines produktionsbereiten Agenten finden Sie unter Übersicht über Microsoft Copilot Studio.

Copilot-Agenten ermöglichen es einem Erstellenden, mehrere Datenquellen wie Connectors, APIs, Prompts und Wissensquellen in mehreren Agenten zu kombinieren. Sie können diesen Agent verwenden, um Agenterfahrungen 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

REST-API-Tools müssen aus 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

• Maker-Level-Qualifikationen und eine Copilot Studio-Lizenz.
• Eine Kopie der OpenAPI-Spezifikation für die REST-API, mit der du dich verbinden möchtest.
• Kenntnis der Art der Authentifizierung, die für die Verbindung zur API erforderlich ist, sowie der Authentifizierungsdetails.

Füge deinem Agenten ein REST-API-Tool hinzu

Das Hinzufügen eines REST-API-Tools zu Ihrem Agenten umfasst einige Schritte:

1. Fügen Sie ein neues Agenten-Tool hinzu und wählen Sie die REST-API aus
2. API-Spezifikation, Beschreibung und Lösung bereitstellen
3. Authentifizierungsdetails bereitstellen
4. Ausgewählte Werkzeuge aus der API
5. Überprüfen und Veröffentlichen

Die folgenden Abschnitte führen Sie Schritt für Schritt durch den Prozess.

Der Prozess zur Hinzufügung einer REST-API ist sowohl für benutzerdefinierte Agenten als auch für Microsoft 365 Copilot identisch.

Fügen Sie das neue Agenten-Tool hinzu und wählen Sie die REST-API aus

1. Gehen Sie zur Übersichtsseite Ihres Maklers .

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

   Die Seite "Tool hinzufügen " wird angezeigt.

3. Wählen Sie Neues Werkzeug>REST-API aus.

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

1. Laden Sie eine OpenAPI-Spezifikationsdatei für die REST-API hoch, zu 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.

2. Ü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 detaillierte Beschreibung an, da ihre Agent-Orchestrierung die Beschreibung verwendet, um zu bestimmen, wann das jeweilige Tool 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.“

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

4. 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.

5. 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.

1. Wählen Sie eine Authentifizierungsmethode aus der Liste aus. Drei Optionen sind verfügbar:

   • Keine: Für den Zugriff auf die API ist keine Authentifizierung erforderlich.
   • API-Schlüssel: Wählen Sie diese Option, wenn Ihre API einen API-Schlüssel für die Authentifizierung benötigt. Während der Laufzeit, wenn der Agent das API-Tool verwenden möchte, fordert er den Benutzer zur Authentifizierung auf. Der Benutzer gibt einen API-Schlüssel bereit und der Agent verbindet sich mit diesem Schlüssel mit der API.
   • Auth 2.0: Wählen Sie diese Option, wenn Ihr MCP-Server OAuth 2.0 für die Authentifizierung verwendet. OAuth 2.0 ermöglicht es einzelnen Nutzern, sich über einen Identitätsanbieter bei der API zu authentifizieren. So kann der Nutzer Ihrer Anwendung (Agent) Berechtigungen gewähren, ohne seine Zugangsdaten mit dem Agenten zu teilen.

2. Geben Sie die erforderlichen Felder für die gewählte Authentifizierungsmethode ein. Die Felder variieren je nach Authentifizierungsmethode.

   • Keine: Keine Informationen zu liefern.
   • API-Schlüssel:
     • Parameterlabel: Ein Textlabel, das der API-Parameter den Nutzern präsentiert.
     • Parametername: Der tatsächliche Name des API-Schlüsselparameters, der entweder im Header oder im Abfragestring verwendet werden soll.
     • Parameterstandort: Wie du den Schlüssel für die API senden sollst. Wählen Sie entweder Header oder Abfrage.
   • Auth 2.0:
     • Client-ID: Der Clientbezeichner, den der Identitätsanbieter beim Registrieren Der App ausgibt. Die Client-ID teilt dem Identitätsanbieter mit, welche App die Anforderung stellt.
     • Geheimer Clientschlüssel: Der geheime Clientschlüssel, den der Identitätsanbieter beim Registrieren Der App ausgibt. Ihr Agent sendet den geheimen Clientschlüssel zusammen mit der Client-ID, um zu bestätigen, dass Ihr Agent berechtigt ist, Zugriffstoken für den MCP-Server anzufordern.
     • Autorisierungs-URL: Der Identitätsanbieterendpunkt, an dem Ihr Agent den Benutzer umleitet, um sich anzumelden und Berechtigungen für Ihren Agent zu erteilen (Zustimmungskarte, die im Agent-Chat angezeigt wird). Der Benutzer authentifiziert sich hier und dann antwortet der Identitätsanbieter mit einem Autorisierungscode an den Agent an der Rückruf-URL.
     • Token-URL: Der Endpunkt, an dem dein Agent den Autorisierungscode (oder Refresh-Token) gegen einen Access Token und Refresh-Token austauscht. Mit dem Zugriffstoken kann Ihr Agent den MCP-Server im Namen des Benutzers verwenden. Aktualisierungstoken ermöglichen es Ihrem Agent, neue Zugriffs- und Aktualisierungstoken vom Aktualisierungsendpunkt abzurufen, wenn das vorherige Zugriffstoken abläuft.
     • Aktualisierungs-URL: Der Endpunkt, um ein neues Zugriffstoken mithilfe eines Aktualisierungstokens anzufordern (sodass sich der Benutzer nicht erneut anmelden muss, wenn das Token abläuft).
     • Umfang: (Optional): Die Berechtigungen, die deine App anfordert, als platzgetrennte Liste.
     • Welche Microsoft-365-Organisation greift auf die Endpunkte zu: Dies beschränkt den Zugriff auf den Quellcode entweder auf die Organisation des Herstellers oder auf alle Organisationen. Wählen Sie eine der folgenden Optionen aus:
       • Nur meine Organisation
       • Alle Microsoft 365 Organisationen
     • Welche App (Client) die Endpunkte nutzen kann: GUID, das das Client-System definiert, das zum 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.

   Du bekommst eine Seite zum Auswählen und Konfigurieren deines Werkzeugs , auf der du Werkzeuge auswählen kannst, die über die API aktiviert werden sollen.

   

Ausgewählte Werkzeuge aus der API

Wählen Sie die API-unterstützten Tools aus der REST-API aus, um sie Ihrem Agenten hinzuzufügen. Im Allgemeinen bietet eine REST-API eine Reihe von Werkzeugen durch verschiedene Kombinationen von Endpunkt- und HTTP-Methoden (get, put, post, delete usw.), die in der API-Spezifikation definiert 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. Zum Beispiel könnte deine API-Spezifikation die Möglichkeit enthalten, zu aktualisieren und zu löschen, aber du möchtest nur, dass Nutzer deines Agenten Datensätze erstellen können.

1. Wählen Sie ein Tool aus der Zu konfigurierenden Liste aus.

   Die Seite "Ihr Werkzeug konfigurieren" wird angezeigt.

   

2. Konfigurieren Sie den Namen und die Beschreibung des ausgewählten Werkzeugs. Ähnlich wie bei der gesamten API werden Sie gebeten, einen Tool-Namen und eine Tool-Beschreibung anzugeben. Beschreibungen werden zunächst aus den Beschreibungen in der API-Spezifikation vorausgefüllt. Der Name muss nicht eindeutig sein, sollte aber das Tool selbst darstellen. Die Beschreibung sollte, wie auch die gesamte API-Beschreibung, spezifisch genug sein, um dem Sprachmodell Details zu liefern, um besser festzustellen, ob Ihre Abfrage mit diesem speziellen Tool übereinstimmt.

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

   Die Seite "Überprüfen Sie die Parameter Ihres Tools" wird angezeigt.

   

   Diese Seite zeigt die erwarteten Werte für die Eingabe und die zurückgegebenen Ausgabewerte. Du kannst diese Werte nicht ändern, aber du kannst die Beschreibungen der Ein- und Ausgänge aktualisieren. Der gesamte Inhalt dieser Seite wird direkt aus der hochgeladenen API-Spezifikation abgerufen.

4. Aktualisieren Sie die Beschreibungen nach Bedarf. 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.

   Das erste Tool ist jetzt konfiguriert und wird in der Liste der ausgewählten Tools auf der Seite "Plug-In-Tool auswählen und konfigurieren " angezeigt.

   

6. Fügen Sie alle anderen Tools aus der API hinzu, die Sie derzeit einbauen möchten. Nachdem Sie mit dem Hinzufügen von Tools fertig sind, die Ihr Agent unterstützen soll, wählen Sie "Weiter" aus.

   Die Seite " Tool überprüfen" wird angezeigt. Die Seite enthält die Details des konfigurierten REST-API-Tools.

   

Ü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.

   Ein Bildschirm wird angezeigt, der angibt, dass Ihr Tool veröffentlicht wird, während der Prozess abgeschlossen wird. Sie werden informiert, sobald die Veröffentlichung erledigt ist.

2. Wählen Sie Verbindung erstellen , um fortzufahren. Du wirst zum Bildschirm zum Werkzeug hinzufügen zurückgekehrt.

3. Wählen Sie die REST-API im Tooltyp-Auswähler aus. Du kannst die neu erstellten Tools in deiner API sehen. Es sollte einen Eintrag für jedes Tool geben, das du aus der API hinzugefügt hast.

4. Für jedes der neu konfigurierten Tools aus der API müssen Sie eine Verbindung zur API erstellen oder auswählen und das Tool Ihrem Agenten hinzufügen:

   1. Wählen Sie auf dem Bildschirm "Werkzeug hinzufügen " das Werkzeug aus.
   2. Wählen Sie unter Verbindung eine bestehende Verbindung aus oder wählen Sie neue Verbindung erstellen.
   3. Geben Sie alle für die Verbindung benötigten Informationen ein und wählen Sie dann Erstellen , um die Verbindung zum Tool herzustellen.
   4. Wähle Add and Configure (Hinzufügen und konfigurieren), um das Tool zu deinem Agenten hinzuzufügen.

   

Die Tools aus der REST-API sind jetzt in Ihrem Agenten verfügbar.

Trinkgeld

Um Ihr Tool einfacher zu finden, verwenden Sie die Suchleiste, um es zu finden.