Afinar o prompt de um agente com dados

"O agente está ruim" quase nunca é o prompt inteiro. Às vezes é o roteador mandando para o agente errado; às vezes é um portão de saída vetando por vocabulário que o próprio prompt ensinou; às vezes é a base de conhecimento que não cobre; às vezes é o horário. Otimizar prompt sem olhar os dados troca um problema por outro. Este guia diagnostica primeiro.

Como você age

• Sabe o que o prompt controla e o que não controla. O texto do agente é uma camada dentro de um prompt montado pelo motor, e onze portões barram a resposta na saída. Reescrever regra que o motor já impõe é ruído; escrever jargão ou "encaminhe ao gerente" cria veto e mata a agenda. Lista completa em references/anatomia-e-antipadroes.md.
• Diagnóstico antes da reescrita. Execuções, vetos, handoffs, consultas à base, custo por turno: references/diagnostico.md. Só depois disso você abre o prompt.
• Amostra mínima de conversa, com ciência da pessoa. Ler mensagens é ler dado pessoal de terceiros. Quando for indispensável, poucas conversas, só o trecho, só na instalação, e a pessoa sabe. Preferir agregados (o guia deskcomm-metricas cobre).
• Versão nova, nunca edição. A otimização vira uma versão em rascunho, testada pelo botão Testar com o mesmo roteiro antes e depois; o clique em Publicar é da pessoa. Versão publicada é imutável e reversível.
• Uma mudança por vez, medida. Trocar cinco coisas e a conversão subir não ensina nada.

Passo 0 — o que a pessoa vê

Uma pergunta por vez: qual agente; o que acontece (a frase exata que incomoda, se houver); desde quando; o que mudou perto disso (versão publicada, materiais, roteador, número novo). Descubra a versão publicada e a data — as métricas comparam "antes/depois" por essa data.

Passo 1 — o diagnóstico

Rode o bloco de references/diagnostico.md: vetos por portão nas execuções recentes (se o veto é internal_vocabulary ou promise, a origem costuma ser o prompt); handoffs e casos (passa demais ou de menos); consultas à base sem acerto (material que falta × limiar); roteador errando (intenções, não prompt); custo e tamanho do turno; fora da janela. Cada sinal aponta para uma causa — e nem toda causa é prompt.

Passo 2 — a revisão do prompt

Com o diagnóstico, abra a versão publicada e revise contra o checklist de references/anatomia-e-antipadroes.md: o que está lá e o motor já impõe (corte); o que está lá e cria veto (reescreva); o que falta (diagnóstico antes da oferta, situações, quando usar capacidade, limites por situação); tom e tamanho. Conteúdo situacional (objeção de preço, reativação) vai para skill do produto, não para o prompt — o corpo só entra quando o assunto aparece.

Escreva a versão nova inteira em prompt-<agente>-v<N>.md com um bloco "o que mudou e por quê", uma linha por mudança, ligada ao sinal do diagnóstico.

Passo 3 — antes/depois pelo botão Testar

Monte 5 a 8 mensagens do nicho (o guia deskcomm-cliente-novo tem roteiros) cobrindo o que incomodava. Rode cada uma na versão publicada e na versão nova (rascunho) pelo botão Testar: compare texto, ações tentadas e portões. Registre a tabela em references/diagnostico.md (seção "antes/depois"). Se a nova não melhora onde doía, não publique — volte ao diagnóstico.

Passo 4 — publicar (a pessoa) e medir (você, depois)

A pessoa clica em Publicar. Anote a data e a versão. Em 7 a 14 dias, o guia deskcomm-metricas compara handoffs, vetos, custo por turno e conversão antes/depois da data da publicação — é a única prova de que a otimização valeu. Piorou? Reverter cria uma versão a partir da anterior em segundos.

O que você nunca faz

• Não edita a tabela do agente no banco (o motor ignora; a rota barra).
• Não publica sem a pessoa ver o antes/depois.
• Não troca modelo, provedor ou credencial "de brinde" — é outra mudança, medida à parte.
• Não escreve no prompt regra que é portão do motor, nem nome de ferramenta, nem placeholder {{assim}}.
• Não conclui pela conversa de um cliente só. Uma frase ruim é anedota; padrão é dado.