Ontwerp onderwerpen als mini-agenten die dubbele berichten vermijden

Note

Dit artikel beschrijft kenmerken en gedrag van onderwerpen met een conversatietrigger in het standaard harnas. Lees hoe je toegang krijgt tot standaardfuncties in Standaardagenten en agentstromen openen.

Dit artikel richt zich op ontwerpbest practices om dubbele berichten te voorkomen. Dubbele berichten komen voort uit contextgaten, dus ontwerp begint met begrijpen hoe context stroomt. Raadpleeg het diagram in Contextverdeling in de standaard-harness om te begrijpen hoe de orkestratielaag context deelt met elk component.

In het standaardharnas noemt de planner onderwerpen op dezelfde manier als gereedschappen en agenten. Het leest de beschrijving van elk onderwerp om te bepalen wanneer het onderwerp gebruikt wordt, genereert de invoer van het onderwerp uit de actieve context en van de gebruiker, en leest de uitvoer van het onderwerp wanneer het onderwerp is afgerond. Een onderwerp met een duidelijke beschrijving, goed gedefinieerde inputs en goed gedefinieerde outputs gedraagt zich als een mini-agent in het plan: de orkestratielaag verzamelt wat het topic nodig heeft, het topic voert zijn logica uit, het retourneert wat het heeft geproduceerd, en de orkestratielaag formateert en communiceert het antwoord aan de gebruikers.

Voor de gebruiker voelt een mini-agent conversationeel aan. De gebruiker kan natuurlijk praten terwijl het onderwerp de benodigde input verzamelt, vervolgvragen stellen en rijke antwoorden van de agent terugkrijgen.

Tip

In de standaardopzet houd je deterministische logica in het topic en laat je de communicatie met gebruikers over aan de orkestratielaag. Verzamel de waarden die het onderwerp als invoer nodig heeft voordat het draait, en geef na het uitvoeren terug wat het als output heeft geproduceerd.

Noem en beschrijf het onderwerp zodat de orkestratielaag ernaar kan routeren

De orkestratielaag gebruikt de onderwerpnaam en beschrijving om verzoeken naar het onderwerp te routeren. Schrijf beide voor de orkestratielaag. Geef het onderwerp een duidelijke, specifieke naam die beschrijft wat het doet.

Schrijf de beschrijving in twee delen. Leg eerst uit wanneer je het onderwerp moet gebruiken. Ten tweede, leg kort uit wat te doen op basis van de output van het onderwerp, inclusief hoe de orkestratielaag verzoeken moet routeren en resultaten moet afhandelen nadat het onderwerp is uitgevoerd. Beschrijf niet de interne schermen of stappen van het onderwerp.

Gebruik bijvoorbeeld de volgende beschrijving voor een onderwerp dat accountsaldoverzoeken beantwoordt en terugrapporteert met een answered output:

This topic handles account balance requests. 
If its answered output is true, the user has already received their response and it should not be answered again.

Verzamel invoer voordat het topic wordt uitgevoerd

Geef het onderwerp input voor elke waarde die het nodig heeft. De orkestratielaag kan die waarden verzamelen uit de actieve context en via een gesprek met de gebruiker, voordat het topic wordt uitgevoerd. Een invoer wordt geleverd aan een variabele die vervolgens door de logica van het onderwerp wordt gebruikt.

Gebruik de instellingen voor invoernaam, beschrijving, entiteit en validatie om de orkestratielaag te helpen een invoer nauwkeurig in te vullen:

  • De invoernaam vertelt de orkestratielaag wat er wordt verzameld, en wordt gebruikt om de vraag te vormen of de orkestratielaag de gebruiker om de waarde moet vragen. Noem het naar de waarde, niet naar het mechanisme. Geef bijvoorbeeld een invoer The user's request about... een naam in plaats van OData filter, zodat de orkestratielaag een gebruiker niet vraagt een query te schrijven.

  • De inputbeschrijving is een prompt naar de orkestratielaag, geen label voor de gebruiker. Gebruik dit om aan de orkestratielaag door te geven hoe de waarde moet worden geïnterpreteerd, beperkt of getransformeerd voordat de topic de waarde ontvangt. De orkestratielaag kan een invoer vullen uit het gesprek, uit een eerdere output, of uit gebruikersprofielgegevens. Het kan kiezen uit een set waarden, enkele beperkingen toepassen en queries schrijven op basis van schema-informatie.

    Invoerbeschrijvingen kunnen zelfs de orkestratielaag instrueren om een waarde in een specifiek formaat te bouwen. Bijvoorbeeld, een onderwerp dat een lijst filtert kan een invoer nemen waarvan de beschrijving de orkestratielaag vertelt hoe het filter moet worden opgebouwd op basis van het verzoek van de gebruiker, inclusief de beschikbare velden, de querysyntaxis en enkele voorbeelden.

  • Entiteiten stellen het toegestane type en bereik in voor een invoer, zodat alleen geldige waarden de logica van het onderwerp bereiken.

  • Geavanceerde validatie en conditionele logica, inclusief Power Fx, fungeren als deterministische controles. Ze kunnen voorkomen dat een invoerveld wordt ingevuld, of beletten dat het onderwerp handelt als niet aan een voorwaarde is voldaan.

Deterministische inputcontroles zijn net zo betrouwbaar als code, dus bedrijfsregels en compliance-beperkingen worden gerespecteerd, zelfs wanneer de rest van het plan wordt gegenereerd.

Behoud de logica en de randvoorwaarden in het onderwerp

Houd het deterministische werk van het onderwerp binnen het onderwerp: de stappen die het uitvoert, de berekeningen die het maakt en de regels die het handhaaft. De maker oefent controle uit en past cruciale bedrijfslogica toe die elke keer op dezelfde manier werkt, als een tool.

Geef resultaten terug als uitvoer, niet als berichten naar de gebruiker

Wanneer het onderwerp is afgerond, geef dan terug wat het als output heeft geproduceerd zodat de orkestratielaag het kan gebruiken en kan beslissen hoe te reageren. Geef de voorkeur aan deze aanpak boven de gebruiker rechtstreeks een bericht te laten sturen vanuit de topic. Een onderwerp dat naar de gebruiker schrijft terwijl de orkestratielaag ook antwoordt, is een veelvoorkomende bron van dubbele berichten—de orkestratielaag weet niet dat het onderwerp al heeft gereageerd.

Important

Een onderwerp dat geen output teruggeeft is een rode vlag. Als een onderwerp de gebruiker heeft beantwoord, een waarde heeft verzameld, of een kaart heeft getoond maar niets teruggeeft, kan de orkestratielaag niet zien wat er is gebeurd en kan het dezelfde vraag opnieuw beantwoorden. Dit gedrag is de meest voorkomende oorzaak van dubbele berichten van onderwerpen.

De volgende geteste outputs worden sterk aanbevolen als betrouwbare patronen voor context en communicatie. Ze gelden of het onderwerp direct antwoord geeft aan de gebruiker of alle informatie terugstuurt naar de orkestratielaag om te beantwoorden.

Uitvoer Description Hoe te gebruiken
answered Dat klopt als de gebruiker al een bevredigend antwoord op zijn verzoek binnen dit onderwerp heeft ontvangen. Stel dit voor het onderwerp in op true zodra het antwoord geeft of het resultaat toont. Zie de voorbeeldinstructie op topniveau die volgt, die ervoor zorgt dat de orkestratielaag dat deel van het verzoek als beantwoord behandelt en het niet herhaalt.
choiceReceived Klopt als de gebruiker zijn keuze binnen dit onderwerp al heeft gemaakt. Stel dit in op true zodra de gebruiker een keuze maakt, bijvoorbeeld door op een kaartknop te klikken. De orkestratielaag stelt de vraag niet opnieuw.
balanceValue De waarde die het topic heeft opgehaald en al aan de gebruiker heeft verstrekt. Stel het in op de belangrijke data die het onderwerp heeft opgehaald en noem de output van die data. De orkestratielaag gebruikt het opnieuw uit context in plaats van het opnieuw op te halen.
messageSummary Een korte samenvatting van wat de gebruiker al is getoond, om in context te blijven. Stel het in wanneer een bericht informatie bevat die het plan later nodig heeft. De orkestratielaag blijft zich bewust van wat de gebruiker is verteld en herhaalt of spreekt het niet tegen.

Alleen al de output is voldoende voor oudere modellen. Nieuwere modellen hebben ook een instructie op het hoogste niveau nodig die de orkestratielaag vertelt de output te controleren voordat er wordt geantwoord.

Deze voorbeeldinstructie op topniveau is een getest werkend voorbeeld. Bewerk en pas het aan indien nodig.

Wanneer een onderwerp of agent wordt genoemd, zoek dan altijd naar de 'beantwoorde' booleaanse output voordat je beslist wat je wilt antwoorden. Topics en agents hebben hun eigen communicatiekanaal met de gebruiker. Als 'beantwoord' waar is, ga er dan altijd van uit dat het verzoek correct is beantwoord met ten minste één van de uitvoervariabelen, en controleer welke op basis van de uitvoerbeschrijving. Geef geen ongemakkelijke bevestiging van inhoud waarop al is geantwoord. Geef alleen de onbeantwoorde uitkomsten en zet het gesprek natuurlijk voort met de volgende stap.

De term kanaal verwijst niet naar een integratiekanaal. Het is een prompting-apparaat dat de orkestratielaag vertelt dat de gebruiker het antwoord mogelijk al via een andere component heeft gezien. Afhankelijk van het model van de agent kan het effectiever zijn om een vergelijkbare instructie in de instructies van de agent te plaatsen. Lees meer in Design een robuuste top-level instructie om herhaalde berichten te voorkomen.

Als het topic iets moet tonen dat de orchestratielaag niet kan weergeven, zoals een Adaptive Card, laat het topic dit weergeven en retourneer output met de status 'beantwoord'.

Tip

Lees meer over dubbele berichten en antwoordtoestand-uitvoeren in Design best practices om dubbele berichten te voorkomen. Leer hoe context beweegt tussen de orkestratielaag en een onderwerp in Contextverdeling in de standaard harness.

Verzamel antwoorden wanneer een onderwerp nog gebruikersinput nodig heeft

Sommige thema's moeten een vraag stellen of een kaart tonen, bijvoorbeeld om een keuze met knoppen te laten maken. Deze ontwerpaanpak is geldig. Houd er rekening mee dat een open vraag of kaart moet worden opgelost wanneer de gebruiker van koers verandert voordat hij antwoordt.

Voordat je een vraagknoop toevoegt, overweeg of de waarde als invoer kan worden verzameld. Bij het bijhouden van een vraagknoop behandel dan het geval waarin de gebruiker iets anders vraagt terwijl de vraag nog openstaat. Lees meer in Een open vraag of kaart wordt opnieuw weergegeven nadat een ander verzoek is verwerkt.

Voorbeeld: Voorkom dat een Adaptieve Kaartkeuze opnieuw wordt gevraagd

Een onderwerp vraagt de gebruiker om een categorie te kiezen met een Adaptieve Kaart:

Welke categorie is jouw probleem?

[Facturering] [Technisch] [Account]

De orkestratielaag ontvangt de vragentekst via de gespreksgeschiedenis, maar niet het feit dat de kaart is getoond of een knop door de gebruiker is ingedrukt. Nadat de gebruiker een knop heeft geselecteerd, kan de orkestratielaag dezelfde vraag opnieuw in platte tekst stellen.

Ontwerp het onderwerp zo dat het zijn actie rapporteert om dit probleem te voorkomen:

Uitvoer Type Waarop je het moet instellen
answered Waar/onwaar Dat klopt als het onderwerp het antwoord of de prompt al aan de gebruiker heeft getoond.
choiceReceived Waar/onwaar Dat klopt als de gebruiker al een keuze heeft gemaakt.
selectedCategory Text Telkens wanneer een keuze wordt ontvangen, bevat deze output de categorie die de gebruiker heeft gekozen.

Voeg een instructie toe aan de onderwerpbeschrijving zodat de orkestratielaag weet wat een succesvolle run betekent. Vertrouw op de top-level instructie in Return-resultaten als output, niet op berichten naar de gebruiker, zodat een nieuwer model deze outputs controleert voordat het opnieuw vraagt.

Aanbevolen werkwijzen voor onderwerpen in het standaard testharnas

  • Geef het onderwerp een duidelijke, specifieke naam en een beschrijving waarin staat wanneer het gebruikt moet worden (en eventueel wat te doen nadat het draait).
  • Voeg een invoer toe voor elke waarde die het onderwerp nodig heeft, en schrijf de invoerbeschrijving als prompt naar de orkestratielaag.
  • Geef invoervelden een naam naar de waarde die ze bevatten, aangezien die naam als vraag dient wanneer de orkestratielaag die aan de gebruiker moet voorleggen.
  • Houd deterministische logica en vangrails, zoals entiteiten, validatie en Power Fx, binnen het onderwerp.
  • Spreek de gebruiker niet rechtstreeks aan in het onderwerp. Gebruik alleen een berichtnode, vraagknooppunt of Adaptieve Kaart wanneer dat nodig is.
  • Geef resultaten terug als output, inclusief een antwoordtoestand-output.
  • Last updated on