Afficher les citations avec la sémantique des réponses

Les citations renforcent la confiance dans le fait qu’une réponse de Microsoft 365 Copilot est précise et ancrée. Le corps de la réponse inclut automatiquement des citations pour les réponses synthétisées par Copilot. Toutefois, l’utilisateur final peut ou non être en mesure d’ouvrir la source d’information. Lorsque Copilot fonde une réponse sur un contenu web public, l’URL est citée automatiquement.

Pour le contenu provenant d’un serveur MCP (Model Context Protocol) ou d’une API, ce contenu peut renvoyer une URL qu’un utilisateur final peut ouvrir et examiner. Vous définissez response_semantics dans votre définition de plugin afin que Copilot sache où se trouve cette URL dans la réponse du plugin et puisse rendre la citation cliquable avec le lien approprié.

Si vous ignorez cette étape, la réponse peut toujours inclure une citation, mais uniquement avec une pilule ou une icône représentative. L’utilisateur final ne peut pas cliquer et confirmer les données de votre site.

Copilot peut également déduire automatiquement les métadonnées de citation à partir des noms de champ courants, de sorte que vous n’avez plus besoin de définir response_semanticsexplicitement . Les explicites response_semantics sont toujours prioritaires lorsque vous les fournissez. Le recours à cette solution de secours dynamique est particulièrement utile lorsque vous utilisez la découverte dynamique d’outils, où la surface de l’outil peut changer au moment de l’exécution. Pour plus d’informations, consultez Sémantique des réponses dynamiques.

Expérience de pointage pour des citations cliquables dans une réponse Copilot.

Importante

Vous n’avez pas besoin d’une carte adaptative pour obtenir des citations. La sémantique des réponses à elle seule (plus data_path quelques properties mappages) suffit à Copilot pour afficher une citation cliquable pointant vers votre source.

Envisagez d’utiliser des applications MCP interactives pour une expérience utilisateur riche au-delà des citations.

Utilisation de la sémantique des réponses

La sémantique de réponse définie dans votre manifeste de plug-in agit comme un contrat entre votre serveur MCP ou votre API et Copilot.

  1. Votre outil renvoie du code JSON.

  2. Dans le manifeste du plug-in :

    • Vous indiquez à Copilot où se trouvent les éléments citables dans ce JSON (data_path).
    • Vous indiquez à Copilot quels champs de chaque élément correspondent au titre, au sous-titre et à l’URL (properties) de la citation.

  3. Copilot affiche une citation pour chaque élément. Les utilisateurs cliquent sur votre source.

Si vous fournissez des mappages explicites properties , Copilot les utilise tels quels. L’inférence dynamique s’applique uniquement en l’absence de ces mappages. Pour plus d’informations, consultez Sémantique des réponses dynamiques.

Configuration minimale

Votre response_semantics configuration est pilotée par la forme de la réponse de votre outil, et non par le protocole de la réponse de votre outil. Les agents Copilot avec tous les protocoles d’outil (MCP, OpenAPI, extensions de message) utilisent le même schéma de manifeste.

La plupart des réponses des outils se présentent sous l’une des deux formes suivantes :

  • Un tableau de résultats (comme un outil de recherche) : l’outil renvoie plusieurs éléments, chacun devant devenir sa propre citation.
  • Un seul objet (comme un outil de récupération) : l’outil renvoie exactement un document ou un enregistrement, qui devient une seule citation.

Tableau de résultats (style de recherche)

Les outils qui renvoient plusieurs éléments renvoient généralement un tableau sous une results clé (ou équivalente), comme illustré dans l’exemple suivant.

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

L’exemple suivant montre une configuration de la sémantique de réponse minimale dans le manifeste du plug-in.

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

La data_path propriété pointe vers le tableau. Chaque élément produit sa propre citation cliquable. Les properties JSONPaths sont résolus par rapport à chaque élément du tableau, et non par la racine.

Objet unique (style fetch)

L’exemple suivant montre une réponse avec un seul enregistrement (un document, une entité, un fichier) à citer comme une source.

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

L’exemple suivant montre une configuration de la sémantique de réponse minimale dans le manifeste du plug-in.

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

La data_path propriété définie sur $ sélectionne l’objet racine en tant qu’élément de citation unique. Il s’agit du bon choix chaque fois que l’outil renvoie un enregistrement, même si cet enregistrement inclut des champs imbriqués tels que metadata.

Wrapper de contenu MCP

Les outils MCP enveloppent leur réponse dans un content tableau d’éléments TextContentBlock . Copilot analyse le champ de chaque bloc au format JSON, puis applique le text vôtre data_path à la valeur analysée. La forme à l’intérieur de la text chaîne détermine votre configuration, et non l’enveloppe extérieure content .

Exemple de réponse 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\"}"
    }
  ]
}

L’analyseur déroule d’abord la text charge utile, en ne laissant qu’un seul objet. Vous utilisez la configuration d’objet unique ("data_path": "$"). Un outil de recherche MCP qui renvoie un tableau à l’intérieur du text champ utilise le tableau de configuration des résultats (data_path: "$.results").

Sémantique de réponse dynamique (secours sans config)

Explicit response_semantics ne fonctionne bien que lorsque vos outils sont stables et immuables. Ce n’est souvent pas le cas : un connecteur construit sur un serveur MCP tiers met fréquemment à jour ses outils, de sorte que vous devez synchroniser le manifeste à mesure que le serveur évolue. Lorsque le serveur change mais pas le manifeste, l’ancrage structuré revient silencieusement au texte brut et les citations cessent de s’afficher.

Lorsque votre manifeste omet les mappages explicites properties , Copilot déduit les champs de citation en analysant chaque objet de résultat par rapport à une liste hiérarchisée d’alias bien connus. Cette solution de secours sans configuration est particulièrement utile avec la découverte d’outils dynamique, où vous ne pouvez pas épingler un manifeste à une surface d’outil fixe.

Alias de champ

Pour chaque champ de citation, Copilot vérifie les alias suivants dans l’ordre de priorité et utilise la première correspondance trouvée.

Champ de citation Alias (ordre de priorité)
URL display_url, displayUrl, web_url, webUrl, url, citation_url, citationUrl, reference_url, referenceUrl, website_url, websiteUrl, web_link, webLink, link, href
Titre display_title, displayTitle, title, name, display_name, displayName, web_title, webTitle, subject, heading, caption
Sous-titre subtitle, description, summary, snippet, source, provider, site_name, siteName, highlight
Miniature thumbnail_url, thumbnailUrl, thumbnail, image_url, imageUrl, logo_url, logoUrl, icon_url, iconUrl
Tableau des résultats results, items, data, value, records, entries

Règles de résolution

  • L’URL est l’exigence absolue. Si aucune URL non vide n’est trouvée, Copilot ignore l’élément et n’émet aucune citation.
  • Le titre revient au nom d’hôte si aucun alias de titre n’est présent.
  • Les sous-titres et les vignettes sont opportunistes. Copilot les inclut lorsqu’il reconnaît un champ correspondant et les omet dans le cas contraire.

Exemple

Si votre outil MCP renvoie la réponse suivante, vous n’avez pas besoin de la définir response_semantics explicitement. Copilot déduit les champs de citation des alias bien connus.

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

Le text champ contient les résultats à chaînes :

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

Étant donné que results, urltitle, et subtitle tous correspondent à des alias connus, Copilot affiche une citation cliquable pour chaque élément. Tous les alias équivalents fonctionnent à leur place - par exemple, items ou data à la place de results, ou webUrlhref ou au lieu de url.

Propriétés de citation

Les propriétés suivantes sont disponibles sur les citations. Toutes les valeurs sont des expressions JSONPath relatives par rapport à un élément sélectionné par data_path.

Propriété Obligatoire Ce qu'il fait
title Oui (pratiquement) En-tête cliquable de la citation.
subtitle Non Deuxième ligne - dates, auteurs, catégories.
url Oui (pratiquement) Où la citation navigue au clic. Doit être un lien canonique vers votre source.
thumbnail_url Non Petite image montrée à côté de la citation.

Remarque

Si url c’est manquant, la citation n’est pas cliquable. Cette propriété manquante est une raison très courante pour laquelle les développeurs voient des citations non fonctionnelles.

Cadre data_path

La data_path propriété est une expression JSONPath (RFC 9535). L’utilisation d’une expression JSONPath incorrecte est l’une des raisons les plus courantes pour lesquelles les citations ne s’affichent pas.

Si votre réponse ressemble à... Utilisez ceci data_path
{ "results": [ ... ] } $.results
{ "content": [ { "results": [ ... ] } ] } (imbriqué de style MCP) $.content[0].results
Un seul objet à la racine (pas d’enveloppe de tableau) $
{ "content": [ { "type": "text", "text": "<stringified JSON>" } ] } (MCP brut) $ for root, ou $.results si le JSON interne a un tableau

Conseil

Aplatissez vos tableaux. Les tableaux imbriqués à plusieurs niveaux (par exemple, $.content[0].results[0].items) sont le modèle de schéma le plus susceptible d’échouer silencieusement. Si vous possédez la forme Réponse de l’outil, renvoyez un tableau plat results: [...] .

Aller au-delà de la sémantique des réponses

Comme première préférence, envisagez d’ajouter des widgets d’interface utilisateur enrichis à votre agent. Cette approche est plus évolutive et native de l’IA, ce qui permet des interactions plus intelligentes, adaptatives et transparentes.

Remarque

Les instructions relatives aux cartes adaptatives dans cette section s’appliquent uniquement aux agents déclaratifs. La staticTemplate propriété et le rendu de la carte adaptative pour les citations ne sont pas pris en charge par les connecteurs Copilot.

Ajoutez une carte adaptative en dernier recours si - et seulement si - vous avez besoin de l’une des conditions suivantes :

  • Une disposition visuelle personnalisée pour la citation seule (plusieurs colonnes, bannières d’image, blocs de texte formatés) ou plusieurs champs affichés dans le corps de la carte de citation (au-delà du titre, des sous-titres et de l’URL).
  • Boutons d’action au-delà du comportement par défaut « cliquer sur la citation » (par exemple, Action.Executebarres d’outils à plusieurs boutons).

Pour la grande majorité des scénarios de citation - « montre-moi la source et laisse-moi cliquer » - ignorer complètement les cartes adaptatives. Elles ajoutent de la complexité, sont plus difficiles à déboguer et l’interface utilisateur de citation par défaut est propre et cohérente avec le reste de Copilot.

Exemple avec carte adaptative

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

Notez les ${title}jetons , ${subtitle}et ${url} . La même properties carte que vous avez vue précédemment remplit ces jetons. La carte adaptative est une couche de présentation au-dessus de la sémantique des réponses ; elle ne la remplace pas.

Liste de pour la résolution des problèmes

Si les citations n’apparaissent pas, utilisez la liste de contrôle suivante :

  • Pointe data_path vers le bon nœud ? Collez la réponse JSON brute de votre outil dans un testeur JSONPath et confirmez que votre expression renvoie le tableau ou l’objet que vous attendez.
  • Chaque élément a-t-il un non vide url? Les URL manquantes entraînent des citations non cliquables.
  • Pour les outils MCP, le champ à l’intérieur TextContentBlock est-il text JSON valide ? Analysez-le manuellement pour confirmer.
  • Le schéma est-il plat ? Si vous avez des tableaux profondément imbriqués, essayez de retourner un seul tableau plat.
  • Avez-vous déclaré response_semantics par fonction (à l’intérieur de capabilities cette fonction dans le manifeste du plugin) et non à la racine du plugin ? Vous devez l’étendre à la fonction.

Contenu connexe

  • Last updated on