Circuit breaker é um mecanismo que interrompe temporariamente chamadas a uma dependência que apresenta falhas repetidas. Em agentes de IA, ele pode proteger consultas ao CRM, serviços de busca e outras ferramentas externas. A interrupção evita que o agente continue consumindo recursos em uma operação com pouca chance de funcionar naquele momento.
Implemente esse controle fora do raciocínio do modelo, na camada que executa ferramentas. Defina quais erros contam, quando bloquear novas chamadas, como comunicar a indisponibilidade e como testar a recuperação. Combine a proteção com limite de tentativas, prazo da tarefa e verificação de efeitos para que uma falha técnica não gere ações duplicadas.
Resumo rápido
- O circuit breaker interrompe chamadas; a repetição tenta recuperar falhas transitórias.
- Separe falha de infraestrutura, recusa de negócio e resposta inválida.
- Proteja cada dependência com um escopo que corresponda ao problema.
- Controle tentativas, duração total e concorrência fora do modelo.
- Retome com chamadas limitadas e mantenha um caminho seguro durante a pausa.
Quando interromper é melhor que tentar novamente
Um agente recebe um objetivo e escolhe ferramentas para avançar. Se a consulta ao estoque demora, ele pode interpretar a falha como algo recuperável e repetir. Quando a ferramenta depende de um serviço indisponível, novas tentativas podem aumentar a fila e dificultar a recuperação. A operação continua ocupando conexões e recursos mesmo sem produzir progresso.
O circuit breaker observa um conjunto de resultados recentes e bloqueia chamadas quando a regra configurada é atingida. Isso protege o restante do fluxo de uma dependência degradada. Entretanto, ele não corrige a causa da falha, não restaura dados e não garante que o fornecedor se recuperou. A equipe continua responsável pela investigação e pelo caminho alternativo.
A documentação do Azure Architecture Center diferencia esse padrão do mecanismo de repetição. Essa distinção é útil no desenho do agente: uma tentativa adicional trata uma interrupção curta; o bloqueio temporário limita a insistência quando há evidência de problema persistente. Os dois controles podem coexistir.
Antes de acrescentar outro componente, verifique o que já existe no cliente da API, no gateway e na plataforma. Proteções sobrepostas sem coordenação podem criar esperas difíceis de explicar. Se a arquitetura já isola mensagens com mecanismos suficientes para o caso, um novo circuit breaker precisa ter uma justificativa operacional clara.
Os estados e os controles que trabalham juntos
No estado fechado, as chamadas passam e seus resultados alimentam o monitoramento. No estado aberto, a operação protegida é recusada temporariamente. Na fase de teste, também chamada de semiaberta, apenas chamadas limitadas verificam a recuperação. O retorno à operação normal depende do resultado dessas verificações, conforme a política implementada.
Esses estados descrevem o padrão geral. Seus valores de tempo e quantidade dependem da aplicação. Não copie limites de um exemplo como se fossem adequados a qualquer ferramenta. Uma consulta de catálogo e uma alteração financeira apresentam consequências diferentes. Volume de tráfego, tolerância à espera e comportamento da dependência também mudam a configuração.
| Controle | Pergunta que responde | Aplicação no agente |
|---|---|---|
| Prazo por chamada | Quanto esperar por esta resposta? | Encerrar uma espera que excede o permitido |
| Limite de tentativas | Quantas repetições são aceitáveis? | Evitar repetição indefinida da ferramenta |
| Circuit breaker | A dependência deve receber novas chamadas? | Interromper acesso durante falhas recorrentes |
| Limite de concorrência | Quantas chamadas podem coexistir? | Conter acúmulo de trabalho simultâneo |
| Prazo total | Quanto a tarefa pode durar? | Encerrar a operação mesmo com várias etapas |
| Idempotência | Repetir pode duplicar efeitos? | Preservar a identidade da mesma operação |
Uma orientação prática é desenhar cada controle antes de escolher a biblioteca. Se o circuito abrir, o agente precisa receber um resultado estruturado que indique indisponibilidade e quais caminhos são permitidos. A mensagem não deve sugerir que uma reformulação do mesmo pedido contorna o bloqueio. O executor precisa fazer essa restrição valer.
Classifique erros e escolha o escopo da proteção
Nem todo resultado negativo significa dependência doente. Um pedido inexistente pode ser uma resposta válida. Uma credencial revogada exige correção de acesso. Uma entrada fora do formato exige validação. Já uma sequência de respostas de indisponibilidade pode justificar interrupção. Defina essa classificação por ferramenta e documente os casos ambíguos.
Uma resposta tecnicamente recebida também pode não servir à tarefa. Se o serviço retorna conteúdo que viola o contrato esperado, registre o problema separadamente. A equipe pode decidir interromper aquela integração por erros de contrato, mas não deve misturar esse indicador com indisponibilidade de rede sem saber o que está medindo.
Escolha a chave do circuito conforme o domínio da falha: serviço, operação, região ou conta, quando essas divisões existirem na arquitetura. Um bloqueio global pode interromper clientes saudáveis por causa de uma conta com configuração incorreta. Por outro lado, separar demais pode permitir que várias partes do sistema continuem sobrecarregando a mesma dependência.
Em aplicações com várias instâncias, defina se os estados serão locais ou compartilhados. A orientação da AWS sobre circuit breaker apresenta o padrão e suas considerações de implementação. A decisão concreta exige observar como as instâncias acessam a dependência e quais chamadas precisam ser contidas em conjunto.
Registre também quem pode forçar abertura ou recuperação manual. Essa intervenção deve deixar motivo e identificação do responsável. Um botão que libera o tráfego sem verificar o contexto pode reiniciar o incidente. Para delimitar o acesso às ferramentas, complemente o desenho com permissões de agentes de IA.
Repetição segura e caminho alternativo
Quando uma repetição é permitida, use espera progressiva e variação aleatória, conforme o comportamento do serviço. Essa variação distribui tentativas que, de outra forma, poderiam ocorrer ao mesmo tempo. Respeite indicações de espera fornecidas pela API quando aplicáveis. O agente não deve decidir sozinho ignorar uma restrição operacional.
A AWS Builders’ Library ressalta que uma resposta ausente não prova que os efeitos da chamada não aconteceram. Antes de repetir uma criação de pedido, consulte o estado ou utilize o mecanismo de idempotência oferecido pelo sistema. Essa verificação é especialmente necessária quando a execução pode ter terminado depois do prazo observado pelo cliente.
Evite multiplicar repetições em várias camadas. Se o cliente, a ferramenta e o planejador repetem independentemente, a quantidade de chamadas cresce sem ficar evidente para quem acompanha a conversa. A documentação da Microsoft sobre o padrão Retry orienta avaliar os efeitos e as condições da repetição. No agente, determine uma camada responsável por esse orçamento.
O caminho alternativo depende da tarefa. Uma busca pode mostrar informação previamente validada com indicação de atualização. Uma operação de escrita pode precisar aguardar conferência humana. Trocar automaticamente de fornecedor requer compatibilidade, acesso e validação próprios. A indisponibilidade de uma ferramenta não torna outra ferramenta equivalente nem autoriza mover informações para um destino diferente.
Se houver fila para processamento posterior, preserve prazo, identificador da operação e critério de expiração. A recuperação do serviço não significa que todos os pedidos antigos continuam válidos. A implementação deve decidir quais operações podem ser retomadas e quais precisam de nova confirmação. Acompanhe isso na orquestração de agentes com estado.
Exemplo: distribuidora em Belo Horizonte
Imagine uma distribuidora fictícia de material elétrico em Belo Horizonte. Seu agente prepara orçamentos consultando catálogo e disponibilidade. Em determinado momento, a integração de estoque começa a responder com indisponibilidade. O catálogo continua funcionando. A equipe deseja manter a consulta de produtos sem apresentar quantidades não confirmadas como se estivessem atualizadas.
O executor identifica as falhas do estoque e abre o circuito daquela dependência conforme a regra testada. As próximas consultas recebem um resultado de indisponibilidade temporária, sem alcançar o serviço. O agente pode montar uma lista preliminar de itens, mas informa que a disponibilidade precisa de confirmação. A emissão do pedido permanece bloqueada quando depende desse dado.
Quando chega a fase de teste, uma consulta limitada verifica a recuperação. Se ela falhar, a proteção volta à pausa. Se os critérios definidos forem atendidos, o fluxo libera gradualmente o acesso conforme a implementação. A equipe confere separadamente os orçamentos pendentes para saber quais ainda precisam ser completados.
Uma gravação anterior teve resposta desconhecida. Esse caso vai para reconciliação pelo identificador da operação, sem repetição automática. O exemplo é ilustrativo e não apresenta ganho de produtividade medido. O resultado esperado é verificável: catálogo acessível, estoque protegido, nenhuma promessa falsa de disponibilidade e nenhuma duplicação de pedido durante a recuperação.
Erros comuns
Tratar todo erro como motivo para abrir o circuito. Uma recusa por regra de negócio pode mostrar que o serviço está funcionando corretamente. Separe categorias e observe o efeito da política. Se entradas inválidas interrompem toda a operação, o controle está escondendo um problema de validação.
Confiar apenas em instruções ao modelo. Um pedido como “não repita muitas vezes” não substitui um contador no executor. O bloqueio deve permanecer válido quando o agente reformula parâmetros, reinicia uma etapa ou recebe outra mensagem. Defina também o que identifica a mesma operação.
Reabrir o tráfego inteiro no primeiro sinal de melhora. A dependência pode estar se recuperando com capacidade reduzida. Teste o estado intermediário e limite a concorrência da retomada. A saúde de uma consulta simples também não garante que todas as operações mais pesadas voltaram a funcionar.
Ocultar o bloqueio do monitoramento. Chamadas recusadas localmente são diferentes de falhas retornadas pelo fornecedor. Registre ambas. Sem essa distinção, a queda do número de erros externos pode parecer recuperação quando o circuito apenas deixou de enviar solicitações.
Testar apenas a abertura. Simule recuperação, nova falha durante o teste, reinício de instância e duas tarefas concorrentes. Verifique a mensagem recebida pelo cliente e os efeitos no sistema de destino. Use testes de regressão de agentes e ferramentas para preservar essas condições após alterações.
Para acompanhar a política, mantenha eventos de mudança de estado, motivo, escopo, tentativas permitidas e chamadas bloqueadas. Associe esses eventos à tarefa sem copiar dados desnecessários do cliente. Revise o comportamento com a operação: uma proteção tecnicamente correta pode precisar de outro caminho de atendimento para manter a utilidade do serviço.
Perguntas frequentes
Circuit breaker impede qualquer loop do agente?
Não. Ele protege o acesso a uma dependência segundo critérios específicos. Um agente ainda pode repetir raciocínio ou alternar ferramentas sem avançar. Limite etapas, duração total e custo da tarefa com controles próprios, além de registrar ausência de progresso.
Existe um número certo de falhas para bloquear?
Não há valor universal. Defina uma política inicial com testes e dados da dependência. Considere volume, janela de observação, duração normal das chamadas e impacto de interromper. Revise a configuração quando a operação mudar, evitando conclusões baseadas em poucas amostras.
Uma resposta de limite de uso deve contar?
Depende do contrato e do escopo. Diferencie limitação da conta, sobrecarga e indisponibilidade geral. Respeite orientações de espera da API e evite que o circuito de uma conta bloqueie outras sem necessidade. Documente a decisão por integração.
Posso apenas trocar o modelo de IA?
Uma falha no CRM não desaparece ao trocar o modelo que o consulta. Quando a dependência problemática é o próprio serviço de geração, uma alternativa precisa ser previamente integrada e avaliada. O circuit breaker identifica a pausa; a política decide o próximo caminho.
Como comprovar que funciona?
Injete falhas em ambiente controlado e observe chamadas reais ao destino de teste. Confirme bloqueio, mensagem de contingência e recuperação limitada. Verifique também que operações de escrita não duplicaram efeitos e que o histórico permite explicar cada decisão tomada pelo executor.
