@andreias.ai · por baixo do capô

Funcionar é uma coisa. Operar em produção é outra.

O mapa das 10 peças do vídeo, na ordem de construção. As 6 primeiras fazem o agente funcionar; as 4 últimas deixam ele operar em produção. Marque o que o seu já tem: o que ficar em branco é por onde começar. No fim, quatro blocos de código pra copiar.

01System prompt

Vai em toda chamada, antes de qualquer pedido.

Está escrito quem o agente é e o que ele pode fazer. Está escrito o que ele nunca faz. Quando escalar para uma pessoa está definido.

02Decisão

O caminho sai de opções fixas, sem o modelo grande improvisando.

Um classificador recebe o pedido e as opções fixas, e devolve uma delas com a confiança. O limiar de confiança está no código: acima segue, abaixo vai para uma pessoa. O modelo caro só entra quando precisa raciocinar.

03Tool calling

O modelo pede, com nome e argumentos. Quem executa é o seu código.

O agente só alcança as ferramentas de uma lista fechada. O loop guarda o passo, os turnos e o gasto. Existe limite de turnos e de gasto, e o loop para neles.

04Memória

O modelo não lembra de nada. Quem lembra é o sistema.

A memória curta é a janela da conversa e some no fim. A memória longa fica num banco, fora do modelo. Regra, exceção e histórico estão separados, e a regra vence. Toda exceção tem dono, escopo e validade.

05Orquestração

Um orquestrador divide o pedido entre especialistas.

Cada especialista roda no próprio contexto. Cada um devolve só o resultado, sem a conversa inteira. Cada um tem só as ferramentas da sua função.

06Humano no loop

Ação irreversível nunca sai sozinha.

Os limites, como o teto de valor, são regra no código, sem depender da opinião do modelo. Acima do limite, o agente para e pede aprovação. Pagar, enviar e apagar passam por aprovação ou por uma regra explícita. O registro guarda quem aprovou e quando.

07Observabilidade

Quando quebra, você segue o fio até o passo exato.

Cada passo vira um trace: agente, ferramenta, tokens e tempo. Dá pra abrir um pedido e ver a sequência inteira. Existe alerta para erro e para gasto fora do normal.

08Evals

Trocou de modelo? Os evals dizem se piorou.

Existe um conjunto de pedidos reais com a resposta certa. Ele roda a cada mudança de prompt, modelo ou ferramenta. Todo erro de produção vira um caso novo no conjunto.

09Guardrails e segurança

Conteúdo de fora é dado, nunca instrução.

Recibo, e-mail e documento passam por filtro na entrada. O agente tem a permissão mínima para a função dele. O agente nunca aprova o próprio pedido. A saída é conferida antes de chegar ao usuário ou a outro sistema.

10Retry, timeout e idempotência

A API do financeiro vai cair. Planeje pra isso.

Toda chamada externa tem timeout. O retry tem limite e espera crescente, e só repete erro temporário. Toda ação com efeito usa chave de idempotência. Se as tentativas acabarem, o pedido vai para uma pessoa em vez de sumir.

11Exceção não vira regra

O erro do João: a exceção de julho foi lida como regra permanente. Aqui ela vale só para o pedido dela e até a validade. O teto fica no código.

// A regra mora no código. Exceção só vale para o pedido dela e dentro da validade.
export function limiteDe(politica, excecoes, pedido, hoje = new Date()) {
  const valida = excecoes.find((e) => e.pedidoId === pedido.id && new Date(e.validaAte) >= hoje);
  return valida ? valida.limite : politica.teto;
}

export const precisaAprovar = (pedido, limite) => pedido.valor > limite;

12Decisão por opção fixa

Liste as opções do seu fluxo. Confiança abaixo do limiar ou opção fora da lista vai para uma pessoa.

// O classificador devolve uma opção fixa e a confiança. Quem decide o caminho é o código.
const OPCOES = ["reembolso", "duvida", "fora_de_escopo"];

export function rota({ opcao, confianca }, limiar = 0.8) {
  if (!OPCOES.includes(opcao) || confianca < limiar) return "pessoa";
  return opcao;
}

13Loop com limite

Ligue ao seu modelo: ele recebe as mensagens e devolve custo, mais o texto final ou a ferramenta pedida.

// O modelo pede a ferramenta, o seu código executa. O loop guarda turnos e gasto e para no limite.
export async function rodar(modelo, ferramentas, mensagens, { maxTurnos = 10, maxUSD = 0.5 } = {}) {
  let gasto = 0;
  for (let turno = 1; turno <= maxTurnos; turno++) {
    const r = await modelo(mensagens);
    gasto += r.custo;
    if (!r.ferramenta) return r.texto;
    if (gasto > maxUSD) throw new Error("limite de gasto");
    const executar = ferramentas[r.ferramenta.nome];
    if (!executar) throw new Error(`ferramenta fora da lista: ${r.ferramenta.nome}`);
    mensagens.push({ papel: "ferramenta", conteudo: await executar(r.ferramenta.argumentos) });
  }
  throw new Error("limite de turnos");
}

14Pagamento sem duplicar

A chave só protege se a API de destino aceitar idempotência: confira antes e mande a chave no formato dela.

// Timeout corta a espera, retry tenta de novo, e a mesma chave impede pagar duas vezes.
export async function pagar(pedido, chamarApi, tentativas = 3) {
  const chave = `reembolso-${pedido.id}`; // igual em todas as tentativas
  for (let i = 1; ; i++) {
    try {
      return await chamarApi(pedido, { chave, signal: AbortSignal.timeout(5000) });
    } catch (e) {
      if (i >= tentativas || e.status < 500) throw e; // erro 4xx não melhora repetindo
      await new Promise((r) => setTimeout(r, 2 ** i * 200));
    }
  }
}