Guia de Prompting para o seu Agente de IA

O guia está organizado em torno das quatro superfícies de prompting dentro de um worker da Darwin. A maioria das regras se aplica a todas as superfícies, mas cada seção foi escrita para que você possa ir direto à que precisa.

Dentro de um worker de IA existem quatro seções nas quais podemos prompter instruções.

Um espaço onde definimos informações ou instruções globais para todo worker do workspace. Por exemplo: localização do negócio, horários de funcionamento, informações de contato e perguntas frequentes. Todos os workers do workspace podem usar esse contexto para responder.

Um espaço reservado para um worker específico, no qual definimos informações, instruções e personalidade que pertencem apenas àquele worker. Por exemplo, em um workspace com um worker de vendas e um worker de pós-vendas, cada um precisa de preços diferentes (produtos vs. manutenção) e personalidades diferentes (persuasivo vs. consultivo).

Tanto a IKB quanto a GKB contêm o mesmo conjunto de subseções.

Um espaço para blocos personalizados ou pré-prontos de informação em formato de texto que o worker tem disponível como contexto permanente. O conteúdo é fixo como parte do prompt e está disponível em toda etapa de toda pipeline. Não é uma ferramenta de recuperação que é chamada apenas quando necessário.

Um espaço onde podemos carregar planilhas para o worker usar como contexto. Funciona como uma ferramenta de recuperação.

Um espaço onde podemos carregar arquivos para o worker usar como contexto ou para enviar à conversa.

Um espaço onde podemos configurar sites para fazer scraping, de modo que o worker possa usar o resultado como contexto. Funciona como uma ferramenta de recuperação.

Uma ferramenta de recuperação permite que o worker consulte fontes de dados externas para obter informações específicas (planilhas, PDFs, scrapes da web) sob demanda. Ao recuperar apenas o que é relevante, ela otimiza o desempenho e evita que a janela de contexto do modelo fique congestionada.

Um espaço dentro de uma etapa de IA em qualquer pipeline no qual definimos o Objetivo do worker para aquela etapa em particular.

Exemplo: Pergunte ao humano seu nome, sobrenome e idade.

Um espaço dentro de uma etapa de IA em qualquer pipeline no qual definimos as condições que, quando atendidas, fazem o worker mover-se para uma etapa diferente.

Exemplo: Se o humano mencionou seu nome, sobrenome e idade.

Esses princípios se aplicam a toda superfície de prompting. Trate-os como o padrão; as regras das seções posteriores os refinam para contextos específicos.

O modelo é capaz, mas não tem contexto sobre nossas normas, nossos clientes ou como queremos que as coisas sejam feitas. Quanto mais precisamente você descrever o destino e os critérios de sucesso, melhor o resultado. Se um colega sem contexto sobre a tarefa ficaria confuso ao ler seu prompt, a IA também ficará.

Descreva o resultado que você quer, não cada micro-passo para alcançá-lo. Reserve linguagem absoluta (Sempre, Nunca, Deve) para invariantes verdadeiras — regras de segurança, saídas obrigatórias ou ações proibidas. Use regras de decisão para o resto.

Explicar a razão por trás de uma instrução faz o modelo generalizar corretamente quando a conversa se desvia dos casos que você antecipou. “Nunca use reticências” é mais fraco que “Nunca use reticências, porque a resposta é lida em voz alta por um motor de text-to-speech”.

O mesmo conceito deve sempre ser chamado pelo mesmo nome. Escolha um termo e mantenha-o no Objetivo, nas condições, na IKB e na GKB. A inconsistência é uma das principais causas do modelo interpretar duas instruções como requisitos diferentes.

O modelo cria o que vê. Dizer-lhe “não escreva frases longas” ainda o prepara para frases longas. Diga primeiro o que ele deve fazer (“Escreva frases curtas e concisas”) e, só então, adicione a negação se ainda for necessária.

Os modelos modernos seguem as instruções literalmente. Se uma regra deve se aplicar amplamente, diga isso (“aplique isto a toda etapa”, “em toda resposta”, “em todo canal”). A generalização implícita não é mais confiável.

Se o Objetivo diz “sempre cumprimentar pelo nome” e a GKB diz “nunca cumprimentar pelo nome quando a conversa é reaberta em menos de uma hora”, o modelo precisa adivinhar qual delas vence. Ou reconcilie-as em um único lugar, ou escreva uma regra explícita de prioridade (“instruções da etapa têm precedência sobre os padrões da base de conhecimento”).

Os prompts de Objetivo são lidos pelo modelo como texto puro, mas a estrutura markdown dentro deles dá ao modelo sinais fortes sobre hierarquia e intenção. Em todo prompt de Objetivo, siga estas convenções.

Quando um Objetivo tem múltiplas fases ou ramificações, separe-as com cabeçalhos (#, ##, ###). Cabeçalhos dão ao modelo um mapa inequívoco da estrutura e permitem aninhar sub-instruções de forma limpa.

Quando você quiser que o assistente diga algo literalmente, coloque-o dentro de um blockquote. Isso separa visualmente a fala literal das meta-instruções.

“Olá {nome}, como posso te ajudar hoje?”

Use bullets - para conjuntos de itens nos quais a ordem não importa (FAQs, opções que o humano pode escolher, coisas a confirmar em qualquer ordem).

Use 1., 2., 3. quando a ordem de execução importa. A numeração comunica uma sequência que o modelo deve respeitar. Quando um passo precisa ser dividido em subpassos que também rodam em ordem, use notação decimal abaixo dele (1.1, 1.2, 1.3, …) para que a hierarquia fique explícita.

Exemplo:

Negrito e itálico raramente mudam o comportamento do modelo e adicionam ruído visual. Use cabeçalhos, listas e blockquotes para dar ênfase. Reserve negrito ou itálico apenas para destacar um único token crítico em um parágrafo longo quando não houver alternativa mais limpa.

O Objetivo diz ao worker o que ele deve realizar durante uma etapa. É o pedaço de texto mais influente de uma etapa — tudo o mais é contexto.

Evite filler de polidez como “Por favor, você poderia…”. Comece pelo Objetivo.

“Seu Objetivo é…”

O system prompt já define quem é o Assistente combinando seu nome, função, empresa e personalidade. Repetir essa caracterização dentro do Objetivo é redundante e empurra a tarefa de fato para baixo. Comece pela tarefa em si, não por uma declaração de identidade.

Os modelos prestam mais atenção ao começo e ao fim de um prompt. Coloque o comando principal primeiro. Se houver uma única restrição inegociável, repita-a no final como um lembrete de fechamento.

Use “Humano” dentro do prompt. Não “lead”, não “cliente”, não “consumidor”. Isso mantém o vocabulário consistente entre o Objetivo, as condições e as bases de conhecimento.

Use “Assistente” ou “IA” para se referir ao worker. Não “você” nem qualquer outro pronome. Pronomes de segunda pessoa mudam o enquadramento do modelo de formas difíceis de prever.

Diga ao modelo o que fazer de forma imperativa.

“Mencione X.” “Pergunte Y.”

Restrições rígidas podem fazer o worker entrar em loop na mesma tarefa. Uma restrição rígida é a que começa com “Sempre”, “Apenas” ou palavras absolutas similares.

Exemplos a evitar:

“Sempre peça ao humano seu nome.” “Apenas mencione que vendemos carros.”

Use absolutos apenas para invariantes verdadeiras (segurança, saídas obrigatórias, proibições rígidas).

Quando algo não deve acontecer, marque-o com “Nunca” para que o modelo trate isso como um limite rígido.

“Nunca mencione X.” “Nunca pergunte Y.”

Não promptie apenas o que o modelo não deve fazer. Diga primeiro o que ele deve fazer e, depois, adicione a negação.

Se uma etapa tem lógica demais, o modelo começa a cortar caminho. Divida-a em múltiplas etapas dentro da mesma pipeline para que cada Objetivo permaneça pequeno e autocontido.

Se a etapa precisa de uma sequência específica, use uma lista numerada.

Um fallback cobre o caso em que a suposição da sua instrução não se sustenta. Sem um, o modelo inventa.

Fallback zero-shot (sem exemplo, apenas a regra):

Fallback one-shot ou few-shot (inclui um exemplo do estilo desejado):

‘Olá {nome}, como você está?’ Se não souber, cumprimente sem chamar nenhum nome.”

Use few-shot quando o formato, tom ou frasear desejados forem difíceis de descrever em palavras. Mantenha os exemplos próximos a conversas reais e cubra casos de borda.

Objetivos e condições da próxima etapa estão profundamente relacionados: um Objetivo geralmente existe para coletar a informação que uma condição de transição requer. Tudo o que é mencionado em uma condição também deve ser perguntado (ou ser alcançável) a partir do Objetivo.

Exemplo ruim:

Exemplo bom:

Os modelos seguem as instruções literalmente. Se uma regra deve se aplicar amplamente, diga isso.

O Objetivo deve descrever o que fazer na etapa, não o que é o negócio. Mova preços, políticas, FAQs, horários de atendimento e detalhes de produto para a IKB ou GKB. Isso mantém o Objetivo curto e torna fatos de negócio reutilizáveis entre etapas.

Diga ao modelo quando a etapa está concluída. Sem um critério de sucesso explícito, o modelo pode continuar fazendo perguntas de acompanhamento ou encerrar prematuramente.

“A etapa está completa quando o humano confirmar seu nome, seu e-mail e uma data preferida. Assim que os três estiverem presentes, pare de fazer perguntas de acompanhamento.”

As condições são o que faz o worker se mover de uma etapa para outra. Elas são avaliadas como gatilhos para ferramentas de transição — errá-las cria a pior classe de bug: o worker silenciosamente transitando para o lugar errado, ou nunca transitando.

Cada condição deve comunicar um único propósito em uma única frase curta. Se uma condição precisar de mais de duas cláusulas — encadeadas com “e”, “ou”, “mas” ou ponto-e-vírgulas — divida-a em condições separadas dentro do mesmo grupo.

Isso vale para os dois tipos de grupo. Em um grupo all, em vez de escrever uma frase que junta vários requisitos com “e”, escreva cada requisito como sua própria condição — o próprio grupo já significa “todas devem ser verdadeiras”. Em um grupo any, em vez de escrever uma frase que junta várias alternativas com “ou”, escreva cada alternativa como sua própria condição — o próprio grupo já significa “qualquer uma torna verdadeiro”. Deixar o grupo fazer o trabalho mantém cada condição focada em um único fato, que o modelo consegue avaliar de forma limpa, em vez de colapsar a cadeia inteira em uma única checagem nebulosa.

Uma frase com negativos embutidos (“…mas não se X”; “isto só é verdade depois de Y”) é o sinal mais forte de que a decomposição é necessária. Os negativos geralmente pertencem como suas próprias condições atômicas ou como qualificadores dobrados dentro dos gatilhos positivos — reformular o lado positivo costuma tornar o negativo redundante.

Mesmo vocabulário do Objetivo. Não “lead”, não “cliente”, não “consumidor”.

Não “você” nem qualquer outro pronome.

Evite “compartilhou” ao falar do que o humano disse. Use “mencionou”.

“O humano mencionou que está interessado em…”

Adicionar “explicitamente” diz ao modelo que a condição só dispara quando o gatilho está inequivocamente presente na mensagem. Esta é a alavanca mais eficaz para reduzir falsos positivos.

“Se o humano mencionou explicitamente…”

Se duas condições parecem similares mas levam a etapas diferentes, o modelo vai adivinhar. Referencie a condição A dentro da condição B para expor a diferença.

Condição A: “Se o humano mencionou explicitamente que sua preferência é X.” Próxima etapa: Etapa A.

Condição B: “Se o humano mencionou explicitamente que sua preferência é Y, que é diferente de X por causa de…” Próxima etapa: Etapa B.

Para disparar uma transição com base no valor de retorno de uma ferramenta, nomeie a ferramenta e descreva o valor que o retorno contém.

“Se o retorno da ferramenta indicar X.”

Quando possível, cite o token literal que o retorno usa para que o modelo não tenha que interpretar.

“Se o retorno da ferramenta contiver explicitamente a palavra ‘paciente’.”

Uma zona morta é um valor que nenhuma condição cobre. O modelo escolherá uma das condições adjacentes, geralmente a errada.

O que acontece em exatamente 50? Ou inclua o limite em uma das duas condições (≥ 50 e < 50), ou adicione uma terceira condição para o caso de igualdade. O mesmo vale para datas, intervalos e qualquer outra variável contínua.

Para números, datas e horários, use comparadores inequívocos (≥, ≤, <, >, =, entre X e Y inclusive). Evite palavras coloquiais como “mais do que”, “alguns”, “logo”, “recentemente”, a menos que a rubrica de auditoria tenha uma definição para elas.

Use um novo bloco de informação para cada novo tópico e dê a cada bloco um nome descritivo (Promoções, Localização, Contatos, Regras gerais, etc.). Um tópico por bloco mantém a recuperação do modelo limpa.

Se um pedaço de dado é muito grande (por exemplo, um catálogo de produtos), ele não pertence a um bloco de texto. Mova-o para um catálogo (planilha), arquivo ou site, de onde o worker possa buscá-lo por uma ferramenta de recuperação.

A seção de FAQs é para pares pergunta/resposta que o worker deve reusar literalmente ou quase literalmente. Use-a apenas para uma relação 1:1 entre uma pergunta e uma resposta. Misturar lógica, ramificações ou política de formato longo nas FAQs degrada a qualidade da recuperação.

Tudo o que deve valer para todo worker do workspace vai para a GKB. Tudo o que se aplica apenas a um worker (sua personalidade, seus preços, seus scripts) vai para a IKB. Isso mantém o conhecimento reutilizável e evita que peculiaridades de um worker vazem para outro.

Se uma instrução pertence ao Objetivo de uma etapa, deixe-a lá. Colocá-la também na base de conhecimento cria uma redundância que o modelo eventualmente trata como conflito.

Use esses dois verbos e cite o nome da ferramenta.

“Execute a ferramenta .” (onde tool_name é o nome da ferramenta) “Chame a ferramenta .” (onde tool_name é o nome da ferramenta)

Se você promptia uma chamada de ferramenta dentro do Objetivo de uma etapa, essa ferramenta precisa estar disponível na seção de ferramentas dessa etapa. Caso contrário, o modelo pode alucinar uma chamada a uma ferramenta que ele não tem.

Se você promptia uma chamada de ferramenta a partir da IKB ou GKB, essa ferramenta precisa estar disponível em toda etapa em que o worker poderia alcançar o prompt. Caso contrário, o modelo pode alucinar a chamada em etapas onde a ferramenta está ausente.

Uma chamada de ferramenta sem instrução de downstream é trabalho desperdiçado. Descreva o que deve acontecer para cada valor que a ferramenta pode retornar.

“Se o retorno da ferramenta indicar que o humano tem dívida, mencione…” “Se o retorno da ferramenta indicar que o humano não tem dívida, continue com…”

Se uma ferramenta é cara, lenta ou one-shot (não pode ser repetida), declare as condições sob as quais o modelo NÃO deve chamá-la. Pareie isso com o gatilho positivo da regra 4.

“Chame a ferramenta apenas depois que o humano tiver confirmado tanto a data quanto a localização. Nunca a chame antes que ambas as informações estejam presentes, e nunca a chame mais de uma vez por conversa.”

Use o caractere @ como comando para selecionar o arquivo que você quer que o worker possa enviar.