Human-in-the-Loop Design

No início do meu trabalho em um sistema de suporte à decisão clínica desidentificado, nos deparamos com um atalho familiar: remover a etapa de revisão humana antes de uma recomendação de IA chegar a um clínico. O modelo era preciso nos testes. A etapa de revisão adicionava latência. A pressão do produto era real.

Removemos o gate para uma categoria de recomendações. Em dias, uma recomendação chegou a um clínico que era tecnicamente correta dado os dados de treinamento do modelo, mas contextualmente errada dado as notas do prontuário do paciente — notas adicionadas após o snapshot de entrada do modelo ter sido tirado. O modelo não tinha como saber o que não via. Um revisor humano teria detectado a discrepância em segundos.

Colocamos o gate de volta, e desta vez o projetamos em vez de apenas aparafusá-lo.

Essa experiência moldou cada sistema humano-no-loop que construí desde então, incluindo os pontos de verificação no meu framework de orquestração Python. A lição não é que a IA não é confiável. A lição é: um agente que não consegue pausar e pedir ajuda acabará agindo com informações incompletas exatamente no momento errado.

Pense em um gate humano-no-loop como uma equipe cirúrgica pensa na pausa pré-incisão — uma confirmação breve e estruturada de que todos concordam sobre o paciente, o local e o plano antes de prosseguir. A pausa não é um sinal de desconfiança na equipe. É uma característica de design que captura os erros que a própria equipe não consegue capturar por dentro.

O Exemplo em Execução

Este módulo adiciona uma camada de ponto de verificação humano sobre o agente de orquestração de tarefas construído nos módulos 01–03. Ao final, o agente irá:

1. Planejar uma lista de etapas a partir de uma especificação de tarefa.
2. Executar cada etapa usando uma ferramenta registrada.
3. Pausar e solicitar confirmação humana quando sua confiança for baixa ou a etapa estiver sinalizada para revisão obrigatória.
4. Retomar ou abortar com base na resposta humana.

Um checkpoint não é um handler de erro. É uma pausa deliberada — o agente não está falhando; está surfaçando uma decisão que requer julgamento humano antes de agir. A distinção importa porque os checkpoints devem ser projetados antecipadamente, não adicionados reativamente depois que algo der errado.

Pense em um checkpoint como o botão de escalação que um agente de call center alcança antes de assumir um compromisso que a empresa não pode desfazer. O agente não espera a ligação dar errado; o caminho de escalação está incorporado ao processo desde o início.

O checkpoint mais simples tem três campos: a pergunta para o humano, o contexto necessário para respondê-la e o conjunto de respostas permitidas.

O campo confidence é auto-relatado pelo modelo. Não é uma probabilidade calibrada; trate-o como um sinal relativo. Um modelo que reporta 0.3 está dizendo que tem dois caminhos plausíveis e não consegue escolher — essa informação é útil mesmo que o número em si seja impreciso.

Agora escreva uma função que constrói um checkpoint a partir da saída de uma etapa:

Ponto de Verificação do Módulo

Antes de continuar: o que aconteceria se o modelo sempre reportasse uma confiança de 1.0? Algum checkpoint seria acionado? Pause e trabalhe pela lógica de escalação que você está prestes a ler.

Um checkpoint é o mecanismo. A política de escalação é a regra que decide quando acioná-lo. Sem uma política você obtém um de dois modos de falha: checkpoints em cada etapa (fricção que derrota o propósito da automação) ou checkpoints em nenhuma etapa (não melhor do que remover o gate completamente).

No sistema de suporte à decisão clínica, a política de escalação tinha três entradas: a confiança auto-relatada do modelo, o risco clínico da categoria de recomendação e uma lista curta de categorias sinalizadas como "sempre revisar." Meu harness do SDLC usa uma versão mais simples de dois inputs: confiança e uma lista codificada de tipos de etapas que requerem aprovação humana independentemente da confiança.

O conjunto ALWAYS_REVIEW é a linha mais importante. Ele faz certas ações serem incondicionalmente revisadas por humanos, independentemente da confiança. É aqui que vive a lição clínica: o modelo não consegue avaliar o que não sabe que não sabe. Para ações que são irreversíveis ou externamente visíveis, ignore completamente a verificação de confiança e sempre pause.

Agora integre o checkpoint ao loop de execução do módulo 03. A mudança é mínima: após o modelo executar uma etapa, analise sua confiança, aplique a política e, se um checkpoint for necessário, chame o revisor antes de continuar.

Duas funções auxiliares — _parse_confidence, _parse_reasoning e _parse_result — extraem os campos rotulados da resposta do modelo. Cada uma é um string-split curto no prefixo do rótulo. Manter a análise separada da lógica de execução torna ambas mais fáceis de testar independentemente.

O Caminho Feliz

Quando todas as etapas passam pela verificação de escalação, o agente roda até a conclusão sem nenhuma pausa.

O Caminho de Escalação

Quando uma etapa aciona um checkpoint, o agente pausa e chama human_review_fn. Se o humano aprovar, a execução continua. Se o humano rejeitar, um RuntimeError é levantado — o chamador decide se deve abortar, tentar novamente ou replanejar.

O parâmetro human_review_fn é a emenda que permite substituir uma UI real, um bot do Slack, um prompt de CLI ou um stub de teste sem tocar na lógica do agente. No meu harness do SDLC, ele roteia para um prompt de terminal em execuções locais e para um webhook quando rodando em CI.

Dois contextos moldaram como penso sobre checkpoints, e apontam em direções diferentes.

No sistema de suporte à decisão clínica, os riscos eram a segurança do paciente. A política de escalação era conservadora: qualquer recomendação tocando um julgamento clínico requeria aprovação humana antes de chegar a um clínico. A velocidade era uma preocupação secundária. O conjunto de "sempre revisar" cobria cada categoria de saída que poderia influenciar uma decisão de cuidado. Reduzir a latência estava fora do escopo até que o modelo tivesse um histórico verificável de escalações corretas.

No harness do SDLC, os riscos são menores e a troca segue o outro caminho. O harness executa muitas etapas por sessão. Um checkpoint bloqueante em cada etapa de baixa confiança o tornaria inutilizável para o trabalho diário. A política de escalação dispara apenas quando o agente está genuinamente incerto sobre uma etapa que não pode ser facilmente revertida — uma escrita de relatório, uma notificação externa, uma exclusão de arquivo.

O dataclass HumanCheckpoint, a função needs_human_review e a emenda human_review_fn são idênticos em ambos os contextos. Apenas o conteúdo de ALWAYS_REVIEW e o valor de CONFIDENCE_THRESHOLD diferem.

Como Isso se Conecta ao Restante do Caminho

O módulo 06 mostrará por que a execução linear com contexto compartilhado é a arquitetura padrão certa para agentes. O humano-no-loop não é uma ideia concorrente — ele se encaixa naturalmente dentro do loop linear. Um checkpoint é apenas uma etapa cuja "ferramenta" é um revisor humano.

Um sistema multi-agente onde os agentes rodam em paralelo não tem lugar limpo para inserir um checkpoint bloqueante. Um agente linear tem, porque há sempre um momento bem definido para pausar antes da próxima etapa começar. Essa é mais uma razão para preferir a arquitetura linear por padrão.