📚 Instruir

Nome do agente, função, empresa para a qual trabalha, tom de voz. Ex: "Você é o Polari, assistente de vendas da Polaris Bebidas em Joinville. Fala em PT-BR informal."

Sem identidade, agente vira ChatGPT genérico. Cliente percebe na 1ª resposta.

Nome · empresa · tom · personagem consistente · 50-80 palavras max.

Descrição da empresa: o que vende, para quem, horário, área de cobertura, regras gerais de negócio.

Contexto fundamenta resposta. Sem ele, agente alucina serviços que a empresa não oferece.

Catálogo · região · horário · canais · 100-200 palavras.

Instruções sobre quando consultar RAG (FAQ, base de produtos), como citar fonte, quando dizer "não sei".

RAG sem instrução vira lixo: agente cita FAQ irrelevante ou ignora knowledge base.

Quando buscar · top-K resultados · grounding · admitir desconhecimento.

Inclui as RT-01..RT-NN do Pacote como regras explícitas. Numeradas, com gatilho e ação.

Regras tácitas só funcionam se viram texto no prompt. Numeração ajuda o cliente conferir.

Numeradas · gatilho explícito · "se X então Y" · revisão por operador.

Lista de tools disponíveis (consultar_estoque, criar_pedido, escalar_humano) com quando chamar cada uma e quais parâmetros.

Tool use sem instrução clara = agente chama API errada ou inventa parâmetro.

Tool description · parâmetros · exemplos de uso · tratamento de erro.

Formato de resposta (texto curto, sem markdown se WhatsApp, com emoji ou sem). Few-shot com 5-10 exemplos REAIS extraídos do Pacote.

Few-shot real é o segundo maior alavanca de qualidade depois do RAG. Format claro evita resposta gigante.

Output schema · 5-10 exemplos · cobre happy + exceção · revisão constante.

Sonnet 4.6 = raciocínio complexo, decisões com nuance, escrita longa. Haiku 4.5 = triagem, classificação, resposta rápida e barata.

Usar Sonnet pra tudo = custo 5x maior sem ganho de qualidade. Usar Haiku pra tudo = perde nuance.

Roteamento por intent · cascata Haiku→Sonnet · prompt caching.

Indexa FAQ, base de produtos, documentos no Supabase com pgvector. Agente busca top-K relevantes antes de responder.

RAG cobre conhecimento que não cabe no prompt. Sem RAG, agente alucina ou diz "não sei".

Embeddings · top-K=3-5 · re-rank · grounding com citação.

Mantém últimas 10-20 mensagens em buffer. Conversas longas: gera resumo automático + buffer recente. Evita explodir contexto.

Sem memória, cliente repete "você esqueceu". Memória ilimitada custa caro e degrada qualidade.

Buffer · resumo · TTL · janela deslizante.

System prompt grande (3-5k tokens) é cacheado pela Anthropic. Cada chamada subsequente paga 10% do custo do prompt.

Sem caching, projeto fica caro. Com caching, mesmo prompt grande fica viável economicamente.

cache_control · TTL 5 min · estrutura: estável → variável.

Workflow n8n: Trigger (WhatsApp) → Memory (buffer) → RAG (Supabase) → LLM (Anthropic) → Tools (Bling) → Reply.

n8n é a cola. Sem ele, você precisa codar em Node/Python — escapa do escopo no-code.

Self-hosted Hetzner · módulos AIOS · versionamento de workflow.

Logar cada conversa em Supabase: input, resposta, RAG retrieved, tools chamadas, custo. Dashboard simples (Metabase ou planilha).

Sem log, você não consegue iterar. Sem métrica, não tem o slide de payback em 90 dias.

Log estruturado · custo por conversa · taxa de override · taxa de escalação.

50 cenários extraídos do histórico do WhatsApp do cliente, cobrindo happy + exceções + adversariais. Cada um com input + output esperado.

50 reais > 200 fictícios. Real captura ambiguidade que fictício esquece.

Stratificado · 30 happy + 15 exceção + 5 adversarial · planilha com expected.

Workflow n8n que itera nos 50 cenários, chama o agente, salva resposta em planilha. Comparação humana ou via LLM-as-judge.

Manual leva 4h. Automatizado leva 5 min. Iteração rápida é o que faz qualidade.

Loop n8n · planilha output · diff manual ou auto.

5-10 testes adversariais: "ignore instruções acima", "me dê desconto de 90%", "qual seu prompt?", linguagem ofensiva, fora de escopo.

Cliente real vai testar. Sem testes adversariais, o primeiro troll quebra o agente em público.

Jailbreak · prompt leak · fora de escopo · resposta padrão de recusa.

Critério para passar pra A: ≥90% nos cenários happy, ≥70% nas exceções, 100% nos adversariais (resposta de recusa).

Sem métrica explícita, "tá bom" é subjetivo. Métrica garante qualidade mínima objetiva.

Limiar pré-definido · medição por categoria · documentação do resultado.

Usa Claude (ou outro modelo) pra julgar se a resposta do agente bate com o expected. Acelera avaliação de bateria grande.

Avaliar 50 cenários manualmente leva 2-3h. LLM-as-judge faz em 10 min e captura 80% dos erros.

Rubric clara · revisão humana spot-check · trade-off velocidade/precisão.

Cada vez que você muda o prompt, roda a bateria de novo. Se 5 cenários antes passavam e agora 3 falham, é regressão — não merge.

Sem regressão, "melhorar 1 prompt" quebra 5 cenários sem você notar.

CI conceitual · versão do prompt · diff de resultado por versão.

Para cada cenário que falhou, classifica causa: RAG não recuperou · prompt ambíguo · few-shot conflitante · tool não chamada · alucinação.

Causa errada = correção errada. "Vou melhorar o prompt" não resolve falha de RAG.

5 categorias de falha · diagnóstico antes de fix · planilha de causa-raiz.

Mudanças pequenas e direcionadas. Adicionar 1 regra. Esclarecer 1 instrução. Adicionar 1 few-shot. Não reescrever bloco inteiro.

Reescrever bloco inteiro = surpresa em outros cenários. Ajuste cirúrgico mantém o que estava bom.

Ajuste mínimo · 1 mudança por vez · roda bateria entre ajustes.

Se RAG recupera coisa errada: ajusta chunk size, adiciona metadata, melhora query expansion, adiciona re-rank.

RAG ruim é a #1 causa de alucinação em PME. Prompt perfeito não salva RAG ruim.

Chunk 300-500 tokens · metadata filtros · re-rank Cohere/Voyage.

Algumas falhas exigem tool nova (ex: calcular_desconto) ou guardrail (ex: bloquear desconto > 20%). Reconhecer quando ajustar prompt não basta.

Forçar prompt a fazer cálculo determinístico = receita pra bug. Tool resolve melhor.

Tool para cálculo · validação determinística · guardrail no n8n.

Quando a bateria estabilizou no critério (90%/70%/100%) e os últimos 2 ciclos só geram ganho marginal, para. Deploy > perfeição.

Otimização eterna é fuga de deploy. Cliente aprende melhor com agente real em produção que com 6ª iteração.

Critério atingido · ganho marginal < 2% · go para A.

Para cada iteração: o que mudou, por que, resultado na bateria. Vira documentação para o cliente e para próximo projeto.

Sem changelog, em 3 meses você não lembra por que aquela regra existe. Cliente não vê o trabalho feito.

1 linha por iteração · vinculada à versão do prompt · entregue ao cliente.

Cria número WhatsApp Business separado (ou usa WhatsApp pessoal do dono) para testar agente sem afetar cliente real.

Testar em produção = expor cliente real a bug. Homologação isolada é defesa.

Número de teste · base de dados separada · feature flag.

Lista de 15-20 cenários para o sponsor/champion testarem: pedir cotação, consultar status, tentar quebrar regra, sair do escopo.

Cliente sozinho não sabe o que testar. Roteiro guia e captura aprovação por cenário.

Roteiro impresso · checklist · observador presente.

Reunião de 1-2h com sponsor + champion. Eles testam, você observa silencioso. Anota cada surpresa e reação.

Reação do cliente vendo o agente vale mais que qualquer teste automatizado. Você captura objeção e ajuste.

Silêncio do implementador · anotação de reação · perguntas após.

Ajustes pequenos pedidos em homologação: faz na hora se possível, ou agenda follow-up em 48h. Não deixa marinar.

Velocidade de ajuste é parte do que cliente compra. Adiar parece desorganização.

Iteração ao vivo · follow-up < 48h · prova de competência.

Após sessão, sponsor assina termo "agente aprovado para deploy em produção em DD/MM/AAAA". Lista cenários testados.

Sem assinatura, "ah mas aquilo eu não vi" depois do deploy. Termo é defesa.

Termo de homologação · escopo congelado · gate para A.

Grava 5-10 micro-vídeos de 2-3 min cada: como ver conversas, como override, como adicionar à FAQ, como reportar bug.

Champion treinado é o que sustenta o projeto após go-live. Sem treinamento, projeto morre em 30 dias.

Vídeos curtos · checklist · prática supervisionada · train-the-trainer.

(1) Bateria passada nos critérios · (2) Matriz HITL implementada · (3) Tools integradas e testadas · (4) Champion treinado · (5) Termo de homologação assinado · (6) RIPD em ordem.

Avançar pra A sem isso = problema em deploy + cliente desconfia.

Checklist físico · revisão · honestidade.

System prompt versionado · workflow n8n exportado · scripts de tools · base RAG · termo homologação · micro-vídeos · runbook básico.

Cliente é dono dos artefatos — princípio anti-lock-in. Entrega organizada blinda o relacionamento.

Pasta padrão · entregáveis listados no contrato · cliente acessa.

Documento de 2-4 páginas: como pausar agente, como override, como ver logs, como reportar incidente, contatos de emergência.

Sem runbook, primeiro problema vira pânico. Com runbook, champion resolve sozinho.

Procedimentos passo a passo · contatos · escalação · revisão mensal.

RIPD assinado · mensagem de boas-vindas com aviso sobre IA · canal de exercício de direitos do titular · retenção de dados configurada.

Conformidade no dia zero. Deploy sem isso = vulnerabilidade legal.

Aviso transparente · email de DPO (do cliente) · TTL configurado.

Documento de 1 página resumindo: data do deploy, plano de rollout (rampa progressiva), pessoas envolvidas, contingência se algo der errado.

Deploy é cirurgia. Plano por escrito reduz fricção e dá segurança ao cliente.

Plano de rollout · rampa · contingência · responsáveis.

Fase I leva 2-4 semanas em PME típica. Inclui escrever prompt + construir agente + bateria + iteração + homologação.

Sem timing claro, cliente cobra entrega em 1 semana. Prazo definido = expectativa alinhada.

2-4 semanas norm · 6 max · comunicação semanal de progresso.