Progetta gli argomenti come mini-agenti che evitano messaggi duplicati

Note

Questo articolo descrive le caratteristiche e il comportamento degli argomenti con attivatore conversazionale nel harness standard. Impara come accedere alle funzionalità standard negli agenti standard Access e nei flussi degli agenti.

Questo articolo si concentra sulle migliori pratiche di progettazione per evitare messaggi duplicati. I messaggi duplicati derivano da lacune contestuali, quindi il design parte dalla comprensione di come scorre il contesto. Consulta il diagramma in Distribuzione del contesto nell'harness standard per capire come il livello di orchestrazione condivide il contesto con ogni componente.

Nell'imbracatura standard, il pianificatore chiama gli argomenti allo stesso modo in cui chiama strumenti e agenti. Legge la descrizione di ogni argomento per decidere quando usarlo, genera gli input dell'argomento dal suo contesto attivo e dall'utente, e legge gli output dell'argomento quando l'argomento termina. Un argomento con una descrizione chiara, input ben definiti e output ben definiti si comporta come un mini-agente nel piano: il livello di orchestrazione raccoglie ciò di cui l'argomento ha bisogno, l'argomento esegue la sua logica, restituisce ciò che ha prodotto, e il livello di orchestrazione formata e comunica la risposta all'utente.

Per l'utente, un mini-agente sembra conversazionale. L'utente può parlare in modo naturale mentre l'argomento raccoglie gli input necessari, porre domande di approfondimento e ricevere risposte ricche dall'agente.

Tip

Nell'imbracatura standard, mantenere la logica deterministica all'interno dell'argomento e lasciare la comunicazione con l'utente al livello di orchestrazione. Raccogli i valori di cui l'argomento ha bisogno come input prima di eseguirlo, e restituisci ciò che ha prodotto come output dopo l'esecuzione.

Assegna un nome all'argomento e descrivilo in modo che il livello di orchestrazione possa instradare verso di esso

Il livello di orchestrazione utilizza il nome e la descrizione dell'argomento per instradare le richieste verso l'argomento. Scrivi entrambi per il livello di orchestrazione. Dai al tema un nome chiaro e specifico che descriva ciò che fa.

Scrivi la descrizione in due parti. Prima di tutto, spiega quando usare l'argomento. In secondo luogo, spiega brevemente cosa fare in base agli output dell'argomento, incluso come il livello di orchestrazione dovrebbe instradare le richieste e gestire i risultati dopo l'esecuzione dell'argomento. Non descrivere gli schermi interni o i passaggi dell'argomento.

Ad esempio, usa la seguente descrizione per un argomento che risponde alle richieste relative al saldo del conto e restituisce un output answered:

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.

Raccogli input prima che l'argomento sia iniziato

Dai all'argomento un input per ogni valore di cui ha bisogno. Il livello di orchestrazione può raccogliere quei valori dal suo contesto attivo, e dall'utente in modalità conversazionale, prima che l'argomento venga eseguito. Un input viene inviato in una variabile che la logica dell'argomento utilizza poi.

Usa il nome dell'input, la descrizione, l'entità e le impostazioni di validazione per aiutare il livello di orchestrazione a riempire accuratamente un input:

  • Il nome dell'input indica al livello di orchestrazione cosa viene raccolto, e viene usato per formulare la domanda se il livello di orchestrazione deve chiedere all'utente il valore. Chiamalo per il valore, non per il meccanismo. Ad esempio, nomina un input The user's request about... invece di OData filter, così il livello di orchestrazione non chiede all'utente di scrivere una query.

  • La descrizione dell'input è un prompt per il livello di orchestrazione, non un'etichetta per l'utente. Usalo per indicare al livello di orchestrazione come interpretare, limitare o trasformare il valore prima che il topic la riceva. Il livello di orchestrazione può riempire un input dalla conversazione, da un output precedente o dai dati del profilo utente. Può scegliere tra un insieme di valori, applicare alcuni vincoli e scrivere query basate sulle informazioni dello schema.

    Le descrizioni di input possono persino istruire il livello di orchestrazione a costruire un valore in un formato specifico. Ad esempio, un argomento che filtra una lista può ricevere un input la cui descrizione indica al livello di orchestrazione come costruire il filtro a partire dalla richiesta dell'utente, includendo i campi disponibili, la sintassi della query e alcuni esempi.

  • Le entità impostano il tipo e l'intervallo consentiti per un input, quindi solo valori validi raggiungono la logica dell'argomento.

  • La validazione avanzata e la logica condizionale, inclusa Power Fx, agiscono come controlli deterministici. Possono impedire che un input venga inserito o che il topic entri in azione se una condizione non è soddisfatta.

I controlli deterministici di input sono affidabili quanto il codice, quindi le regole aziendali e i vincoli di conformità sono rispettati anche quando viene generato il resto del piano.

Mantieni la logica e i vincoli nell'argomento

Mantieni l'elaborazione deterministica del topic all'interno del topic stesso: i passaggi che esegue, i calcoli che effettua e le regole che applica. Il creatore esercita il controllo e applica una logica aziendale cruciale che funziona sempre allo stesso modo, come uno strumento.

Restituisci i risultati come output, non messaggi all'utente

Quando l'argomento termina, restituisci ciò che ha prodotto come output così che il livello di orchestrazione possa usarlo e decidere come rispondere. Preferire questo approccio piuttosto che fare in modo che il topic invii un messaggio direttamente all'utente. Un topic che invia un messaggio all'utente mentre anche il layer di orchestrazione risponde è una causa comune di messaggi duplicati: il layer di orchestrazione non sa che il topic ha già risposto.

Importante

Un argomento che non restituisce output è un campanello d'allarme. Se un argomento ha risposto all'utente, raccolto un valore o mostrato una carta ma non restituisce nulla, il livello di orchestrazione non può vedere cosa è successo e potrebbe rispondere di nuovo alla stessa richiesta. Questo comportamento è la causa più comune di messaggi duplicati provenienti dai topic.

I seguenti risultati testati sono fortemente raccomandati come modelli affidabili per contesto e comunicazione. Si applicano sia che l'argomento risponda direttamente all'utente sia che restituisca tutte le informazioni al livello di orchestrazione per rispondere.

Risultato Description Come usare
answered Vero se l'utente ha già ricevuto una risposta soddisfacente alla sua richiesta all'interno di questo argomento. Impostalo su True nell'argomento una volta ottenuta una risposta o visualizzato il risultato. Fai riferimento all'esempio di istruzione di livello superiore che segue, che garantisce che il livello di orchestrazione tratti quella parte della richiesta come risposta e non la ripeta.
choiceReceived È vero se l'utente ha già fatto la sua scelta in questo argomento. Impostalo su true una volta che l'utente effettua una selezione, ad esempio selezionando un pulsante di carta. Il livello di orchestrazione non ripropone la domanda.
balanceValue Il valore che il topic ha recuperato e già fornito all’utente. Impostalo sui dati rilevanti recuperati dall'argomento e assegna un nome all'output di tali dati. Il livello di orchestrazione lo riutilizza dal contesto invece di recuperarlo di nuovo.
messageSummary Un breve riassunto di ciò che era già stato mostrato all'utente, per tenerlo contestualizzato. Impostalo quando un messaggio contiene informazioni di cui il piano ha bisogno in seguito. Il livello di orchestrazione rimane consapevole di ciò che è stato detto all'utente e non lo ripete né lo contraddice.

Gli output da soli sono sufficienti per i modelli più vecchi. I modelli più recenti richiedono anche un'istruzione di alto livello che dica al livello di orchestrazione di controllare gli output prima di rispondere.

Questo esempio di istruzione di livello superiore è un esempio operativo testato. Modifica e personalizza secondo necessità.

Ogni volta che viene invocato un topic o un agente, cerca sempre l'output booleano 'answered' prima di decidere cosa rispondere. Gli argomenti e gli agenti hanno un proprio canale di comunicazione con l'utente. Se 'answered' è vero, si assume sempre che la richiesta sia stata risposta correttamente usando almeno una delle variabili di output e verifica quali basandosi sulla descrizione di output. Non dare un riconoscimento imbarazzante del contenuto a cui è stato risposto. Fornisci solo le uscite non risposte e continua la conversazione in modo naturale con il passo successivo.

Il termine canale non si riferisce a un canale di integrazione. È un dispositivo di prompting che comunica al livello di orchestrazione che l'utente potrebbe aver già visto la risposta tramite un altro componente. A seconda del modello dell'agente, può essere più efficace inserire un'istruzione simile nelle istruzioni dell'agente stesso. Scopri di più in Progettare un'istruzione di alto livello robusta per evitare messaggi ripetuti.

Se l'argomento deve mostrare qualcosa che il livello di orchestrazione non è in grado di riprodurre, ad esempio un'Adaptive Card, consenti all'argomento di mostrarlo e di restituire un output con stato answered.

Tip

Scopri di più sui messaggi duplicati e sugli output a stato risposto nelle migliori pratiche di progettazione per evitare messaggi duplicati. Scopri come il contesto si sposta tra il livello di orchestrazione e un argomento nella distribuzione del contesto nell'imbracatura standard.

Raccogli le risposte quando un argomento necessita ancora di input da parte dell'utente

Alcuni argomenti devono porre una domanda o mostrare una carta, ad esempio, per collezionare una scelta con pulsanti. Questo approccio progettuale è valido. Tieni presente che una domanda aperta o una scheda deve essere risolta quando l'utente cambia rotta prima di rispondere.

Prima di aggiungere un nodo interrogativo, considera se il valore possa essere raccolto come input invece. Quando si mantiene un nodo di domanda, gestisci il caso in cui l'utente chiede qualcos'altro mentre la domanda è ancora aperta. Scopri di più in Una domanda aperta o resi di carta dopo che una richiesta diversa è stata gestita.

Esempio: Impedire che venga nuovamente richiesta la selezione di una scheda Adaptive Card

Un argomento chiede all'utente di scegliere una categoria con una Carta Adattiva:

Quale categoria è il tuo problema?

[Fatturazione] [Tecnico] [Conto]

Il livello di orchestrazione riceve il testo della domanda tramite la cronologia della conversazione, ma non il fatto che la carta sia stata mostrata o che l'utente abbia selezionato un pulsante. Dopo che l'utente seleziona un pulsante, il livello di orchestrazione può riproporre la stessa domanda in testo semplice.

Progetta l'argomento in modo che segnali la propria azione per evitare questo problema:

Risultato Tipo A cosa impostarlo
answered Vero/Falso Vero quando l'argomento ha già mostrato la risposta o il prompt all'utente.
choiceReceived Vero/Falso Vero quando l'utente ha già effettuato una selezione.
selectedCategory Text Ogni volta che viene ricevuta una scelta, questo output contiene la categoria scelta dall'utente.

Aggiungi un'istruzione alla descrizione dell'argomento così il livello di orchestrazione sa cosa significa una run di successo. Affidati all'istruzione di livello superiore in Restituisci i risultati come output, non come messaggi per l'utente, in modo che un modello più recente controlli questi output prima di chiedere di nuovo.

Migliori pratiche per gli argomenti rientrati nell'imbracatura standard

  • Dai al tema un nome chiaro e specifico e una descrizione che dica quando usarlo (e opzionalmente cosa fare dopo l'esecuzione).
  • Aggiungi un input per ogni valore di cui l'argomento ha bisogno e scrivi la descrizione dell'input come prompt al livello di orchestrazione.
  • Assegna agli input un nome in base al valore che contengono, poiché il nome verrà usato come domanda se il livello di orchestrazione deve chiederlo all'utente.
  • Tieni la logica deterministica e i guardrail, come entità, validazione e Power Fx, all'interno dell'argomento.
  • Evita di rivolgerti direttamente all'utente all'interno dell'argomento. Usa un nodo messaggio, un nodo di domanda o una scheda adattiva solo quando necessario.
  • Restituire i risultati come valori di output, incluso un output con stato di risposta.
  • Last updated on