Mostrar citas con semántica de respuesta

Las citas crean confianza en que una respuesta Microsoft 365 Copilot es precisa y fundamentada. El cuerpo de respuesta incluye automáticamente citas para las respuestas sintetizadas de Copilot. Sin embargo, es posible que el usuario final pueda abrir o no el origen de información. Cuando Copilot basa una respuesta en el contenido web público, la dirección URL se cita automáticamente.

Para el contenido procedente de un servidor de Protocolo de contexto de modelo (MCP) o una API, ese contenido debe devolver una dirección URL que un usuario final puede abrir y revisar. response_semantics Defina en la definición del complemento para que Copilot sepa dónde se encuentra esa dirección URL en la respuesta del complemento y pueda hacer clic en la cita con el vínculo correcto.

Si omite este paso, la respuesta seguirá incluyendo una cita, pero solo con una píldora o un icono representativos. El usuario final no puede hacer clic y confirmar los datos del sitio. Por eso, las citas que se pueden hacer clic también son un requisito de directiva de almacén de agentes de Microsoft 365 Copilot para las aplicaciones publicadas en la tienda.

Copilot también puede deducir automáticamente metadatos de citas de nombres de campo comunes, por lo que ya no es necesario definir response_semanticsexplícitamente . Explícita response_semantics sigue teniendo prioridad cuando se proporcionan. Confiar en esta reserva dinámica es especialmente útil cuando se usa la detección dinámica de herramientas, donde la superficie de la herramienta puede cambiar en tiempo de ejecución. Para obtener más información, vea Semántica de respuesta dinámica.

Al mantener el mouse sobre la experiencia de citas que se pueden hacer clic en una respuesta de Copilot.

Importante

No necesita una tarjeta adaptable para obtener citas. La semántica de respuesta por sí sola (más data_path algunas properties asignaciones) es suficiente para que Copilot represente una cita que haga clic y que apunte de nuevo al origen.

Considere la posibilidad de usar aplicaciones MCP interactivas para una experiencia de usuario enriquecida más allá de las citas.

Uso de la semántica de respuesta

La semántica de respuesta definida en el manifiesto del complemento actúa como un contrato entre el servidor MCP o la API y Copilot.

  1. La herramienta devuelve JSON.

  2. En el manifiesto del complemento:

    • Indique a Copilot dónde se encuentran los elementos citables en ese JSON (data_path).
    • Le indicará a Copilot qué campos de cada elemento se asignan al título, el subtítulo y la dirección URL de la cita (properties).

  3. Copilot representa una cita para cada elemento. Los usuarios hacen clic en el origen.

Si proporciona asignaciones explícitas properties , Copilot las usa tal y como están. La inferencia dinámica solo se aplica cuando esas asignaciones están ausentes. Para obtener más información, vea Semántica de respuesta dinámica.

Configuración mínima

La response_semantics configuración se basa en la forma de la respuesta de la herramienta, no en el protocolo de la respuesta de la herramienta. Los agentes de Copilot con todos los protocolos de herramientas (MCP, OpenAPI, extensiones de mensaje) usan el mismo esquema de manifiesto.

La mayoría de las respuestas de herramientas se dividen en una de dos formas:

  • Matriz de resultados (como una herramienta de búsqueda): la herramienta devuelve varios elementos, cada uno de los cuales debe convertirse en su propia cita.
  • Un único objeto (como una herramienta de captura): la herramienta devuelve exactamente un documento o registro, que se convierte en una cita única.

Matriz de resultados (estilo de búsqueda)

Las herramientas que devuelven varios elementos normalmente devuelven una matriz en una results clave (o equivalente), como se muestra en el ejemplo siguiente.

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

En el ejemplo siguiente se muestra una configuración semántica de respuesta mínima en el manifiesto del complemento.

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

La data_path propiedad apunta a la matriz. Cada elemento genera su propia cita en la que se puede hacer clic. Los properties JSONPaths se resuelven en relación con cada elemento de matriz, no con la raíz.

Objeto único (estilo fetch)

En el ejemplo siguiente se muestra una respuesta con exactamente un registro (un documento, una entidad, un archivo) que se va a citar como un origen.

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

En el ejemplo siguiente se muestra una configuración semántica de respuesta mínima en el manifiesto del complemento.

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

La data_path propiedad establecida en $ selecciona el objeto raíz como un solo elemento de cita. Esta es la opción correcta cada vez que la herramienta devuelve un registro, incluso si el registro incluye campos anidados como metadata.

Contenedor de contenido mcp

Las herramientas de MCP encapsulan su respuesta en una content matriz de TextContentBlock elementos. Copilot analiza el text campo de cada bloque como JSON y, a continuación, aplica data_path el valor contra el valor analizado. La forma dentro de la text cadena es lo que impulsa la configuración, no el contenedor externo content .

Respuesta mcp de ejemplo

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

El analizador desencapsula primero la text carga, dejando un solo objeto. Use la configuración de un solo objeto ("data_path": "$"). Una herramienta de búsqueda MCP que devuelve una matriz dentro del text campo usa la matriz de configuración de resultados (data_path: "$.results").

Semántica de respuesta dinámica (reserva de configuración cero)

Explicit response_semantics funciona bien solo cuando las herramientas son estables e invariables. Ese no es el caso a menudo: un conector basado en un servidor MCP de terceros actualiza con frecuencia sus herramientas, por lo que debe mantener el manifiesto sincronizado a medida que evoluciona el servidor. Cuando el servidor cambia, pero el manifiesto no lo hace, la conexión a tierra estructurada vuelve silenciosamente al texto sin formato y las citas detienen la representación.

Cuando el manifiesto omite las asignaciones explícitas properties , Copilot deduce campos de cita mediante el examen de cada objeto de resultado en una lista priorizada de alias conocidos. Esta reserva de configuración cero es especialmente útil con la detección dinámica de herramientas, donde no se puede anclar un manifiesto a una superficie de herramienta fija.

Alias de campo

Para cada campo de cita, Copilot comprueba los alias siguientes en orden de prioridad y usa la primera coincidencia que encuentra.

Campo Cita Alias (orden de prioridad)
URL display_url, displayUrl, web_url, webUrl, url, citation_url, citationUrl, reference_url, referenceUrl, website_url, websiteUrl, web_link, webLink, link, href
Title 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

Reglas de resolución

  • La dirección URL es el requisito obligatorio. Si no se encuentra ninguna dirección URL no vacía, Copilot omite el elemento y no emite ninguna cita.
  • Title vuelve al nombre de host si no hay ningún alias de título presente.
  • El subtítulo y la miniatura son oportunistas. Copilot los incluye cuando reconoce un campo coincidente y los omite en caso contrario.

Ejemplo

Si la herramienta MCP devuelve la siguiente respuesta, no es necesario definir response_semantics explícitamente. Copilot deduce los campos de cita de los alias conocidos.

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

El text campo contiene los resultados con cadena:

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

Dado que results, url, titley subtitle todos coinciden con alias conocidos, Copilot representa una cita en la que se puede hacer clic para cada elemento. Cualquiera de los alias equivalentes funciona en su lugar, por ejemplo, items o data en lugar de results, o hrefwebUrl en lugar de url.

Propiedades de cita

Las siguientes propiedades están disponibles en las citas. Todos los valores son expresiones JSONPath relativas con un elemento seleccionado por data_path.

Propiedad Obligatorio Qué hace
title Sí (prácticamente) Encabezado en el que se puede hacer clic en la cita.
subtitle No Segunda línea: fechas, autores, categorías.
url Sí (prácticamente) Donde navega la cita al hacer clic. Debe ser un vínculo canónico de vuelta a su origen.
thumbnail_url No Imagen pequeña que se muestra junto a la cita.

Nota:

Si url falta, no se puede hacer clic en la cita. Esta propiedad que falta es una razón muy común por la que los desarrolladores ven citas no funcionales.

Configuración data_path

La data_path propiedad es una expresión JSONPath (RFC 9535). El uso de una expresión JSONPath incorrecta es una de las razones más comunes por las que las citas no aparecen.

Si la respuesta es similar a... Use esto data_path
{ "results": [ ... ] } $.results
{ "content": [ { "results": [ ... ] } ] } (Anidado de estilo MCP) $.content[0].results
Un único objeto en la raíz (sin contenedor de matriz) $
{ "content": [ { "type": "text", "text": "<stringified JSON>" } ] } (MCP sin procesar) $ para la raíz, o $.results si el JSON interno tiene una matriz

Sugerencia

Aplane las matrices. Las matrices anidadas de varios niveles (por ejemplo, $.content[0].results[0].items) son el patrón de esquema con mayor probabilidad de que se produzca un error silencioso. Si es propietario de la forma de respuesta de la herramienta, devuelve una matriz plana results: [...] .

Ir más allá de la semántica de respuesta

Como primera preferencia, considere la posibilidad de agregar widgets de interfaz de usuario enriquecidos al agente. Este enfoque está más preparado para el futuro y es nativo de inteligencia artificial, lo que permite interacciones más inteligentes, adaptables y sin problemas.

Agregue una tarjeta adaptable como último recurso si necesita una de las condiciones siguientes:

  • Un diseño visual personalizado solo para la cita (varias columnas, banners de imagen, bloques de texto con formato) o varios campos representados en el cuerpo de la tarjeta de cita (más allá del título, el subtítulo y la dirección URL).
  • Botones de acción más allá del comportamiento predeterminado "clic en la cita" (por ejemplo, Action.Execute, barras de herramientas de varios botones).

Para la gran mayoría de los escenarios de cita - "muéstrame el origen y déjame hacer clic" - omite las tarjetas adaptables por completo. Agregan complejidad, son más difíciles de depurar y la interfaz de usuario de cita predeterminada es limpia y coherente con el resto de Copilot.

Ejemplo con tarjeta adaptable

"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 los ${title}tokens , ${subtitle}y ${url} : estos tokens se rellenan mediante el mismo properties mapa mostrado anteriormente. La tarjeta adaptable es una capa de presentación sobre la semántica de respuesta; no lo reemplaza.

Lista de comprobación para la solución de problemas

Si las citas no aparecen, use la siguiente lista de comprobación.

  • ¿Apunta data_path al nodo correcto? Pegue la respuesta JSON sin procesar de la herramienta en un evaluador de JSONPath y confirme que la expresión devuelve la matriz o el objeto que espera.
  • ¿Cada elemento tiene un elemento no vacío url? Las direcciones URL que faltan dan como resultado citas que no se pueden hacer clic.
  • En el caso de las herramientas de MCP, ¿el campo está dentro de textTextContentBlock JSON válido? Anóselo manualmente para confirmarlo.
  • ¿El esquema es plano? Si tiene matrices profundamente anidadas, intente devolver una sola matriz plana.
  • ¿Declaraste response_semantics por función (dentro de esa función en el manifiesto del capabilities complemento) y no en la raíz del complemento? Debe limitarlo a la función .

Contenido relacionado

  • Last updated on