PRD-024 — Agentic Exception Management & Incident Response
1. Objetivo
O Agentic Exception Management & Incident Response será responsável por detectar, classificar, conter, recuperar e acompanhar exceções que ocorram durante qualquer operação do Agentic Work.
Até aqui, a arquitetura foi projetada principalmente para o caminho feliz:
Intent
↓
Plan
↓
Policy
↓
Capability
↓
Execution
↓
Verification
O PRD-024 define o que acontece quando algo dá errado.
Execution
↓
Exception
↓
Classification
↓
Impact Analysis
↓
Containment
↓
Recovery
↓
Verification
↓
Resolution
↓
Learning
2. Princípio fundamental
Uma falha não pode ser tratada simplesmente como um erro técnico.
Uma exceção poderá representar:
- falha de infraestrutura;
- falha de autorização;
- violação de regra;
- estado inesperado do negócio;
- inconsistência de dados;
- falha de integração;
- timeout;
- execução parcial;
- resultado não verificável;
- possível incidente de segurança;
- problema operacional.
O sistema deverá distinguir esses casos.
3. Exceção vs. Incidente
Exception
é uma ocorrência durante uma operação.
Incident
é uma situação que exige tratamento operacional estruturado.
Exemplo:
API timeout
pode ser apenas:
TRANSIENT_EXCEPTION
Mas:
50 Work Permits parcialmente alteradas
poderá gerar:
OPERATIONAL_INCIDENT
4. Arquitetura
Execution Runtime
│
▼
Exception Detector
│
▼
Exception Classifier
│
▼
Impact Analyzer
│
┌─────────┴─────────┐
▼ ▼
Recoverable Critical
│ │
▼ ▼
Recovery Engine Incident Manager
│ │
└─────────┬─────────┘
▼
Verification
│
▼
Resolution Engine
│
▼
Audit/Learning
5. Exception Model
interface AgentException {
exceptionId: string;
tenantId: string;
category: ExceptionCategory;
severity: ExceptionSeverity;
source: ExceptionSource;
message: string;
operationId?: string;
executionId?: string;
planId?: string;
workflowId?: string;
capabilityId?: string;
resourceRefs: EntityReference[];
retryable: boolean;
recoverable: boolean;
requiresHumanReview: boolean;
detectedAt: string;
metadata: Record<string, unknown>;
}
6. Categorias
AUTHORIZATION
VALIDATION
BUSINESS_RULE
RESOURCE_STATE
CONFLICT
NOT_FOUND
DEPENDENCY
TIMEOUT
NETWORK
RATE_LIMIT
EXTERNAL_SERVICE
DATABASE
CONCURRENCY
VERIFICATION
PARTIAL_EXECUTION
SECURITY
SYSTEM
UNKNOWN
7. Severidade
LOW
MEDIUM
HIGH
CRITICAL
Uma primeira classificação:
| Severidade | Exemplo |
|---|---|
| LOW | operação secundária falhou |
| MEDIUM | operação do usuário precisa retry |
| HIGH | workflow importante interrompido |
| CRITICAL | risco de segurança, compliance ou grande impacto |
8. Error Taxonomy
O sistema deverá evitar mensagens genéricas como:
Something went wrong.
Deverá produzir códigos estruturados:
enum AgentErrorCode {
AUTH_REQUIRED,
NOT_AUTHORIZED,
TENANT_MISMATCH,
RESOURCE_NOT_FOUND,
RESOURCE_STATE_CHANGED,
VALIDATION_FAILED,
POLICY_DENIED,
CONCURRENT_MODIFICATION,
DEPENDENCY_UNAVAILABLE,
RATE_LIMITED,
TIMEOUT,
EXTERNAL_SERVICE_FAILURE,
VERIFICATION_FAILED,
PARTIAL_EXECUTION,
UNKNOWN_STATE
}
9. Exception Classification
A classificação deverá ser inicialmente determinística.
Exemplo:
HTTP 403
↓
NOT_AUTHORIZED
HTTP 409
↓
CONCURRENT_MODIFICATION
HTTP 429
↓
RATE_LIMITED
HTTP 504
↓
TIMEOUT
LLM poderá auxiliar somente em casos realmente ambíguos.
10. Impact Analysis
Depois de detectar uma exceção:
Exception
↓
What was affected?
O sistema deverá determinar:
affected entities
affected operations
affected workflows
affected users
affected capabilities
affected tenant scope
11. Blast Radius
O sistema deverá utilizar o conceito do PRD-021.
SINGLE_RESOURCE
SMALL_BATCH
LARGE_BATCH
TENANT_WIDE
SYSTEM_WIDE
Exemplo:
1 failed Work Permit
versus:
2,300 Work Permits
não podem possuir o mesmo tratamento.
12. Partial Execution
Esse será um dos requisitos mais importantes.
Imagine:
User:
“Atualize 100 Work Permits.”
O plano executa:
1–73 SUCCESS
74 FAILED
75–100 NOT_EXECUTED
O sistema não deverá simplesmente retornar:
“Erro.”
Deverá registrar:
73 succeeded
1 failed
26 not executed
13. Partial Execution Model
interface ExecutionOutcome {
total: number;
succeeded: number;
failed: number;
skipped: number;
pending: number;
results: ExecutionItemResult[];
}
14. Recovery Strategies
O Recovery Engine deverá suportar:
RETRY
RESUME
ROLLBACK
COMPENSATE
SKIP
WAIT
ESCALATE
ABORT
A estratégia deverá ser determinada por:
exception
+
capability
+
policy
+
workflow
+
blast radius
15. Retry Policy
Nem toda falha pode sofrer retry.
Retry permitido
timeout
temporary network failure
429
temporary 5xx
Retry proibido ou condicionado
403
validation error
business rule violation
tenant mismatch
protected resource
16. Exponential Backoff
Exemplo:
1s
2s
4s
8s
16s
Com:
maxAttempts
maxDelay
jitter
configuráveis.
17. Idempotency
Toda capability mutável deverá suportar idempotência quando aplicável.
idempotencyKey =
tenantId
+
executionId
+
stepId
+
resourceId
Isso impede:
retry
↓
duplicate mutation
18. Concurrency Conflict
Exemplo:
Agent reads WP-10231
↓
Human changes WP-10231
↓
Agent attempts update
↓
409 Conflict
O agente não deverá sobrescrever automaticamente a alteração humana.
Resultado:
RESOURCE_STATE_CHANGED
↓
REPLAN_REQUIRED
19. Replanning
Quando o estado mudar, o Planner poderá gerar um novo plano.
Mas:
Uma nova execução deverá passar novamente por Policy e Authorization.
Não poderá simplesmente continuar com permissões antigas.
20. Stale Context
O sistema deverá verificar:
contextVersion
resourceVersion
knowledgeVersion
policyVersion
Se houver mudança relevante:
STALE_CONTEXT
e a operação poderá ser interrompida.
21. Verification Failure
Uma operação pode retornar 200 OK e ainda assim falhar funcionalmente.
Exemplo:
API:
200 OK
Database:
validity did not change
O Verification Engine deverá detectar:
VERIFICATION_FAILED
Isso será tratado como uma exceção própria.
22. Unknown State
Um caso perigoso:
Request sent
↓
Network timeout
Não sabemos se a API executou ou não.
O sistema não poderá simplesmente repetir.
Estado:
UNKNOWN
Deverá tentar determinar o estado através de:
idempotency lookup
read-after-write
operation status
business entity lookup
Se continuar desconhecido:
HUMAN_REVIEW
quando a operação for relevante.
23. Recovery Decision
interface RecoveryDecision {
exceptionId: string;
strategy:
| "RETRY"
| "RESUME"
| "ROLLBACK"
| "COMPENSATE"
| "WAIT"
| "SKIP"
| "ESCALATE"
| "ABORT";
confidence: number;
reason: string;
requiresApproval: boolean;
maxAttempts?: number;
}
24. Compensation
Quando rollback técnico não for possível:
Forward action
↓
Compensating action
Exemplo:
Create assignment
↓
Later failure
↓
Remove assignment
A compensação deverá ser uma capability registrada.
Nunca deverá ser inventada pelo LLM.
25. Saga
Workflows complexos poderão usar:
Step A
↓
Step B
↓
Step C
↓
Failure
↓
Compensate C
↓
Compensate B
↓
...
Somente capabilities com compensação explicitamente definida poderão participar de uma Saga automática.
26. Irreversible Operations
Algumas operações não possuem rollback.
Exemplo:
external notification
legal record submission
external system transaction
Nesses casos:
COMPENSATION = unavailable
O sistema deverá elevar a proteção antes da execução.
27. Incident Creation
Uma exceção deverá gerar incidente quando:
severity >= HIGH
ou:
blastRadius >= LARGE_BATCH
ou:
security concern
ou:
repeated failure
ou:
critical workflow blocked
28. Incident Model
interface AgentIncident {
incidentId: string;
tenantId: string;
severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
category: string;
title: string;
description: string;
exceptionIds: string[];
affectedEntities: EntityReference[];
affectedOperations: string[];
impact: IncidentImpact;
status:
| "OPEN"
| "INVESTIGATING"
| "CONTAINED"
| "RECOVERING"
| "RESOLVED"
| "CLOSED";
owner?: string;
createdAt: string;
resolvedAt?: string;
}
29. Incident Lifecycle
OPEN
↓
INVESTIGATING
↓
CONTAINED
↓
RECOVERING
↓
RESOLVED
↓
CLOSED
Pode haver:
OPEN
↓
ESCALATED
30. Automatic Containment
O sistema poderá executar medidas de contenção previamente autorizadas.
Exemplo:
Repeated capability failures
↓
Disable automatic execution for that capability
Outro:
External integration failing
↓
Pause affected workflows
A contenção deverá estar previamente definida por política.
31. Circuit Breaker
Capabilities e integrações deverão poder possuir circuit breaker.
NORMAL
↓ failures
OPEN
↓ timeout
HALF_OPEN
↓ success
NORMAL
Durante OPEN:
AUTO_EXECUTE = BLOCKED
32. Failure Storm Protection
Se ocorrer:
1,000 failures / minute
o sistema não deverá criar:
1,000 independent incidents
Deverá agrupar:
Failure Pattern
↓
1 Incident
↓
1,000 occurrences
33. Incident Correlation
Os incidentes deverão ser correlacionados por:
tenant
capability
endpoint
workflow
exceptionCode
externalService
time window
resource type
34. Root Cause Assistance
O sistema poderá identificar possíveis causas:
100 workflows failing
+
same external API
+
same HTTP 503
Resultado:
“Possível indisponibilidade do serviço externo X.”
Isso é uma hipótese, não um fato.
35. Root Cause Model
interface RootCauseHypothesis {
hypothesisId: string;
description: string;
evidenceRefs: string[];
confidence: number;
status:
| "SUSPECTED"
| "CONFIRMED"
| "REJECTED";
}
36. LLM no Incident Response
O LLM poderá auxiliar em:
- resumir incidentes;
- correlacionar logs;
- explicar impacto;
- sugerir hipóteses;
- resumir histórico;
- sugerir procedimentos documentados.
Não poderá:
- modificar infraestrutura arbitrariamente;
- executar comandos não registrados;
- alterar políticas;
- conceder privilégios;
- ignorar controles.
37. Incident Knowledge
O Knowledge Router poderá recuperar:
Runbooks
Procedures
Documentation
Known Issues
Previous Incidents
Capabilities
Policies
Exemplo:
“Esse erro já ocorreu 12 vezes e existe um procedimento de recuperação aprovado.”
38. Runbook Registry
Deverá existir um catálogo de procedimentos.
interface Runbook {
runbookId: string;
name: string;
description: string;
applicableExceptions: string[];
requiredCapabilities: string[];
riskLevel: string;
approvalRequired: boolean;
version: string;
status: "ACTIVE" | "DEPRECATED";
}
39. Runbook ≠ Capability
Runbook é:
como tratar
Capability é:
o que o sistema consegue executar
Exemplo:
Runbook:
Recover stalled Work Permit workflow
Capabilities:
workflow.resume
workflow.retry
notification.send
40. Human Incident Response
Incidentes importantes deverão ser enviados ao Decision Center.
Exemplo:
Incidente crítico
42 Work Permits não puderam ser verificadas após falha de integração.
Ações:
[Investigar]
[Executar Runbook]
[Escalar]
[Encerrar]
41. Escalation
A escalada poderá seguir:
Operational Owner
↓
Supervisor
↓
Safety Manager
↓
Administrator
As regras deverão ser definidas por tenant, respeitando políticas globais.
42. Incident SLA
Cada incidente poderá possuir:
response SLA
containment SLA
resolution SLA
Exemplo:
CRITICAL
Response: 15 min
Containment: 30 min
Resolution: 4h
43. Notification Integration
O PRD-022 será utilizado para:
Incident
↓
Attention Item
↓
Notification
↓
Escalation
Não deverá existir um sistema paralelo de notificações.
44. Workflow Integration
Um incidente poderá:
pause workflow
resume workflow
create recovery workflow
request approval
Mas sempre através das APIs/capabilities existentes.
45. Audit
Cada etapa deverá ser auditada:
EXCEPTION_DETECTED
EXCEPTION_CLASSIFIED
IMPACT_ANALYZED
RECOVERY_SELECTED
RETRY_STARTED
RETRY_FAILED
COMPENSATION_STARTED
COMPENSATION_COMPLETED
INCIDENT_CREATED
INCIDENT_ESCALATED
INCIDENT_CONTAINED
INCIDENT_RESOLVED
46. Security Incident
Se a exceção indicar:
tenant mismatch
unexpected privilege
unauthorized access
suspicious mass operation
policy bypass attempt
prompt injection
deverá ser classificada também como potencial:
SECURITY_INCIDENT
e encaminhada ao mecanismo de segurança do PRD-013.
47. Tenant Isolation
Incidentes deverão ser isolados por tenant.
Um incidente de:
Tenant A
não poderá revelar:
Tenant B
mesmo que a causa técnica seja compartilhada.
O sistema poderá manter um padrão global anonimizado:
“A integração X está apresentando aumento de erros.”
mas sem expor dados de outro cliente.
48. Multi-Tenant Incident Correlation
A arquitetura poderá detectar:
Tenant A → API 503
Tenant B → API 503
Tenant C → API 503
e inferir:
Possible shared infrastructure issue
Porém os detalhes de cada tenant deverão permanecer isolados.
49. Data Retention
Exceções e incidentes deverão possuir políticas de retenção separadas:
Operational Exceptions
Audit Records
Security Incidents
Long-term Incident History
Dados sensíveis deverão seguir as políticas de retenção do sistema.
50. Incident Timeline
Cada incidente deverá possuir timeline:
10:02 Exception detected
10:02 Retry attempted
10:03 Retry failed
10:03 Incident created
10:04 Owner notified
10:07 Incident acknowledged
10:12 Recovery started
10:15 Recovery verified
10:16 Incident resolved
Isso será extremamente importante para auditoria.
51. Post-Incident Analysis
Após resolução:
Incident
↓
Analysis
↓
Root Cause
↓
Impact
↓
Recovery
↓
Lessons Learned
52. Post-Incident Record
interface IncidentReview {
incidentId: string;
rootCause?: string;
contributingFactors: string[];
impactSummary: string;
recoverySummary: string;
preventiveActions: string[];
createdAt: string;
reviewedBy?: string;
}
53. Operational Learning
O PRD-012 deverá receber:
exception frequency
recovery success
failed recovery
manual intervention
root cause
false classification
time to recovery
Isso permitirá descobrir:
“A capability
workPermit.updateValidityapresentou aumento de conflitos de concorrência nas últimas três versões.”
54. Automatic Learning Boundary
O sistema poderá sugerir:
“Adicionar retry para timeout dessa integração.”
Mas não poderá alterar automaticamente:
Capability
Policy
Retry limits
Security controls
A mudança deverá passar pelo ciclo:
Suggestion
→ Human Review
→ Test
→ Evaluation
→ Release
55. Testing
O PRD-014 deverá incorporar cenários:
single failure
multiple failures
partial execution
timeout
unknown outcome
concurrency conflict
policy denial
verification failure
external outage
retry storm
compensation failure
incident escalation
56. Chaos Testing
Deverá existir capacidade de simular:
API unavailable
database timeout
Event Fabric delay
duplicate event
out-of-order event
network failure
Worker restart
stale context
external dependency failure
Sem executar operações reais em produção.
57. Observability
O trace deverá permitir:
Operation
↓
Step
↓
Exception
↓
Recovery
↓
Retry
↓
Verification
Métricas:
Exception Rate
Exception by Capability
Exception by Tenant
Retry Rate
Recovery Success Rate
Compensation Rate
Incident Rate
Mean Time To Detect
Mean Time To Recover
Mean Time To Resolve
Unknown Outcome Rate
58. Performance
Objetivos:
Exception classification P95 < 20ms
Impact analysis P95 < 100ms
Recovery decision P95 < 50ms
Investigação complexa poderá ser assíncrona.
59. First Vertical Slice
Domínio:
Work Permit Batch Update
Comando:
“Atualize a validade destas 100 Work Permits.”
Execução:
1–70 SUCCESS
71 TIMEOUT
72–100 PENDING
O sistema deverá:
detect timeout
↓
check idempotency
↓
verify WP-71
↓
if unknown → lookup status
↓
retry if safe
↓
continue remaining
60. Segundo cenário
API externa indisponível:
Work Permit verification
↓
External API
↓
503
Resultado:
Circuit Breaker
↓
Pause affected verification workflows
↓
Create incident
↓
Attention Center
↓
Notify responsible operator
Quando a integração retornar:
HALF_OPEN
↓
health check
↓
resume workflows
61. Terceiro cenário — Verification Failure
Capability:
workPermit.updateValidity
API:
200 OK
Verification:
validUntil unchanged
Resultado:
VERIFICATION_FAILED
O agente não deverá responder:
“Atualização concluída.”
Deverá informar:
“A API aceitou a operação, mas a alteração não pôde ser confirmada. A operação foi colocada em estado de revisão.”
62. Critérios de Aceitação
- Exception Model implementado.
- Error taxonomy implementada.
- Severidade implementada.
- Classificação determinística implementada.
- Impact Analysis implementada.
- Blast Radius integrado.
- Partial Execution implementado.
- Retry Policy implementada.
- Idempotency implementada.
- Concurrency Conflict tratado.
- Stale Context tratado.
- Unknown State tratado.
- Verification Failure tratado.
- Compensation suportada.
- Saga preparada.
- Circuit Breaker implementado.
- Failure Storm Protection implementada.
- Incident Model implementado.
- Incident Lifecycle implementado.
- Incident Timeline implementada.
- Runbook Registry implementado.
- Human Incident Response integrado.
- Escalation integrado.
- Decision Center integrado.
- Notification Engine integrado.
- Security Incident integrado ao PRD-013.
- Operational Learning integrado ao PRD-012.
- Chaos Testing integrado ao PRD-014.
- Observability integrada ao PRD-015.
- Tenant isolation validada.
- Primeira vertical slice de batch update funcionando.
Evidência parcial de implementação — 2026-09-04
Exception/Incident modela taxonomy, severidade, correlação tenant-safe, recuperação limitada, UNKNOWN, retry idempotente, compensação explícita e circuit breaker. Falhas são sanitizadas, replay autenticado preserva o histórico e conflito/stale/verification não são interpretados como sucesso.
Em 2026-09-05, o gate de exceções passou com 313 testes em 55 arquivos. O canário operacional remoto comprovou situação CRITICAL → UNKNOWN → NORMAL, uma exceção e um incidente, Attention, decisão, intervenção, recuperação, reservas liberada/retomada, audit facts, state transitions, isolamento e negação anônima, sem autoridade automática. O Runbook Registry possui catálogo tenant-bound e versionado, com procedimentos imutáveis ACTIVE/DEPRECATED, exceções aplicáveis, capabilities requeridas, risco e necessidade de aprovação; o registro é restrito a gestores e a leitura não executa capability. A migração remota 0137_runbook_registry.sql, três testes focados e typecheck passaram antes da publicação do Worker 0ff197d1-a196-4eee-bb62-b2215a64aa5f.
Em 2026-09-05, incidentes HIGH/CRITICAL passam a gerar Attention Item idempotente na fila humana incident-response, preservando correlação, tenant e severidade; não notificam nem autorizam recuperação automática. Worker 7ec1f0ba-1816-4d18-9e63-35bd669186bb publicado com health público saudável.
Em 2026-09-06, a regressão atual de exceções, projeção operacional e recuperação de intervenção passou com 7 testes. O typecheck do Agent passou novamente, e o health público do Worker confirmou runtime e bindings. O estado permanece PARTIAL: runbooks e integração automática de toda execução ainda exigem cobertura mais ampla.
63. Resultado arquitetural
Com o PRD-024, o Agentic Work passa a ter um sistema completo de recuperação, e não apenas de execução.
AGENTIC WORK
│
┌────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
Reactive Proactive Decision
│ │ │
└────────────────┼─────────────────┘
▼
Execution
│
▼
Failure?
│
▼
Exception
│
▼
Impact Analysis
│
┌───────────┴───────────┐
▼ ▼
Recoverable Incident
│ │
▼ ▼
Recovery Escalation
│ │
└───────────┬───────────┘
▼
Verification
│
▼
Resolution
│
▼
Operational Learning
O princípio passa a ser:
O agente não é considerado bem-sucedido porque conseguiu chamar uma API. Ele só é considerado bem-sucedido quando consegue verificar o resultado ou encaminhar corretamente a situação para recuperação humana.
PRD-025 — Agentic External Integration & Digital Workforce Gateway
O próximo passo natural será expandir o Agentic Work para fora dos limites do próprio SST.
Até agora, praticamente toda a arquitetura trabalha dentro do ecossistema:
React
Hono
Business APIs
HAG
Vectorize
Capabilities
Workflows
Event Fabric
Mas um sistema SST real precisará interagir com:
- sistemas de RH;
- folha;
- sistemas médicos;
- fornecedores;
- LMS/treinamentos;
- sistemas de controle de acesso;
- ERPs;
- APIs governamentais;
- e-mail;
- WhatsApp ou outros canais, quando apropriado;
- sistemas de terceiros;
- webhooks;
- arquivos;
- integrações legadas.
O PRD-025 deverá criar um External Integration Gateway, estabelecendo uma fronteira segura:
Agentic Work
│
▼
Capability Registry
│
▼
External Gateway
│
┌──────────┼──────────┐
▼ ▼ ▼
API Webhook External App
│ │ │
└──────────┼──────────┘
▼
Verification
O ponto crítico será que nenhum agente poderá acessar diretamente credenciais, tokens, URLs arbitrárias ou sistemas externos.
Toda integração deverá possuir:
- identidade própria;
- credenciais isoladas;
- tenant binding;
- capability mapping;
- rate limiting;
- schema validation;
- timeout;
- retry;
- circuit breaker;
- idempotência;
- auditoria;
- verificação;
- política de dados;
- controle de egress.
Isso permitirá que o Agentic Work evolua de um agente que opera o sistema SST para uma camada capaz de operar processos empresariais completos, sem transformar o LLM em um mecanismo de acesso irrestrito à Internet ou às integrações corporativas.