Padrão Saga para agentes de IA: guia prático

Um processo pode falhar depois de produzir efeitos reais

Um agente recebe a aprovação para iniciar o onboarding de um cliente. Ele cria o projeto, reserva uma agenda, solicita acessos e envia a confirmação. Na etapa seguinte, descobre que a conta não pode ser provisionada por uma restrição contratual.

Apagar o registro local não desfaz o convite enviado, a agenda reservada nem a tarefa criada para outra equipe. O processo atravessou sistemas independentes, e cada um confirmou seu próprio efeito.

O padrão Saga organiza esse tipo de operação. Ele divide o processo em etapas locais, registra o resultado de cada uma e define o que fazer quando a sequência não consegue avançar. Algumas etapas podem ser compensadas. Outras exigem correção, nova aprovação ou encerramento com efeito residual conhecido.

Para agentes de IA, esse desenho impede que uma execução longa dependa da memória do modelo. Estado, autoridade, confirmação e resposta à falha ficam explícitos no processo.

Qual problema uma Saga resolve

Processos empresariais raramente cabem em uma única transação de banco. Uma jornada pode envolver CRM, agenda, e-mail, documentos, ERP, pagamentos, filas humanas e fornecedores.

Cada sistema possui:

estado próprio;
regra de confirmação;
disponibilidade;
credencial;
prazo;
forma de reversão;
responsável.

Uma falha depois da terceira etapa não devolve automaticamente os dois primeiros sistemas ao estado anterior. Também pode ser errado desfazer tudo. Um documento enviado talvez precise ser invalidado, sem desaparecer. Uma comunicação entregue não pode ser retirada da caixa do destinatário. Um pagamento confirmado pode exigir estorno com alçada, em vez de simples exclusão.

A Saga cria uma máquina de estados para o processo distribuído. Ela registra quais compromissos aconteceram, quais etapas ainda estão pendentes e qual ação segura encerra ou recupera cada cenário.

Saga, rollback e reconciliação são mecanismos distintos

Rollback local

Uma transação de banco pode desfazer gravações que ainda não foram confirmadas. Ela funciona dentro de uma fronteira controlada pelo mesmo sistema.

Compensação da Saga

Uma ação compensatória produz um novo efeito para reduzir ou corrigir o efeito anterior. Cancelar uma reserva, revogar um convite, abrir um estorno e invalidar uma autorização são exemplos.

A compensação deixa histórico. Ela não finge que a primeira ação nunca aconteceu.

Reconciliação

A reconciliação em agentes de IA entra quando o processo desconhece o resultado real de uma etapa ou encontra divergência entre registros. Antes de compensar ou repetir, a arquitetura precisa confirmar o estado.

Contingência

O plano de contingência para agentes de IA mantém capacidade mínima enquanto uma dependência está indisponível. A Saga governa a trajetória de cada unidade distribuída, inclusive durante e depois do modo degradado.

Quando usar o padrão Saga

A Saga faz sentido quando uma responsabilidade:

atravessa dois ou mais sistemas com commits independentes;
pode durar minutos, horas ou dias;
produz efeitos antes da conclusão total;
depende de aprovação ou ação humana;
possui etapas que podem falhar depois de outras confirmarem;
precisa retomar após reinício;
exige compensação, correção ou encerramento parcial;
deve explicar o estado atual para operação e cliente.

Exemplos:

onboarding de cliente;
criação e confirmação de pedido;
devolução com coleta, inspeção e reembolso;
contratação com documentos, acessos e agenda;
cobrança com acordo e atualização financeira;
publicação de campanha com aprovação e canais;
provisionamento de conta e permissões;
geração, assinatura e ativação de contrato.

Para uma leitura simples seguida de uma resposta, a Saga adiciona peso sem benefício. Use-a quando existem compromissos distribuídos e uma falha intermediária deixa trabalho real para trás.

Comece pela unidade de negócio

A Saga precisa representar algo que a empresa reconhece, como onboarding do cliente, devolução do pedido ou ativação do contrato.

Registre:

saga_id;
tipo e versão da Saga;
objeto empresarial;
cliente, conta e ambiente;
evento de início;
estado atual;
etapa atual;
prazo total;
responsável operacional;
responsável técnico;
política aplicada;
aprovações recebidas;
resultado esperado;
condição de encerramento;
correlação com eventos, tarefas e efeitos externos.

Evite usar apenas o ID da execução do agente. Uma execução pode parar e outra continuar a mesma Saga. O processo precisa sobreviver à troca de worker, modelo ou sessão.

Modele etapas como compromissos observáveis

Cada etapa deve ter entrada, comando, confirmação e próximo estado.

Considere uma ativação de cliente:

validar contrato e escopo;
criar projeto no sistema oficial;
solicitar acessos necessários;
reservar sessão de onboarding;
provisionar ambiente;
confirmar primeiro caso de uso;
registrar ativação.

Para cada etapa, documente:

| Campo | Pergunta | |---|---| | pré-condição | o que precisa ser verdadeiro antes de começar? | | comando | qual ação será solicitada? | | autoridade | quem ou qual sistema permite a ação? | | confirmação | que evidência prova o efeito? | | prazo | quanto tempo a etapa pode permanecer aberta? | | repetição | como evitar duplicidade? | | falha conhecida | quais respostas impedem avanço? | | compensação | qual novo efeito reduz ou corrige o anterior? | | dono | quem resolve a exceção? | | próximo estado | para onde a unidade segue? |

A confirmação deve vir do sistema que governa o efeito. Uma frase gerada pelo agente dizendo “projeto criado” não substitui o ID devolvido pela plataforma e a consulta do registro.

Diferencie etapas reversíveis, compensáveis e irreversíveis

Nem todo compromisso permite o mesmo tratamento.

Reversível antes da confirmação

Uma alteração ainda não aplicada pode ser cancelada localmente. Rascunhos e reservas internas costumam permitir esse caminho.

Compensável

O efeito ocorreu, mas existe uma ação autorizada que reduz ou neutraliza seu impacto. Uma agenda pode ser cancelada. Um acesso pode ser revogado. Uma reserva pode ser liberada.

Corrigível

O efeito permanece e recebe uma mudança posterior. Um cadastro enviado com dado errado pode ser corrigido por nova versão. O histórico continua visível.

Irreversível

Uma mensagem entregue, uma decisão comunicada ou uma divulgação externa não volta ao estado anterior. A resposta pode incluir retratação, contato humano, correção pública ou tratamento de incidente.

Condicional

Estorno, cancelamento contratual e exclusão de registro podem depender de prazo, estado, alçada e obrigação aplicável.

Classificar cada etapa antes da automação evita a promessa perigosa de que tudo possui rollback.

Desenhe a matriz de compensação

A matriz liga etapa confirmada, falha posterior e resposta permitida.

Exemplo simplificado:

| Etapa confirmada | Falha posterior | Resposta | Autoridade | Evidência final | |---|---|---|---|---| | projeto criado | contrato inválido | bloquear uso e arquivar projeto | operação | projeto sem atividade e motivo registrado | | agenda reservada | ambiente indisponível | remarcar ou cancelar | responsável pelo cliente | evento atualizado na agenda | | convite enviado | identidade incorreta | revogar convite e avisar responsável | administrador | acesso revogado | | cobrança autorizada | pagamento já confirmado | cancelar intenção antes do envio | financeiro | unidade encerrada sem contato | | pagamento realizado | pedido cancelado | abrir fluxo de estorno | alçada financeira | protocolo e confirmação do estorno |

A compensação também pode falhar. Por isso, ela precisa de estado, tentativas, confirmação e responsável próprios.

Uma matriz útil declara quando a automação pode executar, quando precisa de aprovação e quando a única resposta segura é interromper e escalar.

Escolha entre orquestração e coreografia

Orquestração

Um componente central mantém o estado da Saga, envia comandos e decide a próxima transição com base nas confirmações.

Vantagens:

trajetória legível;
prazos e compensações centralizados;
facilidade para mostrar pendências;
regras de avanço explícitas;
melhor controle sobre agentes e ferramentas.

Riscos:

orquestrador vira componente crítico;
lógica pode crescer demais;
equipes podem concentrar responsabilidades diferentes no mesmo serviço.

Coreografia

Cada serviço reage a eventos e publica novos fatos, sem um coordenador central para toda a sequência.

Vantagens:

menor acoplamento direto;
autonomia entre serviços;
boa aderência quando os domínios e contratos já são maduros.

Riscos:

trajetória difícil de reconstruir;
ciclos e efeitos inesperados;
compensações espalhadas;
responsabilidade ambígua;
debugging dependente de correlação impecável.

Para operações com agentes, aprovações humanas e maturidade inicial, a orquestração costuma deixar o processo mais governável. Coreografia exige contratos de evento, observabilidade e ownership muito bem estabelecidos.

A orquestração de agentes de IA ajuda a separar coordenação, especialização e responsabilidade sem criar uma multidão de agentes autônomos.

Use uma máquina de estados explícita

Estados possíveis para uma Saga incluem:

iniciada;
validando;
aguardando_aprovacao;
executando_etapa;
aguardando_confirmacao;
pausada_dependencia;
resultado_incerto;
compensacao_pendente;
compensando;
compensacao_falhou;
exige_intervencao;
concluida;
concluida_com_ressalva;
cancelada;
encerrada_com_pendencia.

Um campo falhou não informa se existe efeito externo, se a compensação começou ou se uma pessoa precisa decidir.

Cada transição deve declarar:

evento que autoriza a mudança;
estado anterior permitido;
versão esperada;
política e alçada;
efeito solicitado;
evidência exigida;
timeout;
rota de falha;
registro produzido.

O agente pode interpretar conteúdo e preparar opções. Um componente determinístico aplica a transição depois de validar os critérios.

Separe decisão probabilística de compromisso operacional

A IA pode participar da Saga em tarefas como:

classificar a solicitação;
extrair dados de documentos;
resumir histórico;
identificar pendências;
sugerir a próxima rota;
preparar comunicação;
agrupar exceções;
explicar divergências para revisão.

Ela não deve assumir, sem controle externo:

que uma etapa confirmou;
qual compensação financeira executar;
que ausência de resposta equivale a falha;
que um efeito pode ser repetido;
que uma aprovação continua válida depois de mudança;
que um passo irreversível pode ser desfeito;
que a Saga terminou porque o texto parece completo.

A arquitetura transforma a sugestão em comando somente depois de validar dados, estado, versão, permissão e alçada.

Proteja cada etapa com idempotência e concorrência

Uma Saga pode retomar várias vezes. Cada comando precisa de uma chave ligada à unidade e à etapa.

Exemplo:

ativacao_cliente + cliente_id + etapa_provisionar + versao_saga

Repetir a mesma etapa deve retornar a confirmação existente ou retomar a verificação, sem criar outro projeto, agenda ou cobrança.

Controle de concorrência também importa. Uma pessoa pode cancelar o onboarding enquanto o agente tenta avançar. Antes do compromisso, compare a versão da Saga e o estado do objeto oficial.

Se a versão mudou, suspenda o comando e reavalie. A idempotência para agentes de IA protege repetição. A verificação de versão protege uma ação inédita baseada em estado antigo.

Trate timeout como estado, não como resposta final

Um timeout informa que a confirmação não chegou dentro da janela. O efeito pode ter acontecido.

Depois de timeout:

marque a etapa como resultado_incerto;
consulte o destino pelo identificador estável;
espere a janela de consistência quando aplicável;
bloqueie nova execução da mesma consequência;
confirme efeito, falha sem efeito ou ausência de evidência;
encaminhe para reconciliação se a incerteza continuar.

Compensar imediatamente também pode ser perigoso. Se a criação de uma reserva confirmou no destino e a resposta se perdeu, uma compensação sem consulta pode atuar sobre o objeto errado ou gerar outra sequência ambígua.

Posicione aprovações nos pontos de compromisso

Revisar cada etapa transforma a Saga em fila manual. Liberar tudo transforma um fluxo longo em cadeia de efeitos sem alçada.

Use aprovação onde muda responsabilidade:

condição comercial fora da política;
comunicação sensível;
criação ou revogação de acesso relevante;
movimentação financeira;
cancelamento contratual;
compensação com impacto para cliente;
encerramento com pendência;
retomada depois de incidente;
ação irreversível.

O pacote de aprovação deve mostrar estado atual, etapas concluídas, fontes, efeito pretendido, alternativas, risco, prazo e possíveis compensações.

O artigo sobre aprovação humana em agentes de IA detalha como manter autoridade humana sem pedir validação para cada leitura ou transformação.

Defina prazos, lembretes e expiração

Sagas longas acumulam espera. Cada etapa precisa de prazo e destino após vencimento.

Uma pendência pode:

enviar lembrete ao responsável;
escalar por alçada;
pausar novas etapas;
reduzir o escopo;
expirar uma aprovação;
cancelar uma reserva;
iniciar compensação autorizada;
encerrar com pendência registrada;
entrar em contingência manual.

Prazos devem acompanhar a vida útil da decisão. Uma aprovação comercial recebida antes de uma mudança de escopo pode perder validade. Uma agenda reservada por dias sem confirmação consome capacidade real.

Evite crons que apenas repetem a etapa vencida. O agendador deve emitir um evento de prazo e deixar a política decidir a transição.

Monitore a Saga como serviço empresarial

Métricas técnicas ajudam, mas o estado do processo precisa aparecer em linguagem de negócio.

Acompanhe:

Sagas iniciadas e concluídas;
tempo total por tipo e classe;
tempo por etapa;
unidades aguardando aprovação;
unidades em resultado incerto;
compensações iniciadas, concluídas e falhas;
encerramentos com ressalva;
etapas repetidas e bloqueadas por idempotência;
conflitos de versão;
prazos vencidos;
concentração por responsável;
causas de interrupção;
efeitos irreversíveis seguidos de correção;
horas humanas por exceção;
taxa de conclusão válida;
impacto sobre cliente, receita, custo ou prazo.

Um alerta deve responder:

o que parou;
quais compromissos já aconteceram;
qual risco continua aberto;
qual prazo está correndo;
quem possui autoridade;
qual decisão vem agora.

“Saga 8f21 em erro” obriga a equipe a investigar do zero. “Onboarding pausado após criação do projeto; convite ainda não enviado; provisionamento bloqueado por contrato sem assinatura; responsável comercial deve validar até o fim do expediente” orienta ação.

Teste falha e compensação em cada fronteira

Inclua cenários como:

falha antes do primeiro compromisso;
etapa confirma e a resposta se perde;
duas instâncias tentam avançar a mesma Saga;
aprovação expira antes da execução;
objeto oficial muda durante a espera;
pessoa conclui uma etapa manualmente;
compensação recebe timeout;
compensação é recusada;
etapa irreversível ocorre antes da falha;
evento chega fora de ordem;
serviço retorna estado antigo por consistência eventual;
nova versão da Saga recebe unidades antigas;
reinício acontece entre comando e persistência;
fila acumula além do prazo;
credencial é revogada durante o processo;
cliente solicita cancelamento no meio da sequência.

Verifique estado da Saga, efeitos em cada destino, quantidade de chamadas, evidência de aprovação, rota de compensação e pacote entregue à pessoa.

O ambiente de teste para agentes de IA deve simular sistemas e confirmações. A engenharia do caos para agentes de IA pode testar degradações combinadas depois que os casos determinísticos estiverem cobertos.

Exemplo: Saga de onboarding de cliente

Início

Contrato assinado e escopo validado geram a unidade de onboarding.

Etapas

criar o registro do cliente;
abrir projeto com dono;
solicitar dados e acessos aprovados;
reservar sessão inicial;
provisionar ambiente;
executar o primeiro caso útil;
confirmar ativação.

Controles

cada etapa usa uma chave idempotente;
contrato, escopo e identidade são revalidados antes de acessos;
credenciais seguem por cofre, sem entrar no estado da Saga;
agenda e projeto devolvem IDs confirmados;
provisionamento possui checklist e teste;
primeiro caso útil exige evidência no sistema correto;
pendências têm responsável e data.

Compensações

projeto sem uso pode ser arquivado;
agenda pode ser cancelada ou remarcada;
convite incorreto deve ser revogado;
ambiente pode ser suspenso conforme política;
arquivos recebidos seguem retenção e descarte definidos;
comunicação já entregue recebe correção humana quando necessário.

Encerramento

A Saga termina quando a ativação possui evidência e responsável por continuidade. Se o cliente cancelar no meio, ela encerra somente depois de tratar acessos, agenda, dados, tarefas e comunicações pendentes.

Erros comuns

Chamar exclusão de compensação

Apagar o registro local pode esconder o rastro e manter efeitos ativos em outros sistemas. Compensação produz uma nova ação confirmada e auditável.

Compensar sem confirmar o estado

Timeout e ausência de log não provam falha. Consulte o destino antes de repetir ou compensar.

Colocar toda lógica no prompt

O modelo não deve carregar sozinho estados, prazos, versões e alçadas. O processo precisa persistir essas regras fora da conversa.

Usar um estado genérico de erro

Sem distinguir espera, incerteza, compensação e intervenção, a operação não sabe qual ação é segura.

Ignorar ações humanas

Pessoas resolvem etapas durante pausas. Essas ações precisam voltar ao estado oficial antes da retomada.

Prometer reversão total

Alguns efeitos deixam histórico ou alcançam terceiros. Classifique irreversibilidade e prepare correção, comunicação e incidente quando necessário.

Retomar do início

Uma Saga deve continuar da última confirmação válida. Reiniciar a sequência multiplica efeitos e apaga a noção de progresso.

Checklist do padrão Saga

[ ] A unidade representa um processo empresarial reconhecível?
[ ] Cada etapa possui pré-condição, comando, confirmação e dono?
[ ] Estados e versões sobrevivem a reinício e troca de worker?
[ ] Etapas estão classificadas por reversibilidade?
[ ] Existe matriz de compensação com autoridade e evidência?
[ ] Compensações também possuem idempotência, prazo e confirmação?
[ ] Timeouts entram como resultado incerto?
[ ] A fonte oficial é consultada antes de repetir ou compensar?
[ ] Aprovações ficam nos pontos de compromisso?
[ ] Ações humanas retornam ao estado da Saga?
[ ] Prazos vencidos produzem transições conhecidas?
[ ] O monitoramento mostra compromissos, risco, dono e próxima decisão?
[ ] Versões novas sabem tratar Sagas em andamento?
[ ] Testes cobrem falha, retomada, concorrência e compensação falha?
[ ] O encerramento confirma efeitos e pendências em todos os sistemas relevantes?

Processos longos precisam de uma trajetória governada

Um agente pode coordenar trabalho entre sistemas, pessoas e canais. A dificuldade aparece depois do primeiro compromisso, quando cada etapa passa a ter estado, prazo e consequência próprios.

O padrão Saga transforma essa sequência em uma trajetória persistida. Cada compromisso deixa evidência. Cada falha encontra uma rota conhecida. Compensações recebem a mesma disciplina das ações principais, e efeitos irreversíveis chegam à autoridade adequada.

A empresa ganha capacidade para retomar processos longos sem recomeçar, esconder pendências ou depender da lembrança de quem acompanhou a execução. Essa é a diferença entre uma automação que percorre etapas e uma operação capaz de governar o que aconteceu em cada uma delas.