Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Le citazioni creano fiducia nel fatto che una risposta di Microsoft 365 Copilot sia accurata e fondata. Il corpo della risposta include automaticamente le citazioni per le risposte sintetizzate di Copilot. Tuttavia, l'utente finale potrebbe non essere in grado di aprire l'origine di informazioni. Quando Copilot basa una risposta su un contenuto Web pubblico, l'URL viene citato automaticamente.
Per il contenuto proveniente da un server MCP (Model Context Protocol) o da un'API, tale contenuto può restituire un URL che l'utente finale può aprire e rivedere. La definizione del plug-in viene definita response_semantics in modo che Copilot sappia dove si trova l'URL nella risposta del plug-in e possa rendere la citazione selezionabile con il collegamento corretto.
Se salti questo passaggio, la risposta può comunque includere una citazione, ma solo con una pillola o un'icona rappresentativa. L'utente finale non può fare clic sui dati del sito e confermarli.
Copilot può anche dedurre automaticamente i metadati delle citazioni dai nomi dei campi comuni, quindi non è più necessario definire response_semanticsesplicitamente . Esplicito response_semantics ha ancora la precedenza quando li fornisci. Affidarsi a questo fallback dinamico è particolarmente utile quando si utilizza il rilevamento dinamico degli utensili, in cui la superficie dell'utensile può cambiare in fase di esecuzione. Per altre informazioni, vedere Semantica della risposta dinamica.
Importante
Non è necessaria una scheda adattiva per ottenere citazioni. La sola semantica della risposta, più data_path alcuni properties mapping, è sufficiente per consentire a Copilot di eseguire il rendering di una citazione selezionabile che rimanda alla fonte.
Prendi in considerazione l'uso di app MCP interattive per un'esperienza utente avanzata oltre le citazioni.
Uso della semantica della risposta
La semantica della risposta definita nel manifesto del plug-in funge da contratto tra il server o l'API MCP e Copilot.
Lo strumento restituisce JSON.
-
- Dici a Copilot dove si trovano gli elementi citabili in quel JSON (
data_path). - L'utente indica a Copilot i campi di ogni elemento associati al titolo, al sottotitolo e all'URL della citazione (
properties).
- Dici a Copilot dove si trovano gli elementi citabili in quel JSON (
Copilot esegue il rendering di una citazione per ogni elemento. Gli utenti fanno clic sull'origine.
Se si specificano mapping espliciti properties , Copilot li usa così come sono. L'inferenza dinamica si applica solo quando tali mapping sono assenti. Per altre informazioni, vedere Semantica della risposta dinamica.
Configurazione minima
La response_semantics configurazione è guidata dalla forma della risposta dell'utensile, non dal protocollo della risposta dell'utensile. Gli agenti Copilot con tutti i protocolli dello strumento (MCP, OpenAPI, estensioni messaggio) usano lo stesso schema manifesto.
La maggior parte delle risposte dello strumento rientra in una delle due forme seguenti:
- Una matrice di risultati (come uno strumento di ricerca): lo strumento restituisce più elementi, ognuno dei quali dovrebbe diventare la propria citazione.
- Un singolo oggetto (come uno strumento di recupero): lo strumento restituisce esattamente un documento o un record, che diventa una singola citazione.
Matrice di risultati (stile di ricerca)
Gli strumenti che restituiscono più elementi in genere restituiscono una matrice sotto una results chiave (o equivalente), come illustrato nell'esempio seguente.
{
"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'esempio seguente mostra una configurazione semantica di risposta minima nel manifesto del plug-in.
"capabilities": {
"response_semantics": {
"data_path": "$.results",
"properties": {
"title": "$.title",
"subtitle": "$.publishedDate",
"url": "$.url"
}
}
}
La data_path proprietà punta alla matrice. Ogni elemento produce la propria citazione su cui è possibile fare clic. I properties JSONPath vengono risolti in relazione a ogni elemento dell'array, non alla radice.
Oggetto singolo (stile di recupero)
L'esempio seguente mostra una risposta con esattamente un record - un documento, un'entità, un file - da citare come unica 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" }
}
L'esempio seguente mostra una configurazione semantica di risposta minima nel manifesto del plug-in.
"capabilities": {
"response_semantics": {
"data_path": "$",
"properties": {
"title": "$.title",
"subtitle": "$.publishedDate",
"url": "$.url"
}
}
}
Il data_path set di proprietà seleziona $ l'oggetto radice come singolo elemento di citazione. Questa è la scelta giusta quando lo strumento restituisce un record, anche se il record include campi annidati come metadata.
Wrapper contenuto MCP
Gli strumenti MCP racchiudono la loro risposta in una content serie di TextContentBlock elementi. Copilot analizza il text campo di ogni blocco come JSON e quindi applica U data_path al valore analizzato. La forma all'interno della stringa guida la text configurazione, non l'involucro esterno content .
Esempio di risposta 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\"}"
}
]
}
Il parser esegue prima il wrapping del text payload, lasciando un singolo oggetto. Utilizzate la configurazione a oggetto singolo ("data_path": "$"). Uno strumento di ricerca MCP che restituisce una matrice all'interno del text campo utilizza la configurazione della matrice di risultati (data_path: "$.results").
Semantica della risposta dinamica (fallback zero-config)
Esplicito response_semantics funziona bene solo quando gli strumenti sono stabili e immutabili. Spesso non è così: un connettore costruito su un server MCP di terze parti aggiorna frequentemente i suoi strumenti, quindi è necessario mantenere il manifesto sincronizzato man mano che il server si evolve. Quando il server cambia ma il manifesto no, il grounding strutturato torna automaticamente al testo non elaborato e le citazioni interrompono il rendering.
Quando il manifesto omette i mapping espliciti properties , Copilot deduce i campi di citazione analizzando ogni oggetto risultato rispetto a un elenco prioritario di alias noti. Questo fallback zero-config è particolarmente utile con l'individuazione dinamica degli strumenti, in cui non è possibile bloccare un manifesto a una superficie fissa dell'utensile.
Alias di campo
Per ogni campo di citazione, Copilot controlla gli alias seguenti in ordine di priorità e usa la prima corrispondenza trovata.
| Citation | Alias (ordine di priorità) |
|---|---|
| URL |
display_url, displayUrl, web_url, webUrl, url, citation_url, citationUrl, reference_url, referenceUrl, website_url, websiteUrl, web_link, webLink, link, href |
| Titolo |
display_title, displayTitle, title, name, display_name, displayName, web_title, webTitle, subject, heading, caption |
| Sottotitoli |
subtitle, description, summary, snippet, source, provider, site_name, siteName, highlight |
| Anteprima |
thumbnail_url, thumbnailUrl, thumbnail, image_url, imageUrl, logo_url, logoUrl, icon_url, iconUrl |
| Matrice di risultati |
results, items, data, value, records, entries |
Regole di risoluzione
- L'URL è il requisito fondamentale. Se non viene trovato alcun URL non vuoto, Copilot ignora l'elemento e non genera alcuna citazione.
- Il titolo torna al nome host se non è presente alcun alias del titolo.
- I sottotitoli e l'anteprima sono opportunistici. Copilot li include quando riconosce un campo corrispondente e li omette in caso contrario.
Esempio
Se lo strumento MCP restituisce la risposta seguente, non è necessario definire response_semantics esplicitamente. Copilot deduce i campi di citazione dagli alias noti.
{
"isError": false,
"content": [
{
"type": "text",
"text": "<stringified results>"
}
]
}
Il text campo contiene i risultati inseriti tra stringa:
{
"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"
}
]
}
Poiché results, url, title, e subtitle tutti corrispondono a alias noti, Copilot esegue il rendering di una citazione selezionabile per ogni elemento. Al loro posto funzionano gli alias equivalenti, items ad esempio or data or of results, or webUrl or href or instead of url.
Proprietà citazione
Le proprietà seguenti sono disponibili per le citazioni. Tutti i valori sono espressioni JSONPath relative a un oggetto selezionato da data_path.
| Proprietà | Obbligatorio | Risultato |
|---|---|---|
title |
Sì (praticamente) | Titolo selezionabile della citazione. |
subtitle |
No | Seconda riga - date, autori, categorie. |
url |
Sì (praticamente) | Dove la citazione si sposta al clic del mouse. Deve essere un collegamento canonico all'origine. |
thumbnail_url |
No | Piccola immagine visualizzata accanto alla citazione. |
Nota
Se url manca, la citazione non è selezionabile. Questa proprietà mancante è un motivo molto comune per cui gli sviluppatori vedono citazioni non funzionali.
Impostazione data_path
La proprietà è un'espressione data_path JSONPath (RFC 9535). L'uso di un'espressione JSONPath errata è uno dei motivi più comuni per cui le citazioni non vengono visualizzate.
| Se la tua risposta è simile a... | Usare data_path |
|---|---|
{ "results": [ ... ] } |
$.results |
{ "content": [ { "results": [ ... ] } ] } (annidato in stile MCP) |
$.content[0].results |
| Un singolo oggetto alla radice (nessun wrapper di matrice) | $ |
{ "content": [ { "type": "text", "text": "<stringified JSON>" } ] } (MCP grezzo) |
$ per root o $.results se il JSON interno ha una matrice |
Suggerimento
Appiattisci i tuoi array. Le matrici annidate multilivello (ad esempio, $.content[0].results[0].items) sono il modello di schema che ha maggiori probabilità di fallire silenziosamente. Se si possiede la forma Risposta utensile, restituire una matrice piatta results: [...] .
Andare oltre la semantica della risposta
Come prima preferenza, valuta l'aggiunta di widget avanzati per l'interfaccia utente al tuo agente. Questo approccio è più orientato al futuro e nativo dell'intelligenza artificiale, consentendo interazioni più intelligenti, adattive e senza interruzioni.
Nota
La guida per la scheda adattiva in questa sezione si applica solo agli agenti dichiarativi. Il rendering della proprietà e della staticTemplate scheda adattiva per le citazioni non è supportato dai connettori Copilot.
Aggiungi una scheda adattiva come ultima risorsa se, e solo se, hai bisogno di una delle seguenti condizioni:
- Layout visivo personalizzato per la sola citazione (a più colonne, banner immagine, blocchi di testo formattati) o per più campi di cui viene eseguito il rendering nel corpo della scheda della citazione (oltre a titolo, sottotitoli e URL).
-
Pulsanti di azione oltre al comportamento predefinito "fare clic sulla citazione", ad esempio
Action.Executebarre degli strumenti con più pulsanti.
Per la stragrande maggioranza degli scenari di citazione - "mostrami la fonte e fammi cliccare" - salta completamente le schede adattive. Aggiungono complessità, sono più difficili da debuggare e l'interfaccia utente predefinita per le citazioni è pulita e coerente con il resto di Copilot.
Esempio con scheda adattiva
"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}"
}
}
}
Si noti i ${title}token, ${subtitle}, e ${url} . La stessa properties mappa che hai visto in precedenza popola questi token. La scheda adattiva è un livello di presentazione in cima alla semantica della risposta; non lo sostituisce.
Elenco di controllo per la risoluzione dei problemi
Se le citazioni non vengono visualizzate, usare l'elenco di controllo seguente:
- Punta
data_pathal nodo giusto? Incolla la risposta JSON non elaborata dello strumento in un tester JSONPath e verifica che l'espressione restituisca l'array o l'oggetto previsto. - Ogni elemento ha un elemento non vuoto
url? Gli URL mancanti generano citazioni non selezionabili. - Per gli strumenti MCP, il campo è all'interno
TextContentBlockditextJSON valido? Analizzalo manualmente per confermare. - Lo schema è piatto? Se si hanno matrici profondamente annidate, provare a restituire una singola matrice piatta.
- Hai dichiarato
response_semanticsper funzione (all'interno di quella funzione nel manifestocapabilitiesdel plug-in) e non nella radice del plug-in? Devi definire l'ambito della funzione.