Microsoft 365 Agents Toolkit と TypeSpec を使用して宣言型エージェントを作成する

宣言型エージェントは、Microsoft 365 Copilot を利用した目標指向型の会話エクスペリエンスを提供します。 その目的、指示、知識、およびアクションを定義します。 このガイドでは、 TypeSpec と Microsoft 365 Agents Toolkit を使用して宣言型エージェントを構築する方法を示します。

注:

このチュートリアルで構築するエージェントは、ライセンスを持つ Microsoft 365 Copilot ユーザーを対象としています。 機能が制限された Microsoft 365 Copilot Chat ユーザー用のエージェントを構築することもできます。 詳細については、「Microsoft 365 Copilot 開発者ライセンス」を参照してください。

ヒント

Work IQ Dev Tools (プレビュー) と Microsoft 365 Agents Toolkit は、関連するプロコード ワークフローを提供します。 機能、パッケージ ルート、ターゲット エクスペリエンスに基づいて選択するには、「 プラグインの開発ツールの選択」を参照してください。

注:

Microsoft 365 Copilot に基づく宣言型エージェントが Word と PowerPoint でサポートされるようになりました。

前提条件

  • カスタム アプリをアップロードできる Microsoft 365 テナント。 カスタム アプリのアップロードが有効になっていないと、プロビジョニングが失敗します。 カスタム アプリのアップロードを有効にするには、「 Microsoft 365 Agents Toolkit の要件」を参照してください。 開発環境とライセンス オプションについては、「 Copilot 開発環境」を参照してください。

この記事で説明する手順を完了するには、次のリソースが必要です。

注:

この記事のスクリーンショットとユーザー インターフェイス リファレンスでは、リリース版の Microsoft 365 Agents Toolkit を使用しています。 プレリリース版は、表示されているユーザー インターフェイスとは異なる場合があります。

Microsoft 365 Copilot の宣言型エージェントに関する次の標準とガイドラインを理解してください。

  • Teams ストア検証ガイドラインに記載されているコンプライアンス、パフォーマンス、セキュリティ、およびユーザー エクスペリエンスの標準。

宣言型エージェントの作成

まず、基本的な宣言型エージェントを作成します。

  1. Visual Studio Code を開きます。

  2. [Microsoft 365 エージェント ツールキット] を選択して>新しいエージェント/アプリを作成します。

    Microsoft 365 Agents Toolkit のサイドバーにある [新しいアプリの作成] ボタンのスクリーンショット

  3. 宣言型エージェントを選択します。

    [エージェント] が選択された [新しいプロジェクト] オプションのスクリーンショット

  4. [Microsoft 365 Copilot の TypeSpec で開始] を選択して、基本的な宣言型エージェントを作成します。

  5. [ 既定のフォルダー ] を選択して、プロジェクトのルート フォルダーを既定の場所に保存します。

  6. アプリケーション名として「My Agent」と入力し、Enter キーを押します。

  7. 開いた新しい Visual Studio Code ウィンドウで、[ Microsoft 365 Agents Toolkit] を選択します。 [ ライフサイクル ] ウィンドウで、[ プロビジョニング] を選択します。

    Microsoft 365 エージェント ツールキットのライフサイクル ウィンドウにある [プロビジョニング] オプションのスクリーンショット

エージェントをテストする

  1. https://m365.cloud.microsoft/chat で Copilot アプリケーションに移動します。

  2. [New Chat] ボタンの横にある会話ドロワー アイコンを選択します。

  3. 宣言型エージェントの [マイ エージェント] を選択します。

    Copilot の宣言型エージェントのスクリーンショット

  4. 宣言型エージェントの質問を入力して、実際の動作を確認します。

手順の追加

命令はエージェントの動作を変更します。

  1. main.tsp ファイルを開き、@instructions デコレータを次のコードに置き換えます。

    @instructions("""
  You are an expert at creating poems.
  Every time a user asks a question, you **must** turn the answer into a poem. The poem **must** not use the quote markdown and use regular text.
""")

    このデコレーターの内容は、プロビジョニング中にエージェントのマニフェストの instructions プロパティに挿入されます。 詳細については、「 宣言型エージェント マニフェスト オブジェクト」を参照してください。

  2. Agents Toolkit の [ライフサイクル] ウィンドウで [プロビジョニング] を選択します。

宣言型エージェントは、ページを再読み込みした後、更新された命令を使用します。

更新された手順に基づく宣言型エージェントからの回答のスクリーンショット

会話のきっかけを追加する

会話のきっかけは、Copilot がユーザーに対して表示するヒントで、宣言型エージェントの使用を開始する方法を示します。

  1. main.tsp ファイルを開き、コメント付きの @conversationStarter デコレータを次の内容に置き換えます。

    @conversationStarter(#{
  title: "Getting started",
  text: "How can I get started with Agents Toolkit?"
})

@conversationStarter(#{
  title: "Getting Help",
  text: "How can I get help with Agents Toolkit?"
})

    詳細については、「 スレッド スターター オブジェクト」を参照してください。

  2. Agents Toolkit の [ライフサイクル] ウィンドウで [プロビジョニング] を選択します。

ページを更新すると、更新された会話スターターが宣言型エージェントで使用できるようになります。

Microsoft 365 Copilot の宣言型エージェントによる会話のきっかけを示すスクリーンショット

Web コンテンツの追加

Web 検索機能を使用すると、エージェントは Bing の検索インデックスを使用してユーザーのプロンプトに応答できます。

  1. main.tsp ファイルを開き、次の内容を含む MyAgent 名前空間にWebSearch機能を追加します。

    namespace MyAgent {
  op webSearch is AgentCapabilities.WebSearch<Sites = [
    {
      url: "https://learn.microsoft.com",
    },
  ]>;
}

    詳細については、「 Web 検索オブジェクト」を参照してください。

    注:

    Sites配列を指定しない場合、エージェントはすべての Web コンテンツにアクセスできます。

  2. Agents Toolkit の [ライフサイクル] ウィンドウで [プロビジョニング] を選択します。

宣言型エージェントは、ページを再読み込みした後、Web コンテンツにアクセスして回答を生成できます。

Web コンテンツを含む宣言型エージェントからの応答を示すスクリーンショット

OneDrive と SharePoint のコンテンツを追加する

SharePoint 機能を使用すると、エージェントは OneDrive と SharePoint のコンテンツをナレッジとして使用できます。

  1. main.tsp ファイルを開き、https://contoso.sharepoint.com/sites/ProductSupportを Microsoft 365 organizationの SharePoint サイト URL に置き換えて、MyAgent 名前空間にOneDriveAndSharePoint機能を追加します。

    namespace MyAgent {
  // Omitted for brevity
  op od_sp is AgentCapabilities.OneDriveAndSharePoint<ItemsByUrl = [
    {
      url: "https://contoso.sharepoint.com/sites/ProductSupport"
    }
  ]>;
  // Omitted for brevity
}

    詳細については、「 OneDrive と SharePoint オブジェクト」を参照してください。

    注:

    • URL は、SharePoint アイテム (サイト、ドキュメント ライブラリ、フォルダー、ファイル) へのフル パスである必要があります。 SharePoint の [直接リンクをコピー] オプションを使用すると、完全なパスまたはファイルとフォルダーを取得できます。 ファイルまたはフォルダーを右クリックし、[ 詳細] を選択します。 [ パス] に移動し、コピー アイコンを選択します。
    • ItemsByUrl配列 (または代替の ItemsBySharePointIds 配列) を指定しない場合、エージェントは、サインインしたユーザーがアクセスできる Microsoft 365 organization内のすべての OneDrive および SharePoint コンテンツにアクセスできます。

  2. Agents Toolkit の [ライフサイクル] ウィンドウで [プロビジョニング] を選択します。

宣言型エージェントは、ページの再読み込み後に回答を生成するために OneDrive と SharePoint コンテンツにアクセスできます。

SharePoint と OneDrive のコンテンツを含む宣言型エージェントからの応答を示すスクリーンショット

Teams メッセージを追加する

Teams メッセージ機能を使用すると、エージェントは Teams チャネル、チーム、会議チャットをナレッジとして使用できます。

  1. main.tsp ファイルを開き、https://teams.microsoft.com/l/team/...をorganizationの Teams チャネルまたはチームの URL に置き換えて、次の値を使用して、MyAgent名前空間にTeamsMessages機能を追加します。

    namespace MyAgent {
  // Omitted for brevity
  op teamsMessages is AgentCapabilities.TeamsMessages<TeamsMessagesByUrl = [
    {
      url: "https://teams.microsoft.com/l/team/...",
    }
  ]>;
  // Omitted for brevity
}

    詳細については、「 Microsoft Teams メッセージ オブジェクト」を参照してください。

    注:

    • url プロパティ内の URL は、Teams チャット、チーム、または会議チャットへの整形済みのリンクである必要があります。
    • TeamsMessagesByUrl配列を指定しない場合、エージェントは、認証されたユーザーがアクセスできる Microsoft 365 organization内のすべての Teams チャネル、チーム、会議、1:1 チャット、およびグループ チャットにアクセスできます。

  2. Agents Toolkit の [ライフサイクル] ウィンドウで [プロビジョニング] を選択します。

宣言型エージェントは、ページの再読み込み後に Teams データにアクセスして回答を生成できます。

Teams のコンテンツを含む宣言型エージェントからの応答を示すスクリーンショット

人々の知識を追加する

People 機能を使用すると、エージェントの範囲を設定して、organization内の個人に関する質問に回答できます。

  1. main.tsp ファイルを開き、次の内容を含む MyAgent 名前空間にPeople機能を追加します。

    namespace MyAgent {
  // Omitted for brevity
  op people is AgentCapabilities.People;
  // Omitted for brevity
}

    詳細については、People オブジェクトを参照してください。

  2. Agents Toolkit の [ライフサイクル] ウィンドウで [プロビジョニング] を選択します。

宣言型エージェントは、ページを再読み込みした後、People ナレッジにアクセスできます。

ユーザー知識を含む宣言型エージェントからの応答を示すスクリーンショット

電子メールの知識を追加する

電子メール機能を使用すると、ユーザーのメールボックスまたは共有メールボックスからの電子メールをナレッジ ソースとして使用するようにエージェントの範囲を設定できます。

  1. main.tsp ファイルを開き、次の内容を含む MyAgent 名前空間にEmail機能を追加します。

    namespace MyAgent {
  // Omitted for brevity
  op email is AgentCapabilities.Email<Folders = [
    {
      folder_id: "Inbox",
    }
  ]>;
  // Omitted for brevity
}

    詳細については、「Email オブジェクト」を参照してください。

    注:

    • この例では、エージェントのメールボックスのユーザーにアクセスします。 代わりに共有メールボックスにアクセスするには、省略可能な shared_mailbox プロパティ セットを共有メールボックスのメール アドレスに追加します。
    • Folders 配列は、メールボックスへのアクセスを特定のフォルダーに制限します。 メールボックス全体にアクセスするには、 folders 配列を省略します。

  2. Agents Toolkit の [ライフサイクル] ウィンドウで [プロビジョニング] を選択します。

宣言型エージェントは、ページを再読み込みした後、電子メールのナレッジにアクセスできます。

メールの知識を含む宣言型エージェントからの応答を示すスクリーンショット

画像ジェネレーターを追加する

画像生成機能を使用すると、エージェントはユーザー プロンプトに基づいて画像を生成できます。

  1. main.tsp ファイルを開き、次の内容を含む MyAgent 名前空間にGraphicArt機能を追加します。

    namespace MyAgent {
  // Omitted for brevity
  op graphicArt is AgentCapabilities.GraphicArt;
  // Omitted for brevity
}

    詳細については、「 グラフィック アート オブジェクト」を参照してください。

  2. Agents Toolkit の [ライフサイクル] ウィンドウで [プロビジョニング] を選択します。

宣言型エージェントは、ページを再読み込みした後に画像を生成できます。

生成されたグラフィック アートを含む宣言型エージェントからの応答を示すスクリーンショット

コード インタープリターの追加

コード インタープリター機能は、Python コードを通じて複雑なタスクを解決するように設計された高度なツールです。

  1. main.tsp ファイルを開き、次の内容を含む MyAgent 名前空間にCodeInterpreter機能を追加します。

    namespace MyAgent {
  // Omitted for brevity
  op codeInterpreter is AgentCapabilities.CodeInterpreter;
  // Omitted for brevity
}

    詳細については、「 コード インタープリター オブジェクト」を参照してください。

  2. Agents Toolkit の [ライフサイクル] ウィンドウで [プロビジョニング] を選択します。

宣言型エージェントには、ページを再読み込みした後のコード インタープリター機能があります。

生成されたグラフを含む宣言型エージェントからの応答を示すスクリーンショット

要求されたグラフの生成に使用される Python コードを示すスクリーンショット

Copilot コネクタ コンテンツを追加する

Copilot コネクタによって取り込まれたアイテムを、エージェントで利用可能なナレッジに追加します。

  1. main.tsp ファイルを開き、MyAgent 名前空間に GraphConnectors 機能を追加して、次の値で policieslocal を Microsoft 365 organizationの有効な Copilot コネクタ ID に置き換えます。 Copilot コネクタ ID の検索の詳細については、「 宣言型エージェント マニフェストの機能 ID の取得」を参照してください。

    namespace MyAgent {
  // Omitted for brevity
  op copilotConnectors is AgentCapabilities.GraphConnectors<Connections = [
    {
      connectionId: "policieslocal",
    }
  ]>;
  // Omitted for brevity
}

    詳細については、「 Copilot コネクタ オブジェクト」を参照してください。

    注:

    Connections配列を指定しない場合、エージェントは、サインインしたユーザーがアクセスできる Microsoft 365 organization内のすべての Copilot コネクタからコンテンツを取得します。

  2. Agents Toolkit の [ライフサイクル] ウィンドウで [プロビジョニング] を選択します。

宣言型エージェントは、Copilot コネクタのコンテンツにアクセスして、ページの再読み込み後に回答を生成できます。

Copilot コネクタのコンテンツを含む宣言型エージェントからの応答を示すスクリーンショット

完了

Microsoft 365 Copilot の宣言型エージェント ガイドを完了しました。 TypeSpec を使用して宣言型エージェントを構築することに慣れてきたので、次の記事で詳細を確認できます。

次の手順

TypeSpec を使用してアクションを構築する

  • 最終更新: