Skip to main content

PRD-018 — Agentic Human-in-the-Loop & Approval Workflow

1. Objetivo​

Criar um mecanismo formal de Human-in-the-Loop (HITL) para o Agentic Work, permitindo que o agente execute automaticamente operações de baixo risco e encaminhe operações sensíveis para aprovação humana quando exigido por política, risco, workflow ou configuração do tenant.

O mecanismo deverá transformar:

“Você confirma?”

em um processo operacional formal:

Intent
  ↓
Plan
  ↓
Risk Assessment
  ↓
Policy Decision
  ↓
Approval Request
  ↓
Human Decision
  ↓
Revalidation
  ↓
Execution
  ↓
Verification
  ↓
Audit

2. Princípio Fundamental

A aprovação humana não substitui autorização.

Ela é uma etapa adicional.

Authentication
      ↓
Authorization
      ↓
Policy
      ↓
Human Approval
      ↓
Reauthorization
      ↓
Execution

Portanto:

Um usuário não pode aprovar uma operação para a qual ele próprio não possui autorização.

3. Tipos de Intervenção Humana

O sistema deverá distinguir quatro mecanismos.

3.1 Clarification​

O agente não sabe o que o usuário quis dizer.

"Qual componente?"

Não é aprovação.

3.2 Confirmation​

A operação é conhecida e autorizada, mas exige confirmação simples.

"Confirma adicionar este componente?"

3.3 Approval​

A operação exige uma decisão formal de uma pessoa autorizada.

"Esta alteração exige aprovação de um supervisor."

3.4 Human Review​

A operação foi considerada complexa, excepcional ou de risco elevado e precisa de análise humana antes de continuar.

4. Arquitetura

                 USER
                  │
                  ▼
             Conversation
                  │
                  ▼
               Intent
                  │
                  ▼
                Planner
                  │
                  ▼
             Execution Plan
                  │
                  ▼
             Policy Engine
                  │
        ┌─────────┴─────────┐
        │                   │
      ALLOW            HUMAN REVIEW
        │                   │
        │             Approval Workflow
        │                   │
        │             Human Decision
        │                   │
        └─────────┬─────────┘
                  ▼
              Revalidate
                  │
                  ▼
              Execution
                  │
                  ▼
             Verification
                  │
                  ▼
                 Audit

5. Approval Engine

Criar um novo componente:

Approval Engine

Responsabilidades:

  • criar solicitações de aprovação;
  • determinar aprovadores;
  • controlar estado;
  • receber decisões;
  • validar elegibilidade;
  • controlar expiração;
  • solicitar reaprovação;
  • executar quorum;
  • controlar aprovação sequencial/paralela;
  • produzir eventos de auditoria.

6. Approval Request

Modelo:

interface ApprovalRequest {
  approvalId: string;

  tenantId: string;

  conversationId: string;

  intentId: string;

  planId: string;

  executionId?: string;

  requestedBy: Principal;

  operation: ApprovalOperation;

  risk: RiskLevel;

  requiredApprovals: ApprovalRequirement[];

  currentApprovals: ApprovalDecision[];

  status: ApprovalStatus;

  expiresAt: string;

  policyVersion: string;

  releaseId: string;

  createdAt: string;
}

7. Approval Status

Estados:

PENDING
IN_REVIEW
APPROVED
PARTIALLY_APPROVED
REJECTED
EXPIRED
CANCELLED
SUPERSEDED
INVALIDATED
EXECUTING
COMPLETED
FAILED

8. Approval Lifecycle

PENDING
   ↓
IN_REVIEW
   ↓
APPROVED
   ↓
REVALIDATING
   ↓
EXECUTING
   ↓
COMPLETED

Caminhos alternativos:

PENDING → REJECTED
PENDING → EXPIRED
PENDING → CANCELLED
APPROVED → INVALIDATED

9. Approval Requirement

Uma política poderá definir:

interface ApprovalRequirement {
  requirementId: string;

  role?: string;

  permission?: string;

  userId?: string;

  groupId?: string;

  minimumApprovals: number;

  sequence?: number;

  mode: "SEQUENTIAL" | "PARALLEL";

  allowRequester: boolean;
}

10. Exemplos

Operação simples​

Confirmation:
1 usuário

Operação de alto risco​

Approval:
Supervisor

Operação crítica​

Approval:
Supervisor
+
Safety Manager

Operação com segregação de funções​

Requester ≠ Approver

11. Segregation of Duties

Regra obrigatória para determinadas operações:

creator != approver

Exemplo:

User A
  ↓
creates operation

User B
  ↓
approves

Agent
  ↓
executes

O agente não poderá contornar essa regra.

12. Approval Groups

A política poderá definir:

Safety Supervisors

como grupo de aprovadores.

O sistema deverá resolver os membros atuais no momento da aprovação.

Não confiar em uma lista antiga enviada pelo cliente.

13. Delegation

O sistema poderá suportar delegação formal.

Exemplo:

Supervisor A
   ↓
delegates approvals
   ↓
Supervisor B

A delegação deverá possuir:

delegate
scope
startAt
expiresAt
reason

14. Delegation Restrictions

Delegação não poderá aumentar privilégios.

Se A pode aprovar apenas:

domain = workPermit

sua delegação não poderá conceder:

domain = systemAdministration

15. Approval Quorum

Exemplo:

requiredApprovals = 2

Dos cinco aprovadores disponíveis:

A → approve
B → approve

Resultado:

QUORUM_REACHED

16. Unanimous Approval

Para operações críticas:

A → approve
B → approve
C → reject

Resultado:

REJECTED

mesmo que dois tenham aprovado.

17. Sequential Approval

Exemplo:

Supervisor
    ↓
Safety Manager
    ↓
Director

O segundo nível só fica disponível após o primeiro.

18. Parallel Approval

Exemplo:

Supervisor ──────┐
                 ├── quorum
Safety Manager ──┘

As decisões podem ocorrer independentemente.

19. Approval Policy

Exemplo conceitual:

capability: workPermit.approve

risk: high

approval:
  mode: sequential

  levels:
    - role: supervisor
      approvals: 1

    - role: safety_manager
      approvals: 1

20. Policy Evaluation

O Policy Engine continuará sendo a autoridade.

Ele poderá retornar:

ALLOW
DENY
REQUIRE_CONFIRMATION
REQUIRE_APPROVAL
REQUIRE_HUMAN_REVIEW

21. Risk-Based Approval

O nível de risco poderá depender de:

capability
resource
workflow state
batch size
field
tenant policy
user role
operation scope

Exemplo:

Alterar um campo
    → medium

Alterar 100 registros
    → high

Excluir 1.000 registros
    → critical

22. Dynamic Risk

O risco não deve ser apenas propriedade fixa da capability.

Exemplo:

workPermit.update

normalmente:

MEDIUM

Mas:

update
+
100 records
+
APPROVED state

pode resultar em:

CRITICAL

23. Approval Evidence

O aprovador deverá visualizar exatamente:

O que será feito?
Em qual registro?
Quais campos?
Qual valor atual?
Qual novo valor?
Por quê?
Quem solicitou?
Qual risco?
Qual policy?

24. No Blind Approval

Nunca mostrar apenas:

“Deseja aprovar?”

Deverá existir um resumo operacional.

Exemplo:

Alteração solicitada

Permissão: PT-10231
Campo: Validade
Atual: 15 dias
Novo: 30 dias

Solicitado por: João
Risco: Médio

[Rejeitar] [Aprovar]

25. Approval Diff

Para UPDATE:

BEFORE
validityDays: 15

AFTER
validityDays: 30

Para múltiplos campos:

name:
  "PT Industrial"
→
  "PT Industrial - Área 3"

validity:
  15
→
  30

26. Batch Approval

Nunca apresentar:

“Aprovar 2.583 alterações?”

sem detalhamento.

Deverá existir:

count
scope
filters
sample
impact
risk

e limites configuráveis.

27. Approval Preview

Antes da aprovação, o sistema poderá executar uma capability de preview:

plan.preview

Resultado:

wouldUpdate: 53
wouldFail: 2
wouldSkip: 4

O aprovador decide com base no impacto real.

28. Approval Binding

A aprovação deverá estar vinculada ao plano exato.

approvalId
    ↓
planId
    ↓
planHash

Se o plano mudar:

planHash != approvedHash

a aprovação é invalidada.

29. Anti-Substitution

Isso impede:

Approval:
"Atualizar WP-123"

Execution:
"Atualizar WP-456"

A aprovação não pode ser reutilizada.

30. Revalidation

Depois da aprovação e antes da execução:

Authorization
Policy
Resource state
Plan hash
Tenant
User
Capability

deverão ser novamente validados.

31. State Change

Exemplo:

Approval created
     ↓
WP = DRAFT
     ↓
Supervisor approves
     ↓
WP = APPROVED

A execução planejada para DRAFT pode não ser mais válida.

Resultado:

APPROVAL_INVALIDATED

32. Approval Expiration

Toda aprovação deverá possuir TTL.

Exemplo:

expiresAt = +24h

Após expiração:

EXPIRED

Não poderá ser executada.

33. Reapproval

Se uma aprovação expirar:

new ApprovalRequest

e não:

reuse old approval

34. Rejection

Uma rejeição deverá registrar:

interface ApprovalDecision {
  decisionId: string;

  approvalId: string;

  decidedBy: Principal;

  decision: "APPROVED" | "REJECTED";

  reason?: string;

  timestamp: string;

  authenticationContext: AuthenticationContext;
}

35. Rejection Reason

Para operações de alto risco, o motivo poderá ser obrigatório.

Exemplo:

REJECTED

Motivo:
"Documento de treinamento ainda não anexado."

36. Approval Correction

Se o solicitante alterar a operação:

Plan A
 ↓
approval
 ↓
User changes parameters

o plano anterior deverá ser invalidado.

Novo plano:

Plan B
 ↓
new approval

37. Approval + Conversation

A conversa deverá continuar naturalmente.

Exemplo:

Adicione o componente de trabalho em altura.

Agente:

Posso adicionar, mas esta operação exige aprovação do supervisor.

Depois:

Solicitação enviada para aprovação.

Quando aprovado:

Aprovado. Vou executar agora.

38. Asynchronous Approval

A aprovação não precisa acontecer na mesma sessão.

User A
  ↓
request
  ↓
Approval Pending
  ↓
User leaves
  ↓
User B approves
  ↓
Execution

39. Notification

O Approval Engine poderá emitir eventos:

APPROVAL_REQUESTED
APPROVAL_ASSIGNED
APPROVAL_APPROVED
APPROVAL_REJECTED
APPROVAL_EXPIRED

O sistema de notificações existente poderá consumi-los.

Não criar um sistema de notificações paralelo desnecessariamente.

40. Approval Inbox

Deverá existir uma visão:

My Approvals

com:

Pending
Approved
Rejected
Expired

41. Semantic UI Integration

A inbox poderá expor:

approval.inbox
approval.request
approval.details
approval.approve
approval.reject

Assim o agente também poderá operar sobre o workflow.

Exemplo:

Mostre minhas aprovações pendentes.

O agente poderá navegar para:

approval.inbox

42. Natural Language Approval

O aprovador poderá dizer:

“Aprovar.”

O Conversation Runtime deverá verificar:

activeApproval
currentUser
tenant
approval status

Somente então interpretar a ação.

43. Ambiguous Approval

Se houver:

5 approvals pending

e o usuário disser:

“Aprovar.”

O agente deverá perguntar:

“Qual aprovação você deseja aprovar?”

Nunca escolher arbitrariamente.

44. Contextual Approval

Se houver uma aprovação aberta:

Approval #9821

e o usuário disser:

“Aprovar essa.”

poderá resolver deterministicamente:

this = active approval

45. Approval Authorization

Antes de aceitar:

APPROVED

validar:

user authenticated
tenant matches
approver eligible
permission exists
approval pending
not expired
not requester

46. Emergency Override

Operações críticas poderão possuir mecanismo de emergência.

Mas:

Emergency override não significa ignorar auditoria.

Deverá registrar:

who
why
when
what
policy
override authority

47. Break-Glass

Se implementado:

normal policy
    ↓
DENY
    ↓
authorized break-glass
    ↓
temporary access
    ↓
mandatory audit

O mecanismo deverá ser extremamente restrito.

48. Approval Audit

Registrar:

REQUESTED
VIEWED
CLAIMED
APPROVED
REJECTED
EXPIRED
CANCELLED
INVALIDATED
EXECUTED

49. Approval Forensics

Deverá ser possível responder:

Quem aprovou esta alteração?

E:

O que exatamente essa pessoa aprovou?

E:

Qual versão da política estava ativa?

E:

O plano executado era exatamente o plano aprovado?

50. Approval Record Immutability

Após decisão:

APPROVED

o registro da decisão não deverá ser alterado.

Correções devem gerar novos eventos.

51. Human Decision ≠ LLM Decision

O agente poderá:

recommend
summarize
explain

mas não poderá falsificar:

human approval

52. No Synthetic Approval

É proibido:

Agent → approve()

em nome do usuário.

O agente jamais poderá simular uma aprovação humana.

53. Approval Authentication

Para operações críticas, poderá ser exigida autenticação reforçada:

normal session
+
step-up authentication

O mecanismo deverá ser compatível com a infraestrutura de identidade existente.

54. Multi-Level Approval

Exemplo SST:

Agent
 ↓
Supervisor
 ↓
Safety Manager
 ↓
Responsible Director
 ↓
Execution

Cada etapa deverá ser independente e auditável.

55. Approval Workflow Definition

Modelo:

interface ApprovalWorkflow {
  workflowId: string;

  version: string;

  trigger: ApprovalTrigger;

  levels: ApprovalLevel[];

  quorum?: QuorumPolicy;

  expiration: Duration;

  segregationOfDuties?: boolean;

  revalidation: RevalidationPolicy;
}

56. Workflow Versioning

Uma aprovação criada usando:

workflowVersion = 3

deverá continuar vinculada à versão 3.

Uma nova versão não deverá alterar retroativamente uma aprovação existente sem regra explícita de migração/invalidação.

57. Tenant-Specific Workflows

O tenant poderá configurar:

workPermit.approve

com:

1 supervisor

enquanto outro tenant exige:

1 supervisor
+
1 safety manager

58. Global Safety Minimum

Entretanto, a plataforma poderá definir requisitos mínimos globais.

Exemplo:

GLOBAL:
critical deletion requires human approval

O tenant não poderá desabilitar isso.

59. Approval Policy Resolution

Fluxo:

Global Policy
 ↓
Tenant Policy
 ↓
Resource Policy
 ↓
Current Workflow State
 ↓
Effective Approval Policy

60. Approval SLA

Poderá existir:

approval SLA = 4 hours

para determinadas operações.

Isso permitirá detectar:

approval overdue

61. Escalation

Após SLA:

Supervisor
   ↓ timeout
Manager

A escalada deverá ser definida pela policy.

62. No Automatic Approval on Timeout

Por padrão:

timeout ≠ approve

O comportamento default deverá ser:

EXPIRED

ou escalada.

63. Approval Cancellation

O solicitante poderá cancelar enquanto:

PENDING

desde que a policy permita.

Após:

EXECUTING

não é mais cancelamento da aprovação; passa a ser controle da execução.

64. Approval and Undo

São conceitos diferentes:

Approval
→ autoriza execução futura

Undo
→ tenta compensar execução já realizada

O PRD-012/006 continua responsável pelo mecanismo de compensação.

65. Approval Failure

Se:

approved
 ↓
execution
 ↓
API failure

o status deverá ser:

EXECUTION_FAILED

e não:

REJECTED

A decisão humana continua registrada como aprovada.

66. Partial Execution

Em batch:

Approval:
100 records

Execução:

97 succeeded
3 failed

Resultado:

PARTIAL_SUCCESS

Não solicitar nova aprovação para os 97 já executados.

67. Retry

Retry deverá respeitar:

same approved plan
same tenant
same capability
same authorization

Se os parâmetros mudarem:

new plan
new approval

68. Approval Security Model

              Human
                │
         Authentication
                │
         Authorization
                │
         Approval Engine
                │
          Policy Engine
                │
          Plan Validation
                │
            Execution

Nenhum componente isolado pode conceder autorização.

69. Observability

Registrar métricas:

approval_requests
approval_latency
approval_approval_rate
approval_rejection_rate
approval_expiration_rate
approval_escalation_rate
approval_invalidated_rate

Também:

time_to_approval
time_to_execution_after_approval

70. Agent Performance

O agente deverá saber quando não precisa de HITL.

Meta:

Low Risk
→ automatic execution

e:

High/Critical
→ approval

Isso evita transformar o agente em um sistema que pergunta:

“Você confirma?”

para absolutamente tudo.

71. Fast Path

Exemplo:

"Abra a aba Componentes"

→ sem approval.

"Explique este risco"

→ sem approval.

"Adicione este componente"

→ policy determina.

"Exclua todos os componentes"

→ approval/human review.

72. Integration with Existing PRDs

O HITL deverá integrar diretamente com:

PRD-004 Capability Registry
PRD-005 Intent Engine
PRD-006 Planner & Orchestrator
PRD-008 Policy Engine
PRD-010 Conversation Runtime
PRD-013 Security/Audit
PRD-014 Testing
PRD-015 Observability
PRD-016 Release Management
PRD-017 Multi-Tenancy

73. End-to-End Example

Usuário:

Exclua todos os componentes desta permissão.

Intent​

DELETE
target = workPermit.components
scope = currentWorkPermit

Planner​

workPermit.components.deleteBatch

Policy​

risk = CRITICAL
decision = REQUIRE_APPROVAL

Approval​

Supervisor approval required

Human​

Aprovar.

Revalidation​

tenant ✓
user ✓
policy ✓
plan hash ✓
resource ✓
permission ✓

Execution​

DELETE 17 components

Verification​

remaining components = 0

Audit​

requested
approved
executed
verified

74. Primeiro Vertical Slice

Implementar inicialmente:

workPermit.components.remove

com:

Intent
→ Plan
→ Policy
→ Approval
→ Revalidation
→ Execution
→ Verification
→ Audit

Depois:

workPermit.approve
workPermit.cancel
batch operations

75. Acceptance Criteria

Approval​

  • Approval Engine implementado.
  • Approval Request persistente.
  • Estados formalizados.
  • Aprovação vinculada ao plano.
  • Plan hash validado.
  • TTL implementado.
  • Revalidação antes da execução.

Security​

  • aprovador autenticado;
  • autorização validada;
  • tenant validado;
  • requester ≠ approver quando exigido;
  • nenhum approval sintético;
  • aprovação não pode ser reutilizada.

Workflow​

  • aprovação sequencial;
  • aprovação paralela;
  • quorum;
  • rejeição;
  • expiração;
  • cancelamento;
  • reaprovação;
  • delegação controlada;
  • escalada opcional.

Audit​

  • toda decisão registrada;
  • decisão imutável;
  • plano aprovado registrado;
  • identidade do aprovador registrada;
  • versão de policy registrada;
  • release registrado.

UX​

  • aprovação mostra impacto;
  • mostra diff;
  • mostra risco;
  • mostra solicitante;
  • suporta linguagem natural;
  • suporta aprovação assíncrona.

Evidência parcial de implementação — 2026-09-04​

O Approval Engine e o workspace persistem proposta vinculada a plano/hash, TTL, policy/release e identidade humana; confirmação não substitui reautorização. O fluxo suporta sequência, paralelo, quorum, rejeição, expiração, cancelamento, reaprovação e delegação limitada, com SoD e token one-time hashado. Cada decisão é auditável e imutável, e timeout nunca aprova automaticamente.

Em 2026-09-05, a suíte de Approval passou com 40 testes em 7 arquivos. O canário remoto de colaboração comprovou workspace tenant-isolado, humanos independentes, SoD rejeitada, approval QUORUM com dois votos, two-person rule, token one-time, revalidação antes da execução, revogação por drift material e reapproval, sem burlar policy e com cleanup remainingRows:0. UX de impacto/diff/linguagem natural permanece aberta para prova dedicada.

Em 2026-09-06, a regressão atual de engine, confirmação, sessão Durable Object, access, workspace, delegação e workflow passou com 48 testes, e o typecheck do Agent passou novamente. O health público do Worker confirmou runtime e bindings. O estado permanece PARTIAL porque a UX de impacto/diff/linguagem natural e a expansão do workspace ainda requerem prova dedicada.

Em novo canário remoto de 2026-09-06, dois humanos independentes concluíram aprovação QUORUM com two-person rule e token one-time; autoaprovação por SoD, adulteração de policy/voto e acesso anônimo foram negados. O fluxo revogou approval após drift material de versão, exigiu reapproval, preservou revalidação de execução sem conceder autoridade e confirmou isolamento tenant-scoped, guards concorrentes e cleanup PostgreSQL (remainingRows: 0).

76. Resultado

Com o PRD-018, o Agentic Work deixa de ter apenas:

Agent → Execute

e passa a possuir um modelo corporativo completo:

                USER
                  │
                  ▼
               INTENT
                  │
                  ▼
                PLAN
                  │
                  ▼
               POLICY
                  │
        ┌─────────┴─────────┐
        │                   │
      ALLOW             APPROVAL
        │                   │
        │              HUMAN DECISION
        │                   │
        │              REVALIDATION
        │                   │
        └─────────┬─────────┘
                  ▼
              EXECUTION
                  │
                  ▼
             VERIFICATION
                  │
                  ▼
                AUDIT

Isso é particularmente importante para um sistema de SST, onde determinadas operações não devem depender exclusivamente da decisão autônoma do agente.

PRD-019 — Agentic Workflow & Long-Running Business Processes​

O próximo estágio deverá subir um nível de abstração.

Até aqui construímos a capacidade de o agente executar uma operação:

Intent
→ Plan
→ Capability
→ Policy
→ Approval
→ Execution

O PRD-019 deverá tratar processos de negócio completos e duradouros, que podem durar minutos, horas ou dias e envolver múltiplas pessoas, sistemas e etapas.

Exemplos:

Criar uma Permissão de Trabalho
        ↓
Adicionar equipe
        ↓
Adicionar riscos
        ↓
Adicionar medidas de controle
        ↓
Solicitar aprovação
        ↓
Supervisor aprova
        ↓
Responsável de SST aprova
        ↓
Liberar permissão
        ↓
Executar atividade
        ↓
Encerrar permissão

Nesse estágio, o Agentic Work deixa de ser apenas um agente que executa comandos e passa a ser uma camada capaz de orquestrar processos de negócio completos, preservando estado, timers, eventos, aprovações, compensações, retomadas e auditoria.

Isso será especialmente importante considerando a infraestrutura serverless/Cloudflare existente, porque esses workflows não poderão depender da permanência de uma única execução de Worker.