Como criar um agente de IA que sobrevive à produção

1. Decida se o caso pede agente ou pipeline

Agente é caro em latência, custo e superfície de falha. Antes de escrever a primeira linha, verifique se o problema tem ramificação real de decisão. Se o fluxo é sempre A depois B depois C, você quer um workflow determinístico com uma ou duas chamadas de LLM dentro dele — não um agente.

O critério prático: se você consegue desenhar o fluxograma completo sem usar a palavra "depende", não é agente. Agente se justifica quando o número de caminhos possíveis é grande demais pra codificar e o custo de errar é recuperável.

• Pipeline: extração de dados, classificação, resumo, enriquecimento em lote.
• Agente: triagem com follow-up, suporte que consulta vários sistemas, pesquisa iterativa, operações que exigem verificação antes de escrever.

2. Modele as ferramentas antes do prompt

As capacidades do agente são exatamente o conjunto de funções que você expõe. Cada função precisa de schema tipado, descrição escrita para o modelo (não pro dev), validação de entrada e erros legíveis — o modelo lê a mensagem de erro e tenta de novo, então um "500 Internal Server Error" desperdiça um ciclo inteiro.

Separe leitura de escrita. Ferramentas de leitura podem ser liberadas; ferramentas de escrita passam por confirmação, idempotency key e log de auditoria.

const buscarPedido = {
  name: "buscar_pedido",
  description:
    "Retorna status, itens e prazo de um pedido. Use quando o cliente citar número de pedido.",
  parameters: z.object({
    pedidoId: z.string().regex(/^\d{6,10}$/),
  }),
  handler: async ({ pedidoId }, ctx) => {
    const pedido = await db.pedido.find(pedidoId, { tenant: ctx.tenantId });
    if (!pedido) {
      return { erro: "Pedido não encontrado para este cliente. Peça o número novamente." };
    }
    return pick(pedido, ["status", "itens", "prazoEntrega"]);
  },
};

3. Escolha o loop de controle

Três topologias cobrem quase tudo. Agente único com ferramentas resolve 80% dos casos e é o que você deve tentar primeiro. Orquestrador com sub-agentes especializados vale quando os domínios têm prompts e ferramentas incompatíveis entre si. Grafo de estados explícito vale quando o processo tem etapas obrigatórias auditáveis.

Em qualquer topologia, imponha teto de iterações, timeout por ferramenta e timeout global. Um agente sem teto de loop é um incidente esperando data.

4. Memória: contexto, sessão e conhecimento

Confundir os três tipos de memória é a causa mais comum de agente caro e confuso. Contexto é a janela da chamada atual e deve ser montada, não acumulada. Sessão é o estado da conversa, guardado em banco e resumido quando passa de um limite. Conhecimento é o que o agente busca sob demanda via recuperação.

Para conhecimento, RAG com embeddings resolve busca semântica em documentação; consulta SQL direta resolve dado estruturado e é mais barata, mais rápida e auditável. Muita gente coloca em vetor o que devia ser um SELECT.

• Contexto: system prompt + últimas N mensagens + resultados de ferramenta da rodada.
• Sessão: histórico persistido, resumo rolante, entidades já identificadas.
• Conhecimento: pgvector para texto, banco relacional para fato, cache para o que repete.

5. Guardrails e segurança

Trate toda saída do modelo como entrada não confiável. O agente pode ser induzido por conteúdo que ele lê — um e-mail, uma página, um PDF do cliente — a chamar ferramentas que você não pretendia. A defesa não é prompt melhor, é autorização no handler.

Cada chamada carrega o tenant e o usuário do contexto de execução, nunca argumentos vindos do modelo. Escopo de dados é resolvido no servidor. Operações destrutivas exigem confirmação humana ou passam por fila de aprovação.

• Nunca aceite tenantId, userId ou role como parâmetro de ferramenta.
• Rate limit por sessão e por conta, não só global.
• Filtro de PII na entrada de log e no que sai pro provedor.
• Kill switch por ferramenta, ativável sem deploy.

6. Avaliação: o que separa engenharia de tentativa e erro

Sem conjunto de avaliação, você não consegue trocar de modelo, ajustar prompt ou reduzir custo sem risco. Monte de 30 a 100 casos reais com resultado esperado, rode em CI a cada mudança e acompanhe três métricas: acerto de tarefa, escolha correta de ferramenta e custo médio por execução.

Para saída aberta, use um modelo juiz com rubrica escrita e amostragem humana semanal. Não persiga 100%: defina o patamar aceitável e o comportamento de fallback abaixo dele.

7. Custo e latência como requisito de projeto

Custo de agente cresce de forma não linear: cada iteração recarrega o contexto inteiro. Duas alavancas resolvem a maior parte — reduzir o que entra no contexto e rotear por complexidade, com modelo pequeno na triagem e modelo grande só quando a tarefa exige.

Meça custo por conversa resolvida, não por token. É a única métrica que se compara ao custo do processo manual que o agente substitui.

• Cache de prompt para o system prompt estável.
• Streaming para percepção de latência, com ferramentas em paralelo quando independentes.
• Teto de gasto por sessão, com degradação controlada em vez de conta surpresa.

8. Operação: observabilidade e rollout

Cada execução precisa de trace completo: mensagens, ferramentas chamadas, argumentos, latência, tokens e desfecho. Sem isso, depurar agente vira arqueologia.

Suba com escopo pequeno e caminho de escape claro. Um agente que passa o bastão pra um humano quando não tem certeza gera mais confiança do que um que responde qualquer coisa com convicção.