Agentes multi-step: arquitetura de orquestração que sobrevive em produção

Onboarding completo de funcionário, conciliação financeira, abertura de processo regulatório — esses são casos onde o agente executa uma cadeia de 5-15 passos com decisões intermediárias. É onde mora o ROI mais alto e a complexidade mais traiçoeira.

Por que multi-step é diferente

• Cada passo tem latência → fluxo total fica longo (10s-2min comum).
• Cada chamada externa pode falhar → tratamento explícito.
• Estado intermediário precisa persistir → checkpoint obrigatório.
• Erro no passo 4 pode exigir desfazer passos 1-3 → padrão Saga.
• Decisão "próximo passo" é dinâmica → planning real, não DAG fixo.
• Observabilidade simples não basta → trace estruturado.

Padrão de planning explícito

Antes de executar, o agente declara o plano. Em pseudocódigo:

1. Input: "abrir processo regulatório X"
2. Plan generation: Gemini 2.5 Pro produz JSON com passos previstos
3. Validation: schema + dependência + permissão por passo
4. Execution loop: para cada passo, execute → validate → checkpoint
5. On failure: replan (decide próximo passo com contexto de falha)
6. On success: report + audit log

Por que importa: planning explícito permite (a) review humano antes de execução em casos de risco, (b) replanejamento em vez de loop infinito, (c) audit do que o agente tentou fazer.

Idempotência por padrão

Cada tool e cada passo precisa ser idempotente — re-executar com mesmos parâmetros não cria efeito duplo.

Como garantir:

• Chaves de idempotência em criação de recurso (UUID v4 derivado da intenção + step).
• Verificar antes de criar: "se já existe ticket para esse caso, vincular em vez de criar".
• Operações com PUT/upsert em vez de POST quando possível.
• Retry com mesmo idempotency key.

Sem isso, retry após timeout duplica registros — pesadelo em ERP/CRM.

Padrão Saga (compensação)

Quando passo N falha após passos 1..N-1 terem efeito real, agente precisa desfazer em ordem reversa. Cada passo declara compensação correspondente.

Exemplo de onboarding de funcionário:

Se passo 4 falha, agente roda compensação 3 → 2 → 1 e reporta. Estado consistente, sem "usuário órfão".

Checkpoint de estado

Persistir estado a cada passo concluído permite (a) retomar após falha sem refazer tudo, (b) continuar após reinício de processo, (c) auditar progresso em tempo real.

Padrão: tabela agent_executions em Firestore/Spanner com:

• execution_id, agent_name, user_id, started_at.
• plan_json (versionado).
• steps[] com status, input, output, timestamp, latency.
• compensations[] já executadas.
• final_status, final_output.

Cloud Workflows também serve para orquestração explícita; em casos com lógica dinâmica, mantenha em código + estado próprio.

Observabilidade: trace, não só log

Em multi-step, log linear não basta. Use:

• Trace distribuído (OpenTelemetry → Cloud Trace): cada passo é span, com pai = execução.
• Atributos: tool chamada, modelo, tokens in/out, latência, custo.
• Eventos (não logs soltos): "plan_generated", "step_started", "step_failed", "compensation_started".
• Dashboards por agente: latência p50/p95/p99 por passo, taxa de falha por tool, custo por execução.
• Alertas: latência > X, taxa de falha > Y, custo médio acima do baseline.

Decisão dinâmica: ReAct vs DAG

DAG fixo: passos determinados em design time. Mais previsível, mais auditável, menos flexível. Bom para processos estáveis (KYC, onboarding padrão).

ReAct (reason-act loop): agente decide próximo passo a cada iteração, com base em resultado anterior. Mais flexível, menos previsível, exige guardrails de loop e custo.

Padrão Autenticare: comece com DAG. Migre para ReAct apenas onde casos justificam variabilidade alta. Híbrido funciona — esqueleto DAG com sub-agente ReAct em pontos definidos.

Limites de loop

ReAct sem limite vira agente em loop infinito (ou "agent loop" gastando tokens). Sempre:

• Max iterations hard cap (ex.: 12 passos).
• Max tool calls por execução.
• Max custo por execução (token budget).
• Detecção de loop: se mesmo tool com mesmo parâmetro 2x, alerta + escalação.

Hand-off humano

Em qualquer passo, se confiança baixa ou ambiguidade alta, agente deve poder pausar e pedir input humano:

• Persistir estado completo.
• Notificar humano (Slack, e-mail, fila).
• Aguardar resposta com timeout.
• Retomar ou cancelar conforme decisão.

É o que separa "agente que tenta tudo" de "agente que tem maturidade de pedir ajuda".

Stack que usamos em projetos Autenticare

• Vertex AI Agent Builder: definição do agente + tools.
• Cloud Run jobs: orquestração estável, longa duração.
• Firestore: estado de execução.
• Pub/Sub: hand-off assíncrono e notificação.
• Cloud Trace + Looker: observabilidade.
• BigQuery: análise histórica e auditoria.

Erros comuns

1. Sem idempotência → retry duplica registro.
2. Sem compensação → estado inconsistente.
3. Sem max iterations → loop infinito.
4. Sem checkpoint → reexecuta tudo após falha de infra.
5. Sem hand-off → agente "trava" em decisão fora do escopo.
6. Sem trace → debug vira arqueologia em log.

Agente que pede ajuda é mais maduro que agente que tenta tudo. Hand-off humano em caso de baixa confiança não é fraqueza — é arquitetura.

Leia também

• Case KYC banco médio (8 passos)
• Case triagem seguradora
• RAG corporativo