Por que seu agente de IA responde bobagem (e como consertar cada causa)

Agente que responde bobagem quase nunca tem problema de modelo. Tem problema de contexto: o que entra na janela, o que fica de fora, como as ferramentas são descritas e o que volta depois de cada chamada.

A tabela abaixo cobre a maioria dos casos que aparecem em produção. Cada linha tem uma correção específica, e nenhuma delas é trocar de modelo.

O que é o contexto, na prática

Toda chamada ao modelo envia um pacote inteiro, do zero. Não existe memória entre requisições. O pacote tem cinco partes:

O system prompt, com papel e regras. As definições de ferramenta, com nome, descrição e schema. O histórico da conversa. Os resultados de ferramenta já executados nessa rodada. A mensagem atual do usuário.

Tudo isso ocupa a janela de contexto e tudo isso é cobrado como token de entrada em cada iteração. Um agente que faz cinco chamadas de ferramenta reenvia o pacote cinco vezes, cada vez maior.

Quando alguém diz que o agente "esqueceu", o que aconteceu foi um destes: a informação nunca entrou no pacote, ou foi cortada por algum truncamento automático.

Memória: o que cabe na janela e o que precisa de banco

Existe uma diferença entre histórico e memória, e misturar as duas coisas é o erro mais caro.

Histórico é a conversa atual. Cresce rápido e precisa de estratégia de corte.

O terceiro item é o que a maioria dos agentes não faz. O nome do usuário, o plano contratado e o último pedido não deveriam depender de o modelo lembrar. Isso é consulta ao banco, feita antes da chamada, injetada no system prompt:

Dados do usuário desta conversa:
nome: Ana
plano: pro
último pedido: PED-1042, entregue em 12/08/2026
Use esses dados. Não peça informação que já está aqui.

Corte de janela deslizante tem uma armadilha: se o corte cair no meio de um par de chamada de ferramenta e resultado, o modelo vê um resultado órfão ou uma chamada sem resposta. Corte sempre em bloco completo.

Ferramentas: a descrição é a documentação

O modelo escolhe ferramenta lendo nome, descrição e schema. Nada mais.

Ruim:

{
  "name": "consultar",
  "description": "Consulta informações",
  "inputSchema": {
    "type": "object",
    "properties": { "texto": { "type": "string" } }
  }
}

Melhor:

{
  "name": "consultar_status_pedido",
  "description": "Retorna o status de entrega de um pedido específico. Use apenas quando o usuário informar um número de pedido no formato PED-0000. Não use para dúvidas sobre prazo geral de entrega.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "numero_pedido": {
        "type": "string",
        "pattern": "^PED-[0-9]{4}$",
        "description": "Número do pedido informado pelo usuário"
      }
    },
    "required": ["numero_pedido"]
  }
}

Três mudanças fizeram diferença: o nome diz o que retorna, a descrição diz quando usar e quando não usar, e o schema restringe o formato do argumento.

Campo com valores fixos merece enum. Isso elimina a categoria inteira de erro em que o modelo inventa um valor plausível que o seu sistema não aceita.

Erro de ferramenta volta como texto, não como exceção

Quando a ferramenta falha, o que volta para o modelo precisa ser instrução, não stack trace.

// ruim
throw new Error('ECONNREFUSED');

// melhor
return {
  erro: 'pedido_nao_encontrado',
  mensagem: 'Nenhum pedido com esse número. Peça ao usuário para conferir o número ou o e-mail da compra.'
};

O modelo lê o segundo formato e faz a coisa certa. O primeiro faz ele tentar de novo com o mesmo argumento, e é assim que nasce loop.

Loop: teto de passos e repetição

Todo agente com ferramenta precisa de dois limites no código, não no prompt:

const MAX_PASSOS = 8;
const chamadasFeitas = new Set();

for (let passo = 0; passo < MAX_PASSOS; passo++) {
  const resposta = await chamarModelo(contexto);
  if (!resposta.usouFerramenta) return resposta.texto;

  const chave = `${resposta.ferramenta}:${JSON.stringify(resposta.argumentos)}`;
  if (chamadasFeitas.has(chave)) {
    // mesma chamada com o mesmo argumento: cortar
    contexto.push(aviso('Essa consulta já foi feita e o resultado está acima. Responda com o que já tem.'));
    continue;
  }
  chamadasFeitas.add(chave);
  contexto.push(await executar(resposta));
}

return 'Não consegui concluir. Encaminhando para atendimento humano.';

O caminho de saída importa tanto quanto o limite. Agente que estoura o teto precisa entregar algo ao usuário, nem que seja o encaminhamento.

Nem tudo deve ser decisão do modelo

Roteamento com regra clara é código, não prompt. Se a mensagem contém número de pedido, chame a ferramenta de status direto. Se o usuário digitou "falar com humano", encaminhe sem passar pelo modelo.

Deixar o modelo decidir o que um if resolve gera latência, custo e variação sem ganho nenhum.

Avaliação: 20 casos fixos

Sem conjunto de teste, cada ajuste de prompt é aposta. Monte uma lista de 20 entradas com a saída esperada, cobrindo o caso comum, o caso limite e o caso que já deu problema em produção. Rode a lista inteira a cada mudança de prompt, de ferramenta ou de modelo.

Vinte casos numa planilha já pegam a maior parte das regressões. O padrão que se repete é ajustar o prompt para consertar um caso e quebrar três que funcionavam, sem ninguém perceber por semanas.

Custo: cada iteração reenvia tudo

Como o pacote inteiro vai junto a cada passo, agente com muitas iterações custa mais do que a conta ingênua sugere. Dois mecanismos da API da Anthropic mudam essa matemática.

Cache de prompt: leitura de trecho em cache custa 10% do preço de entrada. System prompt grande e definições de ferramenta são exatamente o tipo de conteúdo que se repete em toda chamada.

Batch: processamento assíncrono sai por metade do preço de entrada e de saída. Serve para o que não precisa de resposta imediata, como classificação em lote e enriquecimento de base.

Escolha de modelo também é alavanca. Classificar intenção e extrair campo de texto não exige o modelo mais caro do catálogo. Deixe o modelo maior para a etapa que precisa de raciocínio e use o menor no resto.

Ordem de investigação

Quando o agente errar, siga esta ordem antes de mexer no prompt:

Imprima o pacote exato enviado ao modelo. Metade dos casos se resolve aqui, porque o dado que você jurava estar lá não estava.

Confira se o resultado da ferramenta voltou ao contexto.

Leia a descrição da ferramenta como se você fosse o modelo, sem saber nada do seu sistema.

Só depois disso ajuste a instrução.