Circuit breaker para agentes de IA: como implementar

Uma integração instável pode derrubar o processo inteiro

Um agente consulta o CRM, chama um modelo, lê documentos e grava o resultado no ERP. O CRM começa a responder lentamente. Cada execução espera, falha e tenta de novo. Novos trabalhos chegam enquanto conexões permanecem ocupadas. Em poucos minutos, uma indisponibilidade localizada pressiona filas, workers e outras integrações que estavam saudáveis.

Esse é o tipo de falha que o circuit breaker tenta conter. O mecanismo observa as chamadas a uma dependência e interrompe novas tentativas quando a taxa de erro ou a latência ultrapassa um limite. Depois de um período controlado, libera poucas chamadas de teste. O fluxo normal volta somente quando existe evidência de recuperação.

Em agentes de IA, esse controle precisa conversar com estado, filas, prioridades e modos degradados. Abrir o circuito sem definir o destino das tarefas pode proteger a API e, ao mesmo tempo, criar um backlog invisível.

O que é circuit breaker

O nome vem de disjuntores elétricos, mas o uso em software segue uma lógica operacional simples. Uma aplicação deixa de insistir em uma dependência que está falhando e passa a responder de forma conhecida.

O mecanismo costuma trabalhar com três estados.

Fechado

As chamadas seguem normalmente. O sistema mede sucesso, erro, timeout e latência. Um conjunto de falhas dentro da regra configurada pode abrir o circuito.

Aberto

Novas chamadas são bloqueadas antes de chegar à dependência. O agente recebe um estado explícito e segue a rota prevista: aguardar, produzir resultado parcial, usar uma alternativa aprovada, encaminhar para uma pessoa ou encerrar a unidade.

Semiaberto

Depois do intervalo de espera, o sistema libera um número pequeno de chamadas de teste. Se elas confirmarem a recuperação, o circuito fecha de forma gradual. Se falharem, ele abre novamente.

O valor está na decisão rápida. Em vez de deixar cada tarefa descobrir repetidamente que o serviço continua indisponível, a arquitetura compartilha o sinal e reduz pressão sobre o ponto fragilizado.

Circuit breaker, rate limit e kill switch resolvem problemas diferentes

Os três controles podem interromper chamadas, mas entram em situações distintas.

O rate limit para agentes de IA distribui capacidade antes da falha. Ele define quem pode consumir um recurso, em qual ritmo e prioridade.

O circuit breaker reage à degradação observada de uma dependência. Seu trabalho é parar insistência inútil e verificar a recuperação sem devolver toda a carga de uma vez.

O kill switch para agentes de IA interrompe capacidades por decisão operacional ou de segurança. Pode bloquear entradas, filas, ferramentas, credenciais e execuções mesmo quando os componentes técnicos parecem saudáveis.

Uma arquitetura pode usar os três. O rate limit controla o volume normal. O circuit breaker contém uma integração instável. O kill switch permite que uma pessoa suspenda o agente diante de risco amplo ou comportamento inadequado.

Onde aplicar o controle

Criar um único circuito para o agente inteiro costuma esconder a causa. Cada dependência relevante precisa de uma política compatível com seu comportamento.

Considere circuitos separados para:

provedor e modelo de IA;
endpoint do CRM;
ERP ou sistema financeiro;
serviço de OCR;
busca e navegação;
banco de dados;
armazenamento de arquivos;
envio de e-mail, WhatsApp ou SMS;
base de conhecimento;
serviço interno compartilhado;
fila de aprovação humana, quando o fluxo depende de capacidade disponível.

Também pode ser necessário separar operações na mesma ferramenta. Consultar um contato no CRM e atualizar uma oportunidade possuem custo, risco e tolerância a falha diferentes. Um circuito aberto para escrita pode manter leituras disponíveis.

Defina a unidade protegida

O circuito precisa saber o que está medindo. Agrupar demais faz uma falha pequena bloquear operações saudáveis. Fragmentar demais produz centenas de controles difíceis de entender.

Uma chave de circuito pode combinar:

dependência;
operação ou endpoint;
ambiente;
cliente ou tenant, quando existe isolamento;
região;
classe de tarefa;
credencial ou conta de consumo.

Imagine que um cliente excedeu a própria cota no CRM. Abrir o circuito global impediria o atendimento dos demais. Nesse caso, a unidade deve preservar o isolamento por conta. Se o fornecedor inteiro está indisponível, um circuito global pode ser adequado.

A regra prática é proteger o menor domínio de falha que a operação consegue observar e administrar.

Escolha sinais que representem degradação real

Contar qualquer erro como falha do fornecedor distorce o controle. Entrada inválida, permissão negada e regra de negócio recusada podem exigir correção, sem indicar indisponibilidade.

Sinais comuns para abrir o circuito incluem:

timeouts;
falhas de conexão;
respostas 5xx;
latência acima da faixa segura;
respostas de sobrecarga;
erro repetido do serviço;
ausência de confirmação em uma operação que deveria concluir;
dependência marcada como indisponível por health check confiável.

Erros que normalmente pedem outro tratamento:

credencial expirada;
permissão insuficiente;
campo obrigatório ausente;
arquivo corrompido;
regra comercial recusada;
saída fora do esquema;
solicitação proibida pela política.

Uma credencial inválida tende a continuar inválida depois de várias tentativas. O fluxo deve bloquear e acionar o responsável. Um timeout breve pode justificar retentativa limitada antes de contribuir para a abertura do circuito.

Configure limiares com janela e volume mínimo

Abrir o circuito depois de uma única falha pode interromper uma operação por ruído. Esperar cem falhas pode permitir que a degradação se espalhe.

Defina pelo menos:

tamanho ou duração da janela observada;
número mínimo de chamadas para avaliar;
taxa de falha permitida;
limite de chamadas lentas;
timeout por operação;
intervalo com circuito aberto;
quantidade de chamadas no estado semiaberto;
número de sucessos necessário para fechar;
limite de reaberturas em determinado período.

Uma dependência de alto volume oferece amostra rapidamente. Um processo financeiro executado poucas vezes por dia exige política mais conservadora e pode combinar alerta humano com abertura imediata para erros específicos.

Use tráfego e latência reais do processo para calibrar. O contrato publicado pelo fornecedor ajuda, mas o limite operacional precisa considerar prazo, risco e capacidade de fila da empresa.

Dê a cada circuito uma resposta operacional

O sistema precisa responder claramente quando a chamada é bloqueada. Retornar apenas “serviço indisponível” deixa o agente sem decisão.

Respostas possíveis:

Aguardar em fila

A unidade preserva identificador, prioridade, prazo, etapa e próxima tentativa. Funciona quando o resultado ainda terá validade depois da recuperação.

Produzir saída parcial

O agente conclui as etapas independentes e marca o que ficou pendente. Uma análise pode usar documentos locais e deixar a atualização do CRM para depois.

Operar somente em leitura

Se a escrita perdeu confiabilidade, o agente continua consultando fontes e preparando recomendações. A execução aguarda confirmação ou ação humana.

Usar fallback aprovado

Outra rota pode assumir quando foi testada para o mesmo contrato de dados, política de privacidade, custo e qualidade. Trocar silenciosamente para qualquer provedor disponível cria uma falha diferente.

Encaminhar para uma pessoa

Casos próximos do prazo, de alto valor ou com efeito sensível seguem para uma fila humana com contexto suficiente.

Expirar ou cancelar

Trabalho cuja validade terminou deve ser encerrado. Uma mensagem comercial preparada antes da resposta do cliente não deve ser enviada horas depois apenas porque a integração voltou.

O plano de contingência para agentes de IA ajuda a desenhar modos degradados e capacidade manual quando a dependência sustenta um serviço relevante.

Preserve estado durante o circuito aberto

Cada unidade bloqueada deveria manter:

identificador único;
dependência e operação afetadas;
estado anterior confirmado;
chamada que foi evitada;
erro que contribuiu para a abertura;
horário de entrada;
prioridade e prazo;
tentativas já consumidas;
custo acumulado;
validade dos dados;
próxima ação prevista;
responsável;
condição de reprocessamento.

Sem esse registro, a proteção técnica cria perda operacional. O painel mostra que a API foi preservada, mas ninguém sabe quais clientes, pedidos ou documentos ficaram pendentes.

Para falhas que ultrapassam o teto de tentativas ou exigem investigação, uma fila de quarentena separa casos problemáticos do fluxo normal. Ela evita que uma unidade defeituosa volte continuamente para a mesma dependência.

Evite tempestade na recuperação

Fechar o circuito e liberar todo o backlog pode derrubar novamente um serviço ainda frágil. A recuperação precisa ser gradual.

Use uma combinação de:

poucas chamadas no estado semiaberto;
limite de concorrência reduzido;
aumento progressivo de tráfego;
prioridade para unidades próximas do prazo;
expiração de trabalho vencido;
releitura do estado oficial antes de agir;
idempotência para escritas externas;
monitoramento reforçado durante a retomada.

A página sobre idempotência em agentes de IA mostra como repetir processamento sem duplicar o efeito de negócio. Essa proteção importa porque uma resposta perdida pode parecer falha mesmo quando o destino executou a ação.

Não deixe o agente contornar o circuito

Um modelo pode tentar outra ferramenta, mudar o endpoint ou criar uma subtarefa para alcançar o mesmo destino. Isso quebra o limite compartilhado.

O bloqueio deve existir no orquestrador, gateway ou adaptador da integração, fora da decisão textual do agente. Toda rota equivalente precisa consultar o mesmo estado de saúde.

O agente pode escolher entre alternativas previamente autorizadas. Ele não deve inventar um caminho para superar uma barreira operacional.

Monitore o efeito sobre o negócio

Métricas técnicas mostram a saúde do mecanismo. A operação precisa enxergar a consequência.

Acompanhe:

circuitos abertos por dependência;
duração de cada abertura;
taxa de falha e latência antes da abertura;
chamadas bloqueadas;
tarefas preservadas;
tarefas expiradas;
tamanho e idade do backlog;
tempo até primeira recuperação;
reaberturas durante o semiaberto;
fallbacks acionados;
casos enviados para pessoas;
prazos afetados;
duplicidades evitadas;
tempo total de reconciliação.

Um alerta útil informa a dependência, os processos atingidos, o volume aguardando, a previsão de validade e o dono da próxima decisão. “Circuito aberto” sem tradução operacional é log, não gestão.

O guia de monitoramento de agentes em produção organiza métricas de execução, qualidade, risco e impacto.

Teste falha e recuperação

O circuit breaker precisa ser exercitado antes de entrar em um processo crítico.

Simule:

timeout intermitente;
indisponibilidade total;
latência crescente sem erro explícito;
erro 5xx em uma operação e sucesso em outra;
falha limitada a um cliente;
credencial inválida, confirmando que o caso não recebe retentativa inútil;
abertura durante execução longa;
fila crescendo enquanto o circuito está aberto;
recuperação parcial;
nova falha no estado semiaberto;
fechamento com backlog acumulado;
escrita concluída com confirmação perdida;
fallback também indisponível;
intervenção manual durante a pausa.

Verifique se novas chamadas param no ponto correto, tarefas mantêm estado, alertas chegam ao responsável e a retomada respeita capacidade e validade. O ambiente de teste para agentes de IA permite simular essas condições sem pressionar sistemas reais.

Checklist de implementação

Antes de ativar um circuit breaker, confirme:

[ ] a dependência e a operação protegidas estão identificadas;
[ ] o domínio de falha evita bloqueio global desnecessário;
[ ] erros temporários estão separados de entrada, permissão e regra;
[ ] janela, volume mínimo e limiares usam dados do processo;
[ ] timeout e retentativas possuem teto;
[ ] o estado aberto produz uma resposta operacional conhecida;
[ ] tarefas bloqueadas preservam identificador, prazo e estado;
[ ] fallbacks foram aprovados para dados, qualidade e custo;
[ ] o estado semiaberto limita chamadas de teste;
[ ] a retomada libera carga gradualmente;
[ ] escritas usam idempotência e confirmação;
[ ] rotas alternativas consultam o mesmo bloqueio;
[ ] alertas mostram impacto e responsável;
[ ] testes cobrem falha, recuperação e reabertura;
[ ] o circuito pode ser inspecionado e operado por pessoas autorizadas.

Resiliência exige uma decisão conhecida para cada falha

Circuit breaker reduz o alcance de uma dependência instável. Ele impede que agentes gastem tempo, conexões e orçamento repetindo uma chamada que continua falhando.

A proteção funciona quando o bloqueio preserva o trabalho e conduz a operação para um estado legível. Com circuitos por dependência, sinais bem classificados, tarefas com estado e recuperação gradual, uma falha localizada deixa de contaminar o sistema inteiro.