Gatilhos
O gatilho define quando um agente começa a trabalhar. Os agentes aparecem em uma lista única com busca textual.
Catálogo inicial
| Gatilho | Quando inicia | Configurações importantes |
|---|---|---|
| Tempo | No intervalo e no horário programados. | Frequência diária, semanal ou mensal; hora, minuto e fuso America/Sao_Paulo. |
| Novo lançamento | Quando um novo lançamento entra na estrutura. | Origens Rica/Open Finance, categorias opcionais, escopo de pessoas e demais condições escritas na instrução. |
| Mensagem no WhatsApp | Quando uma pessoa envia uma mensagem no canal. | Escopo de pessoas e condições escritas na instrução. |
| Mensagem no iOS | Quando uma pessoa envia uma mensagem no aplicativo. | Escopo de pessoas e condições escritas na instrução. |
| Novo investimento B3 | Quando uma posição que não existia na base da B3 é detectada. | Escopo de pessoas e condições escritas na instrução. |
| Novo investimento Open Finance | Quando um investimento inexistente na base conectada é detectado. | Escopo de pessoas e condições escritas na instrução. |
| Meta atingida | Na transição da meta para atingida. | Metas opcionais, pessoa, projeto e ciclo. Sem seleção, considera todas. |
| Objetivo atingido | Quando todas as metas ativas do objetivo são atingidas. | Objetivos opcionais, pessoas e ciclo. Sem seleção, considera todos. |
| Retomada por resposta | Quando chega a resposta de uma pergunta feita pelo agente. | Correlação com a conversa, a mensagem e a execução que aguardava. |
O catálogo é expansível: novos gatilhos podem ser adicionados sem criar outro modelo de agente.
A execução manual não faz parte do catálogo de gatilhos selecionáveis. Todo agente ativo já salvo pode ser executado para teste: abra sua edição e use o bloco Execução manual, com ícone de play. A execução e seus resultados ficam registrados na atividade, mas o teste não fabrica os dados de um evento real.
Identificação visual
As pílulas usam o ícone do próprio gatilho: em Tempo, em Novo lançamento, e nos canais, imagens próprias da B3 e do Open Finance, em Meta atingida e em Objetivo atingido. O CheckToggle da pílula indica a seleção.
O cadastro aceita mais de um gatilho. Os controles específicos só aparecem quando o gatilho correspondente está selecionado.
Novo lançamento
O evento carrega a origem do lançamento. No cadastro, selecione Rica, Open Finance ou ambas e, opcionalmente, uma ou mais categorias da estrutura. Sem categorias selecionadas, qualquer categoria pode acionar o agente. Deixe os demais critérios de negócio na instrução.
Exemplo:
Em novos lançamentos cujo nome contenha “Amazon”, pergunte o que foi comprado. Não pergunte quando o lançamento já tiver uma observação suficiente.
Investimentos da B3 e do Open Finance
“Novo” significa um investimento que ainda não existia no espelho daquela fonte. Mudanças de saldo, quantidade ou preço não devem iniciar esse gatilho como se fossem novos investimentos.
Na primeira sincronização, a Rica estabelece uma base com o que já existe. Esse carregamento inicial não deve gerar uma sequência de eventos antigos. As detecções começam a partir das leituras seguintes.
Meta atingida
O evento acontece quando uma meta passa de não atingida para atingida no ciclo. A mesma meta não deve disparar repetidamente enquanto continuar no mesmo estado e ciclo.
Use a ação com ícone de alvo para abrir o picker. As metas escolhidas aparecem como pílulas; sem escolha, a regra vale para todas as metas dentro do escopo de pessoas.
Objetivo atingido
O objetivo é considerado atingido quando todas as metas ativas e não canceladas vinculadas a ele estiverem atingidas. Assim como nas metas, a emissão deve acontecer uma vez por ciclo ou transição válida.
Use a ação com ícone de bandeira para abrir o picker. Os objetivos escolhidos aparecem como pílulas; sem escolha, a regra vale para todos os objetivos dentro do escopo de pessoas.
Resposta recebida
A resposta a uma pergunta não é uma nova execução independente. Ela é um evento interno que retoma o agente que estava aguardando e conserva o contexto daquela atividade. Por isso, Retomada por resposta aparece na rastreabilidade, mas não precisa ser escolhida como gatilho no cadastro.
Idempotência
Cada evento deve ter uma identidade própria. Se a infraestrutura entregar o mesmo evento mais de uma vez, o agente reutiliza ou ignora a execução já registrada, evitando ações e mensagens duplicadas.
Próximo passo
Veja como combinar ferramentas e escopo.