宣言型エージェントは、organization の特定のニーズに合わせて Microsoft 365 Copilot を調整します。 Microsoft 365 Agents Toolkit を使用して宣言型エージェントを構築する場合、API プラグインを使用してエージェントにスキルを追加できます。 API プラグインを使用すると、エージェントは API を介してorganizationのデータをクエリし、操作できます。
この記事では、エージェントのアーキテクチャについて説明し、API プラグインを含む宣言型エージェントの手順を記述するためのベスト プラクティスを提供します。
API プラグインを使用した宣言型エージェントの主なコンポーネント
API プラグインを呼び出す宣言型エージェントには、効果的な統合と機能を保証するいくつかのコンポーネントが含まれています。 このアーキテクチャを理解すると、エージェントを効果的に設計するのに役立ちます。 このアーキテクチャには、次のコンポーネントが含まれています。
- アプリケーション マニフェスト - アプリの構成方法を説明し、宣言型エージェント マニフェストを参照します。
- 宣言型エージェント マニフェスト - 指示、機能、会話スターター、アクションなどを含むエージェントの構成を定義します。 プラグイン マニフェストを参照します。
- プラグイン マニフェスト - 使用可能な関数や OpenAPI 仕様への参照など、プラグイン構成について説明します。
- OpenAPI 仕様 - パス、パラメーター、要求と応答の形式、認証など、API エンドポイントの詳細な定義を提供します。
これらのファイルが一緒になって、エージェントの動作と、基になる API と対話する方法が定義されます。
API プラグインの詳細については、次を参照してください。
プラグイン マニフェストでの関数のマッピング
プラグイン マニフェストでは、各関数を OpenAPI 仕様の対応する operationId にマップする必要があります。 これにより、エージェントが関数 ( createTask など) を呼び出すときに、エージェントは呼び出す API エンドポイントを確実に認識します。
次の例は、プラグイン マニフェストのマッピングと OpenAPI 仕様のマップされた関数を示しています。
"functions": [
{
"name": "createTask",
"description": "Creates a new task in the specified task list."
}
]
paths:
/me/todo/lists/{listId}/tasks:
post:
operationId: createTask
summary: Create a new task
description: Creates a new task in the specified task list.
parameters:
エージェント命令のベスト プラクティス
効果的な命令を記述することは、API プラグインを備えた宣言型エージェントを確実に成功させるために不可欠です。 エージェントを最適化するには、正しい関数マッピングを適用し、チェーンを使用してより豊富な対話を有効にし、エージェントの動作を繰り返しテストして改良します。
API プラグインを使用して宣言型エージェントの手順を記述する場合は、次のベスト プラクティスを適用します。
- あいまいな指示や否定的な指示は避けてください。 対照的な命令や否定的な命令はあいまいさをもたらし、モデルを混乱させる可能性があります。 肯定的な例を使用して有効なユース ケースを定義することに重点を置きます。 有効なクエリと無効なクエリを区別することが重要な場合は、それぞれに対して予想されるエージェントの応答を定義する明確な基準と例を提供します。
- 使用例 エージェントの動作をガイドするための明確な例を提供します。 例:
ユーザー入力: プラハの天気はどうですか? エージェント呼び出し: getWeather(location="Prague") ユーザー入力: 「明日傘は必要ですか?」 エージェント呼び出し: getWeather(location=user_location, forecast="tomorrow")
手順を確認してテストします。 さまざまなシナリオで手順をテストして、エージェントが正しい関数呼び出しを行ったことを確認します。 テストでエージェントが予期せず関数を呼び出すことがわかった場合は、OpenAPI 仕様の関数の説明を修正し、エージェント命令を明確にしてインテント マッピングを改善します。
マルチターン会話の設計手順。 API プラグインを統合する場合は、エージェントがマルチターンの会話を処理するための指示を設計します。
たとえば、関数に複数のパラメーターが必要な場合は、OpenAPI 仕様で必要なパラメーターを定義するだけでなく、API 呼び出しを行う前にすべてのパラメーターを収集するようにエージェントに指示します。 これにより、エージェントは必要なすべての情報を論理的な順序で収集します。
次の例は、複数ターンの会話について気象エージェントに指示する方法と、その結果として得られるエージェント フローを示します。
| エージェントの手順 | エージェント フロー |
|---|---|
| ユーザーが天気について尋ねた場合: - ユーザーに場所を尋ねます。 - ユーザーに予報日を尋ねます。 - ユーザーに単位システムを確認します。 - すべての値を収集した場合にのみ getWeather を呼び出します。 |
ユーザー:「天気は?」 エージェント:「現在地はどこですか?」 ユーザー: "ロンドン" エージェント: "メートル法とインペリアル単位のどちらでの気象情報が好きですか?" ユーザー: "メトリック" エージェント: "今日の天気と明日の天気予報のどちらが必要ですか?" ユーザー: "今日" エージェント: "今日のロンドンの天気をチェックします" エージェント呼び出し: getWeather(location="London", forecast="today", system="Metric") |
エージェント命令の一般的なベスト プラクティスについては、「 効果的な命令を作成する」を参照してください。
API プラグインでの関数呼び出しのチェーン
関数呼び出しをチェーンすることで、宣言型エージェントは複数の API アクションを 1 つのシームレスなフローで組み合わせることができます。 次のセクションでは、一般的なパターンと、それぞれの命令を記述する方法について説明します。
入力パラメーターとして出力を使用する関数呼び出しのチェーン
1 つの API 呼び出しの結果を別の API への入力として使用します。 これは、最初の関数の結果が 2 番目の関数を実行するために必要な場合に便利です。 これは、複数のプラグインで機能します。
次の例では、Weather API と To-do API を持つ宣言型エージェントが、天気予報のデータを使用して To Do タスクを作成します。
| エージェントの手順 | エージェント フロー |
|---|---|
| 天気を取得するには、必ず getWeather アクションを使用し、タイトルが "temperature in" のタスクを作成し、天気に記載されている場所と気温をタスク タイトルに追加します。 |
ユーザー:"プラハの天気情報を入手" エージェント:getWeather (location="Prague", forecast="today") エージェント: 最初の呼び出しのデータを使用して To Do タスクを作成します createTask (title ="{weather output}") |
1 つのエージェント内の会話履歴に基づくチェーン
会話履歴に基づくチェーンを使用する場合、エージェントは以前の応答を使用してフォローアップアクションを処理します。 このアプローチでは、会話履歴を使用してコンテキストを維持します。
次の例では、エージェントが To Do を名前で削除します。
| エージェントの手順 | エージェント フロー |
|---|---|
| 1. ユーザーがすべての To Do を一覧表示するように要求したら、 getTasks を呼び出して、タイトルと ID を含む To Do のリストを取得します。 2. To Do を一覧表示した後、ユーザーが To Do の削除を求めた場合は、応答の ID を使用して deleteTask を呼び出します。 |
ユーザー: "タスク フォルダー内のすべての To Do を表示しますか?" エージェント: alls getTasks (folderId="Tasks") を作成し、すべての To Do を ID 付きで表示します。 ユーザー: 「TaskMaster Pro to-doを削除」 Agent: 会話履歴の情報を使用して To Do の ID を見つけ、 deleteTask を呼び出して To Do を削除します。 |
SharePoint の知識とのチェーン
API 呼び出しをチェーンすることで、エージェントはナレッジ ソースとアクションを組み合わせて、より複雑なワークフローを設計できます。
次の例では、エージェントが SharePoint からプロジェクト状態データを取得し、追跡用に Microsoft To-Do で対応するタスクを作成します。
| エージェントの手順 | エージェント フロー |
|---|---|
| - プロジェクトのステータスを取得するには、SharePoint ナレッジ ProjectDeadlines を使用します。 - 常にタイトルのステータス更新を使用して、各プロジェクトの To Do を作成します。 |
ユーザー: "すべてのプロジェクトのステータスに関する最新情報を提供できますか?」 エージェント: SharePoint からプロジェクト状態データをプルし、 createTask を使用して各プロジェクトの To Do タスクを生成します。 |
コード インタープリターとのチェーン
API 呼び出しをチェーン化し、コード インタープリターなどの追加機能を統合することもできます。 これにより、エージェントは API 出力を動的に処理して、より高度なワークフローを実現できます。
次の例では、エージェントが To Do タスクのデータに基づいてグラフを作成します。
| エージェントの手順 | エージェント フロー |
|---|---|
| ユーザーがすべての To Do を一覧表示するように要求したら、 getTasks を呼び出してタイトルと ID を持つ To Do のリストを取得し、出力のグラフもプロットします。 |
ユーザー: 「タスク内のすべてのタスクを取得する」 Agent:getTasks (folderId="Tasks") を呼び出し、すべての To Do を ID 付きで表示します。 エージェント: コード インタープリターを呼び出して、最初の呼び出しの出力に基づいてグラフの生成を開始します。 |
この例では、一度に複数のアクションも実行します。 これは、複数のユーザー入力を必要としない一連の関連アクションを開始する場合に便利です。
コード インタープリターがファイル (グラフ画像やスプレッドシートなど) を生成すると、Copilot は応答にダウンロード リンクを自動的に表示し、ユーザーがファイルをローカルに保存できるようにします。 詳細については、「 ダウンロード可能なファイルの生成」を参照してください。