MCP- und API-Plug-Ins für deklarative Agents

MCP- und API-Plug-Ins sind benutzerdefinierte Aktionen, die es deklarativen Agents in Microsoft 365 Copilot ermöglichen, mit MCP-Servern (Model Context Protocol) oder REST-APIs zu interagieren, die eine OpenAPI-Beschreibung aufweisen. Mithilfe eines dieser Plug-Ins können Benutzer einen deklarativen Agenten bitten, einen MCP-Server oder eine REST-API nach Informationen abzufragen und, sofern unterstützt, Daten und Objekte über Eingabeaufforderungen in natürlicher Sprache zu erstellen, zu aktualisieren und zu löschen.

In diesem Artikel wird Plug-In für die technische benutzerdefinierte MCP- oder API-Aktion verwendet, die von einem deklarativen Agenten verwendet wird. Informationen zu produkt, paket, registrierung und lebenszyklus für Kunden finden Sie unter Plug-Ins für Microsoft 365 Copilot.

Verwenden Sie während des Erstellens oder Wiederverwendens diesen Artikel, um eine MCP- oder API-Aktion auszuwählen und zu verstehen, wie der Orchestrator sie aufruft. Sie schließen mit dem technischen Vorgehensmodell und einem Produktverfahren zu dessen Umsetzung ab. Die daraus resultierende Aktion ist eine Abhängigkeit des Agenten, kein separates öffentliches Verteilungsversprechen.

Wichtig

MCP- und API-Plug-Ins stellen Aktionen in deklarativen Agents bereit. Es handelt sich nicht um eigenständige, installierbare Plugin-Pakete: Nur der enthaltende Agent kann auf seine Funktionen und Tools zugreifen. Informationen über die Beziehung zwischen Paket- und Aktionsmanifest finden Sie unter Plugins und deklarative Agent-Aktionen.

Ein API- oder MCP-Plug-In verwendet ein Plug-In-Manifest, das Copilot liest, um mehr über die API oder den MCP-Server zu erfahren, die für den Agent verfügbar sind. Copilot kann dann entscheiden, wann der Agent diese Integration verwenden soll, um eine Eingabeaufforderung zu beantworten. Weitere Informationen zu diesem Manifest finden Sie unter API- und MCP-Plug-In-Manifestschema. Das installierbare Paket verwendet ein separates Microsoft 365-App-Manifest.

So ermittelt Copilot MCP-Servertools

Bei Plug-Ins, die auf einem MCP-Server basieren, löst Copilot die Tools des Plug-Ins standardmäßig dynamisch zur Laufzeit direkt vom MCP-Server auf. Dynamische Toolermittlung bedeutet, dass Sie die neuesten Tools erhalten, die der MCP-Server verfügbar macht, ohne darauf warten zu müssen, dass der Agent neu verpackt und veröffentlicht wird. Beim Erstellen des Agents kann ein Entwickler optional stattdessen einen festen Satz von Tools im Plug-In-Manifest anheften. REST-API-Plug-Ins verwenden immer die Tools, die im Plug-In-Manifest definiert sind. Weitere Informationen finden Sie unter Build Plug-Ins von einem MCP-Server für Microsoft 365 Copilot und Dynamische Toolermittlung für MCP-Plug-Ins in Microsoft 365 Copilot.

Dieser Standard gilt für MCP-Plug-Ins, die als deklarative Agent-Aktionen verwendet werden. Für ein Plug-In, das im Microsoft 365-App-Manifest auf einen Remote-MCP-Server agentConnectors verweist, erfordert die dynamische Toolermittlung die App-Manifestversion 1.29 oder höher und einen Host, der dies zulässt. Weitere Informationen finden Sie unter Konfigurieren von MCP-Remoteservern für Microsoft 365 Copilot-Plug-Ins.

Plug-in-Beispiel

Stellen Sie sich einen Budget-MCP-Server vor, der es ermöglicht, Budgets abzufragen und zu erstellen, Ausgaben abzurechnen oder Guthaben zu vorhandenen Budgets hinzuzufügen. Die Eingabeaufforderung "Wie viel ist noch im Contoso-Reisebudget" könnte ein Budget-Plug-In auslösen und das get-budgets Tool aufrufen.

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "get-budgets",
    "arguments": {
      "budgetName": "contoso travel"
    }
  }
}

Copilot verwendet die Antwort des Toolergebnisses, um seine Antwort zu generieren: "Das Reisebudget von Contoso verfügt derzeit über 5.000 USD an verfügbaren Mitteln. Wenn Sie Geld bestimmten Kategorien zuweisen oder Ausgaben verfolgen müssen, kann ich Ihnen auch dabei helfen. Lass mich einfach wissen, wie ich helfen kann!"

Die Eingabeaufforderung "Berechnen Sie 500 USD auf das Reisebudget von Contoso für Megans Flugticket" könnte in den folgenden MCP-Toolaufruf übersetzt werden.

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "charge-budget",
    "arguments": {
      "budgetName": "contoso travel",
      "amount": 500,
      "description": "Megan's airline ticket"
    }
  }
}

Copilot antwortet dem Benutzer mit den zurückgegebenen Informationen: "Die Gebühr von 500 USD für Megans Flugticket wurde erfolgreich verarbeitet. Im Reisebudget von Contoso sind jetzt noch 4.500 USD verfügbar. Wenn Sie weitere Transaktionen durchführen müssen oder weitere Unterstützung bei Ihrem Budget benötigen, lassen Sie es mich bitte wissen!"

Funktionsweise von Plugins

Ein Sequenzdiagramm, das den Plug-In-Datenfluss zeigt

  1. Der Benutzer fragt den Agenten: "Wie viel ist im Budget für die Renovierung der Fourth Coffee Lobby noch übrig?"

  2. Bei einem MCP-Plug-In, das dynamische Tool-Discovery verwendet, ruft der Agent die aktuellen Tool-Definitionen zur Laufzeit vom MCP-Server des Plug-Ins ab und validiert alle neuen oder geänderten Tools, bevor sie verwendet werden. Für ein Plug-In mit einem angehefteten Toolset oder für ein REST-API-Plug-In verwendet der Agent stattdessen die Tools, die im Plug-In-Manifest definiert sind.

  3. Der Agent identifiziert ein budgetbezogenes Plug-In aus den verfügbaren Plug-Ins, das über ein MCP-Servertool oder eine API GetBudget verfügt, um Budgetdetails abzurufen. Es ordnet Teile der Frage des Benutzers den Parametern der Funktion zu: budgetName="".

  4. Der Agent bittet den Benutzer , das Senden Fourth Coffee lobby renovation an das Plugin zu erlauben.

  5. Der Benutzer entscheidet sich dafür, die Freigabe von Daten mit dem Plug-In einmalig zuzulassen, oder er entscheidet sich dafür, die Freigabe von Daten für diese Funktion immer zuzulassen.

  6. Wenn der MCP-Server oder die API des Plug-Ins eine Authentifizierung erfordert, fordert das Plug-In ein Token oder einen API-Schlüssel aus dem Tokenspeicher an.

  7. Der Tokenspeicher gibt ein Token oder einen Schlüssel zurück. Bei Bedarf fordert der Tokenspeicher den Agent auf, sich anzumelden.

  8. Der Agent sendet eine Anforderung an den MCP-Server oder die API des Plug-Ins, die außerhalb von Microsoft 365 gehostet wird.

  9. Der MCP-Server oder die API gibt eine Antwort zurück.

    {
      "name": "Fourth Coffee lobby renovation",
      "availableFunds": 5000.00
    }
    
  10. Der Agent generiert eine Antwort basierend auf der MCP-Server- oder API-Antwort.

  11. Der Agent sendet die Antwort: "Die verfügbaren Mittel, die im Budget für die Renovierung der Fourth Coffee Lobby verbleiben, betragen 5.000 US-Dollar."

Bestätigen von Aktionen

Copilot fragt den Benutzer, bevor er zum ersten Mal Daten an ein Plug-in sendet.

Ein Screenshot eines Plug-In-Bestätigungsdialogs.

Nachdem der Benutzer die Verbindung bestätigt hat, ist bei MCP-Servertools und APIs, die nur Daten abrufen, keine Bestätigung erforderlich, bei Tools und APIs, die Daten ändern, ist eine Bestätigung hingegen erforderlich. Plug-in-Entwickler können diese Standardeinstellungen außer Kraft setzen. Weitere Informationen finden Sie unter Bestätigungsaufforderungen für MCP- und API-Plug-Ins für Microsoft 365 Copilot.

Anpassen der Antwortpräsentation

Copilot generiert Konversationsantworten mithilfe von Daten vom MCP-Server oder API-Antworten. Plugins können anpassen, wie diese Daten dargestellt werden, und der Mechanismus hängt vom Plugin-Typ ab.

  • MCP-Plug-Ins können umfangreiche, interaktive Antworten liefern, indem sie MCP-Apps verwenden – UI-Widgets, die der MCP-Server zur Laufzeit zusammen mit dem Toolergebnis zurückgibt. Da das Widget mit der Toolantwort bereitgestellt wird und nicht im Manifest definiert ist, funktionieren MCP-Apps unabhängig davon, ob das Plug-In einen angehefteten Satz von Tools oder eine dynamische Toolermittlung verwendet.

  • API-Plug-Ins können Adaptive Card-Vorlagen im Plug-In-Manifest bereitstellen, um Daten auf strukturierte Weise anzuzeigen. Da die Vorlagen für die im Manifest deklarierten Vorgänge definiert werden, gilt dieser Ansatz für API-Plug-Ins und für MCP-Plug-Ins, die einen angehefteten Satz von Tools verwenden.

Für quellenbezogene Zitate in jedem Plugin-Typ verwendet Copilot die Antwortsemantik und kann Zitatmetadaten automatisch aus dem Tool oder der API-Antwort ableiten. Automatische Rückschlüsse sind besonders nützlich für MCP-Plug-Ins, die die dynamische Toolermittlung verwenden, bei der Tools zur Laufzeit aufgelöst werden und keine manifeste Tooldefinition konfiguriert werden muss. Weitere Informationen finden Sie unter Zitate mit Antwortsemantik anzeigen.

Screenshot einer adaptiven Kartenantwort von einem API-Plug-In

URL-Behandlung in Aktionsantworten

Die Chaterfahrung von Microsoft 365 Copilot rendert möglicherweise URLs, die als Teil von Aktionsantworten zurückgegeben werden – sei es von MCP-Plug-Ins, API-Plug-Ins, Connectors oder Flows – als anklickbare Links. Die Copilot-Laufzeit steuert dieses Verhalten und wertet es nicht anhand von Domänen aus, die das Plug-In deklariert (z. B. den servers Abschnitt der OpenAPI-Beschreibung eines API-Plug-Ins).

Plattformsicherheits-, Vertrauens- und Richtlinienregeln regeln das URL-Renderingverhalten für Aktionsantworten und können sich im Laufe der Zeit ändern. Verlassen Sie sich nicht auf klickbare URLs in Aktionsreaktionen für produktionskritische Szenarien.

Helfen Sie dem Copilot-Orchestrator bei der Auswahl der Aktionen Ihres Agents

Beschreiben Sie die API- oder MCP-Integration, ihre Funktionen oder Tools und ihre Eingaben genau, damit der Orchestrator die richtige Aktion für die Anforderung des Benutzers auswählen kann. Diese Beschreibungen beziehen sich auf die Aktionen des Agents, nicht auf den Namen oder die Store-Beschreibung des äußeren Plug-In-Pakets.

Integration von Aktionen Wo man es beschreiben kann Weitere Informationen
API-Plug-In Plugin-Manifest und OpenAPI-Vorgangs- und Parameterbeschreibungen Effektive OpenAPI-Beschreibungen erstellen
MCP-Plug-In Beschreibungen des Plug-In-Manifests und des MCP-Tools; Tooldefinitionen stammen zur Laufzeit vom Server oder sind im Manifest angeheftet Dynamische Werkzeugermittlung und angeheftete Werkzeuge

Funktionen und MCP-Tools sind nicht identisch mit den wiederverwendbaren Anweisungsdateien, die unter Skills als Plug-In-Funktionen beschrieben werden.

Erstellen eines deklarativen Agents mit API- oder MCP-Aktionen

Beginnen Sie für die berufliche Entwicklung mit Work IQ Dev Tools. Wählen Sie zuerst eine dokumentierte Umgebung aus und fügen Sie dann ein Tool in der folgenden Liste hinzu, wenn Sie dessen Projektgenerierungs- oder Integrationsfunktionen benötigen:

  • Work IQ Dev Tools ist das empfohlene Tool. Wird verwendet wiqd agent add action , um einem deklarativen Agent-Projekt eine unterstützte OpenAPI- oder Remote-MCP-Aktion hinzuzufügen.
  • Bestehende toolkitbasierte Exemplarische Vorgehensweisen bleiben für einen MCP-Server, eine OpenAPI-Beschreibung oder eine neue REST-API verfügbar. Befolgen Sie diese Verfahren, wenn Sie mit einem Toolkit-Projekt arbeiten.
  • Kiota kann ein API-Plugin-Manifest aus einer vorhandenen OpenAPI-Beschreibung generieren.

Das API- oder MCP-Plug-In-Manifest konfiguriert die Aktionsintegration des Agents. Verpacken und verteilen Sie den enthaltenden Agent über die unterstützte App-Paket-Route; Das Aktionsmanifest ist kein unabhängig installierbares Plug-In-Paket.

Tipp

Work IQ Dev Tools ist allgemein verfügbar. wiqd agent add action Fügt einem deklarativen Agent-Projekt eine Aktion hinzu und wiqd agent validate --mode source führt Offlineprüfungen für gespeicherte Agent-Quellen durch. Eine erfolgreich bestandene Quellprüfung stellt weder die Erreichbarkeit von Laufzeit- oder OpenAPI-Endpunkten, die Korrektheit der Authentifizierung noch die Akzeptanz des endgültigen Pakets fest. Wenn Sie den Eintrag --modeweglassen, wird bei der Überprüfung standardmäßig der Wert verwendet package, wodurch eine Kopie einer vorhandenen ZIP-Datei hochgeladen wird und möglicherweise eine Anmeldung erforderlich ist. Informationen zu Validierungsmodi und Abdeckung finden Sie in der WIQD-Befehlsreferenz und unter Validierung und MVL.

Beschränkungen

Diese Grenzwerte betreffen API- und MCP-Plug-Ins, die als Aktionen deklarativer Agents verwendet werden, nicht die Anzahl der Skills, Agents oder Connectors in einem installierbaren Plug-In-Paket.

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

Ein Plugin kann eine unbegrenzte Anzahl von Funktionen oder MCP-Tools enthalten. Alle Funktionen oder Tools eines übereinstimmenden Plug-Ins werden zurückgegeben, auch wenn nur eines übereinstimmt. Bei einem MCP-Plug-In, das dynamische Toolermittlung verwendet, werden die Tools, die zur Laufzeit vom MCP-Server aufgelöst wurden, zu dieser Summe hinzugerechnet. Aufgrund von Grenzwerten für Tokenfenster kann sich die Qualität der Antworten verschlechtern, wenn mehr als 10 Funktionen oder Tools enthalten sind.

Das Tokenfenster für Ein- und Ausgaben von einem Plug-In schneidet große Inhalte ab. Die Funktionsgrenze kann sich mit der Verbesserung der Modelle ändern und hängt vom Systemaufwand ab. Optimieren Sie für kleine Tokenlängen, oder entscheiden Sie sich für Erweiterungsoptionen, die bei Bedarf das Streaming großer Inhalte ermöglichen.

Nächster Schritt

Implementieren Sie die ausgewählte MCP-Aktion oder API-Aktion. Nachdem die Komponenten einzeln funktionieren, geben Sie Paket & testen Sie mit Integrieren und testen Sie Ihre Komponenten.