--- title: Máquina de Estados - Detalhes slug: aura/maquina-de-estados-detalhes docTags: createdAt: 2025-07-07T20:39:55.891Z --- Este é um manual mais avançado das capacidades da máquina de estados. Os exemplos mostrados aqui pertencem ao editor de código de uma skill. - `#` Adiciona um comentário; - `/` Caractere de escape - `@` Estado local; - `@+` Espera por um input; - `@@` Estado global; - `-` Adiciona um texto; - `=` Adiciona um exemplo; - `%` Exemplo externo; - `>` Avança para um estado; - `!` Frase apresentada, caso não haja um entendimento; - `?` Frase apresentada, caso haja uma desambiguação; - `^` Permite ocultar menu (botão); - `{{VARIAVEL DE AMBIENTE}}` Variáveis de ambiente; - `$PIPELINE_INTERCEPTOR: PASTA_DO CLIENTE/NOME_DA_PIPELINE/` Chamada de pipeline; - `$HUMAN_ATTENDANCE_INTERCEPTOR:ID_FILA` Chamada de fila de atendimento humano; - Paginação - `more_options_label` Configura mensagem para ver mais opções; - `max_menu_options` Quantidade de menus apresentada por vez; - `min_word_size` Tamanho mínimo para ser considerado uma palavra; ## Estado ou Intenções ### Operadores Especiais ### Não entendimento (!) O **operador (!), mostrará de forma aleatória** uma das **frases apresentadas, ** **caso não haja um entendimento**. ### Desambiguação (?) Outro operador muito similar ao similar ao anterior, é **operador (?)**, onde este **mostrará de forma aleatória uma das frases apresentadas, caso haja uma ** **desambiguação**. ### Texto (-) Para adicionar um texto a um fluxo, use o operador (-). Vale lembrar que **se o ** **fluxo tiver mais de um operador de texto (-), um abaixo do outro, todos no ** **início da linha. A máquina de estados escolherá de forma aleatória um dos textos**. ```text @start = um exemplo aleatorio - Olá, Seja bem-vindo(a)! Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar? > end @end # Se seu fluxo tiver mais de um operador de texto ( - ), um abaixo do outro como no exemplo. A máquina de estados escolherá de forma aleatória um dos textos. - Se precisar de ajuda, basta me chamar. Reduce xyz agradece o contato! - Reduce xyz está sempre a disposição para ajudar e agradecemos o contato! ``` ```text ~/codes/cetralit/wanderson on master ?3 wanderson examples/operador - Olá, Seja bem-vindo(a)! Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar? - Reduce xyz está sempre a disposição para ajudar e agradecemos o contato! start..end 1.000 ~/codes/cetralit/wanderson on master ?3 wanderson examples/operador - Olá, Seja bem-vindo(a)! Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar? - Se precisar de ajuda, basta me chamar. Reduce xyz agradece o contato! start..end 1.000 ``` ### Exemplo (=) O operador de exemplo **(=)** permite cadastrar exemplos a intenções e entidades para serem analisados e interpretados pela nossa NLU. ### Exemplo Externo (%) O operador de exemplo externo (%), permite cadastrar **de forma externa ** **exemplos (=)**, que podem ser **utilizados por mais de uma intenção ou ** **entidade**. Através **do caractere (&)**. Utilizar essa abordagem reduz o número de linhas e facilita a adesão de novos exemplos, após o processo de curadoria. Exemplos Externos devem ser cadastrados em uma única pasta, todos os arquivos nesta pasta devem conter apenas, este operador. ```text %chit_chat_saudacao = Alô = Boa noite = Boa tarde = Bom dia = Bom dia, prezados = Hello = Hi = Oi = Olá = Saudação ``` ```text @start # Uso do exemplo externo ( % ) &chit_chat_saudacao = um exemplo aleatório - Olá, Seja bem-vindo(a)! Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar? > end @end &chit_chat_saudacao - Se precisar de ajuda, basta me chamar. Reduce xyz agradece o contato! - Reduce xyz está sempre a disposição para ajudar e agradecemos o contato! ``` ### Variável de ambiente ({{variavel\_ambiente}}) Este é um operador que permite **acessar variáveis externas de clientes**, para **incorporar** ao nosso **fluxo de conversa**. O exemplo **mais comum** é a variável, **{{username}}** do **Citsmart**. ### Caractere de escape (/) O caractere de escape permite, anular um operador da máquina de estados que seria interpretado de alguma maneira, para ser usado num texto. ```text @start - {{saudacao_tempo}} Olá {{user_name}}. Como vai você? Por favor acesse o perfil \@CentralIT > end @end - Até a próxima! ``` ```text - Bom dia Olá user_name. Como vai você? ePor favor acesse o perfil @CentralIT - Até a próxima! start..end 1.000 ``` ### Intenções Locais (@) Intenções ou estados locais são estados que só podem ser acessados quando um jump (>) a partir do estado atual os aponta. São **categorizados** pelo `@nome_qualquer: titulo do menu` e possuem a seguinte estrutura: ```text @start - Olá, Seja bem-vindo(a)! Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar? > atendente > status @atendente: Atendente = atendente - Um atendente irá te ajuda > end @status: ^ status = status - Seu status está OK > end @reduce: Reduce = reduce - impossivel entrar no reduce, pois nenhum estado, da jump para ele > end @end - acabou ``` ```text - Olá, Seja bem-vindo(a)! Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar? 1. map start..start 1.000 > status - Seu status está OK - acabou filter..end 1.000 ~/codes/cetralit/wanderson on master ?3 wanderson examples/operador - Olá, Seja bem-vindo(a)! Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar? 1. atendente start..start 1.000 > reduce - Não compreendi o que você deseja 1. atendente start..start 0.000 > ``` Perceba que apesar de a intenção **@reduce existir** e **não estar ocultada, ** **pelo operador (^)**. Ela **não aparece de forma alguma no fluxo ** **conversacional**. Isso porque o **estado atual** não aponta para o reduce. ### Aguarde por input (@+) Aguarde por input, faz com que o próximo jump, só seja executado caso o usuário digite o próximo passo. Perfeito para criar listas passo a passo. Veja o exemplo: ```text @start - oi > passo1 @+passo1 - passo 1 > passo2 @+passo2: passo 2 - passo 2 > passo3 @passo3: passo 3 - passo 3 > end @end - tchau ``` ```text ~/codes/cetralit/wanderson on master ?3 wanderson examples/operador - oi - passo 1 1. passo 2 start..passo1 1.000 > 1 - passo 2 1. passo 3 passo2..passo2 1.000 > 1 - passo 3 - tchau passo3..end 1.000 ``` ### Intenções Globais ( @@ ) Intenções ou estados globais, como proprio nome sugere, **podem ser acessados ** **de qualquer etapada da conversa**. São **categorizados** pelo `@@nome_qualquer: titulo do menu` e possuem a seguinte estrtura: ```text @start - Olá {{username}}! Seja bem-vindo(a)! Eu sou o assistente virtual do Reduce. Como posso ajudar? > map > filter #fluxo local @map: map = map > end #fluxo local @filter: filter = filter > end # fluxo global @@fluxo_global_oculto: ^ fluxo global oculto = fluxo global oculto - todo fluxo global, se não ocultado pelo operador (^). Conforme a cima, aparecera nos menus do @start Este é o caso, do fluxo_global_não_oculto > end #fluxo global @@fluxo_global_nao_oculto: fluxo global nao oculto = fluxo global não oculto - todo fluxo global, se não ocultado pelo operador (^). Conforme a cima, aparecera nos menus do @start > end @end - acabou ``` ```text ~/codes/cetralit/wanderson on master ?3 wanderson examples/operador - Olá username! Seja bem-vindo(a)! Eu sou o assistente virtual do Reduce. Como posso ajudar? 1. map 2. filter 3. fluxo global nao oculto start..start 1.000 > fluxo global start..start 0.683 > ~/codes/cetralit/wanderson on master ?3 wanderson examples/operador - Olá username! Seja bem-vindo(a)! Eu sou o assistente virtual do Reduce. Como posso ajudar? 1. map 2. filter 3. fluxo global nao oculto start..start 1.000 > ~/codes/cetralit/wanderson on master ?3 wanderson examples/operador - Olá username! Seja bem-vindo(a)! Eu sou o assistente virtual do Reduce. Como posso ajudar? 1. map 2. filter 3. fluxo global nao oculto start..start 1.000 > fluxo global não oculto - todo fluxo global, se não ocultado pelo operador (^). Conforme a cima, aparecera nos menus do @start - acabou fluxo_global_nao_oculto..end 1.000 ``` Vale lembrar que todo **fluxo global, se não ocultado pelo operador (^)**. Conforme a cima, **aparecerá** nos menus do **@start** Este é o caso, do **fluxo\_global\_não\_oculto** ## Entidades ### Entidades na máquina de estados (\*) O operador que caracteriza uma **Entidade (\*)**, seguido de seu nome `*nome`. Para um melhor uso dessa entidade, você deve pegar exemplos (=) que são muito próximos e cadastrá-los numa mesma entidade. Veja a seguinte estrutura. Entidades devem ser cadastrados em uma única pasta, todos os arquivos dessa pasta devem conter apenas, este operador. Vale lembrar também, que a ordem das Entidades (\*) importa nos exemplos (=). ```text *veiculo = carro = moto = caminhao *marca_veiculo = honda = bmw = ford = fiat *posse = meu = minha *ipva = imposto propriedade veículo automotor = imposto propriedade veículos automotores = ipva *vontade = quero = preciso = gostaria de ``` ```text @start - oi > pagar_ipva > transferir_carro > end @pagar_ipva = *ipva *posse - ipva > end @transferir_carro # a ordem das Entidades ( * ) importa nos exemplos ( = ) = *ipva *marca_veiculo - transferir carro > end @end - tchau ``` ## Interceptadores ( $ ) ### Pipeline De forma bem resumida e abrangente o conceito de pipeline, representa as etapas do processo pelas quais algo passa até cumprir um objetivo. Na equipe Gia, se utiliza muito pipelines para acessar api's do Citsmart para abrir chamados, preenchendo formulários via pipeline. **Como usar?** Basta colocar no fluxo que deseja invocar uma pipeline: “`$ ` `PIPELINE_INTERCEPTOR: PASTA_DO CLIENTE/NOME_DA_PIPELINE/`" O nome da pasta do cliente bem como nome da pipeline pode ser encontrado no CITBot - Filebrowser [File Browser](https://citbot-api.centralit.com.br/fb/login?redirect=%2Ffiles%2F) ```text @@mapear_pasta_rede: ^ Conceder Acesso/Mapear pasta de rede = Acesso a pasta de rede - Entendi que deseja atendimento sobre concessão de acesso/mapeamento de pasta de rede. está correto? > mapear_pasta_rede_sim > mapear_pasta_rede_nao @mapear_pasta_rede_sim: ^ Sim &navigation_sim # INVOCANDO PIPELINE $ PIPELINE_INTERCEPTOR: PASTA_DO CLIENTE/NOME_DA_PIPELINE/ > finalizacao_fluxo_padrao @mapear_pasta_rede_nao: ^ Não &navigation_nao > finalizacao_de_fluxo_em_caso_de_entendimento_incorreto ``` ### Atendimento Humano A plataforma Aura permite que o bot, transfira para uma fila de atendimento humano. Bastando colocar no fluxo que deseja invocar um atendimento humano `$HUMAN_ATTENDANCE_INTERCEPTOR:ID_FILA`. Para conseguir o ID\_FILA, acesse a plataforma aura ou consulte seu manual respectivamente. [Citbot](https://citbot.centralit.com.br/) [Citbot Manual](https://citbot-api.centralit.com.br/manuais/manual-do-usuario-solucao-plataforma-citbot.pdf) ```text @@atendimento_humano: ^ Atendimento Humano - Gostaria de falar com um de nossos analistas? &atendimento_humano &demanda_nao_resolvida &nenhuma_das_opcoes > atendimento_humano_sim > atendimento_humano_nao @atendimento_humano_sim: ^ Sim &navigation_sim # INVOCANDO ATENDIMENTO HUMANO $HUMAN_ATTENDANCE_INTERCEPTOR:ID_FILA > finalizacao_fluxo_padrao @atendimento_humano_nao: ^ Não &navigation_nao > finalizacao_fluxo_padrao ``` ## Parametros de configuração Recomenda-se que os parâmetros citados nesse tópico, sejam passados num arquivo chamado: “**01\_settings**”. ### Paginação Os parâmetros de paginação permitem, mostrar uma quantidade específica de menus na tela. Sendo o `more_options_label`, a mensagem que permite ver mais opções, `max_menu_options`, a quantidade de menus apresentada por vez. ```text # paginated more_options_label = Ver mais max_menu_options = 3 @start ? estou em dúvida entre as opções ! não entendi absolutamente nada - Esses são os parametros de paginação, sendo o more_options_label, a mensagem que permite ver mais opções. O max_menu_options, a quantidade de menus apresentada por vez. > menu > atendimento > status > reclamação > novo_pedido @manu: Menu - Menu = menu > start @atendimento: Atendimento - Atendimento = atendimento > start @status: Status - Status = status > start @reclamação: Reclamação - Reclamação = reclamacao > start @novo_pedido: Novo Pedido - Novo pedido = novo = pedido > start @@end: Sair = tchau = bye - tchau ``` ```text - Esses são os parametros de paginação, sendo o more_options_label, a mensagem que permite ver mais opções. O max_menu_options, a quantidade de menus apresentada por vez. 1. Menu 2. Atendimento 3. Status 4. Sair 5. Ver mais start..start 1.000 > 5 - Opções: 1. Reclamação 2. Novo Pedido 4. Sair 5. Ver mais start..start 1.000 > 4 - tchau end..end 0.000 ``` ### Tamanho minimo de palavra Como o próprio nome sugere, o parâmetro `min_word_size`, especifica o **número mínimo de letras**, que uma palavra deve ter, para a máquina de estados considerar ela como válida. Vale lembrar que por padrão o `min_word_size` é igual a 2, caso queira alterar esse valor, basta passar o parâmetro. **Emojis nos exemplos ( = )** Para passar emoji nos exemplos, `min_word_size` deve ser igual a 0. ```text min_word_size = 0 @start - Oi. Como você está? 🤔 > triste > feliz @triste: Triste = 😢 - Que pena > end @feliz: Feliz = 🙃 - um dia lindo um bom lugar pra ler um livro > end @end - tchau 🦽 ``` ```text ~/codes/cetralit/wanderson on master !2 ?3 wanderson examples/emoji.pagode - Oi. Como você está? 🤔 1. Triste 2. Feliz start..start 1.000 > c - - um dia lindo um bom lugar pra ler um livro - tchau 🦽 feliz..end 1.000 ~/codes/cetralit/wanderson on master !2 ?3 ``` ### Rank Options A máquina de estados trabalha com referência por estado, palavras-chave e número de palavras. Dando uma nota para os inputs, colocados pelo usuário. Como mostra o exemplo do debug export `WANDERSON_INFO=TRUE`. Os Ranks abaixo permitem mudar isso. ```text ~/codes/cetralit/wanderson on master !2 ?3 wanderson examples/emoji.pagode 😢 => triste((1.0, 1)) 🙃 => feliz((1.0, 1)) Referências por estado: 16 end ////////////////////////////// 4 feliz ////////////////////////////// 4 start ////////////////////////////// 4 triste ////////////////////////////// 4 Número de palavras chave: 2 1 ////////////////////////////// 2 Número de estados relacionados a palavra chave: 2 1 ////////////////////////////// 2 - Oi. Como você está? 🤔 1. Triste 2. Feliz start..start 1.000 > 🙃 * 🙃 Rank: 1 feliz ////////////////////////////// 1 triste 0 - - um dia lindo um bom lugar pra ler um livro - tchau 🦽 feliz..end 1.000 ``` **ignore\_below** O valor padrão desse parâmetro fara com que a máquina de estados ignore tudo abaixo de `ignore_below = 0.2` **is\_answer\_above** O valor padrão desse parâmetro fara com que a máquina de estados somente considere como correto, tudo que for superior ou igual a `is_answer_above = 0.8` **parse\_at\_start** Esse paramtro define, se no **@start**, o bot vai começar mandando mensagem `parse_at_start = false` ou se ele vai esperar o usuario digitar `parse_at_start = true`.