O que é um prompt agêntico?

Um prompt agêntico é a instrução escrita para um modelo que vai agir várias vezes seguidas, não responder uma vez. Ele carrega quatro seções que um prompt de tarefa única não tem: o catálogo de ferramentas, o critério de parada, o que fazer quando uma chamada falha e o orçamento de passos. Sem essas quatro o loop roda. Ele só não termina.

A diferença nasce do formato. Dentro de um agente de IA o seu texto não é lido uma vez: ele volta ao modelo em toda iteração, junto com um histórico que cresce a cada volta. Escrever para isso se parece mais com escrever a política de um cargo do que com escrever um pedido, e é por essa razão que quase todo prompt agêntico mora no system prompt e não na mensagem do usuário.

Duas consequências aparecem cedo. Ambiguidade não se dilui, ela se acumula: uma frase que pode ser lida de dois jeitos vai ser lida dos dois jeitos ao longo de trinta iterações. E boa parte do que você tem vontade de escrever não deveria estar no prompt. Regra que precisa valer sempre pertence a um guardrail no código; o system prompt de produção fica com o que é orientação, não com o que é lei.

As quatro seções que um prompt comum não tem

Os exemplos abaixo saem de um agente que investiga falha de pipeline de dados, com três ferramentas: listar_execucoes, ler_log e reprocessar_particao.

Política de ferramenta, não lista de ferramenta

A assinatura de cada ferramenta você declara na API, e o modelo recebe isso pronto. O que falta, e vai no prompt, é a política de uso: qual escolher quando duas servem, qual nunca chamar antes de outra, qual exige confirmação humana.

listar_execucoes e ler_log respondem perguntas parecidas e custam coisas muito diferentes. Se o prompt não disser que a listagem vem primeiro, o modelo puxa um log de 40 MB para descobrir que o job nem chegou a rodar. Escreva a política em negativo sempre que der: “nunca chame reprocessar_particao sem ter lido o log da execução que falhou” sobrevive a trinta iterações. “Use as ferramentas com bom senso” não sobrevive a uma.

Uma definição de pronto que o seu código consiga verificar

Um prompt comum termina quando a resposta sai. Um agente precisa de uma definição explícita de terminado, e ela raramente pode ser “o modelo achou que acabou”.

“Pare quando tiver a partição que falhou e a mensagem de erro dela, ou depois de ler três logs sem encontrar erro nenhum” é verificável. “Pare quando resolver” não é. A diferença prática é quem julga: na primeira frase o julgamento cabe ao seu código, que consegue conferir se os dois campos existem; na segunda ele cabe ao modelo.

E o modelo é ruim justamente nisso. Um trabalho de 2023 testou a autocorreção intrínseca, sem feedback externo, e encontrou o oposto do esperado: em tarefas de raciocínio o desempenho não melhorou depois da revisão e em alguns arranjos piorou, porque o modelo não tem como saber que errou¹. O resultado é sobre raciocínio, não sobre agentes, mas a implicação atravessa: autoavaliação serve como um sinal entre outros e não serve como o único.

O que fazer quando a ferramenta falha

Esta é a seção que quase ninguém escreve e é a que mais muda a trajetória. Sem ela, o comportamento padrão diante de um erro é repetir a mesma chamada, e depois repetir de novo.

Escreva por classe de erro, não por caso. Erro de argumento: corrija o argumento e tente uma vez. Erro transitório de rede: tente uma vez e siga para outra abordagem. Permissão negada: pare e relate, nunca contorne. Vazio que não é erro (a lista veio sem nada): isso é uma resposta, trate como resposta. Quatro linhas cobrem a maior parte do que acontece em produção e economizam dezenas de iterações gastas em teimosia.

O orçamento, escrito onde o modelo vê

O teto rígido de passos vive no seu código, e é ele que efetivamente interrompe. Mas escrever o orçamento também no prompt muda o comportamento antes do limite: “você tem no máximo 12 chamadas de ferramenta para esta investigação” faz o modelo priorizar cedo em vez de varrer.

Vale dizer o que fazer ao chegar perto do fim. Sem instrução, um agente que estoura o orçamento simplesmente para no meio, e o que você recebe é um contexto truncado. Com “ao chegar em 10 chamadas, escreva o relatório com o que tiver e marque como incompleto”, você recebe um resultado parcial que alguém consegue usar.

O prompt é lido quarenta vezes, não uma

Todo texto que você escreve no system prompt é reenviado em cada iteração. Isso tem três efeitos que não existem em prompt de tarefa única.

O primeiro é de custo. Uma seção de 300 tokens que você acrescentou “porque não custa nada” custa 300 tokens vezes o número de iterações. Em vinte passos são 6 mil tokens de entrada, e o prompt caching corta o preço dessa repetição sem tirá-la do lugar. Ela continua ocupando janela.

O segundo é de contradição. Num prompt de uma chamada, duas instruções levemente incompatíveis produzem uma resposta levemente estranha e ninguém percebe. Num agente, a mesma incompatibilidade é resolvida de novo a cada volta, às vezes para um lado e às vezes para o outro, e o resultado aparece como comportamento errático que se atribui ao modelo.

O terceiro é de posição. Na iteração 1 a sua instrução é quase todo o contexto. Na iteração 18 ela é uma fração pequena dele, cercada de resultados de ferramenta que chegaram depois. Modelos não leem a janela de forma uniforme, e o que está no meio recebe menos atenção do que o que está nas pontas. Restrição que precisa valer até o fim ou é reinjetada perto da última mensagem, ou vira validação dentro da ferramenta, onde não depende de leitura nenhuma.

Regra de domínio é a parte que mais escorrega

Escrever “siga a política de reembolso” e testar uma vez com sucesso dá uma sensação de resolvido que não se confirma na repetição.

O τ-bench, publicado em 2024, foi montado para medir exatamente isso: um agente com ferramentas de domínio e um documento de política conversando com um usuário simulado, avaliado pela comparação entre o estado final do banco de dados e o estado esperado. Os autores propuseram uma métrica de consistência, pass^k, que é a taxa de sucesso em todas as k tentativas da mesma tarefa. Agentes de função calling do estado da arte na época resolveram menos de 50% das tarefas, e no domínio de varejo o pass^8 ficou abaixo de 25%². Oito execuções da mesma tarefa, e em três quartos dos casos pelo menos uma saiu errada.

O número envelhece. O formato do problema não: instrução de política é seguida probabilisticamente, e uma execução bem-sucedida não é evidência de que a regra está sendo respeitada. Se a regra importa de verdade, teste-a k vezes, e o que não puder falhar nenhuma vez não deveria depender de leitura.

A instrução não conserta a interface

Um erro comum de diagnóstico é atribuir ao prompt o que é da ferramenta.

O SWE-agent, de 2024, atacou o problema pelo outro lado: em vez de melhorar a instrução, os autores desenharam a interface entre o agente e o computador, tratando o modelo como uma categoria nova de usuário com necessidades próprias. Comandos de edição com feedback imediato de erro de sintaxe, visualização de arquivo em janelas de tamanho controlado, mensagens de retorno escritas para serem lidas por um modelo. Com essa interface, o sistema alcançou 12,5% de pass@1 no SWE-bench, bem acima do que se obtinha com modelos não interativos até ali³.

A lição que interessa aqui é a divisão de trabalho. Se ler_log devolve 3.000 linhas cruas, nenhuma redação de prompt vai salvar a trajetória: o contexto enche na iteração 6. Corte a saída na ferramenta, devolva as 20 linhas em volta do erro e o prompt fica curto porque não precisa mais compensar nada.

A mesma lógica vale para o formato da ação. Um trabalho de 2024 mostrou que deixar o agente emitir código Python executável, em vez de JSON num formato fixo, dá um espaço de ação mais expressivo, permite compor várias ferramentas numa tacada e revisar a ação anterior diante de uma observação nova, com até 20 pontos a mais de taxa de sucesso nas comparações deles⁴. É uma decisão de harness, e ela muda o que o prompt precisa explicar.

Onde falha

“Continue até resolver” é a instrução mais cara que existe. Ela combina duas coisas ruins: uma condição que só o modelo pode julgar e nenhum teto. Diante de um erro que não vai passar, um servidor fora do ar, uma permissão que ele não tem, o agente continua tentando. O ciclo da figura é literal, e ele para quando alguém percebe a fatura.

Prompt longo demais na primeira versão. É tentador escrever quarenta regras antes da primeira execução. Elas vão brigar entre si, você não vai saber qual está sendo obedecida e cada uma custa contexto em toda iteração. Comece com o mínimo e acrescente regra quando uma trajetória real mostrar a falta.

Regra escrita no lugar errado. “Nunca reprocesse uma partição do mês anterior” no prompt é uma sugestão forte. A mesma regra dentro de reprocessar_particao, recusando com uma mensagem clara, é uma garantia. A diferença aparece na iteração 30, quando a frase já está longe.

Exemplo que ocupa a janela inteira. Colar uma trajetória de vinte passos como demonstração parece bom e sai caro: ela é reenviada sempre e empurra o histórico real para o meio do contexto. Fragmento de chamada difícil rende mais que execução completa.

Otimizar o prompt sem ler a trajetória. A maior parte das falhas atribuídas à redação aparece no registro como resultado de ferramenta truncado ou como mensagem de erro que não dizia nada. Reescrever o prompt sem olhar isso é adivinhação com etapa extra.

Como escrever, na ordem

1. Escreva a definição de terminado antes de escrever a tarefa. Se você não consegue descrever o estado final em termos que o seu código confira, o agente também não vai conseguir.
2. Liste o que ele nunca pode fazer. Essa lista é curta, você escreve em dez minutos, e ela é a única parte do prompt que deve ter espelho no código.
3. Escreva a política de ferramenta em duas linhas por ferramenta. Quando usar e quando não usar. Se precisar de mais que isso, o problema é a ferramenta.
4. Cubra as quatro classes de erro. Argumento inválido, falha transitória, permissão negada, resultado vazio. Uma linha para cada.
5. Ponha o orçamento e o que fazer ao chegar nele. Doze chamadas é um começo razoável, e você ajusta com dado.
6. Rode a mesma tarefa oito vezes antes de mudar qualquer coisa. Uma execução boa não é evidência. Duas trajetórias divergentes na mesma tarefa mostram qual frase está sendo lida de dois jeitos.

O passo 6 é o que separa quem melhora um prompt agêntico de quem o reescreve inteiro toda semana.

Quanto custa uma seção a mais

Suponha um agente com system prompt de 1.500 tokens, catálogo de cinco ferramentas com 1.200 e uma tarefa que resolve em quinze iterações. Os 2.700 tokens fixos vão em todas as quinze chamadas: 40,5 mil tokens de entrada só de instrução, antes de qualquer histórico.

Acrescentar uma seção de 400 tokens leva o fixo para 3.100, e os quinze passos para 46,5 mil. São 6 mil tokens a mais para uma seção que talvez você use uma vez. Com prompt caching o preço dessa parte cai bastante, porque o prefixo se repete inteiro entre iterações, mas o espaço ocupado na janela continua o mesmo, e é ele que decide em qual iteração o contexto estoura.

A conta que costuma render mais é a do catálogo. Cinco ferramentas descritas em 1.200 tokens custam 18 mil ao longo de quinze passos; quarenta ferramentas no mesmo padrão custam cerca de 144 mil, e as trinta e cinco que ninguém vai chamar custam igual às outras. Reduzir o catálogo é quase sempre a edição mais barata e mais eficaz que existe num prompt agêntico.

Footnotes

1. Huang et al. (2023) encontraram que, sem feedback externo, a revisão da própria resposta não melhora raciocínio e em alguns arranjos degrada o resultado. ↩

2. Yao et al. (2024) mediram consistência com a métrica pass^k: agentes de function calling do estado da arte na época ficaram abaixo de 50% de sucesso e abaixo de 25% de pass^8 no domínio de varejo, seguindo políticas escritas. ↩

3. Yang et al. (2024) mostraram que o desenho da interface entre agente e computador muda o desempenho de forma direta, alcançando 12,5% de pass@1 no SWE-bench com comandos e mensagens de retorno pensados para leitura por um modelo. ↩

4. Wang et al. (2024) compararam ação em código executável contra ação em JSON de formato fixo e mediram até 20 pontos a mais de taxa de sucesso, com a vantagem de compor ferramentas e revisar a ação diante de nova observação. ↩