Mostrar citações com semântica de resposta

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

Para conteúdo proveniente de um servidor MCP (Model Context Protocol) ou de uma API, esse conteúdo deve retornar uma URL que um usuário final possa abrir e examinar. Você define response_semantics em sua definição de plug-in para que o Copilot saiba onde esse URL está localizado na resposta do plug-in e possa tornar a citação clicável com o link certo.

Se você pular esta etapa, a resposta ainda incluirá uma citação, mas apenas com uma pílula ou ícone representativo. O usuário final não pode clicar e confirmar os dados de seu site. É por isso que as citações clicáveis também são um requisito da política da loja de agentes do Microsoft 365 Copilot para aplicativos publicados na loja.

O Copilot também pode inferir metadados de citação automaticamente de nomes de campos comuns, para que você não precise mais definir response_semanticsexplicitamente. Explícito response_semantics ainda tem precedência quando você os fornece. Contar com esse fallback dinâmico é especialmente útil quando você usa a descoberta dinâmica de ferramentas, em que a superfície da ferramenta pode mudar em tempo de execução. Para obter mais informações, consulte Semântica de resposta dinâmica.

Usando a semântica de resposta

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

1. A ferramenta retorna JSON.

2. No manifesto do plug-in:

   • Você informa ao Copilot onde nesse JSON os itens citáveis estão localizados (data_path).
   • Você informa ao Copilot quais campos em cada item são mapeados para o título, o subtítulo e o URL da citação (properties).

3. O Copilot renderiza uma citação para cada item. Os usuários clicam na sua fonte.

Se você fornecer mapeamentos explícitos properties , o Copilot os usará no estado em que se encontram. A inferência dinâmica aplica-se somente quando esses mapeamentos estão ausentes. Para obter mais informações, consulte Semântica de resposta dinâmica.

Configuração mínima

Sua response_semantics configuração é orientada pela forma da resposta da ferramenta, não pelo protocolo da resposta da ferramenta. Os agentes do Copilot com todos os protocolos de ferramenta (MCP, OpenAPI, extensões de mensagem) usam o mesmo esquema de manifesto.

A maioria das respostas de ferramentas se enquadra em uma de duas formas:

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

Matriz de resultados (estilo de pesquisa)

Ferramentas que retornam vários itens normalmente retornam uma matriz sob uma results chave (ou equivalente), conforme mostrado no exemplo a seguir.

{
  "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 a seguir mostra uma configuração mínima de semântica de resposta no manifesto do 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 sua própria citação clicável. Os properties JSONPaths são resolvidos em relação a cada elemento da matriz, não à raiz.

Objeto único (estilo fetch)

O exemplo a seguir mostra uma resposta com exatamente um registro - um documento, uma entidade, um arquivo - a ser citado como uma fonte.

{
  "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 a seguir mostra uma configuração mínima de semântica de resposta no manifesto do 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. Essa é a escolha certa sempre que a ferramenta retorna um registro, mesmo que o registro inclua campos aninhados como metadata.

Wrapper de conteúdo MCP

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

Exemplo de resposta 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\"}"
    }
  ]
}

O analisador desencapsula a text carga primeiro, deixando um único objeto. Você usa a configuração de objeto único ("data_path": "$"). Uma ferramenta de pesquisa MCP que retorna uma matriz dentro do text campo usa a configuração de matriz de resultados (data_path: "$.results").

Semântica de resposta dinâmica (fallback de configuração zero)

Explícito response_semantics funciona bem apenas quando suas ferramentas são estáveis e imutáveis. Esse geralmente não é o caso: um conector criado em um servidor MCP de terceiros atualiza frequentemente suas ferramentas, portanto, você precisa manter o manifesto sincronizado à medida que o servidor evolui. Quando o servidor é alterado, mas o manifesto não, o fundamento estruturado retorna silenciosamente ao texto bruto e as citações param de renderizar.

Quando o manifesto omite os mapeamentos explícitos properties , o Copilot infere os campos de citação examinando cada objeto de resultado em relação a uma lista priorizada de aliases conhecidos. Esse fallback de configuração zero é especialmente útil com a descoberta dinâmica de ferramentas, em que você não pode fixar um manifesto em uma superfície de ferramenta fixa.

Aliases de campo

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

Regras de resolução

• URL é o requisito rígido. Se nenhuma URL não vazia for encontrada, o Copilot ignorará o elemento e não emitirá nenhuma citação.
• O título retorna ao nome do host se nenhum alias de título estiver presente.
• A legenda e a miniatura são oportunistas. O Copilot os inclui quando reconhece um campo de correspondência e os omite de outra forma.

Exemplo

Se a ferramenta MCP retornar a resposta a seguir, você não precisará definir response_semantics explicitamente. O Copilot infere os campos de citação dos aliases conhecidos.

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

O text campo contém os resultados em seqüências:

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

Como results, url, titlee subtitle todos correspondem a aliases conhecidos, o Copilot renderiza uma citação clicável para cada item. Qualquer um dos aliases equivalentes funciona em seu lugar - por exemplo, items ou data em vez de results, ou webUrl ou href em 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 em relação a um item selecionado por data_path.

Configuração data_path

A data_path propriedade é uma expressão JSONPath (RFC 9535). Usar uma expressão JSONPath incorreta é um dos motivos mais comuns pelos quais as citações não aparecem.

Indo além da semântica de resposta

Como primeira preferência, considere adicionar widgets de interface do usuário avançados ao seu agente. Essa abordagem está mais pronta para o futuro e nativa de IA, permitindo interações mais inteligentes, adaptáveis e perfeitas.

Adicione um Cartão Adaptável como último recurso se - e somente se - você precisar de uma das seguintes condições:

• Um layout visual personalizado apenas para a citação (várias colunas, banners de imagem, blocos de texto formatados) ou vários campos renderizados no corpo do card de citação (além do título, subtítulo e URL).
• Botões de ação além do comportamento padrão "clique na citação" (por exemplo, Action.Executebarras de ferramentas com vários botões).

Para a grande maioria dos cenários de citação - "mostre-me a fonte e deixe-me clicar" - ignore totalmente os Cartões Adaptáveis. Elas adicionam complexidade, são mais difíceis de depurar e a interface do usuário de citação padrão é limpa e consistente com o restante do Copilot.

Exemplo com Cartão Adaptá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}"
    }
  }
}

Observe o ${title}, , e ${url} tokens - esses tokens são preenchidos pelo mesmo properties${subtitle}mapa mostrado anteriormente. O Cartão Adaptá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, use a seguinte lista de verificação.

• Está data_path apontando para o nó direito? Cole a resposta JSON bruta da ferramenta em um testador JSONPath e confirme se a expressão retorna a matriz ou o objeto esperado.
• Cada item tem um url? URLs ausentes resultam em citações não clicáveis.
• Para ferramentas MCP, o campo dentro TextContentBlock de text JSON é válido? Analise-o manualmente para confirmar.
• O esquema é simples? Se você tiver matrizes profundamente aninhadas, tente retornar uma única matriz simples.
• Você declarou response_semantics por função (dentro dessa função está capabilities no manifesto do plug-in) e não na raiz do plug-in? Você deve definir o escopo para a função.

Conteúdo relacionado

• Esquema de manifesto de plug-in 2.4 — response_semantics objeto
• Adicionar aplicativos MCP a agentes declarativos no Microsoft 365 Copilot
• Práticas recomendadas para a criação de agentes declarativos