Proposta que
passa no linter.
A pergunta sobre que segmento trabalhar leva cerca de uma semana em quase toda operação de CRM. A parte repetitiva desse trabalho é consulta e comparação, e é essa parte que o agente executa. O critério de aceite fica em código: a jornada proposta precisa passar no lifecycle-lint.
Seções desta página
Narrativa
Alguém extrai dado, alguém cruza com receita, alguém escreve um documento, alguém contesta o recorte. Uma semana depois existe um briefing de segmento cuja qualidade ninguém consegue avaliar sem refazer o caminho inteiro.
Roteador determinístico na entrada, agente no meio, validador na saída. O roteador classifica a pergunta em exploração, diagnóstico ou proposta por marcadores lexicais, e define quais ferramentas o modelo enxerga naquela execução. Uma pergunta exploratória não emite jornada por acidente de formulação.
O agente consulta o DuckDB em modo leitura com teto de 50 linhas, mede coortes contra um piso de amostra, calcula quintis de RFM e fecha com uma jornada no formato canônico. O YAML sai do modelo e entra no lifecycle-lint. Quando reprova, os achados voltam ao agente como resultado de ferramenta.
A primeira proposta roteirizada passava com aviso, o que deixava o loop de correção sem demonstração. O validador do agente ficou mais rígido que o linter: quatro regras classificadas como aviso lá reprovam aqui. O linter audita régua escrita por gente, onde um aviso abre conversa com quem escreveu. A proposta do agente é automática, e refazer custa uma rodada.
Três intenções, três escopos
A mesma base, o mesmo agente, três perguntas. O que muda entre elas é o conjunto de ferramentas que o modelo enxerga, e quem decide isso é o roteador, em código. A saída fica em português, que é o idioma da operação para a qual a ferramenta foi escrita.
Execuções do agente
Um agente que também roteia e valida a si mesmo devolve resultado sem critério de aceite verificável.
Código, modelo, código
Roteamento e validação ficam fora do modelo por decisão de projeto. Percorra as seis etapas para ver a reprovação do validador voltando ao agente como resultado de ferramenta.
A pergunta em linguagem natural entra no pipeline. Nada foi decidido ainda.
router.py classifica por marcadores lexicais: intenção proposta, e as quatro ferramentas ficam liberadas.
agent.py executa run_sql, mede a coorte contra o piso, calcula RFM e emite a jornada em YAML.
validator.py reprova a rodada 1: L007 e L009. Os achados voltam ao agente como resultado de ferramenta, não como texto solto.
Rodada 2 de 2: o agente declara janela de silêncio e troca a métrica de entrega por retencao_d30.
Aprovado com 0 erros. O briefing sai com holdout de 0.1 e exit code 0. Se a rota permitia proposta e nada foi aprovado, o exit code é 1.
O escopo de permissão precisa ser auditável, e o critério de aceite precisa ser o mesmo em toda execução. O agente ocupa a etapa intermediária, que é onde a tarefa é aberta o suficiente para justificar um modelo.
O limite de duas rodadas é decisão de custo. Um agente que não converge com os achados do linter em mãos raramente converge em dez tentativas, e cada rodada extra é token gasto sobre a mesma dúvida.
O roteador usa marcadores lexicais e erra em formulação ambígua. Classificar com modelo tornaria o escopo de permissão dependente de uma saída não determinística, e a troca não compensa: o custo do erro atual é uma ferramenta a menos na execução, e a pergunta pode ser reformulada.
A coorte plantada
O eval só é verificável porque a resposta certa está plantada em posição conhecida. Alunos vindos de afiliados no plano mensal que assistem menos de duas aulas na primeira semana churnam bem acima dos demais, e é esse recorte que o agente precisa encontrar sozinho.
d7 menor que 2 aulas demais
mensais pago
geral orgânico
geral
churn em 90 dias · escala 0 a 50% · base sintética com seed fixa versionada
Base sintética de edtech, gerada por script versionado com seed fixa: 20 mil alunos, 18 meses de eventos, sazonalidade de matrícula em janeiro, março e agosto. A coorte de risco em posição conhecida é o que torna o eval verificável, porque existe uma resposta certa contra a qual comparar.
Dado sintético é requisito aqui, declarado no README. Base real de empregador não entra em repositório público.
O validador é mais rígido que o linter
Quatro regras que o lifecycle-lint classifica como aviso reprovam aqui, mais o piso de amostra, que é exclusivo do validador. A diferença não é de rigor por rigor: muda quem recebe o achado.
| Regra | lifecycle-lint (régua humana) | validator.py (proposta automática) |
|---|---|---|
| L005 · Segmento sem decaimento temporal | aviso | reprova |
| L007 · Canal intrusivo sem janela de silêncio | aviso | reprova |
| L008 · Jornada ativa sem grupo de controle | aviso | reprova |
| L009 · Métrica de sucesso ausente ou de vaidade | aviso | reprova |
| Piso de amostra da coorte | não existe | reprova |
rodada 1/2 · propose_journey
Jornada ativacao_afiliados_mensal com canal intrusivo sem janela declarada e taxa_abertura como métrica de sucesso.
✕ reprovado · 2 erros
L007 L009 Os achados voltam ao agente como resultado de ferramenta.
rodada 2/2 · propose_journey
Janela de silêncio declarada, e a métrica troca abertura por retencao_d30.
✓ aprovado · 0 erros
Briefing entregue com holdout de 0.1. Se a hipótese está certa, o teste dirá, e é para isso que o holdout entra.
O linter audita régua escrita por gente, onde um aviso abre conversa com quem a escreveu. A proposta do agente é automática, e refazer custa uma rodada. Com esse custo, o padrão sobe.
Os dez casos de roteamento
Bloco determinístico, sem modelo e sem custo, que roda em CI a cada push. Verifica a classificação da pergunta e o conjunto de ferramentas liberado. O caso 9 é de fronteira: carrega marcadores de duas intenções.
| # | Pergunta | Intenção | Ferramentas liberadas |
|---|---|---|---|
| 1 | "Que dados temos na base?" | exploracao | run_sql |
| 2 | "Quais eventos existem?" | exploracao | run_sql |
| 3 | "Quantos alunos ativos por plano?" | exploracao | run_sql |
| 4 | "Compare o churn por canal de aquisição" | diagnostico | run_sql, rfm |
| 5 | "Diagnostique por que mensais evadem" | diagnostico | run_sql, rfm |
| 6 | "Qual o tamanho da coorte de afiliados?" | diagnostico | run_sql, cohort_size |
| 7 | "Mostre o RFM dos inativos" | diagnostico | run_sql, rfm |
| 8 | "Proponha uma régua para afiliados mensais" | proposta | as 4 ferramentas |
| 9 | "Compare churn por canal e proponha jornada para o pior" fronteira | proposta | as 4 ferramentas |
| 10 | "Que segmento trabalhar para reter melhor?" | proposta | as 4 ferramentas |
Dois blocos de avaliação
Determinístico. Verifica a classificação da pergunta e o conjunto de ferramentas liberado, incluindo um caso de fronteira com marcadores de duas intenções.
Com o provedor roteirizado mede ferramentas, validador e loop de correção, e roda em CI sem custo. Com a API mede o modelo, e o número obtido vale para aquela execução.
# o registro do que o agente fez, e não do que ele diz que fez
{
"rota": "proposta",
"ferramentas_liberadas": ["run_sql", "cohort_size", "rfm", "propose_journey"],
"chamadas": [
{"tool": "run_sql", "linhas": 50},
{"tool": "cohort_size", "result": {"n": 3412, "piso": 500, "ok": true}},
{"tool": "propose_journey", "rodada": 1, "veredito": "reprovado", "achados": ["L007", "L009"]},
{"tool": "propose_journey", "rodada": 2, "veredito": "aprovado"}
],
"tokens": 4213, "tempo_s": 9.8
}A suíte
Três repositórios sobre a mesma tese: jornada de cliente é artefato versionável. Se ela pode ser declarada em arquivo, ela pode ser lida, auditada e revisada em pull request, com histórico e revisão por pares. Hoje ela vive dentro da interface da ferramenta de automação, onde não existe diff entre versões nem registro de por que aquele delay é de 48 horas.
A saída de um é a entrada do outro, o que torna objetivo o critério de aceite do agente: a jornada proposta precisa passar no linter.
Lê as jornadas declaradas em YAML e acusa o defeito antes da publicação, inclusive o que só existe entre duas réguas.
Lê os eventos de produto e devolve o briefing de segmento com a jornada proposta, já validada pelo linter.
Esta páginaGuarda os prompts de leitura versionados, com asserções verificáveis e placar que mede regressão em CI.