---
title: "Guia de estilo de prompt"
description: "Como escrever e editar o prompt de um agente de voz do ThunderPhone: as diretrizes, as verificações de revisão de prompt e os IDs citados em suas conclusões."
---

{/*
  ARQUIVO GERADO: não edite manualmente.
  Fonte: api/agents/prompt_style_guide.md
  Regenere: python3 scripts/docs-freshness/generate_prompt_style_guide.py
  A CI regenera esta página e falha em caso de divergência
  (scripts/docs-freshness/generators.d/50-prompt-style-guide.sh).
*/}

<Note>
  Este é o guia em relação ao qual a [revisão de prompt](/api-reference/agents#review-a-prompt) verifica um prompt, e
  suas conclusões citam os IDs abaixo. Agentes de programação conectados ao
  [servidor MCP](/pt/guides/thunderphone-mcp-server) leem o mesmo texto como o recurso
  `thunderphone://guides/prompt-style`. Para modelos e exemplos, consulte o
  [guia de prompting](/pt/guides/prompting).
</Note>

Este guia é para qualquer pessoa que escreve ou edita o prompt de um agente de voz: uma pessoa no construtor, no Copilot ou um agente de programação que trabalha pela API. A ferramenta de revisão de prompt o utiliza como critério e cita os IDs das diretrizes (P1, W2 e assim por diante).

Quem liga ouve o agente uma vez, no ritmo da fala, e não pode voltar para reler. O agente lê o prompt a cada turno e reproduz sua redação de perto. Esses dois fatos moldam tudo abaixo.

## Estrutura

**P1. Escreva como uma pessoa orientaria uma nova recepcionista.** Uma breve abertura informa quem é o agente e para quem
ele trabalha. A chamada segue então a ordem em que acontece: como começa, o que descobrir, o que confirmar,
como termina. Cada regra fica na parte da chamada em que se aplica. Quem lê deve poder perguntar sobre cada
parágrafo: "uma pessoa que administra esta empresa poderia ter escrito isso?" O que descobrir abrange o que a empresa precisa para atender
à solicitação, não apenas quem está ligando e como entrar em contato.

**P2. Títulos simples, texto explicativo abaixo.** Títulos como "Quem você é", "A chamada", "Informações" e "Encaminhamento" ajudam. Estrutura no estilo de máquina não ajuda: manuais de regras numerados, títulos em camelCase ou semelhantes a código, listas longas de regras com marcadores de travessão, uma referência de ferramentas logo no início e referências cruzadas como "consulte a seção 4 abaixo". Listas são adequadas para dados que o agente consulta (horários, preços, endereço).

**P3. Forma de falar, uma vez e brevemente.** A forma como o agente fala durante toda a chamada (falas curtas em primeira pessoa,
tom acolhedor, palavras simples; consulte S2) cabe em um parágrafo curto perto do início. Tudo o que for específico de uma etapa fica
nessa etapa.

**P4. Informações separadas do comportamento.** Horários, preços, locais, políticas e outras informações ficam em uma seção de informações do prompt ou em uma base de conhecimento, não espalhados pelo fluxo da chamada. Catálogos longos e perguntas frequentes devem ficar em uma base de conhecimento. O agente só pode dizer informações que recebeu.

## Conteúdo

**C1. Princípios e fatos, não scripts.** Descreva o que o agente está tentando alcançar e o que ele precisa saber. Não inclua ramificações do tipo "se quem liga disser X, diga Y", respostas roteirizadas para perguntas previstas nem frases prontas. A saudação inicial configurada é o único elemento roteirizado.

**C2. Uma correção estabelece o princípio geral.** Quando uma alteração no prompt responde a uma falha observada, a alteração adiciona um princípio geral ou um fato ausente, não uma correção para aquele caso específico. Os detalhes da chamada que falhou (nomes, números e palavras exatas) não entram no prompt.

**C3. Prefira remover a adicionar.** Quando uma falha decorre de uma regra existente que é específica demais, ampla demais ou mal posicionada, altere ou remova essa regra em vez de adicionar uma regra contrária ao lado dela.

**C4. As configurações decidem algumas coisas, não o prompt.** Estas são configurações do agente, e o texto do prompt sobre elas é ignorado ou entra em conflito com elas: o que é dito enquanto uma ferramenta é executada (frase de início da ferramenta, frases de preenchimento), verificações após silêncio e a ação final após o silêncio, o ritmo da repetição, o estilo de troca de idioma, o aviso de gravação e se o agente ou quem liga fala primeiro. Direcione o prompt ao resultado ("confirme o endereço de e-mail antes de salvá-lo") e defina a configuração. A própria saudação inicial é escrita no prompt.

**C5. Exemplos são frases que o agente dirá.** O agente copia a redação dos exemplos quase palavra por palavra, portanto cada exemplo deve ser uma frase completa e natural para falar, e alguns exemplos variados são melhores do que um só. Apresente-os como exemplos ("Por exemplo, você pode dizer ..."), não como a frase obrigatória. Rótulos curtos como "Ainda está correto?" soam secos quando falados.

**C6. Não use exemplos das chamadas dos nossos próprios clientes.** Os exemplos descrevem o tipo de situação em termos gerais ou usam uma empresa fictícia.

**C7. O prompt é para quem liga, não sobre a implementação.** Quem liga ouve tudo o que o prompt diz quando ele está ativo, portanto
ele não inclui observações sobre implementação, testes ou status de conformidade ("esta versão é para testes", "TESTE" no nome de uma
reserva, "até que os contratos sejam assinados"). Também não inclui avisos legais, ressalvas de responsabilidade nem resumos finais que a empresa não solicitou, como o que aceitar um plano não estabelece ou um resumo do que ainda não foi confirmado. O agente responde ao que quem liga perguntou e para; a empresa adiciona uma ressalva quando quiser. Uma informação ausente ou um limite do sistema é escrito como o que o agente faz ("para preços, ofereça uma ligação de retorno do escritório"), não como uma observação de que ela não foi fornecida ou sobre como as solicitações são registradas, e não sobra nada da redação, como um nome ou título perdido.

## Redação

**W1. Diga o que fazer, de forma clara, uma vez.** Descreva o comportamento desejado como uma instrução em palavras comuns: "Leia o número do pedido de volta dígito por dígito para que quem liga possa corrigi-lo." Diga isso uma vez, onde se aplicar.

**W2. Sem ênfase.** Não use rótulos como IMPORTANTE, OBSERVAÇÃO ou CRÍTICO, palavras em maiúsculas para dar força, pontos de exclamação, pares de "Ruim:" e "Bom:" nem blocos sobre o que não fazer. Palavras como "nunca", "sempre" e "deve", usadas para dar força, também se enquadram aqui. A ênfase direciona a atenção do modelo para uma regra e piora seu desempenho no restante da chamada. Quando o agente ignora uma instrução, torne-a mais clara, mais específica ou melhor posicionada, não mais enfática.

**W3. Corrija a estrutura que causa um comportamento.** Antes de adicionar uma regra contra algo que o agente faz, encontre a redação ou estrutura que o leva a isso: um modelo que o agente preenche literalmente, um termo com dois significados, uma ramificação if-else que um modelo rápido interpreta de forma flexível. Altere isso.

**W4. O específico é melhor que o geral.** "Ofereça os dois primeiros horários disponíveis e depois pergunte qual funciona" é melhor que "ajude com o agendamento". Instruções vagas resultam em comportamentos vagos.

**W5. Consulte antes de perguntar sobre isso.** Quando quem liga mencionar algo que uma ferramenta de consulta somente leitura pode verificar (um produto, um pedido, uma reserva existente), o agente verifica usando as palavras fornecidas por quem liga e só faz uma pergunta complementar se o resultado exigir isso. "Verifique o estoque do produto mencionado por quem liga e informe o que encontrar" é melhor do que "esclareça a marca, o tamanho e a variante e depois verifique o estoque": um agente instruído a esclarecer primeiro continua fazendo perguntas, e a consulta nunca é executada. Isso se aplica apenas a consultas. Antes de usar uma ferramenta que agenda, altera, cancela ou salva algo, o agente ainda confirma os detalhes com quem liga.

## Fala

**S1. Uma pergunta por vez, e a pergunta encerra a vez.** Qualquer coisa dita depois de uma pergunta fala por cima da resposta de quem liga. Coloque qualquer explicação antes da pergunta.

**S2. Turnos curtos, em frases completas faladas.** Uma ou duas frases curtas, a menos que quem liga peça detalhes.
As opções faladas se limitam a poucas. Curto significa poucas palavras, não frases truncadas: o agente fala como uma boa
recepcionista ao telefone, em frases completas na primeira pessoa, como "Vou agendar isso para você agora" ou
"Deixei você agendado para segunda-feira às dez." Fragmentos em estilo de anotação ("Vou agendar isso para você.", "Pronto.",
"Anotado.") soam secos quando falados, e formulações de e-mail ("Observe que ...", "Por gentileza ...", "Espero que isso ajude")
parecem lidas em vez de ditas. O parágrafo do prompt sobre a maneira de falar pede isso claramente, por exemplo: "Mantenha cada turno em
uma ou duas frases e fale na primeira pessoa, como uma recepcionista falaria ao telefone."

**S3. Escreva para o ouvido.** No que o agente diz, evite Markdown, símbolos e notações que a voz lerá de forma estranha (barras, e comercial, "@", ".com", separadores de milhares, números de telefone sem espaços). Fatos e valores que o agente passa para uma ferramenta, como um endereço de e-mail ou número da conta, permanecem em sua forma escrita exata; quando também precisarem ser ditos em voz alta, adicione ao lado como são pronunciados em vez de reescrevê-los. Escreva como nomes incomuns ou siglas são pronunciados e ouça novos termos na voz do agente antes de mantê-los.

**S4. Confirme informações cujo erro teria custo alto.** Números, e-mails, endereços e códigos são repetidos na forma
em que foram fornecidos, uma vez, na resposta logo após quem liga fornecê-los e antes da próxima pergunta, um valor por
repetição. Por padrão, um nome é aceito como foi dito, sem repetição, e o agente pede a soletração apenas quando ele for
incomum ou pouco claro, e pede uma única vez. Quando a empresa precisa do nome exato, como para corresponder aos seus
registros ou para uma reserva nesse nome, o prompt deve indicar isso, e o agente soletra o nome de volta. Uma repetição é a chance de quem liga
corrigir um valor, não uma barreira: quem liga que responde com o próximo detalhe ou continua sem corrigi-lo o
aceitou, e um valor aceito não é perguntado novamente. Um número de telefone para o qual a empresa ligará ou enviará uma
mensagem é a exceção: sua repetição encerra o turno e aguarda a resposta de quem liga. Um prompt que pede leitura
dígito a dígito nomeia apenas os valores lidos dessa forma (um número de telefone, um código); um número de imóvel, um preço,
um horário ou uma data é dito da forma como as pessoas os dizem. O prompt informa o que confirmar; a plataforma define o ritmo da repetição.

## Iteração

**I1. Teste antes de manter uma alteração.** Reproduza o conjunto de desenvolvimento do agente no rascunho editado e compare-o com a
versão atual: quais exemplos uma alteração corrigiu e quais ela prejudicou. Leia as respostas como quem liga as ouviria.
Tudo o que quem liga perceber é um problema, não um detalhe.

**I2. O conjunto de teste é verificado uma vez.** Ajuste apenas no conjunto de desenvolvimento. Execute o conjunto de teste quando uma alteração estiver pronta e
informe o resultado como ele é. Uma alteração feita após ver os resultados do teste exige novos exemplos de teste.

**I3. Refatore quando os remendos se acumularem.** Um prompt que acumulou muitas pequenas correções se afasta de P1: as regras
se repetem, entram em conflito ou ficam longe da etapa que orientam. Nesse caso, reescreva-o nesta estrutura, preservando todos os comportamentos
solicitados. Liste cada comportamento como mantido, mesclado, reformulado ou removido, e não remova nada silenciosamente. Reproduza o conjunto de desenvolvimento antes e depois; uma refatoração deve alterar a redação, não o comportamento.

**I4. Verifique a configuração antes do prompt.** Algumas falhas não são do prompt: entender incorretamente letras soletradas é uma limitação de audição (experimente a audição Plus), uma resposta lenta pode ser causada pelo nível de inteligência ou de audição, ou pela configuração de endpointing. Descarte problemas de configuração antes de reescrever o texto.
