Afficher les citations avec la sémantique de réponse

Les citations permettent de garantir qu’une réponse Microsoft 365 Copilot est précise et fondée. Le corps de la réponse inclut automatiquement des citations pour les réponses synthétisées Copilot. Toutefois, l’utilisateur final peut ou non être en mesure d’ouvrir la source d’informations. Lorsque Copilot crée une réponse sur du 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 doit retourner une URL qu’un utilisateur final peut ouvrir et réviser. Vous définissez response_semantics dans votre définition de plug-in afin que Copilot sache où se trouve cette URL dans la réponse du plug-in et puisse rendre la citation cliquable avec le lien approprié.

Si vous ignorez cette étape, la réponse inclut toujours 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. C’est pourquoi les citations cliquables sont également une exigence de stratégie de magasin d’agents Microsoft 365 Copilot pour les applications publiées dans le Store.

Importante

Vous n’avez pas besoin d’une carte adaptative pour obtenir des citations. La sémantique de réponse 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 de réponse

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

1. Votre outil retourne 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 de la citation (properties).

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

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 votre réponse d’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 répartissent sous l’une des deux formes suivantes :

• Tableau de résultats (comme un outil de recherche) : l’outil retourne plusieurs éléments, chacun devant devenir sa propre citation.
• Objet unique (comme un outil d’extraction) : l’outil retourne exactement un document ou un enregistrement, qui devient une citation unique.

Tableau de résultats (style de recherche)

Les outils qui retournent plusieurs éléments retournent généralement un tableau sous une results clé (ou une clé é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 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 de tableau, et non à la racine.

Objet unique (type fetch)

L’exemple suivant montre une réponse avec exactement un enregistrement (un document, une entité, un fichier) à citer comme 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 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 retourne un enregistrement, même si l’enregistrement inclut des champs imbriqués comme metadata.

Wrapper de contenu MCP

Les outils MCP encapsulent leur réponse dans un content tableau d’éléments TextContentBlock . Copilot analyse le text champ de chaque bloc au format JSON, puis applique votre data_path à la valeur analysée. La forme à l’intérieur de la text chaîne est ce qui pilote votre configuration, et non le wrapper externe 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écompresse d’abord la text charge utile, en laissant un seul objet. Vous utilisez la configuration d’objet unique ("data_path": "$"). Un outil de recherche MCP qui retourne un tableau à l’intérieur du text champ utilise la configuration du tableau de résultats (data_path: "$.results").

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)	Titre cliquable de la citation.
subtitle	Non	Deuxième ligne : dates, auteurs, catégories.
url	Oui (pratiquement)	Cliquez sur l’emplacement de navigation de la citation. Doit être un lien canonique vers votre source.
thumbnail_url	Non	Petite image affichée à côté de la citation.

Remarque

Si url 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.

Réglage 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 n’apparaissent pas.

Si votre réponse ressemble à...	Utilisez ceci data_path
{ "results": [ ... ] }	$.results
{ "content": [ { "results": [ ... ] } ] } (imbriqué de style MCP)	$.content[0].results
Objet unique à la racine (aucun wrapper de tableau)	$
{ "content": [ { "type": "text", "text": "<stringified JSON>" } ] } (MCP brut)	$ pour la racine, ou $.results si le JSON interne a un tableau

Conseil

Aplatir 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 en mode silencieux. Si vous êtes propriétaire de la forme de réponse de l’outil, retournez un tableau plat results: [...] .

Aller au-delà de la sémantique de réponse

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

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 (multicolonne, bannières d’image, blocs de texte mis en forme) ou plusieurs champs affichés dans le corps de la citation carte (au-delà du titre, du sous-titre et de l’URL).
• Boutons d’action au-delà du comportement par défaut « cliquez sur la citation » (par exemple, Action.Execute, barres d’outils multibutton).

Pour la grande majorité des scénarios de citation - « montrez-moi la source et laissez-moi cliquer » - ignorez entièrement les cartes adaptatives. Ils 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} : ces jetons sont remplis par la même properties carte que celle indiquée précédemment. La carte adaptative est une couche de présentation par-dessus la sémantique de réponse ; il ne le remplace pas.

Liste de pour la résolution des problèmes

Si les citations ne s’affichent pas, utilisez la liste de contrôle suivante.

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

Contenu connexe

• Schéma de manifeste de plug-in 2.4 — response_semantics objet
• Ajouter des applications MCP aux agents déclaratifs dans Microsoft 365 Copilot
• Bonnes pratiques pour la création d’agents déclaratifs