Phase 15 - Lesson 15

Human-in-the-Loop: Propose-Then-Commit

O consenso de 2026 sobre HITL é específico. Não é "o agente pergunta, o usuário clica em Aprovar". É propor-e-confirmar (propose-then-commit): a ação proposta é persistida em um armazenamento durável com uma chave de idempotência; apresentada a um revisor com intenção, linhagem de dados, permissões afetadas, raio de impacto e um plano de rollback; confirmada (committed) apenas após confirmação positiva; verificada após a execução para confirmar que o efeito colateral realmente ocorreu. O interrupt() do LangGraph combinado com checkpointing no PostgreSQL, o RequestInfoEvent do Microsoft Agent Framework e o waitForApproval() da Cloudflare implementam todos o mesmo formato. O modo de falha canônico é a aprovação por carimbo (rubber-stamp): "Aprovar?" é clicado sem revisão. A mitigação documentada é o desafio-e-resposta com um checklist explícito.

Tipo: Aprender Idiomas: Python (stdlib, máquina de estado propor-e-confirmar com idempotência) Pré-requisitos: Fase 15 · 12 (Execução durável), Fase 15 · 14 (Tripwires) Tempo: ~60 minutos

O Problema

Um agente realiza uma ação. O usuário precisa decidir: aprovar ou não. Se a decisão for instantânea, provavelmente não é uma revisão. Se a decisão for estruturada, ela é lenta, mas confiável. A questão de engenharia é como tornar a revisão estruturada o caminho de menor resistência.

O padrão HITL da era de 2023 era um prompt síncrono: "O agente quer enviar um e-mail para X com o corpo Y — aprovar?" O usuário clica em Aprovar. Todos sentem que o sistema está seguro. Na prática, essa interface é amplamente carimbada automaticamente (rubber-stamped): os usuários aprovam rapidamente, as aprovações prevêem muito pouco e, quando o agente falha, a trilha de auditoria mostra um longo histórico de aprovações das quais o usuário não se lembra.

O padrão de 2026 — propor-e-confirmar (propose-then-commit) — move o HITL para um substrato durável, anexa metadados estruturados e exige uma confirmação positiva. Todo SDK de agente gerenciado inclui uma versão disso: interrupt() do LangGraph, RequestInfoEvent do Microsoft Agent Framework, waitForApproval() do Cloudflare. Os nomes das APIs diferem; o formato não.

O Conceito

A máquina de estados propor-e-confirmar (propose-then-commit)

  1. Propor (Propose). O agente gera uma ação proposta. Ela é persistida em um armazenamento durável (PostgreSQL, Redis, Durable Object). Inclui:
    • intenção (por que o agente está fazendo isso)
    • linhagem de dados (qual fonte levou a essa proposta)
    • permissões afetadas (quais escopos / arquivos / endpoints)
    • raio de impacto (qual é o pior caso)
    • plano de rollback (se confirmado, como desfazemos)
    • chave de idempotência (única por proposta; o reenvio retorna o mesmo registro)
  2. Apresentar (Surface). O revisor visualiza a proposta com todos os metadados. O revisor é uma pessoa (não o próprio agente se revisando).
  3. Confirmar (Commit). Confirmação positiva. A ação é executada.
  4. Verificar (Verify). Após a execução, o efeito colateral é lido de volta e confirmado. Se a etapa de verificação falhar, o sistema entrará em um estado de erro conhecido e os alertas serão acionados.

A chave de idempotência

Sem uma chave de idempotência, uma tentativa de reexecução após uma falha transitória pode executar duas vezes uma ação aprovada. Exemplo concreto: o usuário aprova "transferir

00 de A para B". Ocorrem oscilações na rede. O workflow tenta novamente. O usuário aprovou uma vez, mas a transferência é executada duas vezes. A chave de idempotência vincula a aprovação a um único efeito colateral exclusivo; a segunda execução se torna uma operação sem efeito (no-op).

Este é o mesmo padrão de idempotência que as APIs da Stripe e da AWS utilizam. A reutilização desse padrão para aprovações de agentes é explícita na documentação do Microsoft Agent Framework.

Durabilidade: por que as aprovações duram mais que os processos

A sala de espera de aprovação é uma parte do estado que o agente não possui. O workflow é pausado (Lição 12). Quando a aprovação chega, o workflow é retomado exatamente a partir desse ponto. É por isso que o LangGraph combina interrupt() com checkpointing no PostgreSQL e não apenas com estado em memória — uma aprovação recebida dois dias depois ainda encontra o workflow intacto.

Aprovações por carimbo automático (rubber-stamp) e a mitigação por desafio-e-resposta

A interface de usuário padrão para HITL (botões "Aprovar" / "Rejeitar") gera aprovações rápidas sem uma revisão real. Mitigação documentada: um checklist de desafio-e-resposta que exige respostas positivas a perguntas específicas antes que o botão Aprovar seja habilitado. Formato concreto:

  • "Você entende qual recurso isso afeta? [ ]"
  • "Você verificou se o raio de impacto é aceitável? [ ]"
  • "Você tem um plano de rollback se isso falhar? [ ]"

Não se trata de burocracia por si só — é uma função de indução (forcing function). O revisor que não consegue marcar as caixas deve solicitar esclarecimentos (escalonamento) ou recusar (padrão seguro). A pesquisa de segurança de agentes da Anthropic cita explicitamente o HITL baseado em checklists como uma mitigação para padrões de aprovação automatizada (rubber-stamp).

O que conta como consequente

Nem toda ação precisa de propor-e-confirmar. A orientação de 2026:

  • Ações consequentes (sempre HITL): gravações irreversíveis, transações financeiras, comunicação externa, alterações no banco de dados de produção e operações destrutivas no sistema de arquivos.
  • Ações reversíveis (às vezes HITL): edições em arquivos locais, alterações em ambiente de homologação (staging) e gravações reversíveis com rollback claro.
  • Leituras e inspeções (nunca HITL): ler um arquivo, listar recursos, chamar uma API somente de leitura.

Verificação pós-ação

"A confirmação (commit) foi executada" não é o mesmo que "o efeito colateral ocorreu". Partições de rede e condições de corrida podem gerar um workflow que acredita ter sido bem-sucedido enquanto o backend não persistiu a alteração. A etapa de verificação lê novamente o recurso de destino após a confirmação para garantir. Este é o mesmo padrão de transações de banco de dados com cláusulas RETURNING ou do GetObject da AWS após o PutObject.

Artigo 14 da Lei de IA da UE (EU AI Act)

O Artigo 14 exige supervisão humana eficaz para sistemas de IA de alto risco na UE. "Eficaz" não é decorativo. A linguagem regulatória exclui especificamente padrões de aprovação automática (rubber-stamp). O modelo propor-e-confirmar com desafio-e-resposta é o formato que sobrevive ao escrutínio do Artigo 14 nos documentos de conformidade do Microsoft Agent Governance Toolkit.

Use na Prática

code/main.py implementa uma máquina de estados propor-e-confirmar em Python com a biblioteca padrão (stdlib). O armazenamento durável é um arquivo JSON. A chave de idempotência é um hash de (thread_id, action_signature). O driver simula três casos: um fluxo de aprovação limpo, uma nova tentativa após uma falha transitória (que não deve executar duas vezes) e um padrão de aprovação automática (rubber-stamp) versus um fluxo de desafio-e-resposta.

Suba para Produção

outputs/skill-hitl-design.md revisa um fluxo de trabalho HITL proposto para o formato propor-e-confirmar e sinaliza a ausência de metadados, idempotência, verificação ou camadas de desafio-e-resposta.

Exercícios

  1. Execute code/main.py. Confirme que uma nova tentativa de uma proposta aprovada usa o registro durável e não realiza uma nova execução. Agora, altere a chave de idempotência para incluir um carimbo de data/hora (timestamp) e mostre que a nova tentativa executa duas vezes.

  2. Estenda o registro da proposta com um campo rollback. Simule uma execução cuja etapa de verificação falhe. Mostre o rollback sendo acionado automaticamente.

  3. Leia a documentação do RequestInfoEvent do Microsoft Agent Framework. Identifique um campo de metadados que a API inclui e que falta no nosso motor simplificado. Adicione-o e explique contra o que ele protege.

  4. Projete um checklist de desafio-e-resposta para uma ação específica (por exemplo, "postar em uma conta pública do Twitter"). Quais são as três perguntas que o revisor deve responder? Por que essas três?

  5. Escolha um caso em que um prompt síncrono "Aprovar?" seria suficiente (sem necessidade de armazenamento durável). Explique o motivo e nomeie a classe de risco que você está aceitando.

Termos-Chave

Termo O que as pessoas dizem O que realmente significa
Propose-then-commit "Aprovação em duas fases" Proposta persistida + confirmação positiva + verificação
Idempotency key "Token seguro contra repetições" Única por proposta; a segunda execução se torna no-op
Data lineage "De onde veio" O conteúdo de origem específico que levou à proposta
Blast radius "Pior caso" Escopo do impacto caso a ação dê errado
Rubber-stamp "Aprovação rápida" Botão "Aprovar" clicado sem uma revisão real
Challenge-and-response "Checklist obrigatório" O revisor deve responder positivamente a perguntas específicas
RequestInfoEvent "Primitiva do MS Agent Framework" Solicitação de HITL durável com metadados estruturados
interrupt() / waitForApproval() "Primitivas de frameworks" Equivalentes no LangGraph / Cloudflare com o mesmo formato

Leituras Adicionais

0 lifetime access. Curriculum based on AI Engineering from Scratch by Rohit Ghumare (MIT, used under attribution).