Estrutura Prática de Prompts para Agentes de Execução Claude IA

Engenharia de Prompts para Agentes de Execução

Um desenvolvedor com meses de experiência construindo agentes Claude AI que executam ações reais—chamadas de API, extração de dados, árvores de decisão de múltiplas etapas e recuperação de erros—compartilha a estrutura de prompt que resolveu problemas persistentes de alucinação. As primeiras tentativas resultaram em agentes alucinando campos, encadeando chamadas de API desnecessárias, ignorando silenciosamente erros e retornando dados parciais como se tudo estivesse bem.

Princípios-chave da Estrutura de Prompts

• Escreva prompts como contratos, não como instruções: Prompts em linguagem natural como "encontre leads relevantes e envie uma mensagem personalizada" convidam à improvisação. O que funciona: definir entradas (esquema exato, tipos, casos extremos), saídas (formato exato incluindo estados de erro) e regras de decisão (se X então Y, se Z então pare).
• Dedique 40% dos seus tokens de prompt ao tratamento de erros: Sem caminhos de erro explícitos, Claude ou tenta infinitamente ou retorna silenciosamente lixo. Cada modo de falha possível precisa de sua própria instrução: o que fazer quando a API retorna um 429, o que fazer quando um campo obrigatório está ausente, o que fazer quando os dados parecem ambíguos.
• Separe "espera" de "parada": Claude não consegue distinguir entre "você ainda não tem informações suficientes para agir" e "as informações estão ruins, aborte" a menos que você especifique ambos os casos. Um agente deveria pausar em dados ambíguos, mas em vez disso pulou tudo que não estava 100% limpo. Adicionar instruções explícitas para ambos os estados melhorou a precisão da noite para o dia.
• Correspondência de padrões > interpretação de papéis: "Você é um engenheiro sênior" faz quase nada pela qualidade da execução. Colar um exemplo real de boa saída e dizer "corresponda exatamente a este padrão" funciona 10 vezes melhor. Claude é melhor em replicar um exemplo concreto do que interpretar uma persona abstrata.
• Roteie por complexidade, não por hábito: Use Opus exclusivamente para decisões de múltiplas etapas onde contexto e casos extremos importam. Todo o resto vai para Sonnet ou Haiku. A maioria das tarefas de agentes não precisa do Opus, e a diferença de custo aumenta rapidamente. Os custos de API passaram de brutais para gerenciáveis com roteamento adequado.
• Force cadeia de pensamento antes de cada ação: Isso custa talvez 15% a mais de tokens, mas quando algo quebra às 2 da manhã, você pode ler exatamente por que o agente decidiu fazer o que fez. Sem isso, você está depurando às cegas.

O desenvolvedor observa que essa estrutura de prompt importa muito mais do que a escolha do modelo para construir agentes que executam ações reais (não apenas geram texto).