«Estava no prompt» não é uma resposta a «porque é que ele fez aquilo?»
A conversa repete-se em todas as empresas que põem um agente em produção. O agente faz uma coisa estranha — promete um prazo que não existe, responde a algo que não lhe competia, inventa um procedimento — e alguém pergunta o que aconteceu. A resposta é sempre a mesma: «estava no prompt». E então vêm as três perguntas incómodas. Em que versão do prompt? Quem escreveu aquela linha? Alguém testou o que acontece se a tirarmos?
Quase nunca há resposta, e não é desleixo: é que a palavra prompt empurra-te a tratar o texto como uma mensagem. Uma mensagem escreve-se uma vez, envia-se e esquece-se. Mas o que governa um agente em produção não é uma mensagem: é o documento que define o que faz, o que não toca e a quem liga quando encrava. Isso tem outro nome em qualquer organização: uma descrição de funções. E as descrições de funções têm dono, versão e data de revisão.
Não é uma metáfora de conveniência. A própria documentação da Anthropic recomenda pensar no modelo como «um colaborador brilhante mas novo, que não conhece as tuas normas nem os teus fluxos de trabalho», e propõe uma regra de ouro que funciona igualmente bem com pessoas: mostra as tuas instruções a um colega com pouco contexto e pede-lhe que as siga; se ele se baralhar, o modelo também se baralha. Fonte: Prompting best practices, Claude Platform Docs, consultado a 11 de setembro de 2026.
Este guia é sobre escrever esse documento. Não é um curso de prompting nem um modelo mágico para copiar: é a estrutura mínima que aguenta produção, a parte em que quase toda a gente se engana e o hábito que separa iterar de rezar.
As seis coisas que têm de estar escritas
Plataforma, modelo e caso de uso não mudam nada disto. Se faltar algum destes seis blocos, o agente preenche-o por sua conta, e o que ele preencher não foste tu que decidiste. Na arquitetura que a OpenAI descreve, um agente são três peças — modelo, ferramentas e instruções — e as instruções são as «diretrizes e guarda-corpos explícitos que definem o seu comportamento». Explícitos é a palavra. Fonte: A practical guide to building agents, OpenAI, consultado a 11 de setembro de 2026.
| Bloco | O que responde | O que acontece se faltar |
|---|---|---|
| Identidade e canal | Quem é, com quem fala e por onde | O tom e o tratamento mudam conforme o dia |
| Âmbito | Do que trata e do que não trata | Responde a tudo, incluindo ao que não sabe |
| O que pode decidir | Onde acaba propor e começa executar | Executa coisas que ninguém autorizou |
| Formato de saída | Com que forma entrega o resultado | O sistema de destino rejeita-o em silêncio |
| O que faz quando não sabe | A saída honesta por omissão | Preenche o buraco com algo verosímil |
| Quando escala | O limiar exato que chama uma pessoa | Ninguém dá por isso até haver uma reclamação |
Repara na coluna da direita: nenhuma destas falhas se manifesta como um erro. Todas se manifestam como comportamento, que é muito mais caro de detetar. Um agente que vai abaixo avisa-te; um agente a quem falta o bloco de âmbito trabalha descansado durante semanas a responder a coisas que nunca lhe competiram.
O erro das regras pela negativa (e o que pôr no lugar)
Aqui está a correção mais útil de todo o guia, e vai contra o que quase toda a gente faz. Quando um agente se porta mal, o reflexo é acrescentar uma proibição: «nunca prometas prazos», «nada de emojis», «nunca dês preços». A lista de nãos cresce semana após semana até virar um regulamento, e o comportamento continua a aparecer.
A documentação da Anthropic é explícita quanto a isto: diz ao modelo o que deve fazer, em vez do que não deve fazer. O exemplo que dão para controlar o formato é exatamente este: em vez de «não uses markdown na tua resposta», escreve «a tua resposta deve ser composta por parágrafos de prosa fluida». E quando a proibição é inevitável, o mesmo guia recomenda acompanhá-la do motivo: «NUNCA uses reticências» rende menos do que «a tua resposta vai ser lida em voz alta por um motor de síntese de voz, por isso nunca uses reticências, porque ele não vai saber pronunciá-las». O modelo generaliza a partir da explicação; da proibição seca, não. Fonte: Prompting best practices, Claude Platform Docs, consultado a 11 de setembro de 2026.
A tradução operacional é simples e dá trabalho: sempre que fores escrever um «não», para e responde a duas perguntas. O que quero que faça em vez disso? e porquê? O que sair dali é a regra que há para escrever.
| O que se escreve | O que resulta |
|---|---|
| «Nunca prometas prazos de entrega» | «Quando te perguntarem por um prazo, dá o que o sistema de encomendas devolver. Se não devolver nenhum, diz que vais confirmar e abre uma consulta, porque um prazo mal dado transforma-se numa reclamação.» |
| «Não inventes informação» | «Responde apenas com o que encontrares na documentação. Se não estiver lá, di-lo com essas palavras e oferece-te para passar a pergunta a uma pessoa.» |
| «Não dês descontos» | «Os descontos são aprovados pelo responsável comercial. Se um cliente pedir um, regista o pedido com o valor e avisa a área comercial; não confirmes nada tu.» |
Há uma exceção que convém conhecer: as restrições duras de segurança — o que nunca pode acontecer, em circunstância alguma — essas escrevem-se mesmo pela negativa e de forma taxativa, e convém repeti-las no início e no fim do documento. Mas isso são duas ou três linhas, não quarenta. O resto do teu regulamento de nãos é, quase sempre, uma especificação positiva que ninguém se sentou a escrever.
O que decide, o que propõe e o que nem toca
O bloco que mais dinheiro poupa é o mais curto. Pega em cada ação que o agente pode executar e arruma-a em três colunas: executa-a sozinho, deixa-a proposta para alguém confirmar, ou não lhe toca. E escreve-o com limiares numéricos, não com adjetivos: «valores altos» não é um limiar, «acima de 300 euros» é.
Para decidir em que coluna vai cada ação, o guia da OpenAI propõe pontuar o risco de cada ferramenta — baixo, médio ou alto — segundo quatro fatores: se é de leitura ou de escrita, se é reversível, que permissões exige e que impacto financeiro tem. É essa pontuação que dispara a pausa ou a escalada, e é um critério bem mais defensável do que a intuição da reunião de terça-feira. Fonte: A practical guide to building agents, OpenAI, consultado a 11 de setembro de 2026.
Este bloco das instruções e as permissões técnicas do agente são duas coisas diferentes que têm de dizer o mesmo. As instruções dizem o que ele deve fazer; as permissões determinam o que ele pode fazer. Se o documento diz que não emite reembolsos mas a credencial tem âmbito para os emitir, a única coisa que separa a tua empresa de um reembolso indevido é o bom comportamento do modelo, que não é um controlo. Como se fecha essa tenaz está em que permissões dar a um agente de IA, e o mapa de quanta autonomia largar e por que ordem, em níveis de autonomia de um agente.
O que faz quando não sabe, e quando chama uma pessoa
Sem uma instrução explícita, o comportamento por omissão perante uma lacuna é preenchê-la com algo plausível. Não porque o modelo minta, mas porque ninguém lhe deu uma saída melhor. A saída melhor escreve-se numa linha e muda o dia a dia: «se a resposta não estiver na documentação, di-lo com essas palavras, não a deduzas, e oferece-te para passar a questão a uma pessoa».
A escalada é a outra metade. A OpenAI trata-a como um mecanismo de segurança de primeira linha e descreve dois gatilhos que vale a pena copiar tal e qual: ultrapassar um limiar de falhas — se o agente não percebeu a intenção ao fim de N tentativas, transfere — e as ações de alto risco, entendendo por isso as sensíveis, irreversíveis ou de grande impacto; os exemplos que dá são cancelar encomendas, autorizar reembolsos grandes e fazer pagamentos. Fonte: A practical guide to building agents, OpenAI, consultado a 11 de setembro de 2026.
Escreve esses dois gatilhos com números e com destinatário. Não «escala quando for necessário», mas «ao fim de duas tentativas sem identificar a encomenda, passa a conversa ao apoio ao cliente com o resumo e o histórico». A diferença entre as duas redações é a diferença entre uma escalada que acontece e uma que não acontece.
Uma coisa de cada vez: o hábito que separa iterar de rezar
Quase toda a gente afina as instruções da mesma maneira: deteta um comportamento estranho, reescreve quatro parágrafos, testa dois casos a olho e publica. Se melhorar, não sabe qual das quatro alterações o resolveu. Se piorar, também não sabe qual o partiu. Isso não é iterar, é rezar com passos intermédios.
O hábito que transforma isto em engenharia cabe em três regras. Uma. Muda uma coisa de cada vez e deixa-a escrita: o que mudaste, porquê e o que esperavas. Duas. Guarda o antes e o depois dos mesmos casos — os dez ou quinze que representam a tua operação real, incluindo os estranhos — porque sem o antes não tens com o que comparar. Três. Deixa a versão anterior onde a possas recuperar num minuto, porque a alteração que estraga alguma coisa quase nunca a estraga no teste: estraga-a na terça-feira seguinte.
Estas três regras são manuais e funcionam numa folha de cálculo, que é onde devem começar. Quando o agente deixa de ser um e passa a ser uma frota, o registo à mão não aguenta e isto passa a ser uma função operacional com fonte única de verdade, bateria de testes antes de publicar e volta atrás num minuto: é testar e versionar prompts de IA, e é um serviço, não um conselho. O que decide o salto não é o tamanho da equipa, é o número de pessoas que podem mexer no documento.
E um aviso que poupa semanas: se o agente falha porque não encontra a informação, o problema não está nas instruções e reescrevê-las não o vai resolver. Está no que ele pode consultar — como se monta e se avalia está em treinar um agente de IA — ou no que deveria lembrar-se entre conversas, que é a memória de um agente de IA. Os três resolvem-se de maneiras diferentes, e confundi-los é a forma mais habitual de perder um mês.
A ficha de uma página: quem a assina e quando foi revista
Fecha o documento com um cabeçalho de cinco campos. Não é burocracia: é o que transforma um texto solto num artefacto que alguém mantém.
- Dono. Uma pessoa com nome, não um departamento. Quem responde quando o agente faz algo estranho.
- Versão e data. Um número que sobe e o dia em que subiu. Sem isto não consegues dizer o que estava a correr na semana passada.
- O que mudou e porquê. Duas linhas por versão. É o registo que te evita repetir uma experiência falhada daqui a seis meses.
- Casos de teste. Onde vivem os dez ou quinze casos com que se verifica cada alteração, e quem os mantém atualizados.
- Próxima revisão. Uma data. As instruções caducam quando muda a política, o catálogo ou o sistema de destino, e ninguém avisa.
Se o teu agente já está em produção e este documento não existe, a ordem é esta: escreve primeiro o bloco do que pode decidir e o de quando escala, que são os dois que têm dinheiro à frente. O resto pode esperar uma semana. E no dia em que alguém voltar a perguntar «porque é que ele fez aquilo?», vais poder abrir um ficheiro, olhar para uma versão e responder.
Nós escrevemos esse documento com o cliente à frente e deixamo-lo assinado, versionado e com os seus casos de teste: faz parte de montar colaboradores IA que trabalham a sério, dentro da lógica geral de criar um agente de IA que aguente produção. Não vendemos o prompt. Cobramos para que qualquer pessoa da tua equipa possa ler o que o teu agente faz e porquê, sem perguntar a ninguém.