セマンティック カーネルを使用して Microsoft Graph アクションを呼び出す

Microsoft 365 Copilot エージェント プラグインを使用すると、セマンティック カーネルを使用して構築されたカスタム エンジン エージェントがユーザー プロンプトを理解し、メールの送信、連絡先の取得、予定表の招待の作成、ファイルへのアクセスなどの Microsoft Graph API アクションを安全に使用できます。 これらのプラグインは、大きな言語モデル (LLM) と REST API の間のギャップを埋め、自然言語の相互作用を通じて Microsoft 365 データを公開できるようにします。

Copilot エージェント プラグインとは

Copilot エージェント プラグインは、セマンティック カーネルと Microsoft Graph API を介して関数を公開することで、Microsoft 365 データとの自然言語対話を可能にする、カスタムビルドの AI を利用した拡張機能です。 Copilot エージェント プラグインには、API (Microsoft Graph など) の OpenAPI 説明とプラグイン マニフェストが含まれます。 セマンティック カーネルは、選択した言語モデルを利用して、ユーザーの意図を分析し、呼び出すプラグインと API 操作を決定します。 これにより、Microsoft 365 データのシームレスでインテリジェントなオーケストレーションが可能になります。

Copilot エージェント プラグインは、プラグインの作成を簡略化するコマンド ライン ツールである Kiota を使用して生成できます。 プラグイン マニフェストの詳細については、Microsoft 365 Copilotのプラグイン マニフェスト スキーマに関するページを参照してください。

Copilot エージェント プラグインのしくみ

セマンティック カーネルで Copilot エージェント プラグインを読み込むかインストールするには、Microsoft.SemanticKernel.Plugins.OpenApi.Extensions ライブラリの ImportPluginFromCopilotAgentPluginAsync 拡張メソッドを使用します。

メソッドには、次の入力が必要です。

  • プラグイン名
  • プラグイン ディレクトリへのパス
  • パラメーター フィルター – これらのフィルターは、一意のパラメーター、構造、および対象となる特定の Microsoft 365 サービスに基づいて、適切なプラグインを識別して読み込むのに役立ちます。

次の例は、 ImportPluginFromCopilotAgentPluginAsync メソッドを示しています。

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);
    }
}

セマンティック カーネルがユーザー プロンプトを処理すると、次のようになります。

  • プロンプトの意図をプラグイン (CalendarPlugin など) と一致させます。
  • 適切な Microsoft Graph API 呼び出しを生成します。
  • 委任された認証を使用して要求を実行します。
  • 自然言語応答として結果を返します。

Microsoft Graph 用の事前構築済みの Copilot エージェント プラグイン

Microsoft では、プロジェクトに読み込み可能な事前構築済みの Copilot エージェント プラグインのセットを提供しています。

  • ContactsPlugin – アドレス帳エントリを管理します。
  • MessagesPlugin – 受信トレイと対話します。
  • CalendarPlugin – 会議を作成または一覧表示します。
  • DriveItemsPlugin – ファイルを検索、読み取り、アップロードします。
  • M365 Copilot プラグイン (取得 API プラグイン) – セマンティック インデックスを使用して Microsoft 365 ファイルコンテンツを検索します。

Kiota と OpenAPI 記述ファイルを使用して、他のサービス用の プラグインを作成 することもできます。

プラグインの機能と例

次の表に、プロンプトと、呼び出す Copilot エージェント プラグインの例を示します。

プロンプト 説明 呼び出されたプラグイン 予想結果 備考
連絡先について教えてください。 連絡先の詳細を取得します。 ContactsPlugin 構造化された連絡先プロファイルを返します。 ヒント: プレフィックスに "my contact" を指定すると、精度が向上します。
同僚からのメールはありますか? メールボックスで最近のメールを検索します。 MessagesPlugin メールの件名、タイムスタンプ、送信者を表示します。 フル ネームを使用すると、一致品質が向上します。
連絡先にメールを送信する... 電子メール を作成して送信します。 MessagesPlugin 送信が成功したことを確認します。 注: 外部ドメインは送信をブロックする可能性があります。
今週は何の会議がありますか? 現在の週に基づいて会議を一覧表示します。 CalendarPlugin イベント時刻と出席者を返します。 自然言語の日付がサポートされています。
[会議の同期] というタイトルの予定表イベントを作成します。 新しい予定表イベントを作成します。 CalendarPlugin 開始時刻と終了時刻で作成を確認します。 "1500 から 1530 東部" のような時間形式の作業。
セマンティック カーネルでユーザーが作業した内容を表示します。 ファイル コンテンツのメタデータを取得します。 Microsoft 365 Copilot プラグイン ドキュメントの詳細を要約します。 アクセス可能なファイル (OneDrive など) が必要です。
上司からのメールを確認し、まとめ、会議を設定します。 電子メールを取得し、要約し、イベントを作成します。 複数のプラグイン 会議のセットアップと概要を確認します。 連絡先、メッセージ、Calendarプラグインを使用します。

Copilot エージェント プラグインの概要

前提条件

開始する前に、次の点を確認してください。

Microsoft Identity Platform アプリを登録する

  1. [Azure Active Directory > アプリの登録 >新しい登録] に移動します。
  2. 名前とサポートされているアカウントの種類を入力します。
  3. リダイレクト URI の設定: http://localhost。
  4. アプリケーション (クライアント) ID とディレクトリ (テナント) ID を記録します。

アクセス許可を構成する

  1. [ アクセス許可の追加] > [API のアクセス許可] に移動します。
  2. [Microsoft Graph > 委任されたアクセス許可] を選択します。
  3. 追加: Contacts.Read、 Mail.Read、 Calendars.Read、 Files.Read。
  4. [ 管理者の同意の付与] を選択します。

シークレットを構成する (該当する場合)

  1. [ 証明書 & シークレット] > [新しいクライアント シークレット] に移動します。
  2. シークレット値をコピーします。

アプリの設定を更新する

  1. appsettings.jsonをappsettings.Development.jsonにコピーします。
  2. 入力: TenantId、 ClientId、 ClientSecret、 RedirectUri。
  3. OpenAI または Azure OpenAI の場合: ApiKey、ModelIdも設定します。

アプリケーションを実行する

オプション 1: サンプル アプリを実行する

次の例に示すように、 サンプル アプリを実行できます。

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

プロンプトに従って認証し、LLM を選択し、プラグインを選択し、クエリを実行します。

オプション 2: 独自のアプリに統合する

Copilot エージェント プラグイン機能を独自の .NET アプリケーションに統合する場合は、適切なライブラリを使用してプロジェクトを構成する必要があります。 これには、構成、認証、ログ記録、および Microsoft Graph およびセマンティック カーネル プラグインのサポートのためのアセンブリが含まれます。 プロジェクトが正常にビルドされ、必要なすべての機能にアクセスできるようにするには、次の必須 NuGet パッケージを追加します。

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

関連コンテンツ

  • Last updated on