Spørg med Adaptive Cards

Adaptive Cards kan du føje indholdsstykker til Copilot Studio-agenter, der også kan udveksles åbent med andre cloudapps og -tjenester. Hvis du vil give din agent omfattende samtalefunktioner, kan du inkludere tekst, grafik og knapper. Da de er platformagnostiske, kan du nemt skræddersy Adaptive Cards til dine behov.

Med en Adaptive kort-node kan din agent vise et adaptivt kort, der indeholder en eller flere send-knapper og eventuelt et eller flere formularinputfelter. Din agent gemmer brugerinput i variabler til brug senere i samtalen.

Copilot Studio indeholder en indbygget adaptiv kortdesigner, som tilbyder de mest nyttige funktioner fra designeren til adaptive kort.

Du kan eventuelt bruge:

• Brug en JSON-repræsentation for det kort, du vil vise til brugeren.
• Brug en Power Fx-formel til at inkludere dynamiske oplysninger på kortet.

Du kan også kontrollere kortets funktionsmåde, f.eks. hvad du skal gøre, når brugeren angiver et ugyldigt svar, eller hvis noden afbrydes.

Noden Adaptive kort er beregnet til interaktive kort, hvor brugeren forventes at sende et svar. Brug noderne Meddelelse og Spørgsmål til at præsentere brugeren med et ikke-interaktivt kort, der viser oplysninger.

Tilføje et adaptivt kortnode

1. Vælg ikonet Tilføj node under den node, hvorefter du vil tilføje en adaptiv kortnode, og vælg derefter Spørg med adaptivt kort.

2. Vælg de tre prikker (...) i noden, og vælg derefter Egenskaber.

3. I panelet Adaptive kortnodeegenskaber skal du vælge Rediger adaptivt kort. Designerpanelet for adaptive kort åbnes.

4. Tilføj de ønskede elementer for dit kort, og konfigurer deres egenskaber. I panelet Editor til kortnyttedata kan du også skifte standardnyttedata til dit kort ved at erstatte den bogstavelige JSON-værdi for dit kort.

   Tip

   Dit kort skal indeholde mindst én send-knap, da det skal være et interaktivt kort, der giver brugeren mulighed for at sende oplysninger tilbage til agenten. Hvis det ikke gør og kun er beregnet til at vise oplysninger, skal du føje dit adaptive kort til en meddelelsesnode.

5. Når du er færdig med det oprindelige design, skal du vælge Gem og lukke designerpanelet. Der vises et eksempel på dit kort på noden. Copilot Studio opretter automatisk outputvariabler baseret på de input, der er angivet i koden.

   

   Tip

   Hvis de outputvariabler, der genereres for kortet, er forkerte, kan du manuelt opdatere listen over variabler og deres typer ved at vælge Rediger skema i panelet med Nodens egenskaber for adaptive kort.

   Dit interaktive adaptive kort er klar. Når en bruger af din agent vælger en send-knap på et kort, udfyldes outputvariablerne med de oplysninger, som brugeren har angivet i deres interaktion med kortet.

Andre egenskaber

Du kan bruge andre egenskaber til at styre, hvordan funktionsmåden for noden Adaptivt kort fungerer, f.eks.:

• Sådan reagerer agenten på et ugyldigt svar
• Om den kan afbrydes

Hvis agenten afventer en indsendelse fra et adaptivt kort, og brugeren i stedet sender en sms, betragtes dette svar som ugyldigt, medmindre meddelelsen udløser en afbrydelse. I dette tilfælde bestemmer følgende egenskaber funktionsmåden.

• Hvor mange genprompter: Det antal gange, din agent forsøger at få en gyldig indsendelse fra kortet. Standarden er Gentag op til 2 gange. Du kan også vælge Gentag én gang eller Gentag ikke. For hvert forsøg sendes kortet til brugeren igen.

• Prompt om forsøg: Brug denne egenskab til at definere en meddelelse, der skal sendes, når der opstår et nyt forsøg, sammen med en gentagelse af kortet. Hvis du vil definere en meddelelse om et nyt forsøg, skal du vælge Tilpas og derefter angive den nye prompt.

• Tillad skift til et andet emne: Hvis indstillingen er valgt (standard), udløser en indgående meddelelse fra en bruger, når agenten afventer indsendelse af et kort, en afbrydelse og skifter til et andet emne. Hvis der skiftes emne, sendes kortet igen til brugeren, når det afbrudte emne slutter.

Funktionsmåde for indsend knap for agenter med efterfølgende kort

Adaptive Cards gør det muligt at vælge deres indsendelsesknapper flere gange. Hvis en agent har fortløbende Adaptive Cards, og brugeren vælger en knap på et tidligere kort, kan brugeren opleve en uventet funktionsmåde.

Sådan forhindrer du, at afsendelseshandlingen på ét kort forstyrrer et andet kort:

• Isoler afsendelseshandlinger: Sørg for, at hvert adaptive kort har sit eget entydige id og handlingshandlere.

• Brug afsendelseshandlinger med entydige data: Når du definerer afsendelseshandlinger for dine kort, skal du inkludere entydige id'er eller datanyttedata, der hjælper med at skelne mellem kortene, når brugeren vælger en send-knap.

• Føj robust hændelseshåndteringslogik til din agent: Definer betingelser baseret på de karakteristiske id'er eller nyttedataelementer, der er knyttet til dine indsendelsesknapper.

• Fejlfinding og logføring: Føj detaljeret logføring til din agents hændelseshåndteringskode for at registrere rækkefølgen af handlinger og identificere, hvor utilsigtede indsendelser finder sted.

Brug et afsendelses-id i Action.Submit-data

Hvis din agent sender flere adaptive kort i en samtale (f.eks. efterfølgende kort, nye forsøg eller afbrydelser), kan brugerne vælge Send på et tidligere kort. For at hjælpe din agent eller brugerdefinerede klient med at skelne mellem det kort og den handling, et svar kom fra, skal du inkludere et entydigt id i datadata for hver afsendelseshandling og validere den, når svaret behandles.

Eksempel:

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

Web Chat UX-tip til at undgå forældede klik

Nogle chatklienter, herunder weboplevelser, kan lade tidligere kort være klikbare, når en bruger har sendt et sidste kort. Hvis du opretter en brugerdefineret webchatoplevelse, kan du overveje at deaktivere afsendelsesknapper efter det første klik eller opdatere den forrige kortmeddelelse for at reducere utilsigtede dublerede eller forældede indsendelser.

I følgende eksempel vises en af måderne til at deaktivere Action.Submit-knapper efter det første klik i en brugerdefineret webchatoplevelse:

1. Gengiv adaptive kort ved hjælp af SDK'en for adaptive kort eller en anden gengivelse, der opretter rigtige HTML-knapper eller -input.

2. Når du modtager en afsendelseshandling, skal du straks markere det aktuelle kort som sendt i brugergrænsefladen. Angiv f.eks. et submitted flag på meddelelsen.

3. Gengiv eller muter kortet DOM (Document Object Model), så alle interaktive elementer er deaktiveret, og send derefter nyttedataene til din bot eller tjeneste.

4. Hvis din chat understøtter flere kort pr. samtale, skal du gentage det samme mønster for hver kortmeddelelse for at forhindre forældede indsendelser fra ældre kort.

Eksempel:

// 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
        });
    };
}

Brug til Power Fx at gøre kortet dynamisk

Du kan bruge en Power Fx formel til at inkludere dynamiske oplysninger på dit kort ved at referere til variabler fra dit emne eller din agent.

1. Vælg de tre prikker (...) i noden, og vælg derefter Egenskaber.

2. I panelet Egenskaber for adaptiv kortnode skal du skifte til Formel. Hvis du vælger Formel , konverteres JSON-repræsentationen af dit kort automatisk til en Power Fx-formel.

   

   Start f.eks. med følgende JSON-konstant for et kort:

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

   Her er den resulterende Power Fx-formel, der bruger to variabler Topic.Title og Topic.Subtitle i stedet for den hårdt kodede tekst fra JSON-konstanten. (I dette eksempel antages det, at variablerne er defineret i dit emne.)

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