Mostrar citações com semântica de resposta

As citações criam confiança de que uma resposta Microsoft 365 Copilot é precisa e fundamentada. O corpo da resposta inclui automaticamente citações para respostas sintetizadas de Copilot. No entanto, o utilizador final pode ou não conseguir abrir a origem das informações. Quando Copilot fundamenta uma resposta em conteúdo Web público, o URL é citado automaticamente.

Para conteúdos provenientes de um servidor de Protocolo de Contexto de Modelo (MCP) ou de uma API, esse conteúdo tem de devolver um URL que um utilizador final pode abrir e rever. response_semantics Define na definição do plug-in para que o Copilot saiba onde esse URL está localizado na resposta do plug-in e pode tornar a citação clicável com a ligação correta.

Se ignorar este passo, a resposta ainda inclui uma citação, mas apenas com um comprimido ou ícone representativo. O utilizador final não consegue clicar e confirmar os dados do seu site. É por isso que as citações clicáveis também são um requisito de política da loja de Agentes Microsoft 365 Copilot para aplicações publicadas na loja.

O Copilot também pode inferir metadados de citação automaticamente a partir de nomes de campos comuns, pelo que já não precisa de definir response_semanticsexplicitamente . Explicit response_semantics continua a ter precedência quando os fornece. Depender desta contingência dinâmica é especialmente útil quando utiliza a deteção de ferramentas dinâmica, onde a superfície da ferramenta pode mudar no runtime. Para obter mais informações, veja Semântica de resposta dinâmica.

Na experiência de passagem do rato para citações clicáveis numa resposta copilot.

Importante

Não precisa de um Cartão Ajustável para obter citações. Só a semântica de resposta - data_path mais alguns properties mapeamentos - é suficiente para o Copilot compor uma citação clicável apontando de volta para a sua fonte.

Considere utilizar aplicações MCP interativas para UX avançado para além das citações.

Utilizar semântica de resposta

A semântica de resposta definida no manifesto de plug-in funciona como um contrato entre o servidor MCP ou a API e o Copilot.

  1. A sua ferramenta devolve JSON.

  2. No manifesto do plug-in:

    • Diz ao Copilot onde nesse JSON estão localizados os itens citaveis (data_path).
    • Indica ao Copilot que campos em cada item mapeiam para o título, subtítulo e URL da citação (properties).

  3. Copilot compõe uma citação para cada item. Os utilizadores clicam na sua origem.

Se fornecer mapeamentos explícitos properties , o Copilot utiliza-os tal como estão. A inferência dinâmica aplica-se apenas quando esses mapeamentos estão ausentes. Para obter mais informações, veja Semântica de resposta dinâmica.

Configuração mínima

A sua response_semantics configuração é condicionada pela forma da resposta da sua ferramenta e não pelo protocolo da resposta da ferramenta. Os agentes copilot com todos os protocolos de ferramentas (MCP, OpenAPI, extensões de mensagens) utilizam o mesmo esquema de manifesto.

A maioria das respostas de ferramentas enquadra-se numa de duas formas:

  • Uma matriz de resultados (como uma ferramenta de pesquisa): a ferramenta devolve vários itens, cada um dos quais deve tornar-se a sua própria citação.
  • Um único objeto (como uma ferramenta de obtenção): a ferramenta devolve exatamente um documento ou registo, o que se torna uma única citação.

Matriz de resultados (estilo de pesquisa)

As ferramentas que devolvem múltiplos itens normalmente devolvem uma matriz sob uma results chave (ou equivalente), conforme mostrado no exemplo seguinte.

{
  "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"
    }
  ]
}

O exemplo seguinte mostra uma configuração semântica de resposta mínima no manifesto de plug-in.

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

A data_path propriedade aponta para a matriz. Cada elemento produz a sua própria citação clicável. Os properties JSONPaths são resolvidos em relação a cada elemento de matriz, não à raiz.

Objeto único (estilo de obtenção)

O exemplo seguinte mostra uma resposta com exatamente um registo - um documento, uma entidade, um ficheiro - a ser citado como uma origem.

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

O exemplo seguinte mostra uma configuração semântica de resposta mínima no manifesto de plug-in.

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

A data_path propriedade definida para $ selecionar o objeto raiz como um único item de citação. Esta é a escolha certa sempre que a ferramenta devolve um registo, mesmo que o registo inclua campos aninhados como metadata.

Wrapper de conteúdo MCP

As ferramentas MCP encapsulam a resposta numa content matriz de TextContentBlock itens. Copilot analisa o text campo de cada bloco como JSON e, em seguida, aplica-o data_path ao valor analisado. A forma dentro da cadeia text é o que impulsiona a configuração e não o wrapper externo content .

Resposta mcP de exemplo

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

O analisador desembrulha primeiro o text payload, deixando um único objeto. Utilize a configuração de objeto único ("data_path": "$"). Uma ferramenta de pesquisa MCP que devolve uma matriz dentro do text campo utiliza a matriz de configuração de resultados (data_path: "$.results").

Semântica de resposta dinâmica (contingência de zero configurações)

Explicit response_semantics funciona bem apenas quando as suas ferramentas são estáveis e inalteradas. Muitas vezes, não é esse o caso: um conector criado num servidor MCP de terceiros atualiza frequentemente as suas ferramentas, pelo que tem de manter o manifesto sincronizado à medida que o servidor evolui. Quando o servidor muda, mas o manifesto não muda, a terra estruturada recaem silenciosamente para texto não processado e as citações deixam de ser compostas.

Quando o seu manifesto omite os mapeamentos explícitos properties , Copilot infere campos de citação ao analisar cada objeto de resultado numa lista priorizada de aliases conhecidos. Esta contingência de configuração zero é especialmente útil com a deteção de ferramentas dinâmicas, onde não é possível afixar um manifesto a uma superfície de ferramenta fixa.

Aliases de campo

Para cada campo de citação, Copilot verifica os seguintes aliases por ordem de prioridade e utiliza a primeira correspondência que encontrar.

Campo Citation Aliases (ordem de prioridade)
URL display_url, displayUrl, web_url, webUrl, url, citation_url, citationUrl, reference_url, referenceUrl, website_url, websiteUrl, web_link, webLink, link, href
Título display_title, displayTitle, title, name, display_name, displayName, web_title, webTitle, subject, heading, caption
Subtítulo subtitle, description, summary, snippet, source, provider, site_name, siteName, highlight
Miniatura thumbnail_url, thumbnailUrl, thumbnail, image_url, imageUrl, logo_url, logoUrl, icon_url, iconUrl
Matriz de resultados results, items, data, value, records, entries

Regras de resolução

  • O URL é o requisito difícil. Se não for encontrado nenhum URL não vazio, Copilot ignora o elemento e não emite nenhuma citação.
  • O título reverterá para o nome do anfitrião se não existir nenhum alias de título.
  • Subtítulo e miniatura são oportunistas. O Copilot inclui-os quando reconhece um campo correspondente e omite-os de outra forma.

Exemplo

Se a sua ferramenta MCP devolver a seguinte resposta, não precisa de definir response_semantics explicitamente. Copilot infere os campos de citação dos conhecidos aliases.

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

O text campo contém os resultados stringified:

{
  "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"
    }
  ]
}

Uma resultsvez que , url, titlee subtitle todos correspondem a aliases conhecidos, Copilot compõe uma citação clicável para cada item. Qualquer um dos aliases equivalentes funciona no respetivo local, por exemplo, items ou data em vez de results, ou webUrl em href vez de url.

Propriedades da citação

As seguintes propriedades estão disponíveis em citações. Todos os valores são expressões JSONPath relativas a um item selecionado por data_path.

Propriedade Obrigatório Função
title Sim (praticamente) O cabeçalho clicável da citação.
subtitle Não Segunda linha - datas, autores, categorias.
url Sim (praticamente) Onde a citação navega ao clicar. Tem de ser uma ligação canónica de volta à sua origem.
thumbnail_url Não Imagem pequena mostrada ao lado da citação.

Observação

Se url estiver em falta, a citação não é clicável. Esta propriedade em falta é uma razão muito comum para os programadores verem citações não funcionais.

Definição data_path

A data_path propriedade é uma expressão JSONPath (RFC 9535). Utilizar uma expressão JSONPath incorreta é uma das razões mais comuns para as citações não aparecerem.

Se a sua resposta for semelhante a... Use esse data_path
{ "results": [ ... ] } $.results
{ "content": [ { "results": [ ... ] } ] } (estilo MCP aninhado) $.content[0].results
Um único objeto na raiz (sem wrapper de matriz) $
{ "content": [ { "type": "text", "text": "<stringified JSON>" } ] } (MCP não processado) $ para raiz ou $.results se o JSON interno tiver uma matriz

Dica

Aplane as matrizes. As matrizes aninhadas de vários níveis (por exemplo, $.content[0].results[0].items) são o padrão de esquema com maior probabilidade de falhar silenciosamente. Se for o proprietário da forma de resposta da ferramenta, devolva uma matriz plana results: [...] .

Ir além da semântica de resposta

Como primeira preferência, considere adicionar widgets de IU avançados ao seu agente. Esta abordagem é mais futura e nativa de IA, permitindo interações mais inteligentes, adaptáveis e totalmente integradas.

Adicione um Cartão Ajustável como último recurso se, e apenas se, precisar de uma das seguintes condições:

  • Um esquema de elemento visual personalizado apenas para a citação (multicoluna, faixas de imagem, blocos de texto formatados) ou vários campos compostos na citação card corpo (além do título, subtítulo e URL).
  • Botões de ação para além do comportamento predefinido "clique na citação" (por exemplo, Action.Execute, barras de ferramentas multibutton).

Para a grande maioria dos cenários de citação - "mostrar-me a fonte e deixar-me clicar" - ignore totalmente os Cartões Adaptáveis. Adicionam complexidade, são mais difíceis de depurar e a IU de citação predefinida é limpo e consistente com o resto do Copilot.

Exemplo com Cartão Ajustável

"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}"
    }
  }
}

Repare que , ${title}${subtitle}e ${url} tokens – estes tokens são preenchidos pelo mesmo properties mapa mostrado anteriormente. O Cartão Ajustável é uma camada de apresentação sobre a semântica de resposta; não o substitui.

Lista de verificação de solução de problemas

Se as citações não aparecerem, utilize a seguinte lista de verificação.

  • Está data_path a apontar para o nó certo? Cole a resposta JSON não processada da sua ferramenta num teste JSONPath e confirme se a expressão devolve a matriz ou objeto esperado.
  • Cada item tem um item que não está vazio url? Os URLs em falta resultam em citações não clicáveis.
  • Para ferramentas MCP, o text campo está dentro TextContentBlock de JSON válido? Analise-o manualmente para confirmar.
  • O esquema é plano? Se tiver matrizes profundamente aninhadas, tente devolver uma única matriz plana.
  • Declarou response_semantics por função (dentro dessa função no manifesto do capabilities plug-in) e não na raiz do plug-in? Tem de definir o âmbito para a função .

Conteúdo relacionado

  • Last updated on