Agente de suporte em produção: Temporal, saga e circuit breaker protegem reembolsos contra falhas

O cliente escreve: «Meu pacote não chegou, devolvam o meu dinheiro». Dá para escrever em uma noite um agente que responda a isso: um loop, três ferramentas, e na demo tudo funciona. Aí o processo reinicia no meio de um reembolso, o provedor do modelo fica meia hora fora do ar e o cliente clica em «enviar» duas vezes. No fim, o agente é só uma pequena parte do sistema. A parte final da série no Habr monta esse sistema passo a passo, e o principal valor está no fato de que cada componente surge como resposta a uma falha concreta.

Do arquivo único à API, ao worker e ao Temporal

A versão inicial guarda o histórico da conversa na memória do processo. A reinicialização apaga todas as conversas, os clientes são atendidos um de cada vez e, se o processo cai entre a chamada de refund_payment e a resposta, ninguém sabe se o dinheiro foi devolvido ou não.

O primeiro passo é separar o script em API e worker. A API recebe a mensagem, grava no banco e responde ao chat na hora. Ela não chama o modelo, por isso responde em milissegundos. O loop do agente roda em workers separados, que podem ser adicionados conforme a carga. O histórico agora fica no banco e sobrevive a reinicializações.

Mas o worker ainda pode cair no meio de um atendimento. Repetir o reembolso é perigoso: dá para pagar duas vezes. Não repetir também é ruim: dá para não pagar nunca. É aqui que entra o Temporal: ele registra cada passo em um log, e outro worker continua do mesmo ponto, sem executar de novo os passos já concluídos. O loop do agente vive no workflow, e as chamadas ao modelo e às ferramentas viram activities.

Dois esclarecimentos importantes. O Temporal tem banco de dados próprio, e os dados de negócio dos clientes não devem ficar nele: o histórico de uma execução é limitado a 51 200 eventos ou 50 MB. Os workers com o seu código são executados por você; o serviço Temporal não os executa. Já o Workflow ID é definido por você: use o id da conversa, e um reenvio não criará duplicata. Só não coloque dados pessoais no ID, porque ele aparece na interface e nos logs.

Retry não é circuit breaker

Quando o provedor do modelo fica meia hora fora do ar, o Temporal faz retry da activity de forma fiel. Cem workers e mil atendimentos abertos martelam juntos a API caída e, quando ela volta, a fila inteira desaba sobre ela.

O retry foi pensado para uma falha que passa em segundos. Para uma indisponibilidade longa, é preciso um circuit breaker. Ele conta as falhas, abre o circuito ao passar de um limite e passa a devolver erro imediatamente, sem consultar o serviço, e depois de um tempo deixa passar uma chamada de teste. O estado do disjuntor precisa ser compartilhado por todos os workers; do contrário, cada um vai descobrir de novo que o provedor caiu. Por isso o lugar dele é no gateway de LLM, entre os workers e os provedores. O LiteLLM, por exemplo, tira o modelo de rotação após uma série de falhas, troca para um modelo reserva e guarda o estado no Redis.

Conselho prático do autor: faça a activity distinguir dois tipos de erro. O erro temporário é repetido pela política do Temporal. O erro «circuit breaker aberto» não deve passar por retry: o próprio workflow decide se muda para um modelo reserva, espera ou transfere o atendimento a um operador. Os mesmos disjuntores devem ficar na frente da transportadora e do gateway de pagamento.

Saga, operador e roteador

O reembolso envolve três sistemas sem transação comum: a etiqueta na transportadora, o dinheiro no gateway de pagamento, a notificação ao cliente e a atualização do pedido. Isso é uma saga: cada passo tem uma compensação. O conceito-chave é o ponto de não retorno (pivot transaction). Antes da devolução do dinheiro, os passos podem ser cancelados; depois dela, o e-mail ao cliente e a atualização do pedido precisam ser concluídos, por mais retries que sejam necessários. Cada ação recebe uma chave de idempotência, por exemplo o id da decisão, e o gateway de pagamento não debita o dinheiro de novo.

O modelo não deve processar valores altos. O workflow mostra a decisão no console do operador e espera um sinal. A espera fica registrada no log e não ocupa um worker, então o operador pode responder só depois de uma hora.

O último passo diz respeito ao custo. Nem todo atendimento exige o loop completo do agente. Um roteador com um modelo pequeno manda as perguntas de FAQ para uma única chamada, a pergunta «onde está o meu pedido» para uma cadeia pré-definida, e só o reembolso em disputa chega ao agente. O princípio é simples: use o nível de complexidade mais baixo que resolva a tarefa de forma confiável.

O que fazer com isso

Não vale a pena montar o esquema inteiro de uma vez. O autor aconselha de forma direta adicionar um componente quando surgir a dor que ele resolve. Se você atende um cliente por vez e não há dinheiro em jogo, o banco de dados basta. Assim que aparecem efeitos colaterais, como pagamentos, são necessárias idempotência e durable execution. Assim que surge a dependência de um provedor externo, é necessário um disjuntor compartilhado.

Há limitações. O código do artigo é pseudocódigo. A afirmação de que o agente web do Codex roda sobre o Temporal vem do próprio fornecedor, e o autor não encontrou confirmação independente. Ainda assim, como mapa das falhas típicas de um sistema com agentes, o texto é útil para qualquer pessoa que leve um agente para produção. Comece pela pergunta: o que acontece se o processo cair depois da chamada mais arriscada?