応答セマンティクスを使用して引用文献を表示する

引用文献は、Microsoft 365 Copilot応答が正確で根拠のある信頼を築きます。応答本文には、Copilot 合成応答の引用が自動的に含まれます。ただし、エンドユーザーが情報ソースを開けることができない場合があります。 Copilot がパブリック Web コンテンツに対する応答を根拠とする場合、URL は自動的に引用されます。

モデルコンテキストプロトコル (MCP) サーバーまたは API からのコンテンツの場合、そのコンテンツはエンドユーザーが開いて確認できる URL を返す必要があります。プラグイン定義で response_semantics を定義して、Copilot がその URL がプラグイン応答内のどこにあるかを認識し、引用を右のリンクでクリックできるようにします。

この手順をスキップしても、応答には引用が含まれますが、代表的なピルまたはアイコンのみが含まれます。エンドユーザーがクリックしてサイトのデータを確認することはできません。そのため、クリック可能な引用は、ストアに発行されたアプリのMicrosoft 365 Copilotエージェントストアポリシー要件でもあります。

また、Copilot は共通フィールド名から引用メタデータを自動的に推論できるため、 response_semanticsを明示的に定義する必要がなくなりました。明示的な response_semantics は、それらを指定するときに引き続き優先されます。この動的フォールバックに依存することは、実行時にツールサーフェスが変更される可能性がある動的ツール検出を使用する場合に特に便利です。詳細については、「動的応答セマンティクス」を参照してください。

Copilot 応答でクリック可能な引用のホバーエクスペリエンス。

重要

引用を得るためにアダプティブカードは必要ありません。応答セマンティクス ( data_path といくつかの properties マッピング) だけでは、Copilot がソースを指すクリック可能な引用をレンダリングするのに十分です。

引用を超えたリッチ UX に対話型 MCP アプリを使用することを検討してください。

応答セマンティクスの使用

プラグインマニフェストで定義されている応答セマンティクスは、MCP サーバーまたは API と Copilot の間のコントラクトとして機能します。

ツールから JSON が返されます。
プラグインマニフェストで、次の手順を実行します。
- その JSON のどこに引用可能な項目が配置されているかを Copilot に伝えます (data_path)。
- 各アイテムのどのフィールドが引用文献のタイトル、サブタイトル、URL (properties) にマップされるかを Copilot に伝えます。
Copilot は各項目の引用をレンダリングします。ユーザーがソースをクリックします。

明示的な properties マッピングを指定した場合、Copilot はそれらをそのまま使用します。動的推論は、これらのマッピングが存在しない場合にのみ適用されます。詳細については、「動的応答セマンティクス」を参照してください。

最小構成

response_semantics構成は、ツール応答のプロトコルではなく、ツールの応答の形状によって駆動されます。すべてのツールプロトコル (MCP、OpenAPI、メッセージ拡張機能) を持つ Copilot エージェントは、同じマニフェストスキーマを使用します。

ほとんどのツール応答は、次の 2 つの図形のいずれかに分類されます。

結果の配列 (検索ツールなど): ツールは複数の項目を返します。それぞれが独自の引用になります。
1 つのオブジェクト (フェッチツールなど): ツールは 1 つのドキュメントまたはレコードを正確に返します。これは単一の引用になります。

結果の配列 (検索スタイル)

次の例に示すように、通常、複数の項目を返すツールは、 results (または同等の) キーの下に配列を返します。

{
  "results": [
    {
      "id": "tr-001",
      "title": "Forecasting AI adoption in the enterprise (2026)",
      "url": "https://www.treyresearch.net/notes/ai-adoption-2026",
      "publishedDate": "2026-03-12",
      "thumbnailUrl": "https://www.treyresearch.net/assets/trey-research-logo.png"
    },
    {
      "id": "tr-005",
      "title": "Enterprise AI spend, deep dive",
      "url": "https://www.treyresearch.net/notes/ai-spend",
      "publishedDate": "2026-03-28",
      "thumbnailUrl": "https://www.treyresearch.net/assets/trey-research-logo.png"
    }
  ]
}

次の例は、プラグインマニフェストの最小応答セマンティクス構成を示しています。

"capabilities": {
  "response_semantics": {
    "data_path": "$.results",
    "properties": {
      "title": "$.title",
      "subtitle": "$.publishedDate",
      "url": "$.url"
    }
  }
}

data_path プロパティは配列を指します。各要素は、独自のクリック可能な引用を生成します。 properties JSONPath は、ルートではなく、各配列要素を基準にして解決されます。

単一オブジェクト (fetch-style)

次の例は、1 つのレコード (ドキュメント、エンティティ、ファイル) を 1 つのソースとして引用する、正確に 1 つのレコードを含む応答を示しています。

{
  "id": "tr-001",
  "title": "Forecasting AI adoption in the enterprise (2026)",
  "text": "Trey Research surveyed 412 enterprise CIOs across North America and EMEA between January and February 2026. We forecast that 64% of Fortune 500 firms will be running at least one production generative AI workload by end of 2026, up from 38% at the close of 2025...",
  "url": "https://www.treyresearch.net/notes/ai-adoption-2026",
  "publishedDate": "2026-03-12",
  "thumbnailUrl": "https://www.treyresearch.net/assets/trey-research-logo.png",
  "metadata": { "source": "trey-research", "category": "AI" }
}

次の例は、プラグインマニフェストの最小応答セマンティクス構成を示しています。

"capabilities": {
  "response_semantics": {
    "data_path": "$",
    "properties": {
      "title": "$.title",
      "subtitle": "$.publishedDate",
      "url": "$.url"
    }
  }
}

$ に設定されている data_path プロパティは、単一の引用項目としてルートオブジェクトを選択します。これは、 metadataなどの入れ子になったフィールドがレコードに含まれている場合でも、ツールが 1 つのレコードを返すたびに適切な選択です。

MCP コンテンツラッパー

MCP ツールは、応答をTextContentBlock項目のcontent配列にラップします。 Copilot は、各ブロックの text フィールドを JSON として解析し、解析された値に対して data_path を適用します。 text文字列内の図形は、外部のcontent ラッパーではなく、構成を駆動します。

MCP 応答の例

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\":\"tr-001\",\"title\":\"Forecasting AI adoption in the enterprise (2026)\",\"url\":\"https://www.treyresearch.net/notes/ai-adoption-2026\"}"
    }
  ]
}

パーサーは、最初に text ペイロードをラップ解除し、1 つのオブジェクトを残します。単一オブジェクト構成 ("data_path": "$") を使用します。 text フィールド内の配列を返す MCP 検索ツールは、結果構成の配列 (data_path: "$.results") を使用します。

動的応答セマンティクス (ゼロ構成フォールバック)

明示的な response_semantics は、ツールが安定していて変更されていない場合にのみ適切に機能します。多くの場合、サードパーティの MCP サーバー上に構築されたコネクタはツールを頻繁に更新するため、サーバーの進化に合わせてマニフェストを同期する必要があります。サーバーが変更されたがマニフェストが変更されない場合、構造化された接地は無言で未加工のテキストにフォールバックし、引用文献はレンダリングを停止します。

マニフェストが明示的な properties マッピングを省略すると、Copilot は、既知のエイリアスの優先順位付けされたリストに対して各結果オブジェクトをスキャンすることで引用フィールドを推論します。このゼロ構成フォールバックは、マニフェストを固定ツールサーフェイスにピン留めできない動的ツール検出で特に便利です。

フィールドエイリアス

引用フィールドごとに、Copilot は次のエイリアスを優先順位でチェックし、最初に見つかった一致を使用します。

引用フィールド	エイリアス (優先順位)
URL	`display_url`, `displayUrl`, `web_url`, `webUrl`, `url`, `citation_url`, `citationUrl`, `reference_url`, `referenceUrl`, `website_url`, `websiteUrl`, `web_link`, `webLink`, `link`, `href`
タイトル	`display_title`, `displayTitle`, `title`, `name`, `display_name`, `displayName`, `web_title`, `webTitle`, `subject`, `heading`, `caption`
サブタイトル	`subtitle`, `description`, `summary`, `snippet`, `source`, `provider`, `site_name`, `siteName`, `highlight`
サムネイル	`thumbnail_url`, `thumbnailUrl`, `thumbnail`, `image_url`, `imageUrl`, `logo_url`, `logoUrl`, `icon_url`, `iconUrl`
結果の配列	`results`, `items`, `data`, `value`, `records`, `entries`

解決ルール

URL はハード要件です。 空でない URL が見つからない場合、Copilot は要素をスキップし、引用を出力しません。
タイトルエイリアスが存在しない場合、タイトルはホスト名にフォールバックします。
サブタイトルとサムネイルは日和見的です。 Copilot は、一致するフィールドを認識し、それ以外の場合は省略するときにそれらを含めます。

例

MCP ツールが次の応答を返す場合は、 response_semantics を明示的に定義する必要はありません。 Copilot は、よく知られているエイリアスから引用フィールドを推論します。

{
  "isError": false,
  "content": [
    {
      "type": "text",
      "text": "<stringified results>"
    }
  ]
}

text フィールドには、文字列化された結果が含まれます。

{
  "results": [
    {
      "url": "https://example.com/result1",
      "title": "Result 1",
      "subtitle": "Subtitle for Result 1"
    },
    {
      "url": "https://example.com/result2",
      "title": "Result 2",
      "subtitle": "Subtitle for Result 2"
    }
  ]
}

results、url、title、subtitleはすべて既知のエイリアスと一致するため、Copilot は各項目のクリック可能な引用をレンダリングします。同等のエイリアスは、その代わりに機能します。たとえば、resultsではなくitemsやdata、urlではなくwebUrlやhrefなどです。

引用プロパティ

引用文献では、次のプロパティを使用できます。すべての値は、 data_pathによって選択された 1 つの項目に対する相対 JSONPath 式です。

プロパティ	必須	機能
`title`	はい (実質的には)	引用文献のクリック可能な見出し。
`subtitle`	不要	2 行目 - 日付、作成者、カテゴリ。
`url`	はい (実質的には)	引用文献がクリックで移動する場所。ソースへの正規のリンクである必要があります。
`thumbnail_url`	不要	引用文献と共に示された小さな画像。

注:

urlが見つからない場合、引用はクリックできません。この不足しているプロパティは、開発者が機能しない引用を見る非常に一般的な理由です。

設定 `data_path`

data_path プロパティは JSONPath (RFC 9535) 式です。不適切な JSONPath 式の使用は、引用が表示されない最も一般的な理由の 1 つです。

応答が次のようになります。...	この `data_path` を使用する
`{ "results": [ ... ] }`	`$.results`
`{ "content": [ { "results": [ ... ] } ] }` (MCP スタイルの入れ子)	`$.content[0].results`
ルートにある 1 つのオブジェクト (配列ラッパーなし)	`$`
`{ "content": [ { "type": "text", "text": "<stringified JSON>" } ] }` (raw MCP)	`$`ルートの場合、または内部 JSON に配列がある場合は`$.results`

ヒント

配列をフラット化します。 複数レベルの入れ子になった配列 (たとえば、 $.content[0].results[0].items) は、サイレントモードで失敗する可能性が最も高いスキーマパターンです。ツール応答図形を所有している場合は、フラットな results: [...] 配列を返します。

応答セマンティクスを超える

最初の設定として、リッチ UI ウィジェットをエージェントに追加することを検討してください。このアプローチは、より将来の準備が整い、AI ネイティブであるため、よりインテリジェントでアダプティブでシームレスな対話が可能になります。

次のいずれかの条件が必要な場合にのみ、アダプティブカードを最後の手段として追加します。

引用のみ (マルチ列、画像バナー、書式設定されたテキストブロック)、または引用カード本文にレンダリングされた複数のフィールド (タイトル、サブタイトル、URL を超える) のカスタムビジュアルレイアウト。
既定の "引用をクリック" 動作を超えるアクションボタン (Action.Execute、マルチボタンツールバーなど)。

引用シナリオの大部分 - "ソースを表示し、私がクリックしてみましょう" - アダプティブカードを完全にスキップします。複雑さが増し、デバッグが困難になり、既定の引用 UI はクリーンされ、Copilot の残りの部分と一致します。

アダプティブカードの例

"response_semantics": {
  "data_path": "$.content[1].results",
  "properties": {
    "title": "$.title",
    "subtitle": "$.publishedDate",
    "url": "$.url"
  },
  "staticTemplate": {
    "type": "AdaptiveCard",
    "version": "1.4",
    "body": [
      {
        "type": "TextBlock",
        "text": "${title}",
        "weight": "bolder",
        "size": "medium"
      },
      {
        "type": "TextBlock",
        "text": "${subtitle}",
        "isSubtle": true
      },
      {
        "type": "TextBlock",
        "text": "${text}",
        "wrap": true
      }
    ],
    "selectAction": {
      "type": "OpenUrl",
      "url": "${url}"
    }
  }
}

${title}、${subtitle}、${url} トークンに注目してください。これらのトークンは、前に示したのと同じproperties マップによって設定されます。アダプティブカードは、応答セマンティクスの上に 表示レイヤー です。置き換えられません。

トラブルシューティングチェックリスト

引用が表示されない場合は、次のチェックリストを使用します。

data_pathは適切なノードを指していますか? ツールの生の JSON 応答を JSONPath テスターに貼り付け、式が予期した配列またはオブジェクトを返していることを確認します。
各項目に空でない urlがありますか? URL が見つからないと、クリックできない引用が発生します。
MCP ツールの場合、有効な JSON 内の text フィールド TextContentBlock ですか? 手動で解析して確認します。
スキーマはフラットですか? 深く入れ子になった配列がある場合は、1 つのフラット配列を返してみてください。
プラグインのルートではなく、(その関数のcapabilities内の) 関数ごとにresponse_semanticsを宣言しましたか? 関数にスコープを設定する必要があります。

フィードバック

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

Last updated on 2026-07-30