Skip to main content

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

1. Objetivo​

Criar uma infraestrutura de workflows de negócio duradouros para o Agentic Work, permitindo que o agente não apenas execute comandos isolados, mas acompanhe processos que podem durar minutos, horas ou dias.

O workflow deverá sobreviver a:

  • encerramento da sessão do usuário;
  • reinicialização de Workers;
  • falhas temporárias;
  • indisponibilidade de APIs;
  • espera por aprovação;
  • timers;
  • eventos externos;
  • mudança de contexto da UI;
  • retomada posterior.

O princípio é:

Uma conversa pode terminar; um processo de negócio não necessariamente termina com ela.

2. Problema

Uma execução simples:

User
 ↓
Intent
 ↓
Capability
 ↓
API
 ↓
Result

é suficiente para:

“Atualize a validade para 30 dias.”

Mas não para:

“Crie uma Permissão de Trabalho completa para esta atividade, adicione os trabalhadores, riscos e medidas de controle, envie para aprovação e me avise quando estiver liberada.”

Isso representa um processo:

Create
 ↓
Add people
 ↓
Add risks
 ↓
Add controls
 ↓
Submit
 ↓
Wait
 ↓
Approve
 ↓
Release

Algumas etapas podem ocorrer imediatamente e outras somente muito tempo depois.

3. Workflow ≠ Plan

O Execution Plan do PRD-006 representa como executar uma intenção.

O Workflow representa o processo de negócio ao longo do tempo.

Intent
  ↓
Execution Plan
  ↓
Workflow
  │
  ├── Step 1
  ├── Step 2
  ├── Wait
  ├── Human Approval
  ├── Timer
  ├── Event
  └── Step N

4. Workflow Definition

Um workflow deverá ser definido de forma declarativa.

interface WorkflowDefinition {
  workflowId: string;

  version: string;

  name: string;

  domain: string;

  trigger: WorkflowTrigger;

  states: WorkflowStateDefinition[];

  transitions: WorkflowTransition[];

  timeout?: Duration;

  compensation?: CompensationDefinition;

  policies: string[];

  status: "DRAFT" | "ACTIVE" | "DEPRECATED";
}

5. Workflow Instance

A definição é o template.

A instância representa uma execução real.

interface WorkflowInstance {
  workflowInstanceId: string;

  workflowId: string;

  workflowVersion: string;

  tenantId: string;

  initiatedBy: Principal;

  status: WorkflowStatus;

  currentState: string;

  context: WorkflowContext;

  correlationId: string;

  createdAt: string;

  updatedAt: string;
}

6. Workflow Status

CREATED
RUNNING
WAITING
WAITING_APPROVAL
WAITING_EVENT
WAITING_TIMER
PAUSED
FAILED
PARTIAL_SUCCESS
COMPLETED
CANCELLED
COMPENSATING
COMPENSATED
TERMINATED

7. State Machine

O workflow deverá ser modelado como uma máquina de estados.

Exemplo:

DRAFT
  ↓
SUBMITTED
  ↓
WAITING_APPROVAL
  ↓
APPROVED
  ↓
RELEASED
  ↓
IN_PROGRESS
  ↓
COMPLETED

8. Transitions

Cada transição deverá possuir:

interface WorkflowTransition {
  from: string;

  to: string;

  trigger: WorkflowTrigger;

  conditions?: Condition[];

  capabilityId?: string;

  policyId?: string;

  compensation?: string;
}

9. Workflow Trigger

Triggers poderão ser:

USER_COMMAND
CAPABILITY_COMPLETED
EVENT
TIMER
APPROVAL_COMPLETED
WEBHOOK
SCHEDULE
SYSTEM_EVENT
WORKFLOW_COMPLETED

10. Exemplo

USER_COMMAND
    ↓
createWorkPermit
    ↓
CAPABILITY_COMPLETED
    ↓
addWorkers
    ↓
CAPABILITY_COMPLETED
    ↓
addRisks
    ↓
APPROVAL_REQUIRED
    ↓
WAIT

11. Wait State

Um workflow poderá parar explicitamente.

WAITING_APPROVAL

Nesse estado:

não consumir CPU
não manter Worker aberto
não fazer polling contínuo

O estado fica persistido.

12. Event Resume

Quando o evento chegar:

APPROVAL_APPROVED

o workflow será retomado.

Persisted Workflow
        ↓
Event
        ↓
Resume
        ↓
Next State

13. Timer

Workflows poderão esperar:

5 minutes
2 hours
24 hours
specific date

Exemplo:

Se a aprovação não ocorrer em 24 horas, escale para o gerente.

WAIT_APPROVAL
      ↓
24h timer
      ↓
ESCALATE

14. Cloudflare Compatibility

A implementação deverá ser compatível com o modelo serverless atual.

Não assumir:

long-running Worker process

O runtime deverá persistir estado externamente e reativar o workflow quando necessário.

A implementação poderá utilizar posteriormente mecanismos como:

Durable Objects
Workflows
Queues

ou abstrações equivalentes, sem acoplar o domínio diretamente a um único produto.

15. Durable State

O estado mínimo deverá conter:

workflowInstanceId
tenantId
workflowVersion
currentState
context
pendingAction
pendingApprovals
timers
correlationId
version

16. Optimistic Concurrency

Cada instância deverá possuir:

version

Exemplo:

version = 17

Uma atualização deverá exigir:

expectedVersion = 17

Se outro processo já tiver atualizado:

version = 18

a operação deverá falhar com:

WORKFLOW_CONCURRENCY_CONFLICT

17. Workflow Lock

Para operações críticas, poderá existir lock lógico:

workflowInstanceId
+
executionId

O lock deverá possuir TTL para evitar deadlock permanente.

18. Idempotência

Cada transição deverá possuir uma chave idempotente.

interface WorkflowOperation {
  operationId: string;

  workflowInstanceId: string;

  stepId: string;

  idempotencyKey: string;
}

19. Retry

Falhas transitórias:

429
502
503
timeout
network

poderão ser repetidas.

Falhas permanentes:

400
403
404
business validation

não deverão ser repetidas automaticamente sem mudança de contexto.

20. Retry Policy

interface RetryPolicy {
  maxAttempts: number;

  backoff: "FIXED" | "EXPONENTIAL";

  initialDelayMs: number;

  maxDelayMs: number;

  retryableErrors: string[];
}

21. Dead Letter

Após exceder tentativas:

RUNNING
 ↓
FAILED
 ↓
RETRY
 ↓
FAILED
 ↓
MAX_ATTEMPTS
 ↓
MANUAL_REVIEW

22. Compensation

Workflows poderão definir compensações.

Exemplo:

Create Permit
   ↓
Add Worker
   ↓
Add Risk

Se posteriormente uma etapa crítica falhar:

compensation

poderá remover ou reverter operações anteriores, quando seguro e permitido.

23. Saga Pattern

O mecanismo deverá utilizar conceito de Saga para processos distribuídos.

Step A → success
Step B → success
Step C → failure

Compensate B
Compensate A

Mas:

compensação não significa necessariamente rollback físico.

Algumas operações de negócio não podem ser desfeitas.

24. Irreversible Operations

Exemplo:

Enviar documento oficialmente
Emitir aprovação
Liberar permissão
Registrar evento regulatório

poderá ser irreversível.

Nesse caso:

compensation = NONE

e o workflow deverá entrar em:

MANUAL_REVIEW

quando necessário.

25. Business State vs Workflow State

Não confundir:

Workflow:
WAITING_APPROVAL

com:

WorkPermit:
SUBMITTED

São estados diferentes.

O workflow acompanha o processo de automação.

O sistema de negócio continua sendo a autoridade sobre o estado da entidade.

26. Source of Truth

O workflow nunca deverá inventar o estado do negócio.

Após cada etapa relevante:

Workflow
 ↓
Existing API
 ↓
Business Database
 ↓
Verification

27. Verification

Depois de uma transição:

CAPABILITY_COMPLETED

o workflow deverá verificar o resultado quando necessário.

Exemplo:

API returned 200

não significa automaticamente:

WorkPermit = RELEASED

28. Workflow Context

interface WorkflowContext {
  entities: EntityReference[];

  variables: Record<string, unknown>;

  outputs: Record<string, unknown>;

  references: Record<string, EntityReference>;

  approvals: ApprovalReference[];

  metadata: Record<string, unknown>;
}

29. Context Security

O contexto do workflow deverá ser:

tenant-scoped
user-authorized
minimal
versioned
auditable

Nunca armazenar desnecessariamente dados sensíveis.

30. Context Snapshot

Antes de uma etapa crítica:

Workflow
 ↓
Context Snapshot
 ↓
Execution

Isso permite reconstruir posteriormente:

Qual era o estado conhecido quando a decisão foi tomada?

31. Stale Context

Antes de executar uma etapa:

entityVersion

deverá ser comparada.

Exemplo:

Workflow expects:
WP-123 version 7

Current:
WP-123 version 9

Resultado:

STALE_CONTEXT

O workflow deverá parar ou recalcular a etapa.

32. Replanning

Quando o contexto mudar significativamente:

STALE_CONTEXT
 ↓
Re-evaluate
 ↓
New Plan

Se a mudança afetar uma aprovação existente:

invalidate approval

e solicitar nova aprovação.

33. Workflow Events

Eventos internos:

WORKFLOW_CREATED
WORKFLOW_STARTED
STATE_ENTERED
STATE_EXITED
STEP_STARTED
STEP_COMPLETED
STEP_FAILED
WAIT_STARTED
TIMER_CREATED
TIMER_FIRED
APPROVAL_REQUESTED
APPROVAL_COMPLETED
CONTEXT_CHANGED
REPLAN_REQUESTED
WORKFLOW_PAUSED
WORKFLOW_RESUMED
WORKFLOW_COMPLETED
WORKFLOW_FAILED
WORKFLOW_CANCELLED
COMPENSATION_STARTED
COMPENSATION_COMPLETED

34. External Events

O workflow poderá aguardar eventos externos.

Exemplo:

WAITING_DOCUMENT

e posteriormente:

DOCUMENT_UPLOADED

retoma o processo.

35. Event Correlation

Um evento externo deverá ser associado por:

tenantId
workflowInstanceId
correlationId
eventType
entityId

Nunca aceitar somente:

eventType = APPROVED

36. Event Security

Eventos externos deverão ser autenticados e validados.

Um tenant não poderá enviar:

APPROVAL_APPROVED

para um workflow de outro tenant.

37. Human Interaction

O workflow poderá solicitar intervenção:

WAITING_APPROVAL
WAITING_INPUT
WAITING_REVIEW
WAITING_DOCUMENT

O agente poderá informar:

“A permissão está aguardando aprovação do supervisor.”

38. User Resume

Depois de horas:

“Como está aquela permissão?”

O Conversation Runtime deverá resolver:

"aquella permissão"
 ↓
workflow reference
 ↓
WP-123
 ↓
workflow status

39. Workflow References

O sistema deverá manter referências semânticas:

workflow → workPermit
workflow → employee
workflow → approval

Isso permite linguagem natural.

40. Workflow Memory

O resultado de cada etapa importante deverá ficar disponível:

Step 1:
permit created = WP-123

Step 2:
workers added = 4

Step 3:
risks added = 7

Step 4:
approval = pending

41. Conversation Independence

A conversa:

conversation-123

pode terminar.

O workflow:

workflow-982

continua.

Uma nova conversa poderá recuperar o workflow se o usuário tiver autorização.

42. Multi-User Workflow

Um workflow poderá envolver:

User A → creates
User B → reviews
User C → approves
Agent → executes

Todos permanecem auditados.

43. Multi-Tenant

Toda instância:

workflowInstanceId

deverá possuir:

tenantId

e seguir todas as regras do PRD-017.

44. Workflow Authorization

A autorização deverá ser reavaliada em cada etapa relevante.

Não assumir:

“O usuário iniciou o workflow, portanto tudo está autorizado.”

Exemplo:

Step 1:
User can create

Step 5:
User cannot approve

Step 5:
requires Supervisor

45. Workflow Policy

Policies poderão controlar:

who can start
who can modify
who can approve
who can cancel
who can resume
who can force-complete

46. Cancellation

Um workflow poderá ser cancelado:

USER_CANCEL
ADMIN_CANCEL
POLICY_CANCEL
SYSTEM_CANCEL
TIMEOUT

Cada motivo deverá ser registrado.

47. Cancellation Safety

Cancelar não significa automaticamente desfazer tudo.

Exemplo:

Workflow
 ↓
Document sent
 ↓
Cancel

O envio não pode ser desfeito.

O workflow deverá usar:

COMPENSATE
ou
MANUAL_REVIEW

quando aplicável.

48. Pause

Workflows poderão ser pausados:

PAUSED

por:

maintenance
tenant suspension
policy
manual intervention
incident

49. Resume

Ao retomar:

tenant active?
authorization valid?
policy valid?
release valid?
context valid?

Se não:

MANUAL_REVIEW

50. Release Pinning

O workflow deverá ficar associado ao:

releaseId

definido no PRD-016.

Assim:

Workflow created under Release 12

não muda silenciosamente para Release 13.

51. Workflow Migration

Uma nova versão poderá migrar workflows ativos.

Mas somente mediante estratégia explícita:

CONTINUE_OLD
MIGRATE
PAUSE
CANCEL

52. Long-Running Timeout

Workflows poderão possuir:

maxDuration

Exemplo:

maxDuration = 30 days

Ao exceder:

TIMEOUT

e aplicar policy.

53. Timer Service

Timers deverão ser persistentes.

Não usar:

setTimeout(...)

como mecanismo de workflow.

O processo deverá registrar:

timerId
workflowId
fireAt
status

54. Scheduling

Um timer poderá ser:

relative:
24h after approval request

absolute:
2026-09-10 18:00

business:
next business day

A última modalidade deverá respeitar timezone e calendário configurados.

55. Timezone

O workflow deverá armazenar timestamps em formato absoluto e possuir timezone contextual:

UTC timestamp
+
tenant timezone

Isso evita erros em deadlines.

56. Workflow UI

O Semantic UI Layer deverá expor:

workflow
workflow.status
workflow.timeline
workflow.currentStep
workflow.pendingApproval
workflow.cancel
workflow.pause

57. Workflow Timeline

A UI deverá apresentar:

✓ Permissão criada
✓ Equipe adicionada
✓ Riscos adicionados
✓ Medidas adicionadas
⏳ Aguardando supervisor
○ Liberação
○ Execução

58. Agent Interaction

O agente poderá responder:

“A permissão está aguardando aprovação do supervisor há 3 horas.”

ou:

“O supervisor aprovou. A próxima etapa é a liberação.”

59. Workflow Commands

Comandos naturais:

“Continue o processo.”

“Pause essa operação.”

“Cancele o processo.”

“Quem precisa aprovar?”

“Qual é a próxima etapa?”

“Por que está parado?”

Cada comando deverá ser convertido em capability/operation registrada.

60. Workflow Explainability

O agente deverá conseguir explicar:

current state
completed steps
pending steps
blocking reason
required approval
next transition

sem expor chain-of-thought.

61. Workflow Failure Explanation

Em vez de:

“Erro 422.”

o agente deverá produzir:

“A permissão não pôde avançar porque o trabalhador selecionado não possui o treinamento obrigatório.”

62. Failure Recovery

O workflow deverá distinguir:

TRANSIENT_FAILURE
BUSINESS_FAILURE
AUTHORIZATION_FAILURE
POLICY_FAILURE
STALE_CONTEXT
SYSTEM_FAILURE

Cada categoria terá estratégia diferente.

63. Manual Intervention

Algumas falhas deverão gerar:

MANUAL_REVIEW_REQUIRED

Exemplo:

external integration unavailable
+
operation irreversible

64. Workflow Observability

O PRD-015 deverá rastrear:

workflow duration
state duration
step duration
wait duration
approval duration
retry count
failure count
compensation count

65. Bottleneck Detection

O sistema deverá identificar:

95% of workflows
wait 18 hours
for approval

Isso permite descobrir gargalos reais do processo.

66. Workflow Analytics

Métricas:

completion rate
average duration
median duration
P95 duration
failure rate
cancellation rate
approval delay
manual intervention rate
replanning rate
compensation rate

67. Workflow Mining

O PRD-012 poderá utilizar esses dados para detectar:

Step A → Step B → Step C

como padrão recorrente e sugerir:

“Essas três operações são normalmente executadas juntas. Deseja criar uma capability composta?”

68. Composite Capability

Uma sequência frequente poderá evoluir para:

workPermit.prepareForApproval

que internamente executa:

addWorkers
addRisks
addControls
validate
submit

Isso não deve acontecer automaticamente em produção; passa pelo ciclo de Registry → Policy → Evaluation → Release.

69. Workflow Security

Nunca permitir que o agente altere diretamente:

workflow definition
policy
approval requirement
security rule

durante uma execução.

70. Workflow Definition Governance

Alterações em workflow deverão passar por:

Git
 ↓
Review
 ↓
Tests
 ↓
Evaluation
 ↓
Release

71. Workflow Testing

O PRD-014 deverá testar:

normal completion
failure
retry
timeout
approval
rejection
expiration
cancellation
pause/resume
stale context
concurrency
tenant isolation
release migration
compensation

72. Simulation

Deverá existir modo:

DRY_RUN

permitindo executar o workflow logicamente sem mutar dados reais.

73. Workflow Replay

Um workflow poderá ser reproduzido a partir de seus eventos:

Event 1
Event 2
Event 3
...
Event N

Isso será essencial para diagnóstico.

74. Event Sourcing — Uso Controlado

Não é necessário transformar toda a aplicação em Event Sourcing.

O mecanismo deverá apenas manter eventos suficientes para:

audit
replay
recovery
diagnostics

O banco de negócio existente continua sendo a fonte de verdade dos dados de negócio.

75. Workflow Store

Criar abstração:

interface WorkflowStore {
  create(instance: WorkflowInstance): Promise<void>;

  get(id: string): Promise<WorkflowInstance | null>;

  update(
    id: string,
    expectedVersion: number,
    patch: WorkflowPatch
  ): Promise<void>;

  appendEvent(event: WorkflowEvent): Promise<void>;

  createTimer(timer: WorkflowTimer): Promise<void>;

  getPendingTimers(): Promise<WorkflowTimer[]>;
}

A implementação concreta fica desacoplada da arquitetura de domínio.

76. First Vertical Slice

Implementar inicialmente:

Workflow​

workPermit.lifecycle

Estados​

DRAFT
SUBMITTED
WAITING_APPROVAL
APPROVED
RELEASED
COMPLETED

Fluxo​

Create
 ↓
Add components
 ↓
Submit
 ↓
Approval
 ↓
Release

77. Exemplo Completo

Usuário:

Prepare a permissão 123 para aprovação.

Agente:

Resolve WP-123

Planner:

validate
add missing components
validate risks
submit

Policy:

ALLOW

Workflow:

RUNNING

Depois:

WAITING_APPROVAL

Agente:

A permissão está pronta e aguardando aprovação do supervisor.

Horas depois:

APPROVAL_APPROVED

Workflow:

APPROVED

Depois:

RELEASED

O agente poderá então informar:

A permissão 123 foi aprovada e liberada.

78. Acceptance Criteria

Core​

  • workflow definitions versionadas;
  • workflow instances persistentes;
  • state machine;
  • transitions;
  • timers;
  • events;
  • pause/resume;
  • cancellation.

Reliability​

  • idempotência;
  • retries;
  • backoff;
  • concurrency control;
  • recovery;
  • stale context detection;
  • durable state.

Security​

  • tenant isolation;
  • authorization por etapa;
  • policy revalidation;
  • approval integration;
  • audit completo;
  • release pinning.

Business​

  • business state separado de workflow state;
  • verification;
  • compensation quando possível;
  • manual intervention;
  • long-running execution.

Agent​

  • workflow consultável em linguagem natural;
  • próxima etapa explicável;
  • motivo de bloqueio explicável;
  • retomada contextual;
  • commands registrados;
  • nenhuma execução arbitrária.

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

O runtime versiona definição/instância e separa workflow de estado de negócio. Checkpoints duráveis cobrem capability, espera humana e timer; callbacks stale e release divergente são rejeitados. Falha transitória só repete etapa idempotente dentro do budget, resultado externo UNKNOWN permanece explícito e falha permanente registra compensation requirement, sem executar comando arbitrário.

Em 2026-09-04, WorkflowRuntime.cancel() passou a encerrar checkpoint não terminal de forma idempotente. Cancelamento somente altera estado/revisão; não executa capability de compensação automaticamente, preservando a distinção entre cancelamento humano e compensação de falha.

Em 2026-09-05, os contratos de Workflow Runtime e dispatch passaram com 28 testes em 6 arquivos. O canário remoto comprovou tenant isolado, plano e instância persistente, snapshot COMPLETED na versão 5, capability workPermit.create@1 e execution stream COMPLETED, sem conceder autoridade além do plano e com cleanup remainingRows:0. Timer real de longa duração, recuperação comprovada de falha de infraestrutura e interface natural explicável permanecem abertos para prova dedicada.

Em 2026-09-06, a regressão atual de runtime, aprovação, dispatch, adaptadores e workflow operacional passou com 59 testes, e o typecheck do Agent passou novamente. O health público do Worker confirmou runtime e bindings. O estado permanece PARTIAL: timer real de longa duração, recovery de infraestrutura e interface natural explicável ainda requerem prova dedicada.

Em novo canário remoto de 2026-09-06, o dispatch durável recebeu recibo de policy emitido pelo servidor, recusou referência de decisão forjada, atingiu somente o caminho de capability limitado e concluiu o execution stream. O fluxo permaneceu sem autoridade implícita (authorizesExecution: false), removeu dados mutáveis de PostgreSQL/D1 (remainingRows: 0) e reteve apenas três recibos imutáveis de auditoria.

79. Resultado

Com o PRD-019, a arquitetura evolui para:

                  AGENTIC WORK
                       │
                 Conversation
                       │
                    Intent
                       │
                    Planner
                       │
                  Workflow
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
   Capability       Approval        Timer
        │              │              │
        └──────────────┼──────────────┘
                       ▼
                 Business APIs
                       │
                       ▼
                Business State
                       │
                       ▼
                 Verification
                       │
                       ▼
                    Audit

O resultado é um agente que não apenas responde ou executa comandos, mas consegue acompanhar um processo empresarial completo durante horas ou dias.

PRD-020 — Agentic Event Fabric & Reactive Architecture

O próximo passo natural é resolver o mecanismo de eventos que alimentará esses workflows.

Hoje já temos eventos conceituais em praticamente todos os PRDs:

UI events
Conversation events
Capability events
Policy events
Approval events
Workflow events
Business events
Audit events

O PRD-020 deverá criar uma camada transversal para que esses acontecimentos possam alimentar o Agentic Work de forma consistente.

O objetivo será permitir cenários como:

“Quando uma permissão for aprovada, continue automaticamente o processo.”

ou:

“Quando um treinamento obrigatório vencer, identifique as permissões afetadas e crie uma tarefa para revisão.”

ou ainda:

“Quando houver uma alteração de risco, verifique se alguma permissão ativa precisa ser reavaliada.”

Nesse estágio, o Agentic Work começa a deixar de ser apenas request-driven:

User → Agent → Action

e passa a ser também event-driven:

Business Event
      ↓
Event Fabric
      ↓
Agentic Event Resolver
      ↓
Policy
      ↓
Workflow
      ↓
Agent

Isso permitirá construir uma arquitetura verdadeiramente reativa, na qual o agente poderá atuar não somente quando alguém conversar com ele, mas também quando acontecimentos relevantes do próprio sistema ocorrerem.