顯示具有回應語意的引文

引文建立信任,相信 Microsoft 365 Copilot 的回應正確且有根據。 回應內文會自動包含 Copilot 合成回應的引文。 不過,使用者不一定能夠開啟資訊的來源。 當 Copilot 在公用網頁內容上建立回應基礎時,系統會自動引用該 URL。

對於來自 模型內容通訊協定 (MCP) 伺服器 或 API 的內容,該內容可以傳回使用者可以開啟和檢閱的 URL。 您可以在外掛程式定義中定義 response_semantics ,讓 Copilot 知道該 URL 在外掛程式回應中的位置,並可以使用正確的連結點選引文。

如果您略過此步驟,回應仍然可以包含引文,但只能包含具有代表性的藥丸或圖示。 使用者無法點選並確認您網站中的資料。

Copilot 也可以從通用欄位名稱自動推斷引文中繼資料,因此您不再需要明確定義 response_semantics。 response_semantics提供明確設定時仍優先。 當您使用 動態工具探索時,依賴此動態遞補特別有用,其中工具表面可以在執行階段變更。 如需詳細資訊,請參閱 動態回應語意。

在 Copilot 回應中可點選引文的暫留體驗。

重要

您不需要調適型卡片即可取得引文。 光是回應語意 - 再加上 data_path 一些 properties 對應 - 就足以讓 Copilot 呈現可點選的引文,並指向您的來源。

考慮使用互動式 MCP 應用程式 來獲得引文之外的豐富使用者體驗。

使用回應語意

外掛程式資訊清單中定義的回應語意可作為 MCP 伺服器或 API 與 Copilot 之間的合約。

  1. 您的工具傳回 JSON。

  2. 在 外掛程式資訊清單中:

    • 您可以告訴 Copilot 可引用項目在該 JSON 中的位置 (data_path) 。
    • 您可以告訴 Copilot 每個項目上的哪些欄位會對應到引文的標題、副標題和 URL (properties) 。
  3. Copilot 會為每個項目呈現引文。 使用者點選前往您的來源。

如果您提供明確 properties 的對應,Copilot 會按原樣使用它們。 只有當這些對應缺失時,動態推論才適用。 如需詳細資訊,請參閱 動態回應語意。

最低設定

您的 response_semantics 組態是由工具回應的形狀所驅動,而不是由工具回應的通訊協定所驅動。 具有所有工具通訊協定的 Copilot 代理程式 (MCP、OpenAPI、訊息延伸模組) 使用相同的資訊清單架構。

大部分的工具回應都分為以下兩種形狀之一:

  • 結果陣列 ( 類似搜尋工具) :該工具會傳回多個項目,每個項目都應該成為自己的引文。
  • 單一物件 (類似於擷取工具) :工具只會傳回一份文件或記錄,這會變成單一引文。

搜尋樣式) (結果陣列

傳回多個項目的工具通常會在 (或對等的) 機碼下 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 是相對於每個陣列元素解析,而不是根。

單一物件 (擷取樣式)

下列範例顯示只有一筆記錄 (文件、實體、檔案) 要作為單一來源引用的回應。

{
  "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。

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 承載,留下單一物件。 您可以使用 單一物件 組態 ("data_path": "$") 。 在欄位內 text 傳回陣列的 MCP 搜尋工具會使用 結果陣列 設定 (data_path: "$.results") 。

動態回應語意 (零設定後援)

只有當您的工具穩定且不變時,明確才能 response_semantics 正常運作。 但事實通常並非如此:建置在協力廠商 MCP 伺服器上的連接器會經常更新其工具,因此您必須隨著伺服器的演進而保持資訊清單同步。 當伺服器變更但資訊清單未變更時,結構化基礎設置會以無訊息方式回復為原始文字,引文會停止轉譯。

當您的資訊清單省略明確 properties 對應時,Copilot 會針對已知別名的優先順序清單掃描每個結果物件,藉此推斷引文欄位。 此零設定遞補對於 動態工具探索特別有用,因為在動態工具探索中,您無法將資訊清單釘選到固定的工具介面。

欄位別名

針對每個引文欄位,Copilot 會依優先順序檢查下列別名,並使用找到的第一個相符項目。

Citation 功能變數 別名 (優先順序)
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"
    }
  ]
}

因為 、 url、 title及subtitle全部符合已知別名,因此 resultsCopilot 會為每個項目呈現可點選的引文。 任何對等的別名都可以取代它們的位置 - 例如,或代替 items 、 或 webUrlurlhref 或 代替 。resultsdata

引文屬性

引文上提供下列屬性。 所有值都是針對由 選取 data_path的一個項目的相對 JSONPath 運算式。

屬性 必要 功能
title 是的, (實際上) 引文的可點選標題。
subtitle 否 第二行 - 日期、作者、類別。
url 是的, (實際上) 按一下時引文瀏覽的位置。 必須是返回來源的規範連結。
thumbnail_url 否 引文旁邊顯示的小圖片。

注意

如果遺失,則 url 無法點選引文。 這種缺失的屬性是開發人員看到非功能性引用的一個非常常見的原因。

設定 data_path

data_path屬性是 JSONPath (RFC 9535) 運算式。 使用不正確的 JSONPath 運算式是無法顯示引文的最常見原因之一。

如果您的回應看起來像... 使用 data_path
{ "results": [ ... ] } $.results
{ "content": [ { "results": [ ... ] } ] } (MCP 樣式的巢狀) $.content[0].results
根目錄的單一物件 (沒有陣列包裝函式) $
{ "content": [ { "type": "text", "text": "<stringified JSON>" } ] } (原始 MCP) $ for root,或 $.results 內部 JSON 是否有陣列

秘訣

將陣列展平。 例如, $.content[0].results[0].items 多層級巢狀陣列 () 是最有可能以無訊息方式失敗的架構模式。 如果您擁有工具回應圖形,請傳回平面 results: [...] 陣列。

超越回應語意

作為首要偏好, 請考慮將 豐富的 UI 小工具新增至您的代理程式。 這種方法更面向未來且人工智慧原生,可實現更智慧、適應性和無縫的互動。

注意

本節中的自適性卡片指導方針僅適用於 宣告式代理程式。 staticTemplate Copilot 連接器不支援引文的屬性和調適型卡片轉譯。

新增調適型卡片作為最後的手段,前提是 - 僅當 - 您需要下列其中一個條件:

  • 僅 引文的自訂視覺版面配置 , (多欄、影像橫幅、格式化文字區塊) 或引文卡正文中呈現的多個欄位, (標題、副標題和 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 工具,該欄位TextContentBlock是否text為有效的 JSON? 手動剖析以確認。
  • 結構描述是否扁平? 如果您有深度巢狀陣列,請嘗試傳回單一平面陣列。
  • 您是否 response_semantics 在外掛程式資訊清單) 而不是在外掛程式根目錄中聲明每個函式 (在該函式 capabilities 內? 您必須將範圍限定為函數。