ラボ E3 - 宣言型エージェントと API プラグインの追加
このラボでは、前のラボで作成した API プラグインおよび SharePoint の特定ファイルに基づいて動作する宣言型エージェントを追加します。
Microsoft 365 が AI モデルとオーケストレーションを提供する宣言型エージェントを構築したい場合は、これらのラボを実施してください。
- 🏁 はじめに
- 🔧 セットアップ
- 🧰 宣言型エージェントの基礎
- 🛠️ API をゼロから構築して統合する
- 🔐 認証
- 🔌 統合
演習 1: サンプルドキュメントのアップロード
この手順では、宣言型エージェントがユーザーのプロンプトに回答する際に使用するサンプルドキュメントをアップロードします。Statements of Work などのコンサルティングドキュメントと、コンサルタントの工数を含む簡単なスプレッドシートが含まれます。
手順 1: SharePoint サイトの作成
https://m365.cloud.microsoft/apps/ にアクセスし、「Apps」内から 「SharePoint」アプリを探します。
「Create Site」1️⃣ をクリックし、「Team site」2️⃣ を選択します。
Standard team site テンプレートを選択すると、サイトのプレビューが表示されます。「Use Template」をクリックして続行します。
サイト名を「Trey Research legal documents」などに設定 1️⃣ し、「Next」2️⃣ をクリックします。
プライバシー設定と言語を選択し、「Create Site」をクリックします。
数秒後、新しい SharePoint サイトが表示されます。
手順 2: サンプルドキュメントのアップロード
Documents Web パーツで「See all」を選択し、ドキュメントライブラリページを表示します。
次に、ツールバーの「Upload」1️⃣ ボタンをクリックし、「Files」2️⃣ を選択します。
作業フォルダーに移動すると sampleDocs ディレクトリがあります。すべてのサンプルドキュメントを選択 1️⃣ し、「Open」2️⃣ をクリックします。
次の演習で必要になるため、サイト URL（例: https://<your-tenant>.sharepoint.com/sites/TreyResearchlegaldocuments）をメモしておいてください。
演習 2: 宣言型エージェントの作成
手順 1: 宣言型エージェント JSON をプロジェクトに追加
appPackage フォルダー内に trey-declarative-agent.json という新しいファイルを作成します。次の JSON をコピーして保存してください。
{
"$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json",
"version": "v1.6",
"name": "Trey Genie Local",
"description": "You are a handy assistant for consultants at Trey Research, a boutique consultancy specializing in software development and clinical trials. ",
"instructions": "You are consulting agent. Greet users professionally and introduce yourself as the Trey Genie. Offer assistance with their consulting projects and hours. Remind users of the Trey motto, 'Always be Billing!'. Your primary role is to support consultants by helping them manage their projects and hours. Using the TreyResearch action, you can: You can assist users in retrieving consultant profiles or project details for administrative purposes but do not participate in decisions related to hiring, performance evaluation, or assignments. You can assist users to find consultants data based on their names, project assignments, skills, roles, and certifications. You can assist users to retrieve project details based on the project or client name. You can assist users to charge hours to a project. You can assist users to add a consultant to a project. If a user inquires about the hours they have billed, charged, or worked on a project, rephrase the request to ask about the hours they have delivered. Additionally, you may provide general consulting advice. If there is any confusion, encourage users to consult their Managing Consultant. Avoid providing legal advice.",
"conversation_starters": [
{
"title": "Find consultants",
"text": "Find consultants with TypeScript skills"
},
{
"title": "My Projects",
"text": "What projects am I assigned to?"
},
{
"title": "My Hours",
"text": "How many hours have I delivered on projects this month?"
}
],
"capabilities": [
{
"name": "OneDriveAndSharePoint",
"items_by_url": [
{
"url": "${{SHAREPOINT_DOCS_URL}}"
}
]
}
],
"actions": [
{
"id": "treyresearch",
"file": "trey-plugin.json"
}
]
}
このファイルにはエージェントの name 、description 、instructions が含まれています。instructions では Copilot に「Always remind users of the Trey motto, 'Always be Billing!'」と指示しています。次の演習で Copilot にプロンプトを送ると、このモットーが表示されるはずです。
手順 2: SharePoint サイトの URL を宣言型エージェントに追加
「capabilities」セクションには SharePoint ファイルコンテナーがあります。Microsoft 365 Copilot は SharePoint または OneDrive 内の任意のドキュメントを参照できますが、この宣言型エージェントは Exercise 1 で作成した Trey Research Legal Documents サイト内のファイルのみを参照します。
"capabilities": [
{
"name": "OneDriveAndSharePoint",
"items_by_url": [
{
"url": "${{SHAREPOINT_DOCS_URL}}"
}
]
}
],
SharePoint URL は環境変数 SHAREPOINT_DOCS_URL として定義しているため、env フォルダー内の .env.local ファイルに追加する必要があります。ファイルの末尾に次の行を追加し、自身の SharePoint URL に置き換えてください。
SHAREPOINT_DOCS_URL=https://mytenant.sharepoint.com/sites/TreyResearchLegaldocuments
手順 3: API プラグインファイルの確認
trey-declarative-agent.json 内の「actions」セクションでは、宣言型エージェントが Trey Research API にアクセスするよう指示しています。
"actions": [
{
"id": "treyresearch",
"file": "trey-plugin.json"
}
]
ここでは trey-plugin.json と、もう 1 つのファイルが Copilot に API を説明する方法を確認します。
これら 2 つのファイルは API を Copilot に説明するために使用されます。ラボ 2 でダウンロードしたプロジェクトに既に含まれているため、今確認できます。
- appPackage/apiSpecificationFile/trey-definition.json - OpenAPI Specification (OAS) または “Swagger” ファイル
- appPackage/trey-plugin.json - OAS では記述されない Copilot 固有の詳細を含むファイル
この演習ではまず内容を確認します。今後のラボでさらに機能を追加しながら詳しく見ていきます。
appPackage/apiSpecificationFile/trey-definition.json にはアプリケーションの全体説明があります。サーバー URL には "${{OPENAPI_SERVER_URL}} が含まれており、Agents Toolkit が developer tunnel を作成してローカル API を公開し、トークンを公開 URL に置換します。その後、すべてのリソースパス、HTTP verb、パラメーターが詳細に記述されており、Copilot が API の使い方を理解するために重要です。
{
"openapi": "3.0.1",
"info": {
"version": "1.0.0",
"title": "Trey Research API",
"description": "API to streamline consultant assignment and project management."
},
...
appPackage/trey-plugin.json には Copilot 固有の詳細があります。API 呼び出しを functions に分割し、Copilot が特定のユースケースで呼び出せるようにします。たとえば、/consultants へのすべての GET 要求は getConsultants 関数にまとめられています。
"functions": [
{
"name": "getConsultants",
"description": "Returns detailed information about consultants identified from filters like name of the consultant, name of project, certifications, skills, roles and hours available. Multiple filters can be used in combination to refine the list of consultants returned",
...
},
さらに下にスクロールするとランタイム設定があります。
"runtimes": [
{
"type": "OpenApi",
...
}
],
ここには trey-definition.json へのパスと、利用可能な関数の列挙が含まれています。
手順 4: エージェントをアプリのマニフェストに追加
appPackage ディレクトリ内の manifest.json を開きます。staticTabs オブジェクトの直前に、次のように copilotAgents オブジェクトとその中の declarativeAgents オブジェクトを追加し、先ほど作成した宣言型エージェント JSON ファイルを参照させます。
"copilotAgents": {
"declarativeAgents": [
{
"id": "treygenie",
"file": "trey-declarative-agent.json"
}
]
},
忘れずに保存してください。
手順 5: マニフェストからダミーフィーチャーを削除
ラボ E2 の初期ソリューションには宣言型エージェントがなかったため、マニフェストに機能がないとインストールできませんでした。そのため、Copilot Developer Camp のホームページを表示する静的タブという「ダミー」フィーチャーを追加していました。Teams、Outlook、Microsoft 365 アプリ (https://office.com) のタブでサイトを閲覧できるようにするためです。
ここでは不要になったため、manifest.json から次の行を削除してください。
"staticTabs": [
{
"entityId": "index",
"name": "Copilot Camp",
"contentUrl": "https://microsoft.github.io/copilot-camp/",
"websiteUrl": "https://microsoft.github.io/copilot-camp/",
"scopes": [
"personal"
]
}
],
"validDomains": [
"microsoft.github.io"
],
演習 3: 宣言型エージェントの実行とテスト
手順 1: 新しいプロジェクトの実行
デバッガーを実行中の場合は停止し、完全に再デプロイさせます。その後、矢印をクリックするか F5 を押してデバッガーを起動します。
自動的にブラウザータブが開き、「Trey Genie Local」エージェントが Immersive で起動します。開かない場合は Copilot チャットを開き、左のフライアウト 1️⃣ で過去のチャットと宣言型エージェントを表示し、Trey Genie Local エージェント 2️⃣ を選択します。
手順 2: 宣言型エージェントのテスト
エージェントとチャットを開始します。次のようなプロンプトを試してください。
Please list my projects along with details from the Statement of Work doc. 1️⃣
API プラグインから取得したプロジェクトの一覧 2️⃣ が、各プロジェクトの Statement of Work の詳細 3️⃣ と共に表示されるはずです。引用としてドキュメントへのリンクが表示されます。クリックしてドキュメントを確認してみてください。
サービスへの接続を求めるメッセージが表示された場合は、「Always allow」を選択してください。
Note
SharePoint ドキュメントが参照されない場合は、ファイルへのアクセスに問題がある可能性があります。Search がサイトをインデックスする時間は十分に経過していますか? エンドユーザーにサイトへの権限はありますか? 管理者がサイトを Search から除外していませんか? Copilot 以外で次のように Search を試してみてください。
woodgrove path:"https://<tenant>.sharepoint.com/sites/<sitename>"
tenant と site 名を capability に合わせて入力してください。Woodgrove ドキュメントが 3 件表示されない場合は Search をトラブルシュートする必要があります。Copilot も同様に見つけられません。
API がどのように呼び出されているかも確認しましょう。次のプロンプトを送ってください。
List my information. 1️⃣
これによりエージェントは Trey Research API の api/me エンドポイントを呼び出し、ユーザー情報を取得します 2️⃣。
下図のように、ログインユーザー（認証はまだ実装していないため現在は Avery Howard）と、そのユーザーのプロジェクトが表示されます。
VS Code プロジェクトで「Terminal」タブに戻ると、以下のように API が呼び出されたログも確認できます。
おめでとうございます！
宣言型エージェントを API プラグインに追加する作業が完了しました。ここからは API とプラグインをさらに強化していきます。