Отображение ссылок с семантикой ответа

Цитаты укрепляют доверие к тому, что ответ Microsoft 365 Copilot точен и обоснован. Текст ответа автоматически включает цитаты для синтезированных ответов Copilot. Тем не менее, конечный пользователь может открыть или не открыть источник информации. Когда Copilot основывает ответ на общедоступном веб-содержимом, URL-адрес цитируется автоматически.

Для содержимого, поступающего с сервера протокола MCP или API, такое содержимое должно возвращать URL-адрес, который может открыть и просмотреть пользователь. Вы определяете response_semantics это в определении плагина, чтобы Copilot знал, где в отклике плагина находится этот URL-адрес, и мог сделать цитату кликабельной с помощью правильной ссылки.

Если пропустить этот шаг, ответ все равно будет содержать цитату, но только с репрезентативной таблеткой или значком. Пользователь не может перейти по ссылке и подтвердить данные с вашего сайта. Вот почему кликабельные цитаты также являются требованием политики магазина агентов Microsoft 365 Copilot для приложений, опубликованных в магазине.

Copilot также может автоматически определять метаданные цитирования из общих имен полей, так что вам больше не нужно явно определять response_semantics. Явные слова response_semantics по-прежнему имеют приоритет, когда вы их предоставляете. Использование этого динамического резерва особенно полезно при использовании динамического обнаружения инструментов, где поверхность инструмента может меняться во время выполнения. Дополнительные сведения см. в статье Семантика динамического отклика.

При наведении курсора для кликабельных цитат в ответе Copilot.

Важно!

Для получения цитат не нужна адаптивная карточка. Одной семантики ответа (а также data_path нескольких properties сопоставлений) достаточно, чтобы Copilot отобразил кликабельную цитату, указывающую на источник.

Рассмотрите возможность использования интерактивных MCP-приложений для создания расширенного взаимодействия с пользователем помимо цитат.

Использование семантики ответа

Семантика отклика, определенная в манифесте подключаемого модуля, действует как контракт между сервером MCP или API и Copilot.

Инструмент возвращает JSON.
В манифесте плагина:
- Вы сообщаете Copilot , где в этом JSON находятся цитируемые элементы (data_path).
- Вы сообщаете Copilot , какие поля в каждом элементе соответствуют заголовку, подзаголовку и URL-адресу цитаты (properties).
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 указывает на массив. Каждый элемент создает свою собственную цитату, которую можно щелкнуть. JSONPaths properties разрешаются относительно каждого элемента массива, а не корня.

Один объект (в стиле fetch)

В следующем примере показан ответ с ровно одной записью - документом, сущностью, файлом, - которая должна быть процитирована в качестве одного источника.

{
  "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 заключают свой ответ в content массив TextContentBlock элементов. 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": "$"). Средство поиска MCP, возвращающее массив внутри поля, text использует конфигурацию массива результатов (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 отображает цитату из списка, которую можно щелкнуть. Любой из эквивалентных псевдонимов будет работать вместо них - например, items или data вместо results, или webUrlhref вместо url.

Свойства цитирования

Следующие свойства доступны в цитатах. Все значения являются относительными выражениями JSONPath для одного элемента, выбранного .data_path

Property	Обязательный	Что делает
`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)	`$` для root или `$.results` если внутренний JSON содержит массив

Совет

Сведение массивов в плоскую сторону. Многоуровневые вложенные массивы (например, ) — это шаблон схемы, $.content[0].results[0].itemsв котором с наибольшей вероятностью произойдет сбой. Если вы являетесь владельцем фигуры отклика инструмента, верните плоский results: [...] массив.

Выходя за рамки семантики ответа

В качестве первого предпочтения рассмотрите возможность добавления в агент мини-приложений с многофункциональным пользовательским интерфейсом. Этот подход более ориентирован на будущее и искусственный интеллект, обеспечивая более интеллектуальное, адаптивное и бесперебойное взаимодействие.

Примечание.

Рекомендации по адаптивным карточкам в этом разделе относятся только к декларативным агентам. Соединительные staticTemplate линии Copilot не поддерживают отображение свойства и адаптивной карточки для цитат.

Добавьте адаптивную карточку в крайнем случае , если и только если вам необходимо выполнить одно из следующих условий:

Настраиваемый визуальный макет только для цитаты (несколько колонок, баннеры изображений, отформатированные текстовые блоки) или несколько полей, отображаемых в тексте цитаты карта (помимо заголовка, подзаголовка и URL-адреса).
Управляющие кнопки , выходящие за рамки поведения по умолчанию "щелкните ссылку" (например, Action.Executeмногокнопочные панели инструментов).

В подавляющем большинстве сценариев цитирования ("покажите мне источник и позвольте мне пройтись") полностью пропускайте адаптивные карточки. Они усложняют работу, их сложнее отлаживать, а пользовательский интерфейс цитирования по умолчанию чистый и соответствует остальным функциям 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-адреса приводят к тому, что цитаты не щелкают.
Является ли поле допустимым text для средств MCP в TextContentBlock JSON? Для подтверждения проанализируйте его вручную.
Схема плоская? Если у вас массивы с глубокой вложенностью, попробуйте вернуть один плоский массив.
Вы объявили response_semanticscapabilities каждую функцию (внутри этой функции в манифесте плагина), а не в корне плагина? Вы должны ограничить его области функцией.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-09-02