Mostrar citas con semántica de respuesta

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

En el caso del contenido procedente de un servidor de Protocolo de contexto de modelo (MCP) o de una API, ese contenido puede devolver una dirección URL que un usuario final puede abrir y revisar. Defina response_semantics 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 que se pueda hacer clic en la cita con el vínculo correcto.

Si omite este paso, la respuesta puede incluir una cita, pero solo con una píldora o un icono representativos. El usuario final no puede hacer clic y confirmar los datos de su sitio.

Copilot también puede inferir metadatos de citas automáticamente a partir de nombres de campo comunes, por lo que ya no es necesario definir response_semanticsexplícitamente . Las opciones explícitas response_semantics siguen teniendo prioridad cuando las proporcionas. 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, consulte Semántica de respuesta dinámica.

Sobre la experiencia de desplazamiento para citas en las que se puede hacer clic en una respuesta de Copilot.

Importante

No necesitas una tarjeta adaptativa 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 en la que se pueda hacer clic que apunte a su fuente.

Considere el uso de aplicaciones MCP interactivas para obtener una experiencia de usuario rica 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 en qué parte de ese JSON se encuentran los elementos citables (data_path).
    • Indica a Copilot qué campos de cada elemento se asignan al título, subtítulo y 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 cual. La inferencia dinámica solo se aplica cuando esas asignaciones están ausentes. Para obtener más información, consulte Semántica de respuesta dinámica.

Configuración mínima

La response_semantics configuración está controlada por la forma de la respuesta de la herramienta, no por el protocolo de la respuesta de la herramienta. Los agentes de Copilot con todos los protocolos de herramienta (MCP, OpenAPI, extensiones de mensaje) utilizan el mismo esquema de manifiesto.

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

  • Una 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 solo objeto (como una herramienta de captura): la herramienta devuelve exactamente un documento o registro, que se convierte en una sola cita.

Matriz de resultados (estilo de búsqueda)

Las herramientas que devuelven varios elementos suelen devolver una matriz con 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 de 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 produce su propia cita en la que se puede hacer clic. Los properties JSONPaths se resuelven en relación con cada elemento de la 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 citará como una fuente.

{
  "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 de semántica de respuesta mínima en el manifiesto del complemento.

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

El data_path conjunto de propiedades selecciona $ el objeto raíz como un único elemento de cita. Esta es la opción correcta siempre que la herramienta devuelva un registro, incluso si el registro incluye campos anidados como metadata.

Contenedor de contenido MCP

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

Ejemplo de respuesta 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\"}"
    }
  ]
}

El analizador desenvuelve la text carga en primer lugar, dejando un solo objeto. Se utiliza la configuración de objeto único ("data_path": "$"). Una herramienta de búsqueda MCP que devuelve una matriz dentro del text campo utiliza la configuración de matriz de resultados (data_path: "$.results").

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

Explícito response_semantics funciona bien solo cuando sus herramientas son estables e inmutables. A menudo, ese no es el caso: un conector construido en un servidor MCP de terceros actualiza con frecuencia sus herramientas, por lo que debe mantener el manifiesto sincronizado a medida que el servidor evoluciona. Cuando el servidor cambia pero el manifiesto no, la conexión a tierra estructurada vuelve silenciosamente al texto sin procesar y las citas dejan de representarse.

Cuando el manifiesto omite las asignaciones explícitas properties , Copilot deduce campos de cita examinando cada objeto resultado con 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 siguientes alias en orden de prioridad y usa la primera coincidencia que encuentra.

Campo de 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 estricto. Si no se encuentra ninguna dirección URL no vacía, Copilot omite el elemento y no emite ninguna cita.
  • El título vuelve al nombre de host si no hay ningún alias de título.
  • Los subtítulos 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 a partir de los alias conocidos.

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

El text campo contiene los resultados encadenados:

{
  "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, title, y subtitle todos coinciden con alias conocidos, Copilot representa una cita para cada elemento. Cualquiera de los alias equivalentes funciona en su lugar, por ejemplo, items o en lugar de results, o webUrl en href lugar de urldata .

Propiedades de citas

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

Propiedad Obligatorio Qué hace
title Sí (prácticamente) Encabezado de la cita en el que se puede hacer clic.
subtitle No Segunda línea: fechas, autores, categorías.
url Sí (prácticamente) A dónde navega la cita al hacer clic. Debe ser un enlace canónico de vuelta a tu fuente.
thumbnail_url No Pequeña imagen 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.

Entorno 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 su respuesta se ve así... Use esto data_path
{ "results": [ ... ] } $.results
{ "content": [ { "results": [ ... ] } ] } (Estilo MCP anidado) $.content[0].results
Un único objeto en la raíz (sin contenedor de matriz) $
{ "content": [ { "type": "text", "text": "<stringified JSON>" } ] } (MCP sin formato) $ para raíz, o $.results si el JSON interno tiene una matriz

Sugerencia

Acople las matrices. Las matrices anidadas de varios niveles (por ejemplo, $.content[0].results[0].items) son el patrón de esquema con más probabilidades de producir errores sin mensajes. Si es el propietario de la forma de respuesta de la herramienta, devuelva una matriz plana results: [...] .

Más allá de la semántica de respuesta

Como primera preferencia, considere agregar widgets de interfaz de usuario enriquecidos a su agente. Este enfoque está más preparado para el futuro y es nativo de la IA, lo que permite interacciones más inteligentes, adaptables y fluidas.

Nota:

La guía de tarjeta adaptativa de esta sección solo se aplica a los agentes declarativos. La staticTemplate propiedad y la representación de la tarjeta adaptable para citas no son compatibles con los conectores de Copilot.

Agrega una tarjeta adaptativa como último recurso si necesitas una de las siguientes condiciones:

  • 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 de "hacer clic en la cita" (por ejemplo, Action.Executebarras de herramientas de varios botones).

Para la gran mayoría de los escenarios de citas, "muéstrame la fuente 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 citas predeterminada es limpia y coherente con el resto de Copilot.

Ejemplo con tarjeta adaptativa

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

Fíjese en , , y ${url} los ${title}${subtitle}tokens. El mismo properties mapa que viste antes rellena estas fichas. La tarjeta adaptativa 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:

  • ¿Está data_path apuntando al nodo correcto? Pegue la respuesta JSON sin procesar de la herramienta en un probador JSONPath y confirme que la expresión devuelve la matriz o el objeto que espera.
  • ¿Cada artículo tiene un elemento no vacío url? Las URL que faltan hacen que las citas no se puedan hacer clic.
  • En el caso de las herramientas MCP, ¿el campo tiene TextContentBlock un text JSON válido? Analice manualmente para confirmar.
  • ¿Es el esquema plano? Si tiene matrices profundamente anidadas, intente devolver una única matriz plana.
  • ¿Declaró 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