Freigeben über

Aufrufen von Microsoft Graph-Aktionen mit semantischem Kernel

Microsoft 365 Copilot-Agent-Plug-Ins ermöglichen benutzerdefinierte Engine-Agents, die mit Semantic Kernel erstellt wurden, Benutzereingabeaufforderungen zu verstehen und Microsoft Graph-API-Aktionen sicher zu verwenden, z. B. das Senden von E-Mails, das Abrufen von Kontakten, das Erstellen von Kalendereinladungen und den Zugriff auf Dateien. Diese Plug-Ins schließen die Lücke zwischen großen Sprachmodellen (LARGE Language Models, LLMs) und REST-APIs, sodass Sie Microsoft 365-Daten über Interaktionen in natürlicher Sprache verfügbar machen können.

Was sind Copilot-Agent-Plug-Ins?

Copilot-Agent-Plug-Ins sind benutzerdefinierte, KI-gestützte Erweiterungen, die Interaktionen in natürlicher Sprache mit Microsoft 365-Daten ermöglichen, indem Funktionen über den semantischen Kernel und Microsoft Graph-APIs verfügbar werden. Copilot-Agent-Plug-Ins enthalten eine OpenAPI-Beschreibung für eine API (z. B. Microsoft Graph) und ein Plug-In-Manifest. Der semantische Kernel, der auf dem Von Ihnen gewählten Sprachmodell basiert, analysiert die Absicht des Benutzers und bestimmt, welches Plug-In und welcher API-Vorgang aufgerufen werden soll. Dies ermöglicht eine nahtlose und intelligente Orchestrierung von Microsoft 365-Daten.

Sie können Copilot-Agent-Plug-Ins mithilfe von Kiota generieren, einem Befehlszeilentool, das die Erstellung von Plug-Ins vereinfacht. Weitere Informationen zu Plug-In-Manifesten finden Sie im API-Plug-In-Manifestschema für Microsoft 365 Copilot.

Funktionsweise von Copilot-Agent-Plug-Ins

Verwenden Sie die Erweiterungsmethode aus der ImportPluginFromCopilotAgentPluginAsyncMicrosoft.SemanticKernel.Plugins.OpenApi.Extensions Bibliothek, um Copilot-Agent-Plug-Ins in Semantic Kernel zu laden oder zu installieren.

Die -Methode erfordert die folgenden Eingaben:

  • Plug-In-Name
  • Pfad zum Plug-In-Verzeichnis
  • Parameterfilter: Diese Filter helfen beim Identifizieren und Laden des richtigen Plug-Ins basierend auf seinen eindeutigen Parametern, seiner Struktur und dem spezifischen Microsoft 365-Dienst, auf den es abzielt.

Das folgende Beispiel zeigt die ImportPluginFromCopilotAgentPluginAsync -Methode.

private async Task AddCopilotAgentPluginAsync(Kernel kernel, IConfigurationRoot configuration, string pluginName)
{
    var copilotAgentPluginParameters = new CopilotAgentPluginParameters
    {
        FunctionExecutionParameters = new()
        {
            {
                "https://graph.microsoft.com/v1.0",
                new OpenApiFunctionExecutionParameters(
                    authCallback: this._bearerAuthenticationProviderWithCancellationToken.AuthenticateRequestAsync,
                    enableDynamicOperationPayload: false,
                    enablePayloadNamespacing: true)
                {
                    ParameterFilter = s_restApiParameterFilter
                }
            },
            {
                "https://graph.microsoft.com/beta",
                new OpenApiFunctionExecutionParameters(
                    authCallback: this._bearerAuthenticationProviderWithCancellationToken.AuthenticateRequestAsync,
                    enableDynamicOperationPayload: false,
                    enablePayloadNamespacing: true)
                {
                    ParameterFilter = s_restApiParameterFilter
                }
            }
        }
    };

    try
    {
        KernelPlugin plugin = await kernel.ImportPluginFromCopilotAgentPluginAsync(
            pluginName,
            GetCopilotAgentManifestPath(pluginName),
            copilotAgentPluginParameters).ConfigureAwait(false);

        AnsiConsole.MarkupLine($"[bold green]{pluginName} loaded successfully.[/]");
    }
    catch (Exception ex)
    {
        AnsiConsole.MarkupLine("[red]Failed to load {pluginName}.[/]");
        kernel.LoggerFactory.CreateLogger("Plugin Creation").LogError(ex, "Plugin creation failed. Message: {0}", ex.Message);
        throw new AggregateException($"Plugin creation failed for {pluginName}", ex);
    }
}

Wenn der semantische Kernel eine Benutzereingabeaufforderung verarbeitet, wird Folgendes ausgeführt:

  • Entspricht der Eingabeaufforderungsabsicht einem Plug-In (z. B. CalendarPlugin).
  • Generiert den entsprechenden Microsoft Graph-API-Aufruf.
  • Führt die Anforderung mit delegierter Authentifizierung aus.
  • Gibt das Ergebnis als Antwort in natürlicher Sprache zurück.

Vordefinierte Copilot-Agent-Plug-Ins für Microsoft Graph

Microsoft stellt eine Reihe vordefinierter Copilot-Agent-Plug-Ins bereit, die Sie in Ihr Projekt laden können:

  • ContactsPlugin : Adressbucheinträge verwalten.
  • MessagesPlugin : Interagieren Sie mit Ihrem Posteingang.
  • CalendarPlugin : Erstellen oder Auflisten von Besprechungen.
  • DriveItemsPlugin : Suchen, Lesen und Hochladen von Dateien.
  • M365 Copilot-Plug-In (Api-Plug-In abrufen) – Durchsuchen Sie Microsoft 365-Dateiinhalte über den semantischen Index.

Sie können auch Plug-Ins für andere Dienste erstellen, indem Sie Kiota und eine OpenAPI-Beschreibungsdatei verwenden.

Plug-In-Funktionen und Beispiele

Die folgende Tabelle enthält Beispiele für Eingabeaufforderungen und die von ihnen aufgerufenen Copilot-Agent-Plug-Ins.

Eingabeaufforderung Beschreibung Aufgerufenes Plug-In Erwartetes Ergebnis Hinweise
Was können Sie mir über meinen Kontakt sagen? Ruft Kontaktdetails ab. KontaktePlugin Gibt ein strukturiertes Kontaktprofil zurück. Tipp: Das Präfix "Mein Kontakt" verbessert die Genauigkeit.
Habe ich eine E-Mail von meinem Kollegen? Durchsucht das Postfach nach aktuellen E-Mails. NachrichtenPlugin Zeigt E-Mail-Betreffe, Zeitstempel und Absender an. Der vollständige Name verbessert die Übereinstimmungsqualität.
E-Mail an meinen Kontakt senden... Erstellt und sendet eine E-Mail. NachrichtenPlugin Bestätigt das erfolgreiche Senden. Hinweis: Externe Domänen können Sendevorgänge blockieren.
Welche Besprechungen habe ich in dieser Woche? Listen Besprechungen basierend auf der aktuellen Woche. CalendarPlugin Gibt Ereigniszeiten und Teilnehmer zurück. Datumsangaben in natürlicher Sprache werden unterstützt.
Erstellen Sie ein Kalenderereignis mit dem Titel "Synchronisierungsbesprechung". Erstellt ein neues Kalenderereignis. CalendarPlugin Bestätigt die Erstellung mit Start- und Endzeit. Zeitformate wie "1500 bis 1530 Eastern" funktionieren.
Zeigen Sie mir, worüber ein Benutzer für Semantic Kernel gearbeitet hat. Ruft Dateiinhaltsmetadaten ab. Microsoft 365 Copilot-Plug-In Fasst Dokumentdetails zusammen. Erfordert eine barrierefreie Datei (z. B. OneDrive).
Überprüfen Sie meine E-Mails von meinem Vorgesetzten, fassen Sie sie zusammen, und richten Sie eine Besprechung ein. Ruft E-Mail ab, fasst zusammen, erstellt ein Ereignis. Mehrere Plug-Ins Bestätigt die Einrichtung und Zusammenfassung der Besprechung. Verwendet Kontakte, Nachrichten und Kalender-Plug-Ins.

Erste Schritte mit Copilot-Agent-Plug-Ins

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:

Registrieren der Microsoft Identity Platform-App

  1. Wechseln Sie zu Azure Active Directory > App-Registrierungen > Neue Registrierung.
  2. Geben Sie den Namen und die unterstützten Kontotypen ein.
  3. Umleitungs-URI festlegen: http://localhost.
  4. Notieren Sie sich die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant).

Konfigurieren von Berechtigungen

  1. Wechseln Sie zu API-Berechtigungen > Berechtigung hinzufügen.
  2. Wählen Sie Microsoft Graph > Delegierte Berechtigungen aus.
  3. Add: Contacts.Read, Mail.Read, Calendars.Read, Files.Read.
  4. Wählen Sie Administratoreinwilligung erteilen aus.

Konfigurieren von Geheimnissen (falls zutreffend)

  1. Wechseln Sie zu Zertifikate & Geheimnisse > Neuer geheimer Clientschlüssel.
  2. Kopieren Sie den Geheimniswert.

Aktualisieren von App-Einstellungen

  1. Kopieren Sie appsettings.json in appsettings.Development.json.
  2. Geben Sie folgendes ein: TenantId, ClientId, ClientSecret, RedirectUri.
  3. Legen Sie ApiKeyfür OpenAI oder Azure OpenAI auch fest. ModelId

Ausführen der Anwendung

Option 1: Ausführen der Beispiel-App

Sie können die Beispiel-App ausführen, wie im folgenden Beispiel gezeigt.

dotnet run demo
# or for debug mode:
dotnet run demo --debug

Befolgen Sie die Anweisungen zum Authentifizieren, wählen Sie die LLM aus, wählen Sie Plug-Ins aus, und führen Sie Abfragen aus.

Option 2: Integrieren in Ihre eigene App

Wenn Sie copilot-Agent-Plug-In-Funktionen in Ihre eigene .NET-Anwendung integrieren, müssen Sie Ihr Projekt mit den entsprechenden Bibliotheken konfigurieren. Dies umfasst Assemblys für Konfiguration, Authentifizierung, Protokollierung und Unterstützung für Microsoft Graph- und Semantic Kernel-Plug-Ins. Fügen Sie die folgenden erforderlichen NuGet-Pakete hinzu, um sicherzustellen, dass Ihr Projekt erfolgreich erstellt wird und Zugriff auf alle erforderlichen Features hat.

dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Json 
dotnet add package Microsoft.Identity.Client 
dotnet add package Microsoft.Extensions.Logging 
dotnet add package Microsoft.SemanticKernel 
dotnet add package Microsoft.SemanticKernel.Plugins.Core 
dotnet add package Microsoft.SemanticKernel.Plugins.OpenApi 
dotnet add package Microsoft.SemanticKernel.Planners.OpenAI 
dotnet add package Microsoft.SemanticKernel.Plugins.MSGraph 
dotnet add package Microsoft.SemanticKernel.Plugins.OpenApi.Extensions

Verwandte Inhalte