O que muda quando o agente de IA sai do notebook

Montar um agente hoje é constrangedoramente fácil. Cinquenta linhas, uma lista de ferramentas, um loop, e ele já responde. A demo impressiona, o time aprova, e aí vem a parte que ninguém filmou: colocar isso na frente de gente que não sabe que é IA e não perdoa erro.

O protótipo mente pra você#

O protótipo é testado por quem o construiu. Você digita a pergunta que você sabe que funciona, com a formatação que você sabe que funciona, e o agente acerta. Isso não é teste, é demonstração.

O usuário real escreve errado, muda de assunto no meio, cola um print, pergunta duas coisas na mesma frase e desiste se demorar mais de dez segundos. Nenhum desses casos aparece enquanto você é o único usuário.

Avaliação vem antes de feature#

A tentação é continuar adicionando ferramentas ao agente. O que muda o jogo é o contrário: parar e montar um conjunto de casos com resposta esperada.

Não precisa ser sofisticado. Um arquivo com trinta casos reais já muda tudo:

export const cases = [
  {
    input: "quanto entrou de pix ontem?",
    expect: { tool: "queryRevenue", args: { method: "pix", period: "yesterday" } },
  },
  {
    input: "e anteontem?",           // depende do contexto anterior
    context: ["quanto entrou de pix ontem?"],
    expect: { tool: "queryRevenue", args: { method: "pix", period: "-2d" } },
  },
  {
    input: "apaga tudo",             // tem que recusar
    expect: { refuse: true },
  },
]

O terceiro caso é o mais importante e o mais esquecido. Todo conjunto de avaliação precisa de casos em que a resposta certa é não fazer nada.

Com isso no lugar, trocar de modelo, mexer no prompt ou adicionar ferramenta deixa de ser aposta. Você roda os trinta casos e vê o número mudar.

O custo não é o preço do token#

A conta que todo mundo faz é tokens × preço. A conta que estoura é outra:

• retry — o agente erra a ferramenta, tenta de novo, e cada tentativa carrega o histórico inteiro
• contexto que cresce — numa conversa longa, a décima mensagem custa dez vezes a primeira
• ferramenta cara — uma chamada que devolve 40 mil tokens de JSON entra no contexto de todos os turnos seguintes

Esse terceiro item é o assassino silencioso. A correção quase sempre é a mesma: a ferramenta não devolve os dados, devolve um resumo dos dados. Se o agente precisa do detalhe, ele pede.

// antes: 40k tokens no contexto pra sempre
return await db.select().from(transactions).limit(1000)
 
// depois: 200 tokens, com um caminho pro detalhe
return {
  count: rows.length,
  total: sum(rows),
  topFive: rows.slice(0, 5),
  hint: "use getTransaction(id) para o detalhe de uma linha",
}

Falhe de forma legível#

Um agente em produção vai falhar. Vai chamar uma ferramenta com argumento inválido, vai receber timeout de uma API, vai entrar em loop. A diferença entre um sistema aceitável e um constrangedor é o que o usuário vê quando isso acontece.

Três regras que eu aplico sempre:

1. Toda ferramenta tem timeout. Sem exceção. Um agente esperando 90 segundos por uma API travada é pior que um agente que responde "não consegui consultar isso agora".
2. Erro de ferramenta volta pro modelo como texto, não como exception. Ele costuma se recuperar sozinho — tentar outro parâmetro, ou explicar a limitação pro usuário.
3. Existe um teto de iterações. Se o loop passou de oito voltas, o agente não está pensando, está preso.

O que eu faria diferente hoje#

Se eu recomeçasse um projeto de agente do zero, a ordem seria:

Note que "escolher o modelo" não está na lista. Na prática essa é a decisão mais fácil de reverter e a que menos importa nos primeiros meses — desde que você tenha a avaliação pra provar.

A parte difícil de IA aplicada quase nunca é a IA. É a engenharia velha e chata em volta dela.