Richiedi con le Adaptive Cards

Adaptive Cards consente di aggiungere frammenti di contenuto agli agenti di Copilot Studio che possono anche essere scambiati apertamente con altre app e servizi cloud. Per fornire la funzionalità di conversazione avanzata per il tuo agente, puoi includere testo, grafica e pulsanti. Poiché sono indipendenti dalla piattaforma, è possibile personalizzare facilmente Adaptive Cards in base alle proprie esigenze.

Con un nodo Scheda adattiva, l'agente può visualizzare una scheda adattiva contenente uno o più pulsanti di invio e, facoltativamente, uno o più campi di input del modulo. L'agente memorizza l'input dell'utente nelle variabili per utilizzarle in un secondo momento nella conversazione.

Copilot Studio include un progettista di schede adattive predefinito, che offre le funzionalità più utili di Adaptive Cards Designer.

In alternativa, è possibile:

• Utilizza una rappresentazione JSON per la scheda che vuoi mostrare all'utente.
• Utilizza una formula Power Fx per includere informazioni dinamiche nella scheda.

Puoi anche controllare il comportamento della scheda ad esempio cosa fare quando l'utente immette una risposta non valida o se il nodo può essere interrotto.

Il nodo Scheda adattiva è pensato per le schede interattive, in cui l'utente deve inviare una risposta. Usare i nodi Messaggio e Domanda per presentare all'utente una scheda non interattiva che visualizza informazioni.

Aggiungere un nodo Scheda adattiva

1. Selezionare l'icona Aggiungi nodo sotto il nodo dopo il quale si vuole aggiungere un nodo scheda adattiva, quindi selezionare Chiedi con scheda adattiva.

2. Seleziona i tre punti (...) del nodo, poi seleziona Proprietà.

3. Nel riquadro delle proprietà del nodo della scheda adattiva, seleziona Modifica scheda adattiva. Viene aperto il pannello di progettazione schede adattive.

4. Aggiungi gli elementi desiderati per la tua scheda e configura le relative proprietà. In alternativa, nel riquadro Card payload editor, sostituisci il payload predefinito con il valore letterale JSON della tua scheda.

   Mancia

   La scheda deve contenere almeno un pulsante di invio, in quanto deve essere una scheda interattiva che consente a un utente di inviare informazioni all'agente. In caso contrario, se ha solo lo scopo di mostrare informazioni, è necessario aggiungere la scheda adattiva a un nodo Messaggio.

5. Al termine della progettazione iniziale, seleziona Salva e chiudi il pannello di progettazione. Nel nodo viene visualizzata un'anteprima della scheda. Copilot Studio crea automaticamente variabili di output in base agli input specificati nel codice.

   

   Mancia

   Se le variabili di output generate per la scheda non sono corrette, puoi aggiornare manualmente l'elenco delle variabili e i relativi tipi selezionando Modifica schema nel pannello delle proprietà del nodo Scheda adattiva.

   La scheda adattiva interattiva è pronta. Quando un utente del tuo agente seleziona un pulsante di invio su una scheda, le variabili di output vengono popolate con le informazioni fornite dall'utente nell'interazione con la scheda.

Altre proprietà

È possibile usare altre proprietà per controllare il comportamento del nodo scheda adattiva , ad esempio:

• Come l'agente risponde a una risposta non valida
• Se può essere interrotto

Se l'agente è in attesa di un invio da una scheda adattiva e l'utente invia invece un messaggio di testo, questa risposta viene considerata non valida, a meno che il messaggio attivi un'interruzione. In questo caso, le seguenti proprietà determinano il comportamento.

• Numero di nuove richieste: il numero di volte in cui l'agente tenta di ottenere un invio valido dalla scheda. Il valore predefinito è Repeat fino a 2 volte. Puoi anche selezionare Ripeti una volta o Non ripetere. Per ogni nuovo tentativo, la scheda viene rispedita all'utente.

• Richiesta di ripetizione dei tentativi: usare questa proprietà per definire un messaggio da inviare quando si verifica un nuovo tentativo, insieme a una ripetizione della scheda. Per definire un messaggio di riprova, selezionare Personalizza e quindi immettere il nuovo prompt.

• Consenti il passaggio a un altro argomento: se questa opzione è selezionata (impostazione predefinita), un messaggio in arrivo da un utente quando l'agente è in attesa dell'invio di una scheda attiva un'interruzione e passa a un altro argomento. Se si verifica un cambio di argomento, la scheda viene inviata nuovamente all'utente al termine dell'argomento di interruzione.

Comportamento del pulsante di invio per gli agenti con schede consecutive

Per impostazione predefinita, le Adaptive Cards consentono di selezionare più volte i pulsanti di invio. Se un agente ha delle Adaptive Cards consecutive e l'utente seleziona un pulsante su una scheda precedente, questi potrebbe incorrere in un comportamento imprevisto.

Per impedire che l'azione di invio su una scheda interferisca con un'altra scheda:

• Isola le azioni di invio: verifica che ogni scheda adattiva abbia un identificatore univoco e gestori di azioni specifici.

• Usare le azioni di invio con dati univoci: quando si definiscono le azioni di invio per le schede, includere identificatori univoci o payload di dati che consentono di distinguere le schede quando l'utente seleziona un pulsante di invio.

• Aggiungi una logica di gestione degli eventi affidabile all'agente: definisci le condizioni in base agli identificatori distintivi o agli elementi payload associati ai pulsanti di invio.

• Debug e registrazione: aggiungi il registro dettagliato al codice di gestione degli eventi dell'agente per acquisire la sequenza di azioni e identificare dove si verificano invii imprevisti.

Utilizzare un identificatore di invio nei dati di Action.Submit

Se l'agente invia più Adaptive Cards in una conversazione (ad esempio, schede consecutive, ripetizioni o interruzioni), gli utenti potrebbero premere Invia su una scheda precedente. Per aiutare l'agente o il client personalizzato a distinguere la scheda e l'azione da cui proviene una risposta, includere un identificatore univoco nel payload dei dati di ogni azione di invio e convalidarlo durante l'elaborazione della risposta.

Esempio:

{
  "type": "Action.Submit",
  "title": "Confirm",
  "data": {
    "actionSubmitId": "booking_confirm_card_v3_confirm"
  }
}

Suggerimento per l'esperienza utente di Web Chat per evitare clic obsoleti

Alcuni client di chat, incluse le esperienze web, possono lasciare le schede precedenti selezionabili dopo che un utente invia una scheda successiva. Se si crea un'esperienza di chat Web personalizzata, è consigliabile disabilitare i pulsanti di invio dopo il primo clic o aggiornare il messaggio della scheda precedente per ridurre gli invii accidentali duplicati o non aggiornati.

L'esempio seguente illustra uno dei modi per disabilitare i pulsanti Action.Submit dopo il primo clic in un'esperienza di chat Web personalizzata:

1. Eseguire il rendering delle Adaptive Cards usando l'SDK delle Adaptive Cards o un altro renderer che crea pulsanti o input HTML effettivi.

2. Quando ricevi un'azione di invio, contrassegna immediatamente la scheda corrente come inviata nell'interfaccia utente. Ad esempio, impostare un submitted flag nel messaggio.

3. Eseguire nuovamente il rendering o la modifica della scheda Document Object Model (DOM), in modo che tutti gli elementi interattivi siano disabilitati e quindi inviare il payload di invio al bot o al servizio.

4. Se la chat supporta più schede per conversazione, ripetere lo stesso modello per ogni messaggio di scheda per impedire invii non aggiornati da schede precedenti.

Esempio:

// Example: disable Adaptive Card submit interactions after the first click.
// This is UI-side logic for custom web chat experiences.

// When you render a card, keep a reference to its container element.
// For example, each chat message could render into its own <div>.
function disableCardInteractivity(cardContainer) {
    // Disable buttons (including Action.Submit rendered as <button>).
    for (const el of cardContainer.querySelectorAll('button, input, select, textarea')) {
        el.disabled = true;
        el.setAttribute('aria-disabled', 'true');
    }

    // Optional: prevent click handlers from firing (defense-in-depth).
    cardContainer.addEventListener(
        'click',
        (evt) => {
            const target = /** @type {HTMLElement} */ (evt.target);
            if (target && target.closest && target.closest('button, input, select, textarea')) {
                evt.preventDefault();
                evt.stopPropagation();
            }
        },
        true
    );
}

// Wire the behavior into your Adaptive Cards host.
// The Adaptive Cards SDK surfaces submits via onExecuteAction.
function wireCardSubmitHandling(adaptiveCard, cardContainer, sendToBot) {
    let submitted = false;

    adaptiveCard.onExecuteAction = async (action) => {
        // Only allow the first submit from this card instance.
        if (submitted) {
            return;
        }
        submitted = true;

        // Disable the UI immediately to avoid duplicate/stale clicks.
        disableCardInteractivity(cardContainer);

        // Send the submit payload to your bot/service.
        // If you're using Action.Submit with a unique ID (for example, actionSubmitId),
        // include it in the payload so your bot can de-duplicate safely.
        await sendToBot({
            type: 'adaptiveCard/submit',
            data: action && action.data ? action.data : {},
            verb: action && action.verb ? action.verb : undefined
        });
    };
}

Utilizzare Power Fx per rendere dinamica la scheda

Puoi utilizzare una formula Power Fx per includere informazioni dinamiche nella scheda facendo riferimento alle variabili dell'argomento o dell'agente.

1. Seleziona i tre punti (...) del nodo, poi seleziona Proprietà.

2. Nel pannello Proprietà nodo scheda adattiva passare a Formula. Se si seleziona Formula , la rappresentazione JSON della scheda viene convertita automaticamente in una formula di Power Fx.

   

   Ad esempio, inizia con il seguente valore letterale JSON per una scheda:

   {
     "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
     "type": "AdaptiveCard",
     "version": "1.5",
     "body": [{
         "type": "ColumnSet",
         "columns": [{
             "type": "Column",
             "width": 2,
             "items": [{
                 "type": "TextBlock",
                 "text": "Tell us about yourself",
                 "weight": "Bolder",
                 "size": "Medium",
                 "wrap": true,
                 "style": "heading"
               }, {
                 "type": "TextBlock",
                 "text": "We just need a few more details to get you booked for the trip of a lifetime!",
                 "isSubtle": true,
                 "wrap": true
               }, {
                 "type": "Input.Text",
                 "id": "myName",
                 "label": "Your name (Last, First)",
                 "isRequired": true,
                 "regex": "^[A-Z][a-z]+, [A-Z][a-z]+$",
                 "errorMessage": "Please enter your name in the specified format"
               }
             ]
           }
         ]
       }
     ],
     "actions": [{
         "type": "Action.Submit",
         "title": "Submit"
       }
     ]
   }
   

   Ecco la formula risultante Power Fx, con due variabili , Topic.Title e Topic.Subtitle, anziché il testo hardcoded del valore letterale JSON. Questo esempio presuppone che le variabili siano definite nell'argomento.

   {
     '$schema': "http://adaptivecards.io/schemas/adaptive-card.json",
     type: "AdaptiveCard",
     version: "1.5",
     body: [
       {
         type: "ColumnSet",
         columns: [
           {
             type: "Column",
             width: "2",
             items: [
               {
                 type: "TextBlock",
                 text: Topic.Title,
                 weight: "Bolder",
                 size: "Medium",
                 wrap: true,
                 style: "heading"
               },
               {
                 type: "TextBlock",
                 text: Topic.Subtitle,
                 isSubtle: true,
                 wrap: true
               },
               {
                 type: "Input.Text",
                 id: "myName",
                 label: "Your name (Last, First)",
                 isRequired: true,
                 regex: "^[A-Z][a-z]+, [A-Z][a-z]+$",
                 errorMessage: "Please enter your name in the specified format"
               }
             ]
           }
         ]
       }
     ],
     actions: [
       {
         type: "Action.Submit",
         title: "Submit"
       }
     ]
   }