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 zur Verfügung stellen:

• 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

Sie können REST-APIs zu Copilot Agents und benutzerdefinierten Agents über Copilot Studio hinzufügen.

Copilot Agents ermöglichen es einem Hersteller, mehrere Datenquellen wie Connectors, APIs, Eingabeaufforderungen und Wissensquellen in einem einzigen Agent zu kombinieren. Verwenden Sie diesen Agent, um Microsoft-Marken-Agent-Erfahrungen wie 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.

Anforderungen

• Zugangsdaten auf Herstellerebene 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

Führen Sie die folgenden Schritte aus, um Ihrem Agent ein REST-API-Tool hinzuzufügen:

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 zum Hinzufügen einer REST-API ist für benutzerdefinierte Agents und Microsoft 365 Copilot-Agents 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 bereitstellen

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 Sie eine v3-Spezifikation übermitteln, übersetzt der Erstellungsprozess diese automatisch in eine v2-Spezifikation.

   Nachdem Sie die Spezifikation hochgeladen haben, wird der Bildschirm aktualisiert, um den Dateinamen der Spezifikation und die Details anzuzeigen.

   

   In den folgenden Schritten verwendet die Prozedur ein bestimmtes Beispiel für SunnyADO, ein 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 aufgefü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. Erfahren Sie mehr über Lösungen in Lösungskonzepten.

   

   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 die Standardlösung oder die CDS-Standardlösung in diesem Fall nicht als Option angezeigt wird, fügen Sie eine benutzerdefinierte Lösung für die einfache Verwaltung hinzu. Weitere Informationen finden Sie in der Standardlösung im Vergleich zur benutzerdefinierten Lösung.

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

Authentifizierungsdetails bereitstellen

Die Seite "Authentifizierung " wird angezeigt. Wählen Sie den Typ der Authentifizierung aus, die für die API verwendet werden soll.

1. Wählen Sie eine Authentifizierungsmethode aus der Liste aus. Wählen Sie aus drei Optionen aus:

   • 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. Mit dieser Authentifizierungsmethode kann der Benutzer Ihrer Anwendung (Agent) Berechtigungen erteilen, ohne ihre Anmeldeinformationen für den Agent freizugeben.

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: Eine Textbeschriftung für den API-Parameter, die den Nutzern präsentiert wird.
     • Parametername: Der tatsächliche Name für den API-Schlüsselparameter, der entweder in der Header- oder Abfragezeichenfolge verwendet werden soll.
     • Parameterposition: So senden Sie den Schlüssel für die API. 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: Diese Einstellung beschränkt den Zugriff auf die Quelle auf die Organisation des Erstellers oder auf alle Organisationen. Wählen Sie eine der folgenden Optionen aus:
       • Nur meine Organisation
       • Jede Microsoft 365-Organisation
     • Welche App (Client) die Endpunkte nutzen kann: GUID, das das Client-System definiert, das zum Zugriff auf diese Daten verwendet werden kann. Apps können Microsoft 365, Power Automate und andere Optionen enthalten.

3. Wenn Sie alle Felder abgeschlossen haben, wählen Sie "Weiter" aus.

   Die Seite " Tool auswählen und konfigurieren " wird angezeigt, auf der Sie Tools auswählen können, 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. Geben Sie ähnlich wie die allgemeine API einen Toolnamen und eine Toolbeschreibung an. 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. Sie können diese Werte nicht ändern, aber Sie können die Beschreibungen der Eingaben und Ausgaben 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, müssen Sie sie abschließen, bevor Sie fortfahren können. Sie können den Namen einfügen, wenn Sie keine bessere Beschreibung haben.

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 zurzeit einschließen möchten. Wenn 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, wählen Sie "Zurück " aus, und nehmen Sie Ihre Änderungen vor. Wählen Sie andernfalls "Weiter" aus.

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

2. Wählen Sie Verbindung erstellen , um fortzufahren. Sie werden zum Add-Tool-Bildschirm zurückgebracht.

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. Erstellen oder wählen Sie für jedes der neu konfigurierten Tools aus der API eine Verbindung mit der API aus, und fügen Sie das Tool Ihrem Agent hinzu:

   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 informationen ein, die für die Verbindung erforderlich sind, und wählen Sie dann "Erstellen" aus, um die Verbindung mit dem Tool zu erstellen.
   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.