Pular para conteúdo

Guia de edição de prompts — Gita Agents

Guia prático pra editar prompt de um agente existente. Cobre: o que você faz sozinho, quando chamar o dev, padrões validados.

O que é um "prompt" no Gita Agents

Campo ai_agents.prompt_text (TEXT, gigante). Vira o systemInstruction do Gemini após:

  1. Interpolação de variáveis — {{chave}} trocada pelo valor em ai_agents.variables
  2. Append de data/hora atual — \n\nData e hora atual: <now>

Depois do prompt, o Gemini recebe o histórico (últimas 40 mensagens da conversa) + a mensagem atual.

Separação — prompt fixo vs variáveis

No prompt_text (código) vão

  • Identidade fixa do agente (nome, papel, tom)
  • Regras invioláveis
  • Estrutura de fluxo (sempre a mesma)
  • Guardrails (o que nunca fazer)
  • Formato das respostas (balões curtos, emojis permitidos)

Nas variables (editável) vão

  • Preço vigente, condição especial, bônus
  • Links (checkout, suporte, evento)
  • Datas de evento
  • Modo (lancamento_ativo / perpetuo)
  • Nome de produto/oferta quando muda por campanha

Regra de ouro: se o valor muda mais de 1x por mês, vira variável.

Quando você edita sozinho pelo admin

Aba "Variáveis" no form do agente

  1. Abre <admin_url>/agents/<id>
  2. Vai na aba Variáveis
  3. Edita par key/value (existentes) ou adiciona novas
  4. Salva → efeito imediato na próxima mensagem

Casos típicos:

  • Trocar link de checkout: edita link_checkout
  • Abrir lançamento: modo_captacao = lancamento_ativo + preenche evento_gratuito_nome, evento_gratuito_link, evento_datas
  • Fechar lançamento: modo_captacao = perpetuo + zera variáveis de evento
  • Trocar oferta: condicao_especial_titulo, valor_vista, parcelamento_cartao, bonus_extras

⚠️ Cuidado: se você adicionar nova variável que o prompt não referencia, ela fica inerte. Pra o agente usar, precisa que o prompt tenha {{nova_chave}} — aí é edição de prompt e pode chamar dev.

Aba "Básico" — prompt text

Você pode editar o prompt direto, mas minha recomendação é me chamar porque:

  • Prompt mal editado causa regressão de comportamento difícil de detectar
  • Adicionar/remover regras afeta tools e fluxo
  • Ordem das seções importa (Gemini presta mais atenção nas primeiras/últimas)
  • Algumas frases são testadas e validadas com dump real

Edição segura que você pode fazer sozinho: - Corrigir typo - Trocar um nome que esteja errado - Ajustar um emoji

Edição que exige dev: - Mudar abertura/fluxo - Adicionar/remover regra invioável - Alterar condição comercial estrutural - Adicionar novo placeholder {{chave}} - Adicionar nova tool

Quando você precisa do dev

Abre nova conversa com Claude (ou continua a atual) informando:

  1. Qual agente (slug + client_name)
  2. O que quer mudar (ex: "quero que ela ofereça boleto em 10x quando não tiver cartão")
  3. Por que (ex: "acabamos de negociar condição nova com a Janaina")
  4. Contexto do cliente (se precisar validar com histórico real de conversa)

O dev vai: - Ler prompt atual - Confirmar com você o que muda exatamente - Revisar se a mudança gera efeito colateral (algum guardrail conflita?) - Aplicar via SQL (sem precisar deploy, só UPDATE em prompt_text) - Testar com mensagem real antes de liberar

Tempo esperado: 15-30 min pra ajuste pequeno, 1-2h se precisar analisar dump.

Estrutura de um prompt (seções padrão)

Ordem importa. Ver exemplo completo em ~/gita/agents/janaina-ortiga/whatsapp/conversao.prompt.md.

1. Identidade

Quem o agente é, quem ele NÃO é. Nome do atendente humano que ele simula.

Você é a Isis, atendente humana do time da Janaina Ortiga.
Você não é uma IA, não se apresenta como robô.

2. Estilo WhatsApp

Formato de resposta. Balões curtos, oral, sem markdown.

3. Abertura padrão

Template de primeira mensagem. Exemplo literal pro Gemini imitar.

4. Contexto do produto (fixo)

Fatos que não mudam: nome produto, formato, plataforma, garantia.

5. Condição comercial vigente (variáveis)

Tudo com {{chave}}. Essa é a parte que o admin edita.

6. Fluxo de conversa

Passos numerados. Ex: "1. Entender momento. 2. Apresentar oferta. 3. Confirmar dados. 4. Enviar link."

7. Tratamento de objeções

Respostas prontas pras objeções mais comuns (extraídas do dump).

8. Regra crítica sobre URLs

Anti-alucinação de link. Critical — LLM inventa URLs se não for blindado.

9. Regra crítica sobre contato/telefone

Anti-alucinação de número. Critical — LLM inventa (XX) XXXX-XXXX se pedido.

10. Quando escalar (tool reportar)

Critérios objetivos pra chamar humano.

11. Tools disponíveis

Lista das functions que o agente pode chamar. Descrição de quando usar cada.

12. Regras invioláveis

Lista de "nuncas". Final do prompt (Gemini dá peso maior ao final).

Anti-patterns (o que evitar)

❌ "Nunca" sem o "o quê"

Ruim: "Nunca seja genérica."

Bom: "Nunca use 'prezada', 'venho por meio desta', texto corrido longo."

❌ Regra negativa sem alternativa positiva

Ruim: "Nunca invente telefone."

Bom: "Nunca invente telefone. Se pedirem contato, responda sempre com {{link_suporte_alunas}}."

❌ Múltiplas perguntas no mesmo balão

Gemini copia padrão do prompt. Se o prompt tem exemplo com 3 perguntas juntas, ele vai fazer 3 perguntas juntas.

Bom: regra "uma pergunta por vez" + exemplos com uma pergunta.

❌ Markdown visível em exemplos

Se o exemplo no prompt tem **negrito** ou - bullet, o Gemini vai mandar markdown literal no WhatsApp. Use MAIÚSCULA pra destacar palavras únicas.

❌ Placeholders não preenchidos

Se o prompt tem {{xyz}} e as variáveis do agente não têm xyz, o texto literal {{xyz}} vai sair na resposta ao cliente. Sempre garantir que todo {{chave}} no prompt existe em variables.

❌ Histórico contaminado

Se o agente respondeu algo errado no passado (ex: "não consigo áudios"), o Gemini imita essa resposta nas próximas conversas, mesmo depois de corrigir o prompt. Precisa limpar mensagens antigas da tabela messages pra aquele remote_jid.

SQL de limpeza: 

DELETE FROM messages
WHERE agent_id = '<uuid>' AND remote_jid = '<phone>@s.whatsapp.net';
DELETE FROM leads
WHERE agent_id = '<uuid>' AND remote_jid = '<phone>@s.whatsapp.net';

Padrões validados (Janaina)

Abertura que funciona

"Oi! Tudo bem? Aqui é a Isis, da equipe da Janaina Ortiga."

Validado em 614 conversas reais do dump. Não inventar outro.

Tratamento "vou pensar" / "depois"

Pergunta o motivo real antes de aceitar o adiamento:

"Posso te perguntar uma coisa? Qual é o maior 'mas' que você tem pra entrar agora? É financeiro, é dúvida se serve pra sua loja, ou é outra coisa?"

Se cliente some, fechamento firme:

"Posso te passar o link ou devo encerrar sua inscrição por enquanto?"

(85× no dump humano — padrão validado)

Redirecionamento de aluna

"Que bom saber que você já é uma Lojista de Sucesso! ✨ O seu atendimento como aluno é feito pela Ana, que é a pessoa responsável. É só chamar por aqui que ela vai te ajudar 👇🏼 {{link_suporte_alunas}}"

Nunca inventar número (XX) XXXX-XXXX. Sempre link.

Tratamento "quero desconto"

"A condição de hoje ({{condicao_especial_titulo}}) já é o melhor preço que a Jana libera. Do valor cheio de R$3.000 pra {{valor_vista}} à vista, é praticamente 1/3 fora. Fora dessa janela não temos nada além."

Não inventa cupom, não promete "vou ver com gerente" (a menos que use tool reportar).

Checklist ao editar prompt

Antes de salvar:

  • Toda {{chave}} usada existe em variables
  • Não introduziu markdown visível em exemplos
  • Abertura mantém padrão validado
  • Regra crítica de URL está intacta (nunca inventar link)
  • Regra crítica de contato está intacta (nunca inventar telefone)
  • Tools mencionadas existem no banco (tools table pra esse agent_id)
  • Fluxo numerado segue ordem lógica
  • Regras invioláveis no final
  • Tamanho razoável (4k-12k chars — muito mais que isso, Gemini esquece começo)

Depois de salvar:

  • Testa com curl ou WhatsApp real
  • Confere resposta não tem {{placeholder}} literal
  • Confere abertura está correta
  • Se mudou comportamento, limpa histórico de números de teste

Processo seguro pra prompt grande (mudança estrutural)

Quando precisar reescrever bloco grande:

  1. Copia prompt atual pra arquivo de staging (ex: /tmp/prompt-<cliente>-<agente>-backup.md)
  2. Edita localmente no arquivo .prompt.md em ~/gita/agents/<cliente>/whatsapp/
  3. Diff visual com versão atual no banco
  4. Revisa com dump real — alguma conversa cobriria um caso novo?
  5. UPDATE via SQL ou PostgREST
  6. Testa com curl (5-10 cenários)
  7. Testa com WhatsApp real (2-3 casos)
  8. Commit o arquivo .prompt.md versionado no repo Gita (não commit do banco — banco é estado, .prompt.md é fonte de verdade)

Fluxo "mudança urgente em produção"

Quando cliente liga dizendo "o agente tá falando X, muda agora":

  1. Identifica agente afetado (slug)
  2. Se for texto específico (ex: preço errado) → editar variables via admin/SQL, efeito em segundos
  3. Se for comportamento (ex: "ela não pode mais vender Y") → editar prompt_text via SQL direto

Pra pausar completamente IA numa conversa específica: no Chatwoot, aplicar label pausar-ia (engine respeita, para de responder).

Pra desativar agente inteiro: UPDATE ai_agents SET is_active = false WHERE slug = '<slug>'. Mensagens são recebidas mas ignoradas.

Onde ficam os prompts versionados

~/gita/agents/<cliente>/whatsapp/<fluxo>.prompt.md

Importante: o arquivo .md é a fonte de verdade versionada (git). O campo prompt_text no Supabase é o estado vigente em produção.

Quando editar o prompt no banco, sempre sincroniza de volta pro arquivo .md e commit. Isso permite: - Histórico de mudanças via git log - Rollback fácil - Code review - Onboarding de outros devs