Health check para agentes de IA em produção

Um processo pode estar online e incapaz de concluir trabalho

O endpoint responde. O worker continua ativo. O painel mostra o serviço em verde. Mesmo assim, o agente recebe tarefas que não consegue terminar porque a credencial do CRM venceu, a fila perdeu conexão com o banco de estado ou a base autorizada deixou de atualizar.

Esse cenário aparece quando o health check verifica apenas se o processo está vivo. Para uma operação com agentes de IA, saúde significa capacidade de receber uma unidade, consultar as fontes necessárias, executar as ferramentas permitidas, preservar estado e confirmar o resultado no destino.

Um health check útil transforma essa capacidade em sinais objetivos. Ele também define o que a plataforma deve fazer quando um sinal falha: reiniciar um processo, retirar uma instância da rota, bloquear novas tarefas, reduzir o escopo ou encaminhar trabalho para contingência.

O que um health check precisa responder

A verificação deve separar perguntas que levam a ações diferentes.

O processo está vivo?

A sonda de liveness confirma que o runtime responde e consegue avançar. Ela detecta travamento, deadlock, loop sem progresso ou falha interna que exige reinício.

Uma resposta HTTP de sucesso pode ser insuficiente. Se o endpoint usa uma thread saudável enquanto todos os workers estão presos, o processo parece vivo e continua sem entregar trabalho. Inclua um sinal de progresso, como atualização recente do loop principal, consumo de fila ou avanço de checkpoints.

A instância pode receber trabalho agora?

A sonda de readiness decide se novas tarefas podem ser roteadas para aquela instância. Ela considera as dependências essenciais, o estado local, a conexão com filas e a capacidade disponível.

Quando readiness falha, o balanceador ou orquestrador deve interromper novas admissões. As tarefas em curso precisam seguir a política de conclusão, pausa ou transferência prevista. Reiniciar automaticamente pode piorar o cenário se a causa estiver em uma dependência externa.

A inicialização terminou?

A sonda de startup protege serviços que precisam carregar modelos, restaurar estado, validar contratos, aquecer cache ou registrar consumidores antes de operar.

Sem essa separação, uma inicialização lenta pode ser confundida com travamento. O sistema entra em ciclos de reinício e nunca alcança o estado pronto.

O serviço consegue cumprir sua responsabilidade?

Uma verificação sintética percorre uma parte representativa do caminho operacional. Ela pode consultar uma fonte controlada, validar uma saída conhecida e confirmar que a ferramenta responde dentro do contrato esperado.

A tarefa sintética deve evitar consequências reais. Use tenant de teste, registro fictício, operação somente de leitura ou destino isolado. Nunca envie mensagem, movimente dinheiro ou altere cadastro real para provar que o serviço funciona.

Liveness, readiness e teste sintético têm trabalhos diferentes

Misturar todas as verificações em um único endpoint produz decisões ruins.

Liveness deve ser estável e restrita ao processo. Se ela depender do CRM, uma indisponibilidade externa reinicia todas as instâncias sem corrigir o CRM.

Readiness pode consultar o conjunto mínimo de condições necessárias para receber trabalho. Uma instância sem acesso ao banco de estado deve sair da rota. Uma integração opcional indisponível pode manter a instância pronta em modo reduzido, desde que a política de cada tarefa reconheça essa limitação.

O teste sintético verifica o caminho funcional em intervalos próprios. Ele costuma ser mais caro e mais lento, por isso não deveria rodar a cada requisição do balanceador.

A arquitetura ganha três respostas claras:

reiniciar quando o processo perdeu capacidade de avançar;
retirar da rota quando a instância não pode assumir novas tarefas;
alertar ou degradar quando o percurso funcional deixou de cumprir o contrato.

Defina saúde a partir da unidade de trabalho

Comece pela entrega reconhecida pela operação. Pode ser um chamado triado, uma oportunidade comercial preparada, um documento conferido ou uma solicitação encaminhada para aprovação.

Para essa unidade, mapeie:

o evento que inicia o trabalho;
a fila ou canal de entrada;
o estado que precisa ser preservado;
as fontes indispensáveis;
as ferramentas obrigatórias;
as validações antes de qualquer consequência;
o sistema que confirma a conclusão;
a rota de exceção;
o prazo útil do caso.

Esse mapa mostra quais dependências afetam disponibilidade e quais apenas reduzem conveniência. Um agente que prepara follow-up pode continuar lendo o CRM quando o canal de envio está suspenso. Ele não deveria marcar a unidade como concluída até registrar a próxima ação ou encaminhar a pendência para a rota prevista.

O artigo sobre SLA para agentes de IA ajuda a ligar disponibilidade, prazo e qualidade à unidade completa.

Classifique dependências por criticidade

Verificar todas as integrações como se tivessem o mesmo peso torna o serviço frágil. Ignorá-las deixa o agente receber trabalho que ficará preso.

Essencial para admissão

Sem a dependência, nenhuma unidade válida consegue começar ou preservar estado. Exemplos incluem fila principal, banco de estado e serviço de identidade.

A falha deve retirar a instância da rota ou bloquear a classe afetada.

Essencial para uma classe de tarefa

O CRM pode ser obrigatório para follow-up comercial e irrelevante para análise interna de documentos. A readiness pode ser calculada por capacidade, rota ou tipo de trabalho.

Essa granularidade evita interromper todo o agente por uma falha localizada.

Opcional com modo degradado

Busca complementar, modelo secundário ou fonte de enriquecimento podem ficar indisponíveis sem impedir uma entrega mínima. A saída precisa registrar que o recurso não foi usado e respeitar critérios de qualidade mais conservadores.

Externa sob observação

Algumas dependências não oferecem endpoint de saúde confiável. A plataforma deve observar chamadas reais, erros, latência e testes sintéticos controlados. Declarar uma API saudável porque o domínio responde não comprova que o endpoint, a conta e a operação autorizada funcionam.

Verifique estado, fila e capacidade de progresso

Agentes assíncronos podem aceitar trabalho e perder a capacidade de consumi-lo. O health check precisa observar o caminho entre entrada e avanço.

Sinais úteis incluem:

conexão ativa com a fila;
consumidor registrado;
checkpoint recente;
idade da última unidade concluída;
diferença entre chegada e conclusão;
tamanho e idade do backlog;
locks presos;
tarefas em execução sem atualização;
disponibilidade do armazenamento de estado;
capacidade restante por classe;
relógio sincronizado para prazos e expiração.

Use contexto. A ausência de conclusão durante a madrugada pode ser normal para uma rotina diurna. Cinco minutos sem avanço podem ser críticos em atendimento e irrelevantes em processamento noturno.

A página sobre planejamento de capacidade para agentes mostra como demanda, tempo de serviço e capacidade de drenagem mudam a leitura de filas.

Teste fontes e contexto sem vazar conteúdo

Uma fonte pode estar acessível e operacionalmente inútil. O arquivo existe, mas está vazio. A base responde, mas a atualização parou. O índice vetorial carrega, mas aponta para uma versão antiga da política.

Verifique:

acesso com a identidade real do runtime;
presença de um registro sentinela controlado;
data de atualização dentro da faixa esperada;
versão do contrato ou esquema;
autoridade da fonte para aquela responsabilidade;
isolamento entre clientes e ambientes;
capacidade de recuperar uma referência conhecida;
ausência de conteúdo sensível na resposta do endpoint.

O health check deve retornar estado, versão e motivo sanitizado. Ele não deve imprimir documentos, prompts, tokens, chaves, dados de cliente ou mensagens de erro com credenciais.

O guia sobre freshness de dados para agentes de IA detalha como validade temporal afeta decisões e ações.

Trate modelos e ferramentas de forma diferente

Uma chamada simples ao modelo confirma acesso, cota e latência básica. Ela não comprova que o agente executa bem uma tarefa empresarial.

Para modelos, verifique:

autenticação;
modelo ou perfil aprovado disponível;
limite e cota restantes;
formato de saída exigido;
tempo de resposta dentro da faixa técnica;
região ou política de dados esperada;
bloqueio de fallback não aprovado.

Para ferramentas, confirme o contrato da operação usada pelo agente. Uma API pode responder em leitura e falhar na escrita. Um CRM pode autenticar e negar o escopo necessário. Um serviço pode devolver HTTP 200 com um corpo incompatível.

Testes de escrita exigem ambiente isolado e limpeza confirmada. Em produção, prefira operações de leitura, validação de contrato e telemetria das execuções reais.

Modele estados de saúde além de verde e vermelho

Um estado binário esconde degradação e induz reações bruscas.

Uma taxonomia simples pode usar:

saudável: recebe e conclui as classes autorizadas dentro da faixa;
degradado: continua operando com limitação conhecida;
sem prontidão: permanece vivo, mas não recebe novas tarefas da classe afetada;
indisponível: perdeu capacidade de avançar ou preservar trabalho;
desconhecido: faltam sinais confiáveis para autorizar admissão.

Cada estado precisa declarar alcance. O problema pode atingir uma ferramenta, uma classe, um cliente, uma região, um worker ou o serviço inteiro.

Também precisa declarar a resposta operacional. Um estado degradado pode suspender envio externo e manter preparação interna. Estado desconhecido em uma ação financeira deve bloquear compromisso até nova verificação.

Evite falsos positivos e tempestades de reinício

Health checks também falham. Uma consulta pesada pode sobrecarregar a própria dependência. Muitas instâncias podem executar a mesma sonda no mesmo segundo. Uma oscilação breve pode retirar toda a capacidade da rota.

Controles importantes:

timeout curto e compatível com a sonda;
intervalo com pequena variação entre instâncias;
volume mínimo antes de mudar estado;
limiar diferente para entrar e sair da degradação;
cache curto para dependências compartilhadas;
limite de concorrência das tarefas sintéticas;
separação entre erro da sonda e erro da dependência;
período de estabilização antes da retomada plena;
proteção contra reinícios repetidos;
registro da última transição e da causa.

O circuit breaker para agentes de IA pode usar sinais de saúde para conter chamadas. A sonda não deveria abrir ou fechar o circuito sozinha sem a janela e os critérios definidos para a dependência.

Desenhe a recuperação junto com a detecção

Detectar falha sem definir o próximo estado cria um alerta que ninguém consegue operar.

Para cada verificação, registre:

condição observada;
severidade;
alcance;
ação automática permitida;
ação que exige pessoa;
dono;
prazo de resposta;
modo degradado;
fila afetada;
critério de recuperação;
evidência exigida antes de voltar.

A recuperação pode reiniciar uma instância, renovar credencial por processo autorizado, retirar uma classe da rota, reduzir concorrência, abrir contingência ou preservar tarefas até a dependência voltar.

Retomar exige cuidado. Recolocar todos os workers e liberar o backlog de uma vez pode derrubar o serviço novamente. Use admissão gradual, releitura do estado oficial, expiração de tarefas vencidas e idempotência nas escritas.

Monitore o próprio sistema de saúde

A empresa precisa saber se as sondas continuam executando e se ainda representam o processo.

Acompanhe:

execução e duração de cada sonda;
taxa de sucesso por dependência;
mudanças de estado;
tempo em degradação;
instâncias retiradas da rota;
reinícios acionados;
falsos positivos confirmados;
falhas descobertas por usuários antes das sondas;
tarefas admitidas durante falta de prontidão;
tempo entre recuperação técnica e operacional;
idade da definição de cada verificação.

Uma integração mudou de endpoint ou contrato? A sonda precisa mudar junto. Uma nova classe de tarefa passou a depender de outra fonte? A readiness deve refletir essa responsabilidade.

O monitoramento de agentes em produção reúne sinais de execução, qualidade, risco e impacto. Health checks fornecem decisões rápidas de disponibilidade e admissão dentro desse sistema maior.

Testes antes da produção

Exercite as verificações no ambiente de teste para agentes de IA antes de confiar nelas.

Simule:

processo travado com endpoint ainda respondendo;
fila acessível sem consumidor ativo;
banco de estado indisponível;
credencial vencida;
dependência lenta;
resposta válida com esquema antigo;
fonte disponível com dado vencido;
uma integração opcional fora do ar;
falha limitada a um cliente;
tarefa em curso durante perda de readiness;
sonda sintética falhando por erro próprio;
recuperação parcial;
retorno com backlog acumulado;
oscilação rápida entre sucesso e falha.

Confirme que o sistema toma a ação correta em cada caso. Reiniciar, retirar da rota, degradar e alertar não são respostas intercambiáveis.

Checklist de health check para agentes de IA

A unidade de trabalho está definida?
Liveness verifica progresso do processo sem depender de serviços externos?
Readiness bloqueia novas tarefas quando falta uma condição essencial?
Startup protege inicializações longas?
Testes sintéticos evitam consequências reais?
Dependências estão classificadas por criticidade e classe de tarefa?
Fila, estado e checkpoints entram na verificação?
Fontes possuem controle de versão, validade e isolamento?
Ferramentas são testadas no contrato realmente usado?
Respostas das sondas omitem segredos e dados sensíveis?
Estados degradados possuem alcance e comportamento conhecidos?
Limiares evitam oscilação e tempestade de reinício?
Cada falha possui dono e ação definida?
A retomada libera capacidade gradualmente?
As sondas são versionadas e revisadas quando o processo muda?

Saúde operacional aparece na capacidade de concluir

Um agente saudável consegue receber a classe certa de trabalho, avançar com estado preservado, consultar fontes válidas e terminar na condição reconhecida pelo processo.

Liveness, readiness, startup e tarefas sintéticas tornam essas capacidades observáveis. A empresa passa a retirar instâncias da rota antes de acumular erro, operar modos degradados com clareza e exigir evidência antes da retomada.

O resultado é uma operação menos dependente de painéis verdes e mais capaz de provar que o trabalho ainda pode ser concluído com segurança.