PRD-008 — Agent Policy, Safety & Governance Engine
1. Objetivo
O Agent Policy, Safety & Governance Engine será a camada de controle que determina se uma ação planejada pelo agente pode realmente ser executada.
Até o PRD-007, temos:
- contexto da interface;
- intenção;
- conhecimento;
- capabilities;
- planejamento;
- execução;
- verificação.
Agora adicionamos a barreira de segurança:
USER
│
▼
Intent Engine
│
▼
Agent Planner
│
▼
Execution Plan
│
▼
┌──────────────────────┐
│ POLICY ENGINE │
│ PRD-008 │
└──────────┬───────────┘
│
ALLOW / DENY /
CONFIRM / REVIEW
│
▼
Execution Runtime
Princípio central
O fato de uma capability existir não significa que o usuário ou o agente possa executá-la naquele contexto.
2. Objetivos
O Policy Engine deverá:
- validar autorização;
- validar tenant;
- validar usuário;
- validar recurso;
- validar contexto;
- avaliar risco;
- determinar necessidade de confirmação;
- bloquear ações proibidas;
- limitar ações em massa;
- impedir escalada de privilégios;
- aplicar segregação de funções;
- controlar ações sobre dados sensíveis;
- registrar todas as decisões;
- permitir revisão humana;
- fornecer uma decisão determinística e explicável.
3. Policy Decision
Toda execução deverá receber uma decisão:
ALLOW
DENY
REQUIRE_CONFIRMATION
REQUIRE_HUMAN_REVIEW
Exemplo:
{
"decision": "REQUIRE_CONFIRMATION",
"risk": "HIGH",
"reason": "Deleting a work permit requires explicit user confirmation."
}
4. Policy Decision Point — PDP
O núcleo do sistema será o:
Policy Decision Point
Ele recebe:
Subject
+
Action
+
Resource
+
Context
+
Risk
e produz:
Policy Decision
Formalmente:
Decision =
PDP(
user,
tenant,
capability,
resource,
context,
intent,
executionPlan
)
5. Policy Enforcement Point — PEP
O PDP decide.
O PEP executa a decisão.
Arquitetura:
Execution Runtime
│
▼
PEP
│
▼
PDP
│
▼
ALLOW / DENY / ...
│
▼
Capability
Nenhuma capability mutável deverá ser executada sem passar pelo PEP.
6. Zero Trust
O Agentic Work deve seguir um modelo:
Never trust, always verify.
Não confiar em:
- intenção do LLM;
- contexto enviado pelo frontend;
- capability escolhida pelo Planner;
- autorização armazenada anteriormente;
- confirmação antiga;
- estado da conversa.
A cada operação crítica:
authenticate
→ authorize
→ validate
→ execute
→ verify
7. Policy Context
O Policy Engine receberá um contexto estruturado.
interface PolicyContext {
user: {
id: string;
roles: string[];
};
tenant: {
id: string;
};
capability: {
id: string;
version: string;
risk: RiskLevel;
};
resource?: {
type: string;
id: string;
};
uiContext?: SemanticUIContext;
intent: Intent;
plan?: ExecutionPlan;
execution?: {
id: string;
stepId: string;
};
}
8. RBAC + ABAC
Somente RBAC será insuficiente.
Precisamos combinar:
RBAC
Admin
Supervisor
Engenheiro
Técnico
Auditor
com:
ABAC
Acesso baseado em:
- tenant;
- unidade;
- empresa;
- recurso;
- estado do recurso;
- relação do usuário com o recurso;
- horário;
- localização lógica;
- workflow;
- risco;
- quantidade;
- contexto.
9. Exemplo
Usuário possui:
role = Supervisor
Isso não significa automaticamente:
workPermit.delete = ALLOW
A policy pode exigir:
role = Supervisor
AND
permit.status != APPROVED
AND
user.unit == permit.unit
AND
confirmation = true
10. Policy as Code
As políticas deverão ser declarativas e versionadas.
Exemplo conceitual:
policy:
id: workPermit.delete
version: 1
when:
capability: workPermit.delete
allow:
all:
- user.role: Supervisor
- resource.status: DRAFT
- resource.tenantId: session.tenantId
require:
confirmation: true
A sintaxe definitiva deverá ser definida durante a implementação.
O importante é:
políticas não devem ficar espalhadas pelo código.
11. Policy Lifecycle
Cada política terá:
DRAFT
↓
REVIEW
↓
APPROVED
↓
ACTIVE
↓
DEPRECATED
↓
RETIRED
Mudanças críticas deverão ser auditadas.
12. Risk Model
As capabilities já possuem risco no PRD-004.
Agora o Policy Engine poderá calcular o Effective Risk.
Exemplo:
Capability risk
+
Resource sensitivity
+
Operation scope
+
Batch size
+
Workflow state
+
User context
Resultado:
LOW
MEDIUM
HIGH
CRITICAL
13. Risk Matrix
Exemplo inicial:
| Operação | Risco |
|---|---|
| Consultar documentação | LOW |
| Consultar registro | LOW |
| Criar registro | MEDIUM |
| Alterar registro | MEDIUM |
| Alteração em massa | HIGH |
| Cancelar | HIGH |
| Excluir | HIGH |
| Aprovar | HIGH |
| Alterar configuração crítica | CRITICAL |
Esses níveis são apenas baseline.
A policy poderá aumentar o risco conforme o contexto.
14. Batch Protection
Um agente não deve interpretar:
“Altere todas as permissões.”
como autorização ilimitada.
Deverá existir:
maxAffectedResources
Exemplo:
≤ 5 → LOW/MEDIUM
6–50 → HIGH
> 50 → HUMAN_REVIEW
Os valores reais deverão ser configuráveis por tenant e domínio.
15. Mass Action Confirmation
Para operações em massa:
UPDATE 127 permits
o agente deverá apresentar:
- quantidade;
- filtro utilizado;
- tipo de alteração;
- impacto;
- possibilidade de reversão.
Exemplo:
“Você está solicitando a alteração da validade de 127 permissões. Essa operação afetará 127 registros da unidade X. Deseja continuar?”
16. Segregation of Duties
Uma pessoa que criou uma permissão pode não poder aprová-la.
A policy deverá suportar:
creator != approver
Exemplo:
User A → CREATE
User A → APPROVE
→ DENY.
Isso é particularmente importante em workflows regulatórios.
17. Workflow State Policies
O estado do registro deverá influenciar a autorização.
Exemplo:
DRAFT
→ editável
SUBMITTED
→ edição limitada
APPROVED
→ bloqueado
CANCELLED
→ somente leitura
Assim:
workPermit.update
pode existir como capability, mas:
permit.status == APPROVED
pode resultar em:
DENY
18. Immutable / Protected Fields
Alguns campos poderão ser protegidos.
Exemplo:
approvalDate
approvedBy
auditHash
createdBy
O agente não poderá alterá-los simplesmente porque a API possui uma operação genérica de update.
A policy deverá poder declarar:
protectedFields:
- approvalDate
- approvedBy
19. Field-Level Authorization
A autorização poderá ocorrer por campo.
Exemplo:
workPermit.description → ALLOW
workPermit.responsible → ALLOW
workPermit.approvalStatus → DENY
workPermit.auditMetadata → DENY
Isso evita que:
workPermit.update
se torne uma capability excessivamente poderosa.
20. Capability Scope
Uma capability poderá declarar escopo.
Exemplo:
workPermit.update
não significa:
update(any field, any permit)
Poderá significar:
update allowed fields
on resources accessible to user
within tenant
21. Confirmation Levels
Teremos diferentes níveis.
NONE
Nenhuma confirmação.
Exemplo:
“Mostre a permissão.”
SOFT
Confirmação simples:
“Deseja alterar para 30 dias?”
STRONG
Confirmação explícita vinculada ao plano.
HUMAN_REVIEW
Outra pessoa precisa aprovar.
22. Confirmation Anti-Ambiguity
Não aceitar:
“ok”
quando existem vários planos pendentes.
O contexto deverá conter:
planId
confirmationToken
Exemplo:
CONFIRM PLAN-8F21
A UI pode esconder o token do usuário e gerenciar a associação de forma segura.
23. Expiração de Confirmação
Uma confirmação não deve permanecer válida indefinidamente.
Exemplo:
confirmation TTL = 5 minutes
Depois:
EXPIRED
e o plano deve ser revalidado.
24. Re-Authorization
Mesmo após confirmação:
confirmation
↓
authorization
↓
execution
Se a autorização mudar:
DENY
25. Sensitive Data Policy
O Policy Engine também controla exposição de dados.
Exemplo:
Employee medical information
pode exigir:
role = authorized_health_professional
O agente deverá aplicar minimização.
Em vez de retornar:
todos os dados médicos
poderá retornar somente:
informação necessária para a tarefa solicitada
26. Prompt Injection Protection
A Policy Engine deve ser completamente independente do LLM.
Mesmo que o LLM gere:
{
"capability": "workPermit.delete"
}
o Policy Engine decide independentemente se pode.
O LLM nunca pode:
overridePolicy()
ou:
disableConfirmation()
27. Policy Explanation
Quando bloquear uma operação, o sistema deve produzir uma explicação útil.
Não:
“Permission denied.”
Mas:
“Não posso excluir esta permissão porque ela já foi aprovada. Permissões aprovadas não podem ser excluídas diretamente.”
A explicação deve vir de um Policy Reason Code, não de uma invenção do LLM.
Exemplo:
WP_APPROVED_DELETE_FORBIDDEN
28. Policy Reason Codes
Exemplos:
AUTH_REQUIRED
USER_NOT_AUTHORIZED
TENANT_MISMATCH
RESOURCE_NOT_ACCESSIBLE
RESOURCE_STATE_FORBIDS_ACTION
CONFIRMATION_REQUIRED
HUMAN_REVIEW_REQUIRED
BATCH_LIMIT_EXCEEDED
FIELD_PROTECTED
SEGREGATION_OF_DUTIES
POLICY_VIOLATION
CONTEXT_STALE
Isso também facilita analytics.
29. Human-in-the-Loop
Algumas operações não deverão ser executadas autonomamente.
Exemplo:
critical safety configuration
Fluxo:
Agent
↓
Plan
↓
Policy
↓
HUMAN_REVIEW
↓
Authorized Reviewer
↓
Execution
O agente pode preparar tudo.
Mas não pode concluir sozinho.
30. Approval Workflow
Um review deverá conter:
interface ReviewRequest {
id: string;
executionPlanId: string;
requestedBy: string;
tenantId: string;
risk: RiskLevel;
reason: string;
status:
| 'pending'
| 'approved'
| 'rejected'
| 'expired';
reviewerId?: string;
}
31. Policy Caching
Policies estáticas podem ser cacheadas.
Mas decisões altamente dinâmicas não devem permanecer em cache por muito tempo.
Estratégia:
Policy Definition
↓
Cache
User Permission
↓
Short TTL
Critical Authorization
↓
Evaluate live
32. Policy Version
Toda decisão deverá registrar:
policyVersion
Exemplo:
policy:
workPermit.delete
version: 7
Assim, no futuro será possível responder:
“Por que o sistema permitiu essa operação em 2026?”
33. Audit Record
Cada decisão:
{
"decision": "DENY",
"policyId": "workPermit.delete",
"policyVersion": 7,
"reasonCode": "RESOURCE_STATE_FORBIDS_ACTION",
"userId": "...",
"tenantId": "...",
"resourceId": "WP-10231",
"timestamp": "..."
}
deverá ser auditada.
34. Policy Evaluation Pipeline
O fluxo recomendado:
Execution Request
│
▼
Authentication
│
▼
Tenant Resolution
│
▼
Capability Validation
│
▼
Resource Resolution
│
▼
RBAC
│
▼
ABAC
│
▼
Risk Evaluation
│
▼
Workflow Rules
│
▼
Batch Rules
│
▼
Confirmation
│
▼
Final Decision
35. Fail Closed
Se o Policy Engine estiver indisponível para uma operação crítica:
UNKNOWN
não significa:
ALLOW
Significa:
DENY / RETRY
Especialmente para:
- DELETE;
- APPROVE;
- CANCEL;
- alterações críticas;
- ações em massa.
36. Fail Open
Pode existir somente para operações explicitamente classificadas como seguras.
Exemplo:
documentation.read
Mesmo assim, isso deverá ser uma policy explícita.
37. Policy Testing
Policies deverão possuir testes automatizados.
Exemplo:
Given:
user = technician
permit.status = APPROVED
When:
workPermit.delete
Then:
DENY
Outro:
Given:
user = supervisor
permit.status = DRAFT
When:
workPermit.delete
Then:
REQUIRE_CONFIRMATION
38. Policy Simulation
Antes de ativar uma policy nova, deverá ser possível executar:
Policy Simulation
Exemplo:
“Como a nova política teria decidido sobre as últimas 1000 operações?”
Resultado:
ALLOW 812
DENY 103
CONFIRM 71
REVIEW 14
Isso permite validar políticas sem afetar produção.
39. Shadow Mode
Uma nova policy poderá inicialmente funcionar em:
SHADOW
Ela calcula a decisão mas não bloqueia.
Exemplo:
Current policy → ALLOW
New policy → DENY
O sistema registra a divergência.
Depois de validada:
SHADOW
↓
ACTIVE
40. Policy Conflict Resolution
Diferentes policies podem entrar em conflito.
Exemplo:
Role policy → ALLOW
Resource policy → DENY
Regra:
DENY explícito sempre vence ALLOW.
Hierarquia inicial:
Explicit DENY
>
Critical safety policy
>
Resource policy
>
Tenant policy
>
Role policy
>
Default allow
Na prática, recomenda-se evitar default allow para operações mutáveis.
41. Default Deny
Para Agentic Work:
UNKNOWN CAPABILITY
↓
DENY
UNKNOWN POLICY
↓
DENY
UNKNOWN RESOURCE
↓
DENY
UNKNOWN AUTHORIZATION
↓
DENY
O agente deve operar por allowlist, não por blacklist.
42. Policy + Planner
O Planner poderá receber feedback do Policy Engine.
Exemplo:
Planner:
DELETE permit
Policy:
DENY
Planner pode então procurar uma alternativa válida:
CANCEL permit
se essa alternativa fizer sentido e estiver autorizada.
Mas não deve simplesmente substituir uma operação crítica sem preservar a intenção do usuário.
43. Policy + Intent
Exemplo:
Usuário:
“Apague essa permissão.”
Policy bloqueia DELETE porque o registro está aprovado.
O agente não deve automaticamente decidir:
“Vou cancelar então.”
Pode, entretanto, informar:
“Esta permissão aprovada não pode ser excluída. O sistema permite cancelá-la. Deseja cancelar em vez de excluir?”
Isso preserva a intenção e pede autorização para uma mudança de ação.
44. Policy + UI Context
Contexto também pode alterar a decisão.
Exemplo:
User is editing a draft
Pode permitir:
update
Mas:
User changed tab
context became stale
Para uma ação crítica:
REQUIRE_REVALIDATION
45. Emergency Mode
O sistema pode futuramente suportar um modo especial para situações operacionais críticas.
Porém:
Emergency Mode não deve significar “bypass de segurança”.
Deve possuir:
- justificativa;
- autorização especial;
- auditoria reforçada;
- duração limitada;
- escopo limitado;
- revisão posterior.
46. Policy Observability
Dashboard deverá permitir analisar:
Policy decisions/day
ALLOW
DENY
CONFIRM
REVIEW
E também:
Top denied capabilities
Top policy violations
Top users
Top tenants
Top resources
47. Métricas de segurança
Indicadores:
- unauthorized attempts;
- denied actions;
- confirmation rate;
- review rate;
- policy conflicts;
- stale-context blocks;
- batch-limit blocks;
- segregation-of-duties blocks;
- sensitive-data blocks;
- policy evaluation latency.
48. Performance
O Policy Engine deve ser extremamente rápido.
Objetivo:
P50 < 10 ms
P95 < 30 ms
para decisões locais/cacheadas.
Não deverá chamar LLM.
Não deverá consultar o HAG para decisões básicas de autorização.
49. Primeiro Vertical Slice
Utilizar novamente o domínio:
Work Permit
Policies:
workPermit.read
workPermit.create
workPermit.update
workPermit.updateValidity
workPermit.delete
workPermit.approve
workPermit.cancel
Estados:
DRAFT
SUBMITTED
APPROVED
CANCELLED
Implementar primeiro:
Caso 1
Usuário autorizado:
UPDATE DRAFT
→ ALLOW
Caso 2
Usuário sem permissão:
UPDATE
→ DENY
Caso 3
DELETE de aprovado:
→ DENY
Caso 4
DELETE permitido:
→ REQUIRE_CONFIRMATION
Caso 5
Criador tentando aprovar:
→ DENY
Caso 6
Alteração em massa:
127 records
→ REQUIRE_HUMAN_REVIEW
50. Critérios de Aceitação
AC-01
Nenhuma capability mutável será executada sem decisão do Policy Engine.
AC-02
A decisão deverá considerar usuário e tenant.
AC-03
A decisão deverá considerar o recurso quando aplicável.
AC-04
O sistema deverá suportar RBAC e ABAC.
AC-05
Deny explícito deverá prevalecer sobre Allow.
AC-06
Ações críticas deverão exigir confirmação ou revisão.
AC-07
Operações em massa deverão possuir limites.
AC-08
O sistema deverá suportar segregação de funções.
AC-09
Policies deverão ser versionadas.
AC-10
Decisões deverão ser auditáveis.
AC-11
O sistema deverá funcionar em fail-closed para operações críticas.
AC-12
O LLM não poderá modificar ou ignorar policies.
AC-13
Policies deverão possuir testes automatizados.
AC-14
Deverá existir modo de simulação/shadow para novas policies.
AC-15
A decisão deverá ser suficientemente rápida para não comprometer o Fast Path.
Evidência de implementação e produção — 2026-09-05
O PolicyEngine avalia capability e contexto canônico de principal/tenant/company; ausência de policy para mutação falha fechada, deny explícito prevalece, recurso de outro tenant é recusado antes da policy e lote além do blast radius exige aprovação. As respostas preservam reason codes, risco e versões de policy, e capacidades mutáveis continuam sujeitas a confirmação/approval em vez de receber autoridade do LLM.
Em 2026-09-04, o PlanDispatchWorkflow passou a atuar também como PEP: antes de transicionar para RUNNING ou chamar a capability mutável, ele consulta o mesmo controle emergencial persistente da borda HTTP para os escopos global, tenant, agente, capability, recurso e execução. Um controle aplicável falha fechado com AGENT_EXECUTION_DISABLED; o teste prova que não há chamada interna nem checkpoint RUNNING. A decisão reutiliza o tenant e o identificador de execução verificados pelo workflow e não expõe justificativa do controle à capability.
O PolicyEngine agora também oferece avaliação shadow pura: compara um conjunto candidato com a decisão efetiva, preserva ambas as versões/reason codes, registra divergência e fixa authorizesExecution=false; o conjunto shadow nunca substitui enforcement. Em 2026-09-05, o núcleo de policy/emergência passou com 20 testes em 4 arquivos, o PEP de plan dispatch e registry passou com 22 testes em 3 arquivos, e o typecheck do Agent passou. O canário autenticado de produção criou e despachou um plano de Work Permit com capability registrada, concluiu snapshot COMPLETED na versão 5, preservou authorizesExecution=false na resposta e removeu os dados sintéticos (remainingRows: 0). A integração ampla entre domínios, a persistência governada de observações shadow e a medição formal de latência do Fast Path seguem como expansão operacional, sem reduzir o enforcement certificado.
Em 2026-09-06, a regressão foi repetida contra a suíte atual: 87 testes de engine/governance, controle emergencial, recibos, workflow, adaptadores, rota e cleanup passaram, assim como o typecheck do Agent. O health público do Worker ativo confirmou o runtime com Durable Objects, D1, KV, R2, Vectorize e Queue disponíveis. Esta evidência confirma o recorte implementado, mas não transforma em completa a cobertura entre domínios, a persistência governada das observações shadow ou a medição formal do Fast Path.
51. Arquitetura consolidada
Neste ponto, o Agentic Work começa a adquirir uma arquitetura muito sólida:
USER
│
▼
┌─────────────┐
│ React UI │
└──────┬──────┘
│
Semantic Context
│
▼
┌──────────────────┐
│ Context Bridge │
│ PRD-007 │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Intent Engine │
│ PRD-005 │
└────────┬─────────┘
│
┌─────────────┴─────────────┐
│ │
▼ ▼
Knowledge Router Capability
HAG/BM25/etc. Registry
│ │
└─────────────┬─────────────┘
▼
┌──────────────────┐
│ Agent Planner │
│ PRD-006 │
└────────┬─────────┘
│
▼
Execution Plan
│
▼
┌──────────────────┐
│ POLICY ENGINE │
│ PRD-008 │
└────────┬─────────┘
│
ALLOW / DENY /
CONFIRM / HUMAN REVIEW
│
▼
┌──────────────────┐
│ Execution Runtime│
└────────┬─────────┘
│
▼
Hono APIs
│
▼
Application DB
│
▼
Verification
│
▼
React UI
52. O que já temos
Com os PRDs 003–008, já definimos os principais componentes do núcleo cognitivo e operacional:
| Camada | Responsabilidade |
|---|---|
| HAG | conhecimento especializado |
| Knowledge Router | recuperação ultrarrápida |
| BM25 | busca lexical/ranking |
| Wikilinks | relacionamento entre conhecimento |
| Vectorize | busca semântica |
| Capability Registry | catálogo de ações permitidas |
| Intent Engine | entender intenção |
| Agent Planner | montar plano |
| Context Bridge | entender estado da UI |
| Tool Runtime | disponibilizar ferramentas |
| Policy Engine | decidir se pode executar |
| Execution Orchestrator | executar |
| Verification | verificar resultado |
| Audit | registrar tudo |
O próximo passo é particularmente importante porque começa a resolver como o agente aprende a operar sobre diferentes partes do gigantesco sistema sem precisarmos programar manualmente cada diálogo.
PRD-009 — Agent Knowledge-to-Capability Binding
O próximo PRD deverá criar a ligação formal entre conhecimento, entidades, telas, documentação e capabilities.
Por exemplo, o sistema deverá conseguir estabelecer automaticamente relações como:
workPermit
│
├── documentation
│ ├── validity
│ ├── components
│ └── approval
│
├── UI
│ ├── page
│ ├── tabs
│ └── fields
│
├── capabilities
│ ├── read
│ ├── create
│ ├── update
│ ├── approve
│ └── cancel
│
└── business rules
Essa camada será crucial para escalar o agente para centenas ou milhares de entidades, funções, telas e operações sem criar manualmente um prompt ou fluxo específico para cada uma.
Ela também permitirá q