宣言型エージェントは、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 呼び出しを行う前にすべてのパラメーターを収集するようにエージェントに指示します。 これにより、エージェントが論理シーケンス内のすべての必要な情報を確実に収集します。
次の例は、複数ターンの会話とその結果のエージェント フローについて気象エージェントに指示する方法を示しています。
| エージェントの手順 | エージェント フロー |
|---|---|
| ユーザーが天気について尋ねる場合: - ユーザーに場所を尋ねます。 - 予測日をユーザーに尋ねる. - ユーザーにユニット system. を要求する- すべての値を収集する場合にのみ getWeather を呼び出します。 |
利用者：「天気とは」 エージェント："場所は何ですか?" ユーザー: "London" Agent: "メトリック単位またはインペリアル 単位の気象情報を希望しますか?" ユーザー: "Metric" Agent: "今日の天気が必要ですか、明日の予測が必要ですか?" ユーザー: "Today" Agent: "今日のロンドンの天気をチェックします" Agent call: getWeather(location="London", forecast="today", system="Metric") |
エージェントの手順の一般的なベスト プラクティスについては、「 効果的な手順を記述する」を参照してください。
API プラグインでの関数呼び出しのチェーン
関数呼び出しをチェーンすると、宣言型エージェントは複数の API アクションを 1 つのシームレスなフローで結合できます。 次のセクションでは、一般的なパターンと、それぞれの手順を記述する方法について説明します。
出力を入力パラメーターとして関数呼び出しをチェーンする
ある API 呼び出しの結果を別の API 呼び出しの入力として使用します。 これは、2 番目の関数を実行するために最初の関数の結果が必要な場合に便利です。 これは、プラグイン間で機能します。
次の例では、Weather API と To-do API を使用した宣言型エージェントによって、天気予報からのデータを含む To Do タスクが作成されます。
| エージェントの手順 | エージェント フロー |
|---|---|
| 天気を取得するには、常に getWeather アクションを使用し、タイトル "temperature in" でタスクを作成し、天気に記載されている場所と温度をタスク タイトルに追加します。 |
利用者："Get the weather in Prague" Agent:getWeather (location="Prague", forecast="today") Agent: 最初の呼び出しのデータを使用して To Do タスク createTask (title ="{weather output}") を作成します |
1 つのエージェント内の会話履歴に基づくチェーン
会話履歴に基づいてチェーンを使用する場合、エージェントは以前の応答を使用してフォローアップ アクションを処理します。 この方法では、会話履歴を使用してコンテキストを維持します。
次の例では、エージェントが To Do を名前で削除します。
| エージェントの手順 | エージェント フロー |
|---|---|
| 1. ユーザーがすべての To Do を一覧表示するように求められたら、 getTasks を 呼び出して、タイトルと ID を使用して To Do の一覧を取得します 2. To Do を一覧表示した後、ユーザーが To Do を削除するように求められた場合は、応答の ID を使用して deleteTask を呼び出します。 |
利用者： "タスク フォルダー内のすべての to dos を表示する?" エージェント: alls getTasks (folderId="Tasks") で、ID を持つすべての To Dos が表示されます 利用者： "Delete 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") を呼び出し、ID を使用してすべての To Do を表示します エージェント： コード インタープリターを呼び出して、最初の呼び出しの出力に基づいてグラフの生成を開始します。 |
この例では、一度に複数のアクションも実行します。 これは、複数のユーザー入力を必要としない一連の関連アクションを開始するのに役立ちます。