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.

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.

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").

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