API-Plug-Ins für Microsoft 365 Copilot

API-Plug-Ins ermöglichen deklarative Agents in Microsoft 365 Copilot die Interaktion mit REST-APIs, die über eine OpenAPI-Beschreibung oder MCP-Server verfügen. Mit einem API-Plug-In können Benutzer einen deklarativen Agent bitten, nicht nur eine REST-API oder einen MCP-Server nach Informationen abzufragen, sondern auch Daten und Objekte zu erstellen, zu aktualisieren und zu löschen. Auf alles, was die REST-API oder der MCP-Server ausführen kann, kann über Eingabeaufforderungen in natürlicher Sprache zugegriffen werden.

Ein API-Plug-In stellt ein OpenAPI-Beschreibungsdokument (bei Verwendung einer REST-API) und ein Plug-In-Manifest bereit, das Copilot verwendet, um die Funktionen der API zu erlernen. Copilot kann dann entscheiden, wann die API eines installierten und aktivierten Plug-Ins geeignet ist, um eine bestimmte Aufforderung zu beantworten. Weitere Informationen zur Manifestdatei, die für ein API-Plug-In erforderlich ist, finden Sie unter API-Plug-In-Manifestschema für Microsoft 365 Copilot.

Betrachten Sie beispielsweise eine Budget-API, die das Abfragen und Erstellen von Budgets, das Berechnen von Ausgaben oder das Hinzufügen von Mitteln zu vorhandenen Budgets ermöglicht. Die Aufforderung "Wie viel ist im Contoso-Reisebudget übrig?" könnte ein Budget-Plug-In auslösen, das den folgenden API-Aufruf vornimmt.

GET /budgets?name=contoso%20travel

Copilot verwendet die Antwort des API-Aufrufs, um seine Antwort zu generieren: "Das Contoso-Reisebudget verfügt derzeit über 5.000 US-Dollar an verfügbaren Mitteln. Wenn Sie Mittel bestimmten Kategorien zuordnen oder Ausgaben nachverfolgen müssen, kann ich Ihnen auch dabei helfen. Lassen Sie mich einfach wissen, wie ich helfen kann!"

Die Aufforderung "500 US-Dollar auf das Contoso-Reisebudget für das Flugticket von Megan berechnen" könnte in den folgenden API-Aufruf übersetzt werden.

POST /budgets/charge
Content-Type: application/json

{
  "budgetName": "Contoso travel",
  "amount": 500,
  "description": "Megan's airline ticket"
}

Copilot antwortet dem Benutzer mit den zurückgegebenen Informationen: "Die Gebühr von 500 US-Dollar für das Flugticket von Megan wurde erfolgreich verarbeitet. Das Contoso-Reisebudget verfügt jetzt über 4.500 US-Dollar an verfügbaren Mitteln. Wenn Sie weitere Transaktionen tätigen oder weitere Unterstützung bei Ihrem Budget benötigen, lassen Sie es mich wissen!"

Funktionsweise von API-Plug-Ins

1. Der Benutzer fragt den Agent: "Wie viel bleibt im Budget für die Renovierung der vierten Kaffeelobby übrig?"

2. Der Agent identifiziert ein budgetbezogenes Plug-In aus seinen verfügbaren Plug-Ins, das über eine Funktion GetBudget zum Abrufen von Budgetdetails verfügt. Es ordnet Teile der Frage des Benutzers den Parametern der Funktion zu: budgetName="".

3. Der Agent fordert den Benutzer auf, das Senden Fourth Coffee lobby renovation an das Plug-In zuzulassen.

4. Der Benutzer entscheidet, dass Daten einmal für das Plug-In freigegeben werden, oder er entscheidet, dass Daten für diese Funktion immer freigegeben werden.

5. Wenn die API des Plug-Ins eine Authentifizierung erfordert, fordert das Plug-In ein Token oder einen API-Schlüssel vom Tokenspeicher an.

6. Der Tokenspeicher gibt ein Token oder einen Schlüssel zurück. Bei Bedarf veranlasst der Tokenspeicher den Agent, den Benutzer zur Anmeldung aufzufordern.

7. Der Agent sendet eine Anforderung an die API des Plug-Ins, die außerhalb von Microsoft 365 gehostet wird.

   GET /budgets?budgetName=Fourth+Coffee+lobby+renovation
   

8. Die API gibt eine API-Antwort in dem format zurück, das in ihrer OpenAPI-Spezifikation angegeben ist.

   {
     "name": "Fourth Coffee lobby renovation",
     "availableFunds": 5000.00
   }
   

9. Der Agent generiert eine Antwort basierend auf der API-Antwort.

10. Der Agent sendet die Antwort "Die verfügbaren Mittel, die im Budget für die Renovierung der vierten Kaffeelobby verbleiben, sind 5.000 US-Dollar."

Bestätigen von Aktionen

Copilot fragt den Benutzer vor dem Senden von Daten an ein API-Plug-In.

Standardmäßig bieten APIs, die nur Daten abrufen, dem Benutzer die Option "Immer zulassen", während APIs, die Daten ändern, dies nicht der Fall ist. Plug-In-Entwickler können diese Standardwerte außer Kraft setzen. Weitere Informationen finden Sie unter Bestätigungsaufforderungen für API-Plug-Ins für Microsoft 365 Copilot.

Anpassen der Antwortpräsentation

Copilot generiert Konversationsantworten mithilfe von Daten aus API-Antworten. Plug-Ins können diese Antworten anpassen, indem sie Vorlagen für adaptive Karten bereitstellen, um Daten auf strukturierte Weise anzuzeigen.

Optimieren Ihres Plug-Ins für Copilot Orchestrator

Microsoft 365 Copilot können aus den vielen Fähigkeiten ihres Repertoires die richtige Fähigkeit auswählen. Aber wie können Sie sicherstellen, dass Copilot Ihr Plug-In auswäht, um die richtige Qualifikation bereitzustellen?

Die Antwort liegt darin, wie Sie Ihr Plug-In, seine Fähigkeiten und die Parameter für die Initiierung von Skills beschreiben. Geben Sie präzise und genaue Beschreibungen in Ihrem Plug-In-Manifest an, um am besten sicherzustellen, dass der Copilot-Orchestrator weiß, wann und wie Ihr Plug-In aufgerufen werden soll.

Die Art und Weise, wie Sie Ihr Plug-In für den Orchestrator beschreiben, hängt vom Typ des Plug-Ins ab, das Sie erstellen, wie in der folgenden Tabelle beschrieben.

Generieren von API-Plug-In-Paketen

Es gibt zwei Tools, mit denen Entwickler API-Plug-In-Pakete generieren können.

• Das Microsoft 365 Agents Toolkit in Visual Studio oder Visual Studio Code kann Plug-In-Pakete basierend auf einer vorhandenen OpenAPI-Beschreibung erstellen. Wenn Sie noch nicht über eine API verfügen, verfügt das Agents Toolkit auch über Startprojekte mit einer Beispiel-API und einem entsprechenden Plug-In-Paket.
• Kiota ist ein Befehlszeilentool und eine Visual Studio Code-Erweiterung, die Plug-In-Pakete basierend auf einer vorhandenen OpenAPI-Beschreibung generieren kann.

Begrenzungen

Plug-Ins für deklarative Agents

Wenn ein deklarativer Agent bis zu fünf Plug-Ins enthält, die im Manifest des deklarativen Agents definiert sind, werden die Plug-Ins immer in die Eingabeaufforderung eingefügt. Wenn mehr als fünf Plug-Ins definiert sind, verwendet der Agent den semantischen Abgleich. Der semantische Abgleich basiert auf der Beschreibung des Plug-Ins, nicht auf einer der einzelnen Funktionen innerhalb des Plug-Ins selbst.

Ein Plug-In kann eine unbegrenzte Anzahl von Funktionen enthalten. Alle Funktionen werden zurückgegeben, auch wenn nur eine Funktion übereinstimmt. Aufgrund von Tokenfenstergrenzwerten kann die Qualität der Antworten jedoch beeinträchtigt werden, wenn mehr als 10 Funktionen enthalten sind.

Das Tokenfenster für Eingaben in und Ausgaben eines Plug-Ins schneidet große Inhalte ab. Der Funktionsgrenzwert kann je nach Verbesserung der Modelle und abhängig vom Systemaufwand geändert werden. Optimieren Sie für kleine Tokenlängen, oder entscheiden Sie sich für Erweiterbarkeitsoptionen, mit denen bei Bedarf große Inhalte gestreamt werden können.

Verwandte Inhalte

• Erstellen von API-Plug-Ins aus einer vorhandenen API für Microsoft 365 Copilot
• Erstellen von API-Plug-Ins mit einer neuen API für Microsoft 365 Copilot
• Erstellen von API-Plug-Ins von einem MCP-Server für Microsoft 365 Copilot
• Manifestschema des API-Plug-Ins für Microsoft 365 Copilot
• Schreiben effektiver Anweisungen für deklarative Agents mit API-Plug-Ins