API プラグインを使用して宣言型エージェントを作成する

7 分

宣言型エージェントにアクションを追加することで、外部システムに格納されているデータを取得および更新できます。エージェントをorganizationで使用する外部システムに接続すると、エージェントを使用してビジネスプロセスをサポートできます。以降のセクションでは、アクションを使用した宣言型エージェントの拡張に関連するさまざまな要素について説明します。

宣言型エージェント

宣言型エージェントには、外部システムとリアルタイムで対話できる 1 つ以上のアクションを含めることができます。エージェントは、アクションを使用して、外部アプリケーションに格納されているデータの読み取りと変更を行うことができます。アクションは、API プラグインを介して API に接続します。エージェントは、actions 配列を使用してマニフェストでその アクション を定義します。

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
  "version": "v1.0",
  "name": "Il Ristorante",
  "description": "Order the most delicious Italian dishes and drinks from the comfort of your desk.",
  "instructions": "$[file('instruction.txt')]",
  "actions": [
    {
      "id": "menuPlugin",
      "file": "ai-plugin.json"
    }
  ]
}

アクションを定義するには、 actions 配列に要素を追加します。各要素は 、ID を 使用してアクションを一意に識別し、 file プロパティを使用して、API プラグインを記述するプロジェクト内の個別のプラグイン定義ファイルを参照します。

プラグイン定義

プラグイン定義ファイルは、宣言型エージェントが API との通信に使用する API プラグインを記述します。プラグイン定義は、基本情報、関数、ランタイムなど、いくつかのセクションで構成されます。

基本情報

各プラグイン定義ファイルには、プラグインの名前や説明など、プラグインに関する基本情報が含まれています。次のコードスニペットは、基本的なプラグイン情報の例を示しています。

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.1/schema.json",
  "schema_version": "v2.1",
  "namespace": "ilristorante",
  "name_for_human": "Il Ristorante",
  "description_for_human": "See the today's menu and place orders",
  "description_for_model": "Plugin for getting the today's menu, optionally filtered by course and allergens, and placing orders",
  "functions": [
  ],
  "runtimes": [
  ],
  "capabilities": {
    "localization": {},
    "conversation_starters": []
  }
}

name_for_humanプロパティとdescription_for_humanプロパティの内容は、純粋に有益です。 description_for_model プロパティは、エージェントがそれを使用して、ユーザーのプロンプトに対してプラグインを呼び出す必要があるかどうかを判断するため、重要です。エージェントが特定のプロンプトに対してプラグインを呼び出していない場合は、モデルの説明に関連があるとエージェントが考慮するために必要な情報が含まれているかどうかをチェックする必要があります。

もう 1 つの重要なプロパティは、必要な名前空間と、エージェントがさまざまなプラグイン間でアクションを明確にするために使用する 名前空間 です。スキーマと一致しない無効な値を指定した場合、エージェントがプラグインを使用できなくなる可能性があります。名前空間は、次の正規表現 ^[A-Za-z0-9_]+と一致する必要があります。つまり、 A-Z、 a-z、 0-9、 _など、少なくとも 1 つの文字で構成する必要があります。その他の文字が無効です。

関数

プラグイン定義の次のセクションは関数です。関数は、API プラグインが実行できる 1 つ以上の API 操作を定義し、API から受信したデータを表示する方法をエージェントに指示します。次のコードスニペットは、関数の例を示しています。

{
  "functions": [
    {
      "name": "getDishes",
      "description": "Returns information about the dishes on the menu. Can filter by course (breakfast, lunch or dinner), name, allergens, or type (dish, drink).",
      "capabilities": {
        "response_semantics": {
          "data_path": "$.dishes",
          "properties": {
            "title": "$.name",
            "subtitle": "$.description"
          },
          "static_template": {
            ...trimmed for brevity
          }
        }
      }
    }
  ]
}

各関数は、複数の要素で構成されます。

名前

名前は API プラグイン内の操作を一意に識別し、関連する API 仕様の operationId と完全に一致する必要があります。指定した名前が操作と一致しない場合、Microsoft 365 Agents Toolkit はプロジェクトのビルド時にエラーをスローします。 operationId と一致しない名前の関数をデプロイした場合、エージェントはその関数を呼び出すことはできません。

説明

エージェントは説明を使用して、関数をユーザーのプロンプトに一致させます。関数を記述するときは、フィルター処理や並べ替え情報などのバリエーションを含め、完了するタスクを必ず説明してください。説明が不正確または不完全な場合、エージェントは特定のプロンプトと一致せず、関数を呼び出すことはできません。

応答セマンティクス

response_semantics プロパティは、API から受信したデータを表示する方法をエージェントに指示します。このプロパティは、data_path、プロパティ、static_templateの 3 つのプロパティで構成されます。

API が複雑なデータ構造を返し、エージェントにその特定の部分のみを表示する場合は、 data_path プロパティを使用して、API 応答の関連部分を指す JSON パス式を指定します。次の API 応答を検討してください。

{
  "dishes": [
    {
      "id": 1,
      "name": "Classic Italian Frittata",
      "description": "A fluffy omelette filled with sautéed mushrooms, onions, and melted pecorino, served with a side of roasted cherry tomatoes.",
      "image_url": "https://raw.githubusercontent.com/pnp/copilot-pro-dev-samples/main/samples/da-ristorante-api/assets/frittata.jpeg",
      "price": 8.99,
      "allergens": [
        "eggs",
        "dairy"
      ],
      "course": "breakfast",
      "type": "dish"
    },
    ...trimmed for brevity
  ]
}

エージェントに表示するデータは、dishes プロパティにあります。そのため、data_path プロパティを $.dishes JSONPath 式に設定します。これは、$で示されるルートオブジェクトの dishes プロパティを参照します。

応答セマンティクスの次の部分は プロパティです。プロパティを使用して、API 応答のデータプロパティのうち、タイトル、説明、URL などのアイテムのプロパティを表すデータプロパティをエージェントに伝えます。 API が複数の項目を返す場合、エージェントはセマンティックマッピングを使用して、最も関連性の高い情報を応答に含めます。次のセマンティックマッピングについて考えてみましょう。

{
  "response_semantics": {
    "properties": {
      "title": "$.name",
      "subtitle": "$.description"
    }
  }
}

エージェントが応答すると、次のような回答が生成されます。

各料理について、エージェントには太字のタイトルと説明が含まれます。マッピングには URL または秘密度ラベルが含まれていないため、エージェントはその応答に含まれません。

応答セマンティクスの最後の部分は static_templateです。静的テンプレートを使用して、エージェントが API からのデータを表示するために使用するアダプティブカードテンプレートを定義します。

ヒント

API プラグインでアダプティブカードテンプレートを使用する方法の詳細については、この学習モジュールの最後にある「その他のリソース」セクション の「アダプティブカードを使用して宣言型エージェントの API プラグインにデータを表示 する」learn モジュールを参照してください。

ランタイム

プラグイン定義の最後の部分は ランタイムです。ランタイムは、プラグインが使用する API と、どの API に属する関数を記述します。次のスニペットは、ランタイム定義を示しています。

{
  "type": "OpenApi",
  "auth": {
    "type": "None"
  },
  "spec": {
    "url": "apiSpecificationFile/ristorante.yml"
  },
  "run_for_functions": [
    "getDishes",
    "placeOrder"
  ]
}

最初に、API の説明の種類を定義します。現在、API プラグインでは OpenAPI のみがサポートされています。

次に、API が匿名であるか、認証が必要かどうかを定義します。認証の種類 None は、エージェントが API を匿名で呼び出すことができることを意味します。セキュリティで保護された API と通信する必要がある場合は、API の認証メカニズムに合わせて値を更新します。サポートされている認証メカニズムの詳細については、ドキュメントを参照してください。

ヒント

API プラグインをセキュリティで保護された API に接続する方法の詳細については、この学習モジュールの最後にある「 セキュリティで保護された API を使用した宣言型エージェントの API プラグインの認証」 の「その他のリソース」セクションを参照してください。

spec という名前の次のセクションでは、API プラグインで使用できる API について説明するローカル API 仕様ドキュメントへの参照を提供します。 url プロパティを使用して、プロジェクト内のファイルへの相対パスを指定します。

最後の部分は、指定された関数のうち、この API に属するかを指定する run_for_functions プロパティです。

ヒント

プロジェクトをビルドするときに、Microsoft 365 Agents Toolkit は、このプロパティで指定された関数が functions セクションで定義されている関数と一致することを確認し、そうでない場合はエラーで失敗します。 Microsoft 365 Agents Toolkit でプロジェクトの整合性を確認すると、早期のフィードバックが得られ、エラーのデバッグが難しいのを防ぐことができます。

API 仕様

各 API プラグインの重要な部分は API 仕様であり、API に関する次のような重要な情報を提供します。

API が配置されている場所。
API で認証が必要な場合は、どのような方法で行います。
API でサポートされる操作。
各操作について、予想されるデータと応答方法。

エージェントは、API プラグインを読み込むとき、この情報をすべて使用して API 要求をビルドし、API を呼び出して応答を処理します。そのため、エージェントがユーザーの要求を満たすためにそれらを使用する方法を理解できるように、すべてのパラメーターとプロパティを明確に記述することが重要です。

既存の API を使用する場合は、API プラグインで使用する予定の API 仕様の部分のみを含めておきます。 API 仕様全体を含めて、1 つまたは 2 つの操作のみを使用すると、エージェントが大きな API 仕様から関連情報を解析するのが困難になります。

ヒント

既存の API 仕様の一部を使用する必要がある場合は、Hidi の使用を検討してください。これは Microsoft によって構築されたツールであり、API 仕様の関連部分と関連するすべてのエンティティを簡単に抽出できます。詳細については、この学習モジュールの最後に説明します。

エージェントは、YAML と JSON の両方で OpenAPI API 仕様をサポートします。

ヒント

API プラグインで使用するカスタム API を構築し、ローカルコンピューターから実行する場合は、エージェントが呼び出すことができるようにインターネットに公開する必要があります。開発トンネルを使用して API を公開できます。これは、インターネット経由でローカルサービスを共有するために Microsoft によって作成されたツールです。 Microsoft 365 Agents Toolkit を使用して API プラグインを使用してエージェントをビルドすると、開発トンネルが自動的に開始されるだけでなく、API 仕様の API の URL も自動的に更新されるため、ソリューションの構築に集中できます。

組み合わせる方法

API プラグインを持つ宣言型エージェントが構成するさまざまな要素について説明したので、それらがどのように組み合わされているかを見てみましょう。次の図は、さまざまな要素間のリレーションシップを示しています。

Microsoft Teams アプリを使用して、エージェントのパッケージ化と配布を行います。各 Teams アプリには、特定のシナリオ用に最適化された 1 つ以上の宣言型エージェントを含めることができます。エージェントには、その目的に応じて、外部システムとの通信を可能にする 0 個以上の API プラグインを含めることができます。プラグインは、1 つ以上の関数を定義します。各関数は特定のタスクを実行し、正確に 1 つの API 操作を参照します。関数の横にある API プラグインは、使用する API を記述する 1 つ以上の API 仕様を参照します。そのターンで、各 API 仕様は、プラグインがその関数を通じて使用できる 1 つ以上の操作を定義します。

フィードバック

このページはお役に立ちましたか?