ラボ E1 - 指示ベース Geo Locator ゲームエージェント

このラボでは、ファイルで提供される補足知識と指示を用いて、基本的な宣言型エージェントを作成します。
作成するエージェントは、仕事の合間に楽しみながら世界各都市を学べるゲームを提供します。抽象的な手掛かりを提示し、都市を当てるまでに使用した手掛かりが少ないほど高得点が得られます。ゲーム終了時に最終スコアが表示されます。

このラボで学べること:

Agents Toolkit テンプレートを使用して宣言型エージェントを作成する方法
指示をカスタマイズして Geo Locator ゲームを構築する方法
アプリを実行しテストする方法
ボーナス演習として、SharePoint Teams サイトを使用する方法

この動画でラボの概要をご覧ください。

Microsoft 365 が AI モデルとオーケストレーションを提供する宣言型エージェントを構築したい場合は、これらのラボを実施してください。

🏁 はじめに
🔧 セットアップ
- ラボ E0 - セットアップ
🧰 宣言型エージェントの基礎
- ラボ E1 - 詳細な宣言型エージェントを構築する
- ラボ E1a - Geo ロケーターゲーム
🛠️ API をゼロから構築して統合する
🔐 認証
🔌 統合
- ラボ EB - Graph Connector を追加する

はじめに

宣言型エージェントは、Microsoft 365 Copilot と同じスケーラブルなインフラとプラットフォームを活用し、特定のニーズにフォーカスした体験を提供します。
特定分野やビジネスニーズの専門家として機能し、標準の Microsoft 365 Copilot チャットと同じインターフェイスで利用できますが、特定タスクのみに集中します。

このラボでは、まず Agents Toolkit の既定テンプレートを用いて宣言型エージェントを構築します。
次に、エージェントを Geo Locator ゲームに特化したものへと変更します。

AI の目的は、仕事の合間に楽しく世界各都市を学べる時間を提供することです。抽象的なヒントをもとに都市を当ててもらい、ヒントを多く使うほど得点は低くなります。ゲーム終了時に合計スコアが表示されます。

The initial UI of the Geo Locator Game with a couple of guesses from the user.

ボーナスとして、エージェントに秘密の日記 🕵🏽 と地図 🗺️ のファイル参照を与え、プレイヤーへのチャレンジを増やします。

それでは始めましょう 💪🏼

演習 1: テンプレートから宣言型エージェントをスキャフォールディングする

宣言型エージェントのファイル構成を把握していれば、任意のエディターでも作成できますが、Agents Toolkit を使うとファイル作成からデプロイ、公開まで簡単に行えます。
ここでは Agents Toolkit を使用し、できるだけシンプルに進めます。

手順 1: Agents Toolkit のインストール

Visual Studio Code の拡張機能タブを開き、 Microsoft 365 Agents Toolkit を検索します。
選択してインストールします。

手順 2: Agents Toolkit で宣言型エージェントアプリを作成

Visual Studio Code 左側にある Agents Toolkit 拡張機能 1️⃣ を開き、 Create a New Agent/App 2️⃣ を選択します。

The UI of the Agents Toolkit to start creating a new app with the 'Create a New Agent' button highlighted.

パネルが開いたら、プロジェクトタイプの一覧から Declarative Agent を選択します。

The project types available when creating a new app with Agents Toolkit. Options include 'Agent', which is highlighted.

次に、基本的な宣言型エージェントか API プラグインを持つものかを選択する画面が表示されます。 No Action を選びます。

The Agents Toolkit app creation flow with the type of Declarative Agent with 'No plugin' selected.

なぜここで Action 付きエージェントを作成しないのですか？

次のラボで REST API を構築し、その API を Action として宣言型エージェントに組み込む方法を学びます。今回は宣言型エージェントのみを作成します。まずは一歩ずつ！

続いて、プロジェクトフォルダーを作成するディレクトリを入力します。

The Agents Toolkit app creation flow with the prompt to provide a target path where to store the new app.

アプリケーション名に Geo Locator Game と入力して Enter を押します。

The Agents Toolkit app creation flow with the prompt to provide a name for the app.

数秒でプロジェクトが指定フォルダーに作成され、Visual Studio Code の新しいウィンドウで開きます。これが作業用フォルダーです。

Visual Studio Code with the new app scaffolded and ready to be extendend and the README file on the screen.

お疲れさまでした！基本の宣言型エージェントがセットアップできました。次に、Geo Locator ゲームアプリへカスタマイズするためにファイル内容を確認しましょう。

手順 3: Agents Toolkit でアカウント設定

左側の Agents Toolkit アイコン 1️⃣ を選択し、「Accounts」セクションで Sign in to Microsoft 365 2️⃣ をクリックし、ご自身の Microsoft 365 アカウントでログインします。

The UI of Agents Toolkit to allow logging into a target Microsoft 365 tenant.

ブラウザーウィンドウが開き、Microsoft 365 へのログインが完了すると「You are signed in now and close this page」と表示されますので閉じてください。

続いて "Custom App Upload Enabled" のチェックマークが緑になっていることを確認します。緑でない場合は、Teams アプリをアップロードする権限がありません。ラボの演習 1 の手順に従ってください。

同様に "Copilot Access Enabled" が緑であることを確認します。緑でない場合は Copilot のライセンスが付与されていません。ラボを続行するには必須です。

The UI of Agents Toolkit after logging in, when the checkmarks are green.

それではコードツアーに進みましょう。

手順 4: アプリ内のファイルを理解する

プロジェクト構成:

フォルダー/ファイル	内容
`.vscode`	デバッグ用 VS Code 設定
`appPackage`	Teams アプリマニフェスト、エージェントマニフェスト、API 仕様 (存在する場合)
`env`	環境ファイル (`.env.dev` が既定)
`appPackage/color.png`	アプリロゴ画像
`appPackage/outline.png`	アプリロゴのアウトライン画像
`appPackage/declarativeAgent.json`	宣言型エージェントの設定と構成
`appPackage/instruction.txt`	宣言型エージェントの動作を定義する指示
`appPackage/manifest.json`	Teams アプリマニフェスト
`m365agent.yml`	Agents Toolkit プロジェクトファイル (プロパティと Stage 定義)

本ラボで特に重要なのは appPackage/instruction.txt です。
プレーンテキストで自然言語の指示を書きます。

もう一つ重要なのが appPackage/declarativeAgent.json です。Microsoft 365 Copilot を拡張するためのスキーマが定義されています。主なプロパティ:

$schema: スキーマリファレンス
version: スキーマバージョン
name: 宣言型エージェントの名前
description: 説明
instructions: instruction.txt へのパス。ここに直接指示テキストを入力することも可能ですが、本ラボでは instruction.txt を使用します。

さらに appPackage/manifest.json には、パッケージ名、開発者名、アプリが利用するエージェントの参照など重要なメタデータが含まれます。以下は manifest.json の抜粋です:

"copilotAgents": {
        "declarativeAgents": [            
            {
                "id": "declarativeAgent",
                "file": "declarativeAgent.json"
            }
        ]
    },

color.png と outline.png を差し替えてアプリのブランドに合わせることもできます。本ラボでは color.png を変更します。

演習 2: 指示とアイコンを更新

手順 1: アイコンとマニフェストを更新

まずロゴを差し替えます。こちらの画像をコピーし、プロジェクトルートの appPackage フォルダー内の同名ファイルに置き換えます。

次に appPackage/manifest.json を開き、 copilotAgents ノードを探します。declarativeAgents 配列の最初の id を declarativeAgent から dcGeolocator へ変更し、一意になるようにします。

 "copilotAgents": {
        "declarativeAgents": [            
            {
                "id": "dcGeolocator",
                "file": "declarativeAgent.json"
            }
        ]
    },

続いて appPackage/instruction.txt を開き、下記の指示で既存内容を上書きします。

System Role: You are the game host for a geo-location guessing game. Your goal is to provide the player with clues about a specific city and guide them through the game until they guess the correct answer. You will progressively offer more detailed clues if the player guesses incorrectly. You will also reference PDF files in special rounds to create a clever and immersive game experience.

Game play Instructions:
Game Introduction Prompt
Use the following prompt to welcome the player and explain the rules:
Welcome to the Geo Location Game! I’ll give you clues about a city, and your task is to guess the name of the city. After each wrong guess, I’ll give you a more detailed clue. The fewer clues you use, the more points you score! Let’s get started. Here’s your first clue:
Clue Progression Prompts
Start with vague clues and become progressively specific if the player guesses incorrectly. Use the following structure:
Clue 1: Provide a general geographical clue about the city (e.g., continent, climate, latitude/longitude).
Clue 2: Offer a hint about the city’s landmarks or natural features (e.g., a famous monument, a river).
Clue 3: Give a historical or cultural clue about the city (e.g., famous events, cultural significance).
Clue 4: Offer a specific clue related to the city’s cuisine, local people, or industry.
Response Handling
After the player’s guess, respond accordingly:

If the player guesses correctly, say:
That’s correct! You’ve guessed the city in [number of clues] clues and earned [score] points. Would you like to play another round?
If the guess is wrong, say:
Nice try! [followed by more clues]
PDF-Based Scenario
For special rounds, use a PDF file to provide clues from a historical document, traveler's diary, or ancient map:
This round is different! I’ve got a secret document to help us. I’ll read clues from this [historical map/traveler’s diary] and guide you to guess the city. Here’s the first clue:
Reference the specific PDF to extract details: Do not provide the citations and also link to the document since its a secret document for generating the questions.
Traveler's Diary PDF,Historical Map PDF. Do not provide the citations and also link to the document since its a secret document for generating the questions.
Use emojis where necessary to have friendly tone. 
Scorekeeping System
Track how many clues the player uses and calculate points:

1 clue: 10 points
2 clues: 8 points
3 clues: 5 points
4 clues: 3 points
End of Game Prompt
After the player guesses the city or exhausts all clues, prompt:
Would you like to play another round, try a special challenge?

次の手順で、ユーザーが会話を始めやすいようにコンバーセーションスターターを追加します。

独自ファイルを appPackage に含める

appPackage/declarativeAgent.json には次の行があります:

"instructions": "$[file('instruction.txt')]",

これは instruction.txt から指示を読み込む設定です。appPackage 配下の任意の JSON ファイルで同様にファイルをモジュール化できます。

手順 2 : コンバーセーションスターターを追加

コンバーセーションスターターを追加すると、ユーザーエンゲージメントを高められます。

主な効果:

エンゲージメント: 会話を開始しやすくし、ユーザーの参加を促進
コンテキスト設定: 会話のトーンやトピックを明確化
効率性: 目的を示すことで曖昧さを減らし、スムーズに会話を進行
ユーザー維持: 魅力的なスターターがリピート利用を促進

declarativeAgent.json を開き、instructions ノードの後ろにカンマ , を追加して下記コードを貼り付けます。

 "conversation_starters": [
      { 
            "title": "Getting Started",
            "text":"I am ready to play the Geo Location Game! Give me a city to guess, and start with the first clue."          

         },
        {
            "title": "Ready for a Challenge",
            "text": "Let us try something different. Can we play a round using the travelers diary?"
        },
        { 
            "title": "Feeling More Adventurous",
            "text": "I am in the mood for a challenge! Can we play the game using the historical map? I want to see if I can figure out the city from those ancient clues."
        }
    ]

これでエージェントへの変更は完了です。テストしましょう。

手順 3: アプリをテスト

Visual Studio Code の Agents Toolkit 拡張機能を開き、左ペインの "LIFECYCLE" から "Provision" を選択します。Agents Toolkit がファイルをパッケージ化し、エージェントをアプリカタログにインストールしてくれます。

The UI of Agents Toolkit highlighting the 'Provision' command under the 'Lifecycle' group of commands.

Microsoft 365 Copilot BizChat を開きます: https://microsoft365.com/copilot/
開発テナントでサインインしてください。

Copilot アプリが読み込まれたら、右側のパネルから "Geo Locator Game" を探します。

The UI of Microsoft 365 Copilot with the list of agents on the right side and the 'Geo Locator Game' agent highlighted.

見つからない場合は一覧が長い可能性があります。"see more" を展開して探してください。

起動すると、エージェント専用のチャット画面が開き、下図のようにコンバーセーションスターターが表示されます。

The UI of Microsoft 365 Copilot when the 'Geo Locator Game' agent is selected. The image highlights the conversation starters.

スターターの一つを選択すると、メッセージボックスに自動入力されます。Enter を押すまでアシスタントは待機します 🟢

ゲームのデモをご覧ください。

A video of the 'Geo Locator Game' in action with a user guessing a couple of cities and the agent showing the collected points.

演習 3: 参照用ファイルを追加 (ボーナス)

同じゲームを繰り返すだけでは飽きてしまいます。ゲームを常に新鮮でチャレンジングに保つため、定期的に更新されるデータへアクセスできるようにしましょう。前述のとおり、宣言型エージェントには SharePoint サイトや OneDrive を参照する機能があります。ここではエージェントに 2 つのファイルをアクセスさせます。

手順 1: SharePoint にファイルをアップロード

以下の ZIP ファイルをダウンロードします: リンク

ZIP を展開し、同一テナントの SharePoint Teams サイトの Documents ライブラリへ 2 つの PDF ファイル (historical_map.pdf, travelers_diary) をアップロードします。

サイトの絶対 URL をコピーします (例: https://xyz.sharepoint.com/sites/contoso)。

[!NOTE] ファイルやフォルダーのフルパスは SharePoint の「Copy direct link」で取得できます。対象を右クリックし Details → Path のコピーアイコンを選択してください。

次の手順へ進みます。

手順 2: 宣言型エージェントマニフェストを更新

環境ファイル .env.dev を開き、変数 SP_SITE_URL を追加して SharePoint サイトの絶対 URL を値として設定します。

続いて appPackage/declarativeAgent.json を開き、conversation_starters 配列の後ろにカンマ , を追加し、下記の配列オブジェクトを貼り付けて SharePoint データ参照機能を拡張します。

 "capabilities": [
        {

            "name": "OneDriveAndSharePoint",
            "items_by_url": [
            {
                "url": "${{SP_SITE_URL}}"
            }
        ]
        }
    ]

これで宣言型エージェントがこの SharePoint サイトのドキュメントを読み取れるようになり、ゲームがさらにスパイスアップされます。
URL は制限なく追加可能です 💪🏼

手順 3: アプリマニフェストをアップグレード

appPackage/manifest.json を開き、version を "1.0.0" から "1.0.1" に更新します。これによりインストール時に変更が反映されます。

手順 4: アプリをテスト

Visual Studio Code の Agents Toolkit 拡張機能を開き、左ペインの "LIFECYCLE" から "Provision" を実行してアップグレード版エージェントをパッケージ化・インストールします。
Microsoft 365 Copilot BizChat (https://microsoft365.com/copilot/) を開き、開発テナントでサインインします。
再度 "Geo Locator Game" を起動します。

The UI of Microsoft 365 Copilot when the 'Geo Locator Game' agent is selected. The image highlights the conversation starters.

今回は旅行日記を使ったチャレンジを試してください。2 つ目のコンバーセーションスターターを選びます。

The 'Geo Locator Game' when relying on the travel diary. The agent answers providing a reference to the travelers_diary.pdf document stored in SharePoint Online.

あなたは宣言型エージェントのボスになりましたね。詳しくは次の動画をご覧ください。

Declarative エージェントの紹介

参考資料

おめでとうございます！

ゲームエージェントの構築お疲れさまでした 🎉! 次のラボでは REST API を作成し、それを使ってプラグインを構築し、別のエージェントで実際のビジネスシナリオを解決していきます。ワクワクしますね。 Next を選択して次のラボへ進みましょう。

ラボ E1 - 指示ベース Geo Locator ゲーム エージェント