GOgenier - Boas práticas na construção de agentes

Modificado em Sex, 20 Mar na (o) 2:59 PM

Este documento apresenta as boas práticas na construção de agentes no GOgenier, abordando a estrutura correta dos fluxos, a separação entre passos e regras e as diretrizes para garantir clareza, eficiência e facilidade de manutenção.

Os tópicos abordados são:

1. Contexto
2. Passos e Regras

2.1. Passos
2.2. Regras

3. Estrutura do Fluxo
4. Exemplos de aplicação

4.1. Exemplo adequado
4.2. Exemplo inadequado

5. Revisão do Agente

1. Contexto

A construção de agentes no GOgenier deve seguir uma estrutura clara e previsível, pois o agente executa exatamente as instruções definidas no fluxo, sem interpretar intenções implícitas.

Para garantir consistência, facilidade de manutenção e melhor desempenho, é essencial separar corretamente o que é fluxo principal do que são condições e exceções.

2. Passos e Regras

Os agentes são estruturados a partir de dois elementos fundamentais: Passos e Regras.

2.1. Passos

Os passos representam o fluxo principal do atendimento. Eles definem o que o agente deve fazer e em qual ordem, sendo sempre executados do início ao fim do fluxo.

Cada passo deve conter apenas uma ação clara, sem ambiguidade e sem qualquer tipo de condição. Como fazem parte da base do fluxo, são responsáveis por garantir previsibilidade na execução.

Na prática, os passos costumam envolver ações como iniciar o atendimento, coletar informações, consultar dados e retornar uma resposta ao cliente.

Os passos são sempre executados ao longo do fluxo, independentemente do contexto da conversa, funcionando como o esqueleto que sustenta toda a execução do agente.

2.2. Regras

As regras são responsáveis por tratar variações do fluxo, como exceções, erros ou cenários específicos.

Diferente dos passos, elas não são executadas sempre, apenas quando uma condição é atendida. Por isso, são escritas de forma condicional, iniciando com termos como “Se”, “Caso” ou “Quando”.

Sempre que uma instrução começar com “Se”, “Caso” ou “Quando”, ela deve ser tratada como regra e não como passo, evitando a mistura entre execução e decisão.

As regras permitem que o agente lide com situações fora do fluxo padrão sem comprometer a simplicidade da estrutura principal.

3. Estrutura do Fluxo

Um fluxo bem estruturado segue uma sequência lógica de execução.
Exemplo:

O agente inicia o atendimento

Identifica a necessidade do cliente

Coleta as informações necessárias

Executa a ação principal

Finaliza com um retorno claro

As regras ficam separadas do fluxo principal e concentram todas as decisões condicionais, como validações, erros e desvios de comportamento.

Essa organização mantém o fluxo limpo e facilita tanto a leitura quanto a manutenção.

A qualidade do agente depende diretamente da forma como os passos e regras são definidos dentro dessa estrutura.

Nos passos, é importante manter uma única ação por etapa, com linguagem objetiva e sem qualquer tipo de condicional. Já nas regras, a condição deve estar explícita, acompanhada da ação correspondente, evitando duplicidade ou ambiguidade.

Outro ponto importante é não incluir exceções, validações ou tratamentos de erro dentro dos passos. Esses cenários devem sempre ser tratados como regras.

Quando condicionais são incluídas nos passos, o fluxo passa a executar verificações desnecessárias, aumenta o número de etapas e se torna mais difícil de manter.

4. Exemplos de aplicação

4.1. Exemplo adequado

Em um agente de atendimento clínico, o fluxo pode seguir de forma simples:

Nos passos:

O agente inicia o atendimento com uma saudação
Solicita o nome do cliente e o tipo de consulta ou exame desejado e consulta a base de conhecimento para identificar o serviço
Em seguida, pergunta a forma de atendimento
Por fim, gera um resumo das informações e direciona o atendimento.

Nas regras:

Caso a especialidade não exista, o agente informa a indisponibilidade do serviço.
Se o convênio não for atendido, o agente comunica a limitação e direciona o atendimento.
Se não conseguir identificar o serviço desejado, o agente solicita mais informações ao cliente, mantendo o contexto da conversa.

4.2. Exemplo inadequado

Um fluxo problemático ocorre quando os passos incluem condições como “caso esteja claro”, “se existir CPF” ou “caso o cliente solicite”. Nesse cenário, o fluxo deixa de ser linear e passa a misturar execução com decisão, tornando-se mais complexo, difícil de manter e propenso a erros.

A correção consiste em transformar essas condições em regras e manter os passos apenas com ações diretas.

5. Revisão do Agente

Antes de finalizar um agente, é importante validar se a estrutura está correta.

O fluxo deve conter apenas as ações principais, organizadas em sequência lógica, sem redundâncias. Cada passo deve ser claro, direto e conter uma única ação.

As condições devem estar isoladas nas regras, incluindo validações, erros, comportamentos proibidos e cenários de fallback. Se houver qualquer uso de “Se”, “Caso” ou “Quando” dentro dos passos, isso indica que a estrutura precisa ser ajustada.

Durante a revisão, verifique principalmente se cada passo possui uma única ação, se o fluxo segue uma ordem lógica e se não há condicionais dentro dos passos. Também é importante garantir que exceções, erros e validações estejam descritos exclusivamente nas regras.

Seguindo essas diretrizes, é possível construir agentes mais eficientes, consistentes e alinhados com as boas práticas de desenvolvimento no GOgenier.