Orquestração de agentes de IA em produção

O agente unico com um prompt gigante e todas as tools no mesmo contexto e a arquitetura que mais rapido chega na demo e mais rapido quebra em producao. O contexto incha, o modelo confunde qual tool usar, o custo por chamada explode porque tudo entra no prompt, e uma tarefa que precisa de dez passos vira uma sequencia de decisoes onde qualquer erro no meio contamina o resto. Nao existe onde intervir: e uma caixa preta que ou acerta tudo ou erra tudo.

Orquestrar e quebrar essa caixa preta em partes com responsabilidade unica. Um agente que so classifica intencao. Um que so consulta a base. Um que so redige a resposta. Um supervisor que decide a ordem. Cada parte tem contexto menor, prompt focado, tools limitadas e ponto de observacao proprio. Quando algo falha, voce sabe qual agente falhou e por que, em vez de reprocessar a conversa inteira tentando adivinhar. E a mesma logica de quebrar um monolito em servicos, aplicada ao raciocinio.

Nao existe um jeito unico de orquestrar. Ha tres padroes base, e a maioria dos sistemas reais combina os tres. Escolher o padrao certo por etapa e o que separa uma orquestracao enxuta de uma que gasta o dobro de tokens sem ganho.

Na pratica voce aninha os padroes. O supervisor roteia para um pipeline; dentro do pipeline, um passo faz fan-out para tres consultas paralelas e agrega. A regra e usar paralelo so quando as sub-tarefas sao de fato independentes (senao voce paga o custo sem ganhar latencia) e usar supervisor so quando ha divergencia real de intencao (senao um pipeline fixo e mais barato e mais previsivel).

O erro mais caro em agentes de producao e tratar o estado como algo que vive na memoria do processo. Uma tarefa de agente pode levar segundos ou minutos, chamar varias tools e sobreviver a um deploy no meio. Se o estado esta so na RAM, qualquer restart perde o progresso, e voce ou reprocessa tudo (caro, e as tools com efeito colateral rodam duas vezes) ou perde a tarefa. Estado duravel significa persistir cada passo concluido, de forma que o orquestrador consiga retomar exatamente de onde parou.

// orchestrator/state.js
// Estado da execucao persistido por passo. A chave e o runId;
// cada passo concluido e gravado antes de avancar, para retomar apos falha.

export function createRun(store, runId, input) {
  return store.put(runId, {
    runId,
    input,
    status: 'running',
    step: 0,
    // Historico append-only: cada entrada e um passo ja concluido.
    history: [],
    createdAt: null, // preenchido pela store, evita depender de relogio aqui
  });
}

// Grava o resultado de um passo ANTES de chamar o proximo agente.
// Assim, se o processo morrer no passo N+1, o passo N nao se perde.
export async function commitStep(store, runId, stepResult) {
  const run = await store.get(runId);
  run.history.push(stepResult);
  run.step += 1;
  await store.put(runId, run);
  return run;
}

// Ao reiniciar, retoma do ponto salvo em vez de recomecar do zero.
export async function resume(store, runId, agents) {
  const run = await store.get(runId);
  if (run.status !== 'running') return run;
  // O proximo agente e decidido pelo passo atual, nao pela memoria perdida.
  const next = agents[run.step];
  if (!next) return finish(store, run);
  return next.run(run);
}

A consequencia pratica: tools com efeito colateral (enviar mensagem, cobrar, criar pedido) precisam ser idempotentes ou registradas como concluidas no estado, para que a retomada nao dispare a mesma acao de novo. Persistir o passo antes de avancar, e nao depois, e o detalhe que garante que a retomada nunca pule nem repita um passo critico.

A tool e onde o agente toca o mundo real, e por isso e onde mais falha. API externa cai, responde lento, devolve payload fora do contrato ou retorna erro transitorio. Um agente de producao nunca chama uma tool crua: ele envolve toda chamada em timeout, retry com backoff, validacao de saida e um caminho de degradacao para quando a tool falha de vez. Sem isso, uma unica API instavel derruba a execucao inteira.

// orchestrator/tool-runner.js
// Executa uma tool com timeout, retry com backoff e validacao de saida.
// Isola a falha da tool para que o orquestrador decida o que fazer.

export async function runTool(tool, args, opts = {}) {
  const { retries = 2, timeoutMs = 8000, backoffMs = 500 } = opts;

  for (let attempt = 0; attempt <= retries; attempt += 1) {
    try {
      const result = await withTimeout(tool.execute(args), timeoutMs);
      // Valida o contrato ANTES de devolver ao agente.
      if (!tool.validate(result)) {
        throw new Error('tool_output_invalid');
      }
      return { ok: true, result, attempts: attempt + 1 };
    } catch (err) {
      const transient = isTransient(err);
      // So faz retry em erro transitorio; erro de contrato nao adianta repetir.
      if (!transient || attempt === retries) {
        return { ok: false, error: err.message, attempts: attempt + 1 };
      }
      // Backoff exponencial simples entre tentativas.
      await sleep(backoffMs * 2 ** attempt);
    }
  }
}

function withTimeout(promise, ms) {
  return Promise.race([
    promise,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('tool_timeout')), ms),
    ),
  ]);
}

O ponto sutil: retry so faz sentido em erro transitorio (timeout, 503, conexao caiu). Erro de contrato ou 4xx nao melhora repetindo, so queima tempo e tokens. E quando a tool falha de vez, o orquestrador precisa de um plano B explicito: responder com o que tem, escalar para humano, ou marcar a tarefa como parcial. O agente nunca deve inventar o resultado de uma tool que falhou, porque ai a falha vira alucinacao silenciosa, que e pior que o erro visivel.

Agente sem limite e um gerador de custo. Ele pode entrar em loop chamando a mesma tool, raciocinar em circulos, ou expandir o contexto ate estourar o limite do modelo. Producao exige guardrails duros que cortam a execucao antes de virar prejuizo. Esses limites nao sao opcionais nem "para depois": sao o que impede uma unica tarefa de consumir o orcamento de mil.

• Limite de passos: um teto de iteracoes por execucao (por exemplo, 12). Ao atingir, o orquestrador para e devolve o melhor resultado parcial em vez de rodar para sempre.
• Orcamento de tokens por tarefa: some os tokens de todos os passos e aborte se passar do limite. Uma tarefa que ja gastou o esperado provavelmente esta em loop.
• Deteccao de repeticao: se o agente chama a mesma tool com os mesmos argumentos duas vezes seguidas, e sinal de loop; interrompa e mude de estrategia.
• Timeout de ponta a ponta: alem do timeout por tool, um teto de tempo total da tarefa, para nada ficar pendurado indefinidamente segurando recurso.
• Confianca minima para agir: em acao com efeito colateral, exija que o agente esteja acima de um limiar de certeza; abaixo dele, escale para humano em vez de arriscar.

A filosofia e simples: prefira falhar de forma visivel e barata a ter sucesso caro e imprevisivel. Um limite atingido e um evento observavel que voce investiga e ajusta; um loop sem limite e uma fatura no fim do mes que ninguem entende. Cada guardrail que dispara deve virar log e metrica, para voce saber quais tarefas batem no teto e por que.

Orquestracao sem tracing e impossivel de depurar. Quando uma tarefa da errado, voce precisa ver a arvore inteira: qual agente rodou, qual tool chamou, o que cada passo custou em tokens e latencia, onde parou. Sem isso, todo bug vira arqueologia. O modelo mental certo e o de tracing distribuido: cada execucao e um trace, cada passo de agente ou tool e um span aninhado, com atributos de custo e resultado.

Trace de uma execucao orquestrada

  Run abc123  (tarefa: "trocar meu pedido")
    |
    +-- span: supervisor            12 tok-in / 40 tok-out   90ms
    |     roteou -> agente "pedidos"
    |
    +-- span: agente pedidos        320 tok-in / 85 tok-out  240ms
    |     |
    |     +-- span: tool getOrder   ok    retry=0            310ms
    |     +-- span: tool checkStock ok    retry=1            720ms  <- lenta
    |
    +-- span: agente redator        410 tok-in / 190 tok-out 300ms
    |
    v
  status: ok    total: 632 tok-out   custo: US$ 0,004   1,66s

1. Gere um runId por execucao e propague em todos os passos, para amarrar o trace inteiro a uma tarefa.
2. Emita um span por agente e por tool, com tokens de entrada e saida, latencia, numero de retries e status.
3. Registre a decisao do supervisor: para qual agente roteou e por que, senao o roteamento vira caixa preta.
4. Agregue custo e latencia por execucao e por tipo de tarefa, para achar qual jornada esta cara ou lenta.
5. Alerte em sinais que importam: taxa de tarefas que batem o limite de passos, retries de tool acima do normal, custo por tarefa subindo.

Com o trace, um problema que seria horas de adivinhacao vira minutos: voce abre a tarefa que falhou, ve que a tool checkStock deu retry e estourou o timeout, e sabe exatamente onde agir. Sem o trace, voce so tem "o bot respondeu errado" e nenhum caminho ate a causa. Observabilidade nao e enfeite; e o que torna a orquestracao operavel.

A boa noticia e que voce nao precisa de um framework pesado para chegar la. Um orquestrador de producao cabe em poucas pecas bem definidas, e a maioria dos frameworks so embrulha esses mesmos conceitos. O caminho pratico e evoluir o prototipo por camadas, adicionando confiabilidade sem jogar fora o que ja funciona.

• Comece separando o agente unico em papeis: extraia o roteamento e um ou dois especialistas antes de otimizar qualquer coisa.
• Adicione estado duravel cedo: e o que mais dificulta refatorar depois, porque muda a forma como cada passo e chamado.
• Envolva toda tool no runner com timeout e retry desde o primeiro dia; e barato de adicionar e caro de esquecer.
• Ponha os guardrails de passo, custo e timeout antes de abrir para trafego real, nunca depois do primeiro susto de fatura.
• Instrumente o tracing junto com a primeira versao orquestrada; retro-encaixar observabilidade e sempre mais trabalhoso que nascer com ela.

A diferenca entre o agente de demo e o de producao nao esta na inteligencia do modelo, esta na engenharia ao redor dele: coordenacao clara, estado que sobrevive a falha, tools blindadas, limites que cortam o desperdicio e tracing que te deixa enxergar. Quem trata isso como detalhe descobre o custo em producao, no pior momento possivel.