Restituisce risposte avanzate con schede adattive

  • 2 minuti

Quando un agente usa un'azione con un plug-in API per restituire una risposta, accetta le informazioni dall'API ed elabora l'azione usando il modello linguistico. Il modello linguistico restituisce una risposta intuitiva che corrisponde alle istruzioni dell'agente. La compilazione dinamica delle risposte in base alle istruzioni predefinite o dell'utente rende l'agente altamente flessibile. È ad esempio possibile chiedergli di fornire le informazioni come elenco puntato o tabella. Questa flessibilità, tuttavia, ha un prezzo: l'agente potrebbe non sempre comprendere qual è il modo migliore per presentare le informazioni.

Poiché le API in genere restituiscono dati strutturati, è possibile controllare il modo in cui l'agente presenta le informazioni all'utente. Per controllare il modo in cui l'agente presenta i dati dall'API, definire un modello di scheda adattiva nel plug-in API.

Per definire il modello di scheda adattiva che l'agente deve usare per visualizzare i dati dell'API, usare la proprietà static_template nella parte della semantica di risposta della definizione del plug-in API. Il frammento di codice seguente mostra un modello di scheda adattiva di esempio:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "Image",
          "url": "${image_url}",
          "size": "large"
        },
        {
          "type": "TextBlock",
          "text": "${name}",
          "weight": "Bolder"
        },
        {
          "type": "TextBlock",
          "text": "${description}",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "text": "Allergens: ${if(count(allergens) > 0, join(allergens, ', '), 'none')}",
          "weight": "Lighter"
        },
        {
          "type": "TextBlock",
          "text": "**Price:** €${formatNumber(price, 2)}",
          "weight": "Lighter",
          "spacing": "None"
        }
      ]
    }
  ]
}

Si noti che le espressioni ${...} fanno riferimento alle proprietà nella risposta API e che fanno parte della creazione di modelli di schede adattive. In fase di esecuzione, l'agente accetta i dati restituiti dalla funzione e lo sovrappone al modello fornito, creando una scheda adattiva piena di dati.

Quando l'API restituisce più elementi, l'agente usa la scheda adattiva per visualizzare un singolo elemento. Gli utenti visualizzano la scheda passando il puntatore su una citazione:

Screenshot di un agente dichiarativo che mostra una risposta con informazioni sui piatti usando una scheda adattiva.

Importante

Quando si compilano schede adattive per le funzioni, tenere presente che visualizzano sempre un singolo elemento. All'inizio potrebbe sembrare controintuitivo compilare una scheda per un singolo elemento quando si implementano funzioni che restituiscono più elementi. Tenere presente che l'agente costruisce la risposta all'utente usando un LLM, ma vuole comunque offrire la possibilità di visualizzare un'anteprima più completa di ogni elemento, motivo per cui è necessario fornire un modello per un singolo elemento anziché l'intera risposta API.

Quando l'API restituisce un singolo elemento, l'agente potrebbe includere la scheda direttamente nella risposta:

Screenshot di un agente dichiarativo che mostra una risposta con informazioni sull'ordine usando una scheda adattiva.

Consiglio

Quando si compilano schede adattive per l'uso con le funzioni, è più pratico compilare ogni modello di scheda in un file separato. Usando l'estensione Adaptive Card Previewer Microsoft 365 Agents Toolkit, è possibile creare un file di dati e visualizzare in anteprima la scheda direttamente in Visual Studio Code. Quando la scheda è pronta, copiarne il contenuto nel file di definizione del plug-in API.