Microsoft 365 Copilotの宣言型エージェントスキーマ 1.2

[アーティクル]
11/19/2024

この記事では、宣言型エージェントマニフェストで使用される 1.2 スキーマについて説明します。マニフェストは、マシンで読み取り可能なドキュメントであり、ユーザーの問題の選択セットへの対処に特化するために必要な指示、知識、アクションを大きな言語モデル (LLM) に提供します。

宣言型エージェントは、人間のようなテキストを理解して生成する上で重要であり、質問の書き込みや回答などのタスクに対して汎用性が高くなっています。この仕様では、特定のユーザーが必要とする機能を特化および強化するための構造化フレームワークとして機能する宣言型エージェントマニフェストに重点を置いています。

以前のバージョンからの変更

このスキーマバージョンでは、バージョン 1.0 から次の変更が導入されています。

sites プロパティが Web 検索オブジェクトに追加されます。これにより、Web 検索機能を許可されたサイトに制限できます。
グラフィックアート機能が追加されました。この機能により、宣言型エージェントはユーザー入力に基づいて画像とアートを生成できます。

JSON スキーマ

このドキュメントで説明されているスキーマは、 JSON スキーマ形式でこちらで確認できます。

規則

URL 内の相対参照

特に指定しない限り、URL であるプロパティはすべて相対参照になる場合があります。マニフェストドキュメント内の相対参照は、マニフェストドキュメントの場所を基準とします。

文字列の長さ

特に指定しない限り、すべての文字列プロパティを 4K 文字に制限する必要があります。この文字列の長さは、ドキュメント全体に許容されるサイズを与えるわけではありません。実装は、マニフェストの長さに独自の実用的な制限を自由に課すことができます。

認識されないプロパティ

このドキュメントで定義されている JSON オブジェクトでは、説明されているプロパティのみがサポートされています。 JSON オブジェクトの認識されないプロパティまたは余分なプロパティは、ドキュメント全体を無効にする必要があります。

文字列のローカライズ

ローカライズ可能な文字列では、リテラル値の代わりにローカライズキーを使用できます。構文は [[key_name]]で、 key_name はローカライズファイルの localizationKeys プロパティのキー名です。ローカライズの詳細については、「エージェントをローカライズする」を参照してください。

宣言型エージェントマニフェストオブジェクト

マニフェストドキュメントのルートは、必要なフィールド、機能、会話スターター、アクションをカバーする JSON オブジェクトです。

宣言型エージェントマニフェストオブジェクトには、次のプロパティが含まれています。

プロパティ	型	説明
`version`	String	必須。スキーマのバージョン。 `v1.2` に設定する必要があります。
`id`	String	省略可能。
`name`	String	必須です。ローカライズ。宣言型エージェントの名前。空白以外の文字が少なくとも 1 つ含まれており、100 文字以下である必要があります。
`description`	String	必須です。ローカライズ。宣言型エージェントの説明。空白以外の文字が少なくとも 1 つ含まれており、1,000 文字以下である必要があります。
`instructions`	String	必須です。宣言型エージェントの動作方法、その関数、および回避する動作に関する詳細な手順またはガイドライン。空白以外の文字が少なくとも 1 つ含まれており、8,000 文字以下である必要があります。
`capabilities`	Capabilities オブジェクトの配列	省略可能。宣言型エージェントの機能を定義するオブジェクトの配列を格納します。配列には、各派生型の Capabilities オブジェクトが複数存在してはなりません。
`conversation_starters`	Conversation スターターオブジェクトの配列	省略可能。タイトルとテキストはローカライズ可能です。宣言型エージェントが回答できる質問の例の一覧。配列には 6 つ以上のオブジェクトを含めてはいけません。
`actions`	Action オブジェクトの配列	省略可能。宣言型エージェントからアクセスできるアクションを提供する API プラグインを識別するオブジェクトの一覧。

宣言型エージェントマニフェストオブジェクトの例

次の JSON は、宣言型エージェントマニフェスト内の必須フィールドの例です。

{
  "name" : "Repairs agent",
  "description": "This declarative agent is meant to help track any tickets and repairs",
  "instructions": "This declarative agent needs to look at my Service Now and Jira tickets/instances to help me keep track of open items"
}

Capabilities オブジェクト

capabilities オブジェクトは、宣言型エージェントマニフェストオブジェクトの capabilities プロパティ内のオブジェクトの基本型です。使用可能なオブジェクト型は次のとおりです。

Web 検索オブジェクト
OneDrive オブジェクトと SharePoint オブジェクト
Microsoft Graph Connectors オブジェクト
グラフィックアートオブジェクト

機能の例

{
  "capabilities": [
    {
      "name": "WebSearch",
      "sites": [
        {
          "url": "https://contoso.com"
        }
      ]
    },
    {
      "name": "OneDriveAndSharePoint",
      "items_by_sharepoint_ids": [
        {
          "site_id": "bc54a8cc-8c2e-4e62-99cf-660b3594bbfd",
          "web_id": "a5377427-f041-49b5-a2e9-0d58f4343939",
          "list_id": "78A4158C-D2E0-4708-A07D-EE751111E462",
          "unique_id": "304fcfdf-8842-434d-a56f-44a1e54fbed2"
        }
      ],
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/teams/admins/Documents/Folders1"
        }
      ]
    },
    {
      "name": "GraphConnectors",
      "connections": [
        {
          "connection_id": "jiraTickets"
        }
      ]
    },
    {
      "name": "GraphicArt"
    },
    {
      "name": "CodeInterpreter"
    }
  ]
}

Web 検索オブジェクト

宣言型エージェントが Web で接地情報を検索できることを示します。

Web 検索オブジェクトには、次のプロパティが含まれています。

プロパティ	型	説明
`name`	String	必須。 `WebSearch` に設定する必要があります。
`sites`	Site オブジェクトの配列	省略可能。エージェントが検索できるサイトを識別するオブジェクトの配列。このプロパティを省略すると、すべてのエージェントですべてのサイトを検索できます。配列に 4 つ以上の項目を含めてはいけません。

Site オブジェクト

宣言型エージェントがコンテンツを検索できるサイトを示します。

サイトオブジェクトには、次のプロパティが含まれています。

プロパティ	型	説明
`url`	String	必須です。コンテンツを検索するサイトの絶対 URL。 URL には、2 つを超えるパスセグメントを含めてはいけません (たとえば、 `https://contoso.com/projects/mark-8` が有効で、 `https://contoso.com/projects/mark-8/beta-program` は無効です)。 URL にはクエリパラメーターを含めてはいけません。

OneDrive オブジェクトと SharePoint オブジェクト

宣言型エージェントがユーザーの SharePoint と OneDrive で接地情報を検索できることを示します。

OneDrive オブジェクトと SharePoint オブジェクトには、次のプロパティが含まれています。

プロパティ	型	説明
`name`	String	必須。 `OneDriveAndSharePoint` に設定する必要があります。
`items_by_sharepoint_ids`	SharePoint ID オブジェクトによる項目の配列	省略可能。 ID を使用して SharePoint または OneDrive ソースを識別するオブジェクトの配列。 `items_by_sharepoint_ids`プロパティと`items_by_url`プロパティの両方を省略すると、organization内のすべての OneDrive および Sharepoint ソースを宣言型エージェントで使用できます。
`items_by_url`	URL オブジェクトによる Items の配列	省略可能。 SharePoint または OneDrive ソースを URL で識別するオブジェクトの配列。 `items_by_sharepoint_ids`プロパティと`items_by_url`プロパティの両方を省略すると、organization内のすべての OneDrive および Sharepoint ソースを宣言型エージェントで使用できます。

SharePoint ID オブジェクト別の項目

Items by SharePoint IDs オブジェクトには、次のプロパティが含まれています。

プロパティ	型	説明
`site_id`	String	省略可能。 SharePoint サイトまたは OneDrive サイトの一意の GUID 識別子。
`web_id`	String	省略可能。 SharePoint または OneDrive サイト内の特定の Web の一意の GUID 識別子。
`list_id`	String	省略可能。 SharePoint または OneDrive サイト内のリストの一意の GUID 識別子。
`unique_id`	String	省略可能。特定のエンティティまたはリソースを表すために使用される一意の GUID 識別子。

ヒント

SharePoint または OneDrive リソースの一意の識別子を取得する手順については、「宣言型エージェントマニフェストの機能 ID の取得」を参照してください。

URL オブジェクト別の項目

Items by URL オブジェクトには、次のプロパティが含まれています。

プロパティ	型	説明
`url`	String	省略可能。 SharePoint または OneDrive リソースへの絶対 URL。

Microsoft Graph コネクタオブジェクト

宣言型エージェントが、選択した Microsoft Graph コネクタを検索して接地情報を検索できることを示します。

Microsoft Graph コネクタオブジェクトには、次のプロパティが含まれています。

プロパティ	型	説明
`name`	String	必須。 `GraphConnectors` に設定する必要があります。
`connections`	Connection オブジェクトの配列	省略可能。宣言型エージェントで使用できる Microsoft Graph コネクタを識別するオブジェクトの配列。このプロパティを省略すると、organization内のすべての Microsoft Graph コネクタを宣言型エージェントで使用できます。

Connection オブジェクト

Microsoft Graph コネクタを識別します。

接続オブジェクトには、次のプロパティが含まれています。

プロパティ	型	説明
`connection_id`	String	必須です。 Microsoft Graph コネクタの一意識別子。

ヒント

Microsoft Graph コネクタの一意の識別子を取得する手順については、「宣言型エージェントマニフェストの機能 ID の取得」を参照してください。

グラフィックアートオブジェクト

宣言型エージェントが、ユーザーからのテキスト入力に基づいて画像とアートを作成できることを示します。詳細については、「イメージジェネレーター」を参照してください。

グラフィックアートオブジェクトには、次のプロパティが含まれています。

プロパティ	型	説明
`name`	String	必須。 `GraphicArt` に設定する必要があります。

Conversation starters オブジェクト

マニフェストでは、conversation starters オブジェクトは省略可能です。これには、宣言型エージェントの使用を開始する方法を示すためにユーザーに表示されるヒントが含まれています。

会話スターターオブジェクトには、次のプロパティが含まれています。

プロパティ	型	説明
`text`	String	必須です。ローカライズ。宣言型エージェントから目的の結果を取得するためにユーザーが使用できる提案。空白以外の文字が少なくとも 1 つ含まれている必要があります。
`title`	String	省略可能。ローカライズ。会話スターターの一意のタイトル。空白以外の文字が少なくとも 1 つ含まれている必要があります。

Conversation starters オブジェクトの例

{
  "conversation_starters": [
    {
      "title": "My Open Repairs",
      "text": "What open repairs are assigned to me?"
    }
  ]
}

Actions オブジェクト

アクションは、マニフェスト内の省略可能な JSON オブジェクトです。これは開発者の入力として機能し、プラグインと見なすことができます。

アクションオブジェクトには、次のプロパティが含まれています。

プロパティ	型	説明
`id`	String	必須です。アクションの一意識別子。 GUID である可能性があります。
`file`	String	必須です。このアクションの API プラグインマニフェストへのパス。

Actions オブジェクトの例

{
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "plugin.json"
    }
  ]
}

宣言型エージェントマニフェストの例

この記事で説明するマニフェストプロパティの大部分を使用する宣言型エージェントマニフェストファイルの例を次に示します。

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.2/schema.json",
  "version": "v1.2",
  "name": "Teams Toolkit declarative copilot",
  "description": "Declarative copilot created with Teams Toolkit",
  "instructions": "You are a repairs expert copilot. With the response from the listRepairs function, you **must** create a poem out of the repairs listed and always include their title and the assigned person. The poem **must** not use the quote markdown and use regular text. If the user is asking to create a new repair, use the createRepair function and do not add poems.",
  "conversation_starters": [
    {
      "title": "Getting Started",
      "text": "How can I get started with Teams Toolkit?"
    },
    {
      "title": "Getting Help",
      "text": "How can I get help with Teams Toolkit?"
    }
  ],
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "repairs-hub-api-plugin.json"
    }
  ],
  "capabilities": [
    {
      "name": "WebSearch",
      "sites": [
        {
          "url": "https://contoso.com/projects/mark-8"
        }
      ]
    },
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/sites/ProductSupport"
        }
      ]
    },
    {
      "name": "GraphConnectors",
      "connections": [
        {
          "connection_id": "foodStore"
        }
      ]
    },
    {
      "name": "GraphicArt"
    },
    {
      "name": "CodeInterpreter"
    }
  ]
}

宣言型エージェントの効果的な命令を記述する

次の方法で共有

Microsoft 365 Copilotの宣言型エージェントスキーマ 1.2

以前のバージョンからの変更

JSON スキーマ

規則

URL 内の相対参照

文字列の長さ

認識されないプロパティ

文字列のローカライズ

宣言型エージェントマニフェストオブジェクト

宣言型エージェントマニフェストオブジェクトの例

Capabilities オブジェクト

機能の例

Web 検索オブジェクト

Site オブジェクト

OneDrive オブジェクトと SharePoint オブジェクト

SharePoint ID オブジェクト別の項目

URL オブジェクト別の項目

Microsoft Graph コネクタオブジェクト

Connection オブジェクト

グラフィックアートオブジェクト

Conversation starters オブジェクト

Conversation starters オブジェクトの例

Actions オブジェクト

Actions オブジェクトの例

宣言型エージェントマニフェストの例

フィードバック

その他のリソース

次の方法で共有

Microsoft 365 Copilotの宣言型エージェント スキーマ 1.2

以前のバージョンからの変更

JSON スキーマ

規則

URL 内の相対参照

文字列の長さ

認識されないプロパティ

文字列のローカライズ

宣言型エージェント マニフェスト オブジェクト

宣言型エージェント マニフェスト オブジェクトの例

Capabilities オブジェクト

機能の例

Web 検索オブジェクト

Site オブジェクト

OneDrive オブジェクトと SharePoint オブジェクト

SharePoint ID オブジェクト別の項目

URL オブジェクト別の項目

Microsoft Graph コネクタ オブジェクト

Connection オブジェクト

グラフィック アート オブジェクト

Conversation starters オブジェクト

Conversation starters オブジェクトの例

Actions オブジェクト

Actions オブジェクトの例

宣言型エージェント マニフェストの例

関連コンテンツ

フィードバック

その他のリソース

Microsoft 365 Copilotの宣言型エージェントスキーマ 1.2

宣言型エージェントマニフェストオブジェクト

宣言型エージェントマニフェストオブジェクトの例

Microsoft Graph コネクタオブジェクト

グラフィックアートオブジェクト

宣言型エージェントマニフェストの例