Conceber tópicos como miniagentes de modo a evitar mensagens duplicadas

Note

Este artigo descreve as funcionalidades e o comportamento dos tópicos com um acionador conversacional no standard harness. Aprenda a aceder a funcionalidades padrão nos agentes e fluxos de agentes padrão do Access.

Este artigo foca-se nas melhores práticas de design para evitar mensagens duplicadas. Mensagens duplicadas surgem de lacunas de contexto, por isso o design começa por compreender como o contexto flui. Consulte o diagrama em Distribuição de contexto na estrutura padrão para compreender como a camada de orquestração partilha contexto com cada componente.

Na infraestrutura padrão, o planeador invoca os tópicos da mesma forma que invoca as ferramentas e os agentes. Lê a descrição de cada tema para decidir quando o utilizar, gera as entradas do tema a partir do seu contexto ativo e do utilizador, e lê as saídas do tema quando este termina. Um tópico com uma descrição clara, entradas bem definidas e saídas bem definidas comporta-se como um mini-agente no plano: a camada de orquestração recolhe o que o tema precisa, o tópico executa a sua lógica, devolve o que produziu, e a camada de orquestração formata e comunica a resposta ao utilizador.

Para o utilizador, um mini-agente parece conversacional. O utilizador pode falar naturalmente enquanto o tema recolhe os inputs necessários, fazer perguntas de seguimento e obter respostas enriquecedoras do agente.

Sugestão

No harness padrão, mantém-se a lógica determinística dentro do tópico e deixa a comunicação com o utilizador para a camada de orquestração. Recolha os valores que o tema precisa como entradas antes de ser executado e devolve o que produziu como saídas depois de executar.

Nomeie e descreva o tema para que a camada de orquestração possa encaminhá-lo

A camada de orquestração usa o nome e a descrição do tópico para encaminhar os pedidos para o tópico. Escreve ambos para a camada de orquestração. Dê ao tema um nome claro e específico que descreva o que faz.

Escreva a descrição em duas partes. Primeiro, explique quando usar o tema. Segundo, explique brevemente o que fazer com base nos resultados do tópico, incluindo como a camada de orquestração deve encaminhar pedidos e tratar dos resultados após a execução do tópico. Não descrevas os ecrãs internos nem os passos do tópico.

Por exemplo, use a seguinte descrição para um tópico que responda a pedidos de saldo da conta e devolva uma saída 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.

Recolha contributos antes de o tema começar

Dê ao tema um input para cada valor que necessita. A camada de orquestração pode recolher esses valores do seu contexto ativo e do utilizador de forma conversacional, antes de o tópico ser executado. Um valor de entrada é fornecido a uma variável, que a lógica do tópico utiliza depois.

Use o nome da entrada, descrição, entidade e definições de validação para ajudar a camada de orquestração a preencher uma entrada com precisão:

  • O nome da entrada indica à camada de orquestração o que está a ser recolhido, e é usado para formar a questão se a camada de orquestração tem de pedir ao utilizador o valor. Nomeie-o pelo valor, não pelo mecanismo. Por exemplo, nomeie uma entrada The user's request about... em vez de OData filter, para que a camada de orquestração não peça ao utilizador que escreva uma consulta.

  • A descrição de entrada é um prompt para a camada de orquestração, não um rótulo para o utilizador. Use-o para dizer à camada de orquestração como interpretar, restringir ou transformar o valor antes de o tópico o receber. A camada de orquestração pode preencher uma entrada com base na conversa, numa saída anterior ou em dados do perfil do utilizador. Pode escolher entre um conjunto de valores, aplicar algumas restrições e escrever consultas com base na informação do esquema.

    As descrições de entrada podem até instruir a camada de orquestração a construir um valor num formato específico. Por exemplo, um tópico que filtra uma lista pode receber uma entrada cuja descrição indica à camada de orquestração como construir o filtro a partir do pedido do utilizador, incluindo os campos disponíveis, a sintaxe da consulta e alguns exemplos.

  • As entidades definem o tipo e o intervalo permitidos para uma entrada, pelo que apenas valores válidos chegam à lógica do tópico.

  • A validação avançada e a lógica condicional, incluindo Power Fx, atuam como verificações determinísticas. Podem impedir que um campo de entrada seja preenchido, ou impedir que o tópico aja, quando não se verifica uma condição.

As verificações determinísticas de entrada são tão fiáveis como o código, pelo que as regras de negócio e as restrições de conformidade são respeitadas mesmo quando o resto do plano é gerado.

Manter a lógica e as restrições no tópico

Mantenha o trabalho determinístico do tema dentro do tema: os passos que executa, os cálculos que faz e as regras que aplica. O criador exerce controlo e aplica uma lógica de negócio crucial que funciona sempre da mesma forma, como uma ferramenta.

Devolve os resultados como saídas, não como mensagens ao utilizador

Quando o tópico terminar, devolve os resultados produzidos para que a camada de orquestração os possa usar e decidir como responder. Prefira esta abordagem em vez de fazer com que o tópico envie uma mensagem diretamente ao utilizador. Um tópico que envia mensagens ao utilizador enquanto a camada de orquestração também responde é uma fonte comum de mensagens duplicadas — a camada de orquestração não sabe que o tópico já respondeu.

Importante

Um tópico que não devolve saídas é um sinal de alerta. Se um tópico respondeu ao utilizador, recolheu um valor ou mostrou uma carta mas não retorna nada, a camada de orquestração não consegue ver o que aconteceu e pode responder novamente ao mesmo pedido. Este comportamento é a causa mais comum de mensagens duplicadas em tópicos.

Os seguintes resultados testados são fortemente recomendados como padrões fiáveis para contexto e comunicação. Aplicam-se quer o tópico responda diretamente ao utilizador, quer devolva toda a informação à camada de orquestração para que esta responda.

Output Description Modo de utilização
answered Verdade se o utilizador já tiver recebido uma resposta satisfatória ao seu pedido neste tópico. Define-o como verdadeiro no tópico assim que responder ou mostrar o resultado. Consulte o exemplo de instrução de topo que se segue, que garante que a camada de orquestração trata essa parte do pedido como respondida e não a repete.
choiceReceived É verdade se o utilizador já fez a sua escolha neste tópico. Defina-o como verdadeiro assim que o utilizador faz uma seleção, como selecionar um botão de carta. A camada de orquestração não volta a fazer a pergunta.
balanceValue O valor que o tema recuperou e já forneceu ao utilizador. Defina-o como os dados relevantes que o tópico recuperou e dê um nome à saída desses dados. A camada de orquestração reutiliza-a do contexto em vez de a buscar novamente.
messageSummary Um breve resumo do que já foi mostrado ao utilizador, para manter em contexto. Defina-o quando uma mensagem contiver informação de que o plano necessitará mais tarde. A camada de orquestração mantém-se consciente do que o utilizador foi dito e não o repete nem contradiz.

As saídas por si só são adequadas para modelos mais antigos. Modelos mais recentes também precisam de uma instrução de topo que diga à camada de orquestração para verificar as saídas antes de responder.

Este exemplo de instrução de topo é um exemplo testado e funcional. Edite e personalize conforme necessário.

Sempre que qualquer tópico ou agente for chamado, procure sempre a saída booleana 'respondida' antes de decidir o que responder. Os tópicos e agentes têm o seu próprio canal de comunicação com o utilizador. Se 'respondido' for verdadeiro, assuma sempre que o pedido foi respondido corretamente usando pelo menos uma das variáveis de saída e verifique quais com base na descrição de saída. Não faça um comentário de confirmação desajeitado sobre o conteúdo da resposta. Fornece apenas as respostas não respondidas e continua a conversa naturalmente com o passo seguinte.

O termo canal não se refere a um canal de integração. É um dispositivo de aviso que diz à camada de orquestração que o utilizador pode já ter visto a resposta através de outro componente. Dependendo do modelo do agente, pode ser mais eficaz colocar uma instrução semelhante nas instruções do próprio agente. Saiba mais em Desenhar uma instrução robusta de topo para evitar mensagens repetidas.

Se o tópico tiver de mostrar algo que a camada de orquestração não consegue reproduzir, como um Adaptive Card, deixe o tópico apresentá-lo e devolva um resultado com o estado «respondido».

Sugestão

Saiba mais sobre mensagens duplicadas e saídas no estado «respondido» em As melhores práticas de conceção para evitar mensagens duplicadas. Saiba como o contexto circula entre a camada de orquestração e um tópico em Distribuição de contexto no harness padrão.

Recolha respostas quando um tema ainda precisa de intervenção do utilizador

Alguns tópicos têm de fazer uma pergunta ou mostrar um cartão, por exemplo, para recolher uma opção com botões. Esta abordagem de design é válida. Tenha em mente que uma pergunta ou carta em aberto precisa de ser resolvida quando o utilizador muda de rumo antes de responder.

Antes de adicionar um nó de pergunta, considere se o valor pode ser recolhido como um dado de entrada. Ao manter um nó de pergunta, trate do caso em que o utilizador pede outra coisa enquanto a pergunta ainda está em aberto. Saiba mais em Uma pergunta aberta ou devoluções de cartões após um pedido diferente ter sido tratado.

Exemplo: Evitar que uma seleção de Carta Adaptativa seja novamente solicitada

Um tópico pede ao utilizador que escolha uma categoria com um Cartão Adaptativo:

Qual é a categoria do seu problema?

[Faturação] [Técnico] [Conta]

A camada de orquestração recebe o texto da pergunta através do histórico da conversa, mas não o facto de o cartão ter sido mostrado ou de um botão ter sido selecionado pelo utilizador. Depois de o utilizador selecionar um botão, a camada de orquestração pode voltar a fazer a mesma pergunta em texto simples.

Configure o tópico para comunicar a sua ação e evitar este problema:

Output Tipo Para o que definir
answered Verdadeiro/Falso É verdade quando o tópico já mostrou a resposta ou o prompt ao utilizador.
choiceReceived Verdadeiro/Falso Verdadeiro quando o utilizador já tiver feito uma seleção.
selectedCategory Texto Sempre que uma escolha é recebida, esta saída contém a categoria escolhida pelo utilizador.

Adicione uma instrução à descrição do tópico para que a camada de orquestração saiba o que significa uma execução bem-sucedida. Baseie-se na instrução de nível superior em Devolva os resultados como saídas, não como mensagens para o utilizador, para que um modelo mais recente verifique essas saídas antes de voltar a pedir.

Boas práticas para os tópicos do arnês padrão

  • Dê ao tema um nome claro e específico e uma descrição que diga quando o usar (e, opcionalmente, o que fazer depois de ser publicado).
  • Adicione uma entrada para cada valor que o tema precise e escreva a descrição da entrada como um prompt para a camada de orquestração.
  • Dê nomes aos campos de entrada de acordo com o valor que contêm, uma vez que o nome servirá de pergunta caso a camada de orquestração tenha de colocar uma pergunta ao utilizador.
  • Mantenha a lógica determinística e os limites de proteção, como entidades, validação e Power Fx, dentro do tema.
  • Evite enviar mensagens diretamente ao utilizador dentro do tópico. Use um nó de mensagem, um nó de pergunta ou um cartão adaptativo apenas quando necessário.
  • Devolve os resultados como saídas, incluindo uma saída em estado respondido.
  • Last updated on