Skip to main content
O prompt (no painel, Instruções) é o texto que o agente lê antes de toda resposta. Ele diz quem o agente é, o que ele precisa conseguir na conversa, como fala, que passos segue, quando usa cada tool e quando passa o lead para um humano. É a peça que mais muda a qualidade do atendimento. O prompt não trabalha sozinho. O agente também lê a descrição de cada tool, a lista de skills e o bloco de contexto do lead. Um bom agente põe cada informação no lugar certo.

Onde fica no painel

Em Agente, seção Instruções. O ícone de expandir, no canto do campo, abre o editor em tela cheia (Instruções do agente). Digite @ para citar uma tool. Salvar cria um rascunho. A mudança só chega aos leads depois de Publicar, e as conversas em andamento pegam a versão nova em até 2 minutos. Veja Versões e publicação.

O que vai em cada lugar

Regra prática: se a informação só é útil quando o agente vai chamar uma tool, ela vai na descrição da tool. Se é longa e só serve às vezes, vira skill. Se vale sempre, fica no prompt.

Estrutura recomendada

Escreva em seções curtas, com títulos. O modelo segue melhor instruções organizadas e você acha o que mudar depois.

O que cada seção resolve

Por que o prompt é fixo

O prompt é o mesmo em todas as conversas do projeto, de propósito. Os providers (OpenAI, OpenRouter) guardam em cache o começo do pedido que se repete. Quando o começo é igual, o provider reaproveita esse trecho, cobra menos por ele e responde mais rápido. Por isso a Zatten monta cada pedido nesta ordem:
  1. tools e prompt: iguais em todas as conversas;
  2. histórico da conversa: cresce, mas o começo não muda;
  3. o que muda: o bloco “Contexto do lead atual” e o bloco “Agora” (data e hora), sempre no fim. Veja O que a Zatten injeta no contexto.
Consequências para quem escreve:
  • Não escreva dados de um lead no prompt. Eles chegam no fim, pelo contexto.
  • Não escreva data nem hora no prompt. O bloco “Agora” já traz, atualizado.
  • Não troque o prompt a toda hora. Cada versão publicada recomeça o cache.
  • O prompt pode citar os blocos pelo título (“veja o bloco Agora”). Os títulos não mudam.
Detalhe de custo: o desconto do cache aparece como tokens de entrada em cache na fatura do provider. Veja os links em “Para saber mais”.

Citar tools com @

No editor, digite @ e escolha a tool. O prompt guarda o nome técnico dela, por exemplo @kanban_move_agendado, que é o mesmo nome que o modelo vê na lista de tools. Citar pelo nome exato liga a instrução à tool certa. As ações da Zatten têm nomes no formato ação_alvo: kanban_move_<coluna>, tag_add_<tag>, properties_update_<propriedade>, transbordo_notify, attendant_shutdown.
Se você trocar o alvo de uma ação (outra coluna, outra tag) ou apagar a tool, o nome muda e a citação no prompt fica apontando para uma tool que não existe. Revise o prompt sempre que mexer nas tools.

Variáveis do prompt

Variáveis guardam o que muda de um cliente para outro (nome da empresa, cidade, horário, endereço) fora do texto do prompt. Assim o mesmo prompt serve a vários clientes: para adaptar, você troca os valores, não reescreve o texto. No painel, abaixo do prompt, em Variáveis: dê um nome (minúsculas, números e _, como nome_empresa) e um valor. No prompt, digite @ e escolha a variável no grupo Variáveis: ela aparece como um chip âmbar, e pode ser usada quantas vezes quiser. O botão no canto do editor alterna entre ver o nome das variáveis e ver o valor delas no texto.
  • O agente troca a variável pelo valor ao montar o prompt. O cliente final só vê o valor.
  • O valor é fixo por agente. Dados do lead (nome, tags, propriedades) não entram aqui: eles vêm pelo contexto do lead.
  • Uma variável em uso no prompt não pode ser apagada. Renomear atualiza o prompt.
  • Mudar um valor, como qualquer mudança no agente, vale depois de Publicar.
  • O agente não liga enquanto uma variável usada no prompt estiver vazia: ele a trocaria por nada, no meio da frase. A mensagem diz quais faltam.

O gestor responde as variáveis

É o que substitui a planilha que o cliente preenchia para alguém copiar para o prompt: o próprio cliente responde, no painel. Na tabela de Variáveis, ligue Gestor na linha da variável e escreva, logo abaixo, a Descrição: a pergunta que o gestor vê, com um exemplo (por exemplo: “O horário de funcionamento da loja. Ex: segunda a sexta, das 9h às 18h”). Salve e publique: o gestor só vê as perguntas da versão publicada. Quem tem o papel Gestor passa a ver, em Agente, as abas Testar o agente e Informações. Em Informações ele vê só as perguntas liberadas (nunca o prompt), responde e clica em Salvar e publicar:
  • Cada salvamento é uma versão nova, já publicada. O agente usa as respostas na hora.
  • Pode responder aos poucos: o que ele digita fica guardado no navegador até salvar, e a tela mostra quantas faltam.
  • Com o agente ligado, ele não consegue apagar uma resposta.
  • No seletor de versões do builder, a versão aparece com o nome de quem respondeu, e o ícone de diff mostra o que mudou (Versões e publicação).
Ao duplicar o projeto, as variáveis nascem vazias, a menos que você marque Levar os valores das variáveis. As perguntas e o Gestor vão junto: o cliente novo responde as dele.

Exemplos curtos por nicho

São trechos para adaptar, não prompts completos. Os modelos de nicho do painel trazem um prompt inicial para cada um. Veja os playbooks.

Erros comuns

Como testar o prompt

Use o chat de teste do painel antes de publicar. Teste o caminho feliz, um lead que foge do assunto, um pedido de humano, uma pergunta fora do escopo e uma tentativa de fazer o agente quebrar uma regra. Veja Testar o agente.

Pelo MCP

O prompt fica no bloco langchain, em config.instructions.system_prompt. Escrever cria uma versão nova, não publicada; quem publica é uma pessoa, no painel. Veja Como uma escrita funciona.

Armadilhas

  • Salvar não publica. O agente continua com o prompt antigo até alguém clicar em Publicar.
  • O prompt não é o único texto que o agente lê. Uma regra no prompt que contradiz a descrição de uma tool gera comportamento imprevisível. Revise os dois.
  • Citação de tool que não existe mais. Mudar o alvo de uma ação ou apagar a tool deixa o @nome no prompt apontando para o nada.
  • Prompt de motor antigo migrado. Depois de migrar, o prompt continua o mesmo, mas referências a “função”, busca na web ou base de arquivos não valem no LangChain Agent. Revise. Veja Migrar.
  • {{...}} sem variável declarada. O modelo lê o texto literal. Declare a variável em Variáveis ou troque o trecho pelo valor.
  • Ligou “Gestor” e ele não vê nada. As perguntas aparecem para o gestor só depois de Publicar a versão.
  • Repetir informação do contexto. Pedir o nome de um lead que já está no “Contexto do lead atual” irrita o lead. Diga no prompt para usar o que já está lá.

Perguntas frequentes

O menor que cubra as oito seções. Não há limite na Zatten, mas todo o prompt é enviado em toda mensagem: prompt longo custa mais e dilui as regras importantes. Conhecimento longo vai para skills.
Em português, no tom que o agente deve usar com o lead. Os modelos atuais seguem bem instruções em português, e o exemplo de tom já fica no idioma certo.
Sim, poucos e curtos, mostrando o tom e o formato. Exemplos demais fazem o modelo copiar as frases ao pé da letra.
Escreva o horário no prompt (“seg a sex, 8h às 18h”) e peça para comparar com o bloco “Agora”, que traz dia da semana, data e hora de Brasília.
Veja no LangSmith o que o modelo recebeu. Em geral: a regra está enterrada no meio do texto, conflita com outra, ou deveria estar na descrição da tool. Se a regra é crítica, um modelo mais capaz ou com raciocínio ligado ajuda. Veja Escolher o modelo.

Para saber mais

Termos para buscar: “system prompt best practices”, “prompt caching static prefix”, “tool description best practices”, “context engineering”, “few-shot examples”, “GPT-5 prompting guide”.