응답 의미 체계가 있는 인용 표시

인용은 Microsoft 365 Copilot 응답이 정확하고 근거가 있다는 신뢰를 구축합니다. 응답 본문에는 Copilot 합성 응답에 대한 인용이 자동으로 포함됩니다. 그러나 최종 사용자가 정보 소스를 열 수도 있고 열지 못할 수도 있습니다. Copilot이 공개 웹 콘텐츠에 대한 응답을 기반으로 하면 URL이 자동으로 인용됩니다.

MCP(Model Context Protocol) 서버 또는 API에서 오는 콘텐츠의 경우 해당 콘텐츠는 최종 사용자가 열고 검토할 수 있는 URL을 반환할 수 있습니다. Copilot이 플러그 인 응답에서 해당 URL이 있는 위치를 알고 올바른 링크를 사용하여 인용을 클릭할 수 있도록 플러그 인 정의에서 정의 response_semantics 합니다.

이 단계를 건너뛰더라도 응답에는 여전히 인용이 포함될 수 있지만 대표적인 필이나 아이콘만 포함될 수 있습니다. 최종 사용자는 사이트의 데이터를 클릭하여 확인할 수 없습니다.

또한 Copilot은 일반적인 필드 이름에서 인용 메타데이터를 자동으로 유추할 수 있으므로 더 이상 명시적으로 정의 response_semantics할 필요가 없습니다. 명시적 항목 response_semantics 은 여전히 귀하가 제공할 때 우선합니다. 이 동적 대체에 의존하는 것은 도구 표면이 런타임에 변경될 수 있는 동적 도구 검색을 사용할 때 특히 유용합니다. 자세한 내용은 동적 응답 의미 체계를 참조하세요.

Copilot 응답에서 클릭 가능한 인용에 대한 호버 환경.

중요

인용을 가져오기 위해 적응형 카드가 필요하지 않습니다. 응답 의미 체계만으로도 data_pathproperties Copilot은 소스를 가리키는 클릭 가능한 인용을 렌더링하는 데 충분합니다.

인용 이외의 풍부한 UX를 위해 대화형 MCP 앱을 사용하는 것이 좋습니다.

응답 의미 체계 사용

플러그인 매니페스트에 정의된 응답 의미 체계는 MCP 서버 또는 API와 Copilot 간의 계약 역할을 합니다.

  1. 도구가 JSON을 반환합니다.

  2. 플러그인 매니페스트에서:

    • Copilot에게 인용 가능한 항목이 있는 JSON의 위치를 알려줍니다(data_path).
    • Copilot에 각 항목의 필드가 인용의 제목, 부제목 및 URL(properties)에 매핑되도록 지시합니다.
  3. Copilot은 각 항목에 대한 인용을 렌더링합니다. 사용자가 소스를 클릭합니다.

명시적 properties 매핑을 제공하는 경우 Copilot은 이를 있는 그대로 사용합니다. 동적 추론은 이러한 매핑이 없는 경우에만 적용됩니다. 자세한 내용은 동적 응답 의미 체계를 참조하세요.

최소 구성

구성은 response_semantics 도구 응답의 프로토콜이 아닌 도구 응답의 모양에 따라 결정됩니다. 모든 도구 프로토콜(MCP, OpenAPI, 메시지 확장)을 사용하는 Copilot 에이전트는 동일한 매니페스트 스키마를 사용합니다.

대부분의 도구 응답은 다음 두 셰이프 중 하나로 분류됩니다.

  • 검색 도구와 같은 결과 배열: 도구는 여러 항목을 반환하며, 각 항목은 자체 인용이 되어야 합니다.
  • 단일 개체 (예: 가져오기 도구): 도구는 정확히 하나의 문서 또는 레코드를 반환하며, 이는 단일 인용이 됩니다.

결과 배열(검색 스타일)

여러 항목을 반환하는 도구는 일반적으로 다음 예제와 같이 (또는 동등한) 키 아래 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")을 사용합니다.

동적 응답 의미 체계(0 구성 대체)

명시적 도구는 response_semantics 도구가 안정적이고 변경되지 않는 경우에만 잘 작동합니다. 타사 MCP 서버에 구축된 커넥터는 도구를 자주 업데이트하므로 서버가 발전함에 따라 매니페스트를 동기화된 상태로 유지해야 합니다. 서버가 변경되지만 매니페스트가 변경되지 않으면 구조적 기반이 자동으로 원시 텍스트로 대체되고 인용이 렌더링을 중지합니다.

매니페스트가 명시적 properties 매핑을 생략하는 경우 Copilot은 각 결과 개체를 잘 알려진 별칭의 우선 순위가 지정된 목록에 대해 검사하여 인용 필드를 유추합니다. 이 0 구성 대체는 매니페스트를 고정 도구 표면에 고정할 수 없는 동적 도구 검색에 특히 유용합니다.

필드 별칭

각 인용 필드에 대해 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"
    }
  ]
}

, , urltitle, 및 subtitle 모두 잘 알려진 별칭과 일치하므로 resultsCopilot은 각 항목에 대해 클릭 가능한 인용을 렌더링합니다. 동등한 별칭은 그 자리에서 작동합니다(예: items , , resultsdata , , 또는 대신 ).webUrlhrefurl

인용 속성

인용에서 사용할 수 있는 속성은 다음과 같습니다. 모든 값은 에서 선택한 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) $ 또는 내부 $.results JSON에 배열이 있는 경우

팁

배열을 평면화합니다. 다단계 중첩 배열(예: $.content[0].results[0].items)은 자동으로 실패할 가능성이 가장 높은 스키마 패턴입니다. 도구 응답 셰이프를 소유하고 있는 경우 플랫 results: [...] 배열을 반환합니다.

응답 의미 체계 그 이상

첫 번째 기본 설정으로에이전트에 풍부한 UI 위젯을 추가하는 것을 고려하십시오. 이 접근 방식은 미래에 대비하고 AI 네이티브이므로 보다 지능적이고 적응력이 뛰어나며 원활한 상호 작용이 가능합니다.

참고

이 섹션의 적응형 카드 지침은 선언적 에이전트에만 적용됩니다. 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}"
    }
  }
}

, ${subtitle}, 및 ${url} 토큰에 ${title}주목하세요. 앞에서 본 것과 동일한 properties 맵이 이러한 토큰을 채웁니다. 적응형 카드는 응답 의미 체계 위에 있는 프레젠테이션 계층 입니다. 그것을 대체하지는 않습니다.

문제 해결 체크리스트

인용이 표시되지 않으면 다음 체크리스트를 사용하세요.

  • 올바른 노드를 가리키고 있습니까 data_path ? 도구의 원시 JSON 응답을 JSONPath 테스터에 붙여넣고 식이 예상한 배열 또는 개체를 반환하는지 확인합니다.
  • 각 항목에 비어 있지 url않은 ? URL이 누락되면 인용을 클릭할 수 없습니다.
  • MCP 도구의 경우 필드가 text 유효한 JSON 내부 TextContentBlock 입니까? 수동으로 구문 분석하여 확인합니다.
  • 스키마가 평평합니까? 배열이 깊게 중첩된 경우 단일 플랫 배열을 반환해 보세요.
  • 플러그인 루트가 아닌 함수 당 (플러그인 매니페스트의 해당 함수 capabilities 내부)를 선언 response_semantics 했습니까? 함수로 scope해야 합니다.