Projete os tópicos como miniagentes para evitar mensagens duplicadas

Note

Este artigo descreve os recursos e o comportamento de tópicos que têm um gatilho conversacional no standard harness. Aprenda como acessar recursos padrão em agentes e fluxos de agentes padrão do Access.

Este artigo foca nas melhores práticas de design para evitar mensagens duplicadas. Mensagens duplicadas vêm de lacunas de contexto, então o design começa com entender como o contexto flui. Consulte o diagrama em Distribuição de contexto na estrutura padrão para entender como a camada de orquestração compartilha o contexto com cada componente.

Na estrutura padrão, o planejador invoca os tópicos da mesma forma que invoca ferramentas e agentes. Ele lê a descrição de cada tema para decidir quando usá-lo, gera as entradas do tema a partir de seu contexto ativo e do usuário, e lê as saídas do tema quando o tema termina. Um tópico com uma descrição clara, entradas bem definidas e saídas bem definidas se comporta como um mini-agente no plano: a camada de orquestração reúne o que o tópico precisa, o tópico executa sua lógica, retorna o que produziu, e a camada de orquestração formata e comunica a resposta ao usuário.

Para o usuário, um mini-agente tem um tom conversacional. O usuário pode falar naturalmente enquanto o tema coleta as entradas necessárias, fazer perguntas de acompanhamento e receber respostas detalhadas do agente.

Tip

No arcabouço padrão, mantenha a lógica determinística no tópico e deixe a comunicação com o usuário para a camada de orquestração. Colete os valores que o tema precisa como entradas antes de rodar e retorne o que ele produziu como saídas após a execução.

Nomeie e descreva o tema para que a camada de orquestração possa rotear até ele

A camada de orquestração usa o nome e a descrição do tópico para direcionar solicitações ao tópico. Escreva ambos para a camada de orquestração. Dê ao tema um nome claro e específico que descreva o que ele 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 rotear as requisições e lidar com os resultados após a execução do tópico. Não descreva as telas internas ou etapas do tema.

Por exemplo, use a seguinte descrição para um tópico que responde a consultas de saldo da conta e retorna uma answered saída:

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.

Colete informações antes que o tópico comece

Forneça ao tópico um valor de entrada para cada valor de que ele precisa. A camada de orquestração pode coletar esses valores de seu contexto ativo e do próprio usuário, de maneira conversacional, antes de o tópico ser executado. Uma entrada é entregue em uma variável que a lógica do tópico então utiliza.

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

  • O nome da entrada informa à camada de orquestração o que está sendo coletado, e é usado para formar a pergunta se a camada de orquestração precisa pedir ao usuário o valor. Nomeie 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 usuário que escreva uma consulta.

  • A descrição da entrada é um prompt para a camada de orquestração, não um rótulo para o usuário. Use-o para dizer à camada de orquestração como interpretar, restringir ou transformar o valor antes que o tópico o receba. A camada de orquestração pode preencher um campo de entrada a partir da conversa, de uma saída anterior ou de dados do perfil do usuário. Ele pode escolher entre um conjunto de valores, aplicar algumas restrições e escrever consultas baseadas nas informações do esquema.

    Descrições de entrada podem até instruir a camada de orquestração a construir um valor em um 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 usuário, incluindo os campos disponíveis, a sintaxe da consulta e alguns exemplos.

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

  • Validação avançada e lógica condicional, incluindo Power Fx, atuam como verificações determinísticas. Eles podem impedir que uma entrada seja preenchida, ou impedir que o tema atue, quando uma condição não é atendida.

Verificações determinísticas de entrada são tão confiáveis quanto código, então regras de negócios e restrições de conformidade são respeitadas mesmo quando o restante do plano é gerado.

Mantenha a lógica e os limites no tema

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

Devolva os resultados como saídas, não mensagens ao usuário

Quando o tema terminar, retorne o que ele produziu como saídas para que a camada de orquestração possa usar e decidir como responder. Prefira esta abordagem em vez de fazer com que o tópico envie mensagens diretamente ao usuário. Um tópico que envia mensagens ao usuário enquanto a camada de orquestração também responde ao usuário é uma causa 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 retorna saídas é um sinal de alerta. Se um tópico respondeu ao usuário, coletou um valor ou mostrou um cartão mas não retorna nada, a camada de orquestração não consegue ver o que aconteceu e pode responder ao mesmo pedido novamente. Esse comportamento é a causa mais comum de mensagens duplicadas provenientes de tópicos.

Os seguintes resultados testados são fortemente recomendados como padrões confiáveis para contexto e comunicação. Eles se aplicam tanto quando o tópico responde diretamente ao usuário quanto quando retorna todas as informações para a camada de orquestração para que ela responda.

Saída Description Como usar
answered Verdade se o usuário já recebeu uma resposta satisfatória ao seu pedido neste tópico. Defina como verdadeiro no tópico assim que responder ou mostrar o resultado. Consulte a instrução de nível superior que segue a seguir, que garante que a camada de orquestração trate essa parte da solicitação como respondida e não a repita.
choiceReceived Verdadeiro se o usuário já tiver feito uma seleção dentro deste tópico. Defina como verdadeiro assim que o usuário fizer uma seleção, por exemplo, ao selecionar um botão de cartão. A camada de orquestração não faz a pergunta novamente.
balanceValue O valor que o tema recuperou e já forneceu ao usuário. Defina-o como os dados importantes recuperados pelo tópico e dê um nome à saída desses dados. A camada de orquestração o reutiliza do contexto em vez de recuperá-lo novamente.
messageSummary Um breve resumo do que já foi mostrado ao usuário, para manter em contexto. Defina quando uma mensagem traz informações que o plano precisa depois. A camada de orquestração mantém o que o usuário foi informado e não repete nem contradiz.

As saídas, por si só, são adequadas para modelos mais antigos. Modelos mais novos também precisam de uma instrução de nível superior que informe a camada de orquestração para verificar as saídas antes de responder.

Este exemplo de instrução de nível superior é um exemplo testado e funcional. Edite e personalize conforme necessário.

Sempre que qualquer tópico ou agente for invocado, procure sempre a saída booleana 'answered' antes de decidir qual resposta dar. Tópicos e agentes têm seu próprio canal de comunicação com o usuário. Se 'respondido' for verdadeiro, sempre assuma que a solicitação foi respondida adequadamente usando pelo menos uma das variáveis de saída e verifique quais delas com base na descrição de saída. Não faça um reconhecimento estranho do conteúdo respondido. Apenas forneça as respostas não respondidas e continue a conversa naturalmente com o próximo passo.

O termo canal não se refere a um canal de integração. É um mecanismo de sinalização que informa à camada de orquestração que o usuário talvez já tenha visto a resposta por meio 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 Projetar uma instrução robusta de alto nível para evitar mensagens repetidas.

Se o tópico precisar mostrar algo que a camada de orquestração não consegue reproduzir, como um Cartão Adaptável, deixe que o tópico o exiba e retorne uma saída com status de respondido.

Tip

Saiba mais sobre mensagens duplicadas e saídas no estado “respondido” em Práticas recomendadas de design para evitar mensagens duplicadas. Aprenda como o contexto é transferido entre a camada de orquestração e um tópico em Distribuição de contexto no harness padrão.

Colete respostas quando um tema ainda precisa de entrada do usuário

Alguns tópicos precisam fazer uma pergunta ou mostrar um cartão, por exemplo, para coletar uma opção com botões. Essa abordagem de design é válida. Lembre-se de que uma pergunta ou carta aberta precisa ser resolvida quando o usuário muda de rumo antes de responder.

Antes de adicionar um nó de pergunta, considere se o valor pode ser coletado por meio de uma entrada. Ao manter um nó de pergunta, considere o caso em que o usuário solicita outra coisa enquanto a pergunta ainda está em aberto. Saiba mais em Uma pergunta aberta ou devoluções de cartão após uma solicitação diferente ter sido tratada.

Exemplo: Evitar que a seleção de um Cartão Adaptável seja solicitada novamente

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

Qual categoria é o seu problema?

[Faturamento] [Técnico] [Conta]

A camada de orquestração recebe o texto da pergunta pelo histórico da conversa, mas não o fato de que o cartão foi mostrado ou que um botão foi selecionado pelo usuário. Depois que o usuário seleciona um botão, a camada de orquestração pode refazer a mesma pergunta em texto simples.

Projete o tema para relatar sua ação e evitar esse problema:

Saída Tipo Para qual configuração definir
answered Verdadeiro/Falso Verdade quando o tópico já mostrou a resposta ou o prompt para o usuário.
choiceReceived Verdadeiro/Falso Verdadeiro quando o usuário já fez uma seleção.
selectedCategory Texto Sempre que uma escolha é recebida, essa saída contém a categoria escolhida pelo usuário.

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. Confie na instrução de nível superior nos resultados do retorno como saídas, não mensagens para o usuário , para que um modelo mais novo verifique essas saídas antes de pedir novamente.

Melhores 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 usá-lo (e, opcionalmente, o que fazer depois que ele rodar).
  • 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.
  • Nomeie as entradas de acordo com o valor que armazenam, já que o nome servirá como pergunta caso a camada de orquestração precise perguntar ao usuário.
  • Mantenha lógica determinística e proteções, como entidades, validação e Power Fx, dentro do tema.
  • Evite enviar mensagens diretamente ao usuário dentro do tópico. Use um nó de mensagem, um nó de pergunta ou um Cartão Adaptável apenas quando necessário.
  • Retorna os resultados como saídas, incluindo uma saída em estado respondido.
  • Last updated on