Perfeito. Vamos continuar a partir do PRD-000, mantendo a estratégia de documentos encadeados. A ideia é que cada etapa seja suficientemente pequena para ser implementada, testada e validada antes da próxima.
PRD SERIES — AGENTIC WORK PLATFORM
Extensão Agentic sobre a base HAG existente
Princípio fundamental
Não reconstruir o que já existe.
A plataforma já possui:
- Docusaurus;
- documentação TypeScript/React/Hono;
- documentos Markdown;
- vault Obsidian;
- HAG baseado em Markdown;
- palavras-chave indexadas;
- Wikilinks;
- conhecimento contextual do sistema;
- aplicação React;
- APIs REST;
- infraestrutura Cloudflare;
- pipeline de build/deploy.
Os PRDs abaixo tratam exclusivamente da camada Agentic, responsável por transformar essa base de conhecimento em uma interface capaz de:
- compreender perguntas;
- compreender o contexto da aplicação;
- localizar conhecimento rapidamente;
- interpretar intenção;
- planejar ações;
- executar operações;
- navegar pela interface;
- solicitar confirmação quando necessário;
- manter rastreabilidade completa.
Mapa dos PRDs
| ID | Documento | Objetivo |
|---|---|---|
| ADR-000 | Princípios Arquiteturais | Estabelecer as regras que todos os módulos devem seguir |
| PRD-001 | Agentic Architecture | Definir a arquitetura geral |
| PRD-002 | Agent Context Engine | Capturar o contexto atual do usuário/UI |
| PRD-003 | Knowledge Router + BM25 | Busca híbrida ultrarrápida |
| PRD-004 | Capability Registry | Descrever tudo que o agente pode fazer |
| PRD-005 | Intent Engine | Transformar linguagem natural em intenção |
| PRD-006 | Agent Planner | Transformar intenção em plano executável |
| PRD-007 | Execution Engine | Executar ações através das APIs |
| PRD-008 | Navigation Engine | Controlar navegação e foco da interface |
| PRD-009 | Security & Governance | Segurança, autorização e políticas |
| PRD-010 | Agent Memory & State | Estado e memória operacional |
| PRD-011 | Observability | Auditoria, métricas e tracing |
| PRD-012 | Performance Engineering | Latência e otimização |
| PRD-013 | Agent SDK | SDK React/TypeScript para integração |
| PRD-014 | Testing & Evaluation | Testes determinísticos e avaliação do agente |
| PRD-015 | Production Rollout | Implantação progressiva |
A dependência é deliberada:
ADR-000
│
▼
PRD-001
│
├──► PRD-002 ──► PRD-003
│ │
│ ▼
└──────────────► PRD-004
│
▼
PRD-005
│
▼
PRD-006
/ \
▼ ▼
PRD-007 PRD-008
\ /
▼ ▼
PRD-009
│
▼
PRD-010
│
▼
PRD-011
│
▼
PRD-012
│
▼
PRD-013
│
▼
PRD-014
│
▼
PRD-015
ADR-000
Princípios Arquiteturais da Plataforma Agentic
1. Objetivo
Definir as decisões arquiteturais que não poderão ser violadas pelos PRDs subsequentes.
O objetivo é impedir que a implementação evolua para um chatbot tradicional com acesso indiscriminado às APIs.
O sistema será um:
Contextual Agentic Operating Layer
sobre o sistema existente.
2. O que o agente NÃO será
O agente não deverá:
- receber acesso direto ao banco;
- receber credenciais administrativas;
- escolher arbitrariamente endpoints REST;
- executar SQL;
- executar código arbitrário;
- interpretar documentação a cada solicitação;
- enviar milhares de documentos ao LLM;
- depender exclusivamente de embeddings;
- controlar diretamente o DOM;
- executar ações sem autorização;
- substituir as regras de negócio existentes.
3. O que o agente SERÁ
O agente terá quatro capacidades fundamentais:
Understand
Pergunta
↓
Contexto
↓
Conhecimento
↓
Intenção
Decide
Intent
↓
Capabilities
↓
Permissions
↓
Plan
Act
Plan
↓
Validation
↓
Execution
↓
API
Navigate
Intent
↓
UI Target
↓
Route
↓
Tab
↓
Component
↓
Focus
4. Princípio: Knowledge First
O LLM não deve tentar descobrir sozinho como o sistema funciona.
A primeira camada de conhecimento será a existente:
Docusaurus
│
▼
Markdown
│
▼
Obsidian / HAG
│
├── Keywords
├── Wikilinks
├── Metadata
└── Documents
A camada Agentic apenas adicionará mecanismos de consulta e interpretação.
5. Princípio: Retrieval antes de Reasoning
Uma pergunta como:
"O que significa esse campo?"
não deve imediatamente disparar um LLM.
Primeiro:
User Query
↓
UI Context
↓
Keyword lookup
↓
BM25
↓
Wikilinks
↓
Semantic Search
↓
Context Assembly
↓
LLM
Isso reduz:
- custo;
- tokens;
- latência;
- alucinações.
6. Princípio: Deterministic First
Sempre que uma operação puder ser resolvida deterministicamente, ela deverá ser resolvida sem LLM.
Exemplo:
"Abra a aba Componentes."
Não há necessidade de raciocínio generativo.
navigate({
route: "/seguranca/permissoes",
tab: "components"
});
O LLM somente entra quando houver ambiguidade.
7. Princípio: LLM não executa ações
O LLM produz uma intenção estruturada.
Exemplo:
{
"intent": "CREATE_RECORD",
"capability": "workPermit.create",
"entities": {
"employee": "João Silva",
"validityDays": 30
}
}
O sistema então valida:
LLM
↓
Intent
↓
Capability Registry
↓
Authorization
↓
Validation
↓
Execution Engine
↓
REST API
8. Princípio: Capability-Based Architecture
O agente nunca deverá conhecer diretamente:
POST /api/v1/work-permits
Ele conhecerá:
workPermit.create
O Capability Registry fará a tradução.
workPermit.create
↓
POST /api/v1/work-permits
Isso permite alterar a API sem precisar alterar o comportamento do agente.
9. Princípio: Human-in-the-Loop
As ações deverão possuir níveis de risco.
READ
Sem confirmação.
"Explique esta tela."
LOW RISK
Pode executar diretamente.
"Abra a aba documentos."
MEDIUM RISK
Pode exigir confirmação dependendo do contexto.
"Atualize a validade para 30 dias."
HIGH RISK
Sempre confirmar.
"Exclua este registro."
CRITICAL
Política específica + confirmação explícita.
"Finalize esta permissão de trabalho."
10. Princípio: Contexto da UI é informação de primeira classe
O contexto enviado pelo React será parte da consulta.
Exemplo:
interface AgentContext {
application: string;
route: string;
pageId: string;
activeTab?: string;
focusedElement?: {
id: string;
type: string;
label?: string;
};
selectedRecord?: {
type: string;
id: string;
};
visibleComponents?: string[];
user: {
id: string;
roles: string[];
};
}
Assim:
"Explique isso."
não é uma pergunta incompleta.
O agente recebe:
Pergunta:
"Explique isso."
Página:
Permissão de Trabalho
Tab:
Componentes
Focus:
Tabela de componentes
Registro:
PT-2026-004821
e pode interpretar:
"Explique os componentes desta Permissão de Trabalho."
11. Princípio: Context Injection
O contexto não deve ser enviado integralmente para o LLM.
Ele será usado primeiro para restringir a busca.
Context
│
├── pageId
├── tabId
├── componentId
└── recordType
│
▼
Knowledge Router
│
▼
Reduced Knowledge Set
│
▼
LLM
Essa decisão é fundamental para performance.
12. Princípio: Versionamento
Todo conhecimento será versionado.
Knowledge Version
2026.09.01.153
A versão deverá estar associada a:
- commit;
- documentação;
- índices;
- embeddings;
- capabilities;
- ontologia;
- metadata.
Isso permite reproduzir:
"Por que o agente respondeu isso em 1º de setembro?"
13. Princípio: Atomic Knowledge Deployment
Nunca atualizar parcialmente produção.
Errado:
R2 atualizado
D1 parcialmente atualizado
Vectorize parcialmente atualizado
KV antigo
Correto:
Knowledge Package #153
│
├── R2
├── D1
├── Vectorize
├── KV
└── BM25
│
▼
activate(version=153)
O runtime utiliza somente uma versão ativa.
14. Princípio: Fast Path
A arquitetura deverá possuir um caminho extremamente rápido.
Exemplo
Usuário:
"O que é APR?"
Pipeline:
UI Context
↓
Keyword lookup
↓
BM25
↓
Exact document
↓
Cached response
O LLM pode nem ser necessário.
Objetivo:
<100 ms para retrieval interno quando possível.
15. Hybrid Retrieval
A busca será composta por múltiplos mecanismos:
┌── Exact Match
│
Query ───────────┼── Keyword
│
├── BM25
│
├── Wikilinks
│
├── Metadata
│
└── Vectorize
│
▼
Re-ranking
│
▼
Context Builder
O Vectorize não substituirá BM25.
Ele será uma camada complementar.
16. Ranking conceitual
O ranking poderá combinar:
score =
0.35 * bm25
+ 0.20 * keyword
+ 0.15 * context
+ 0.15 * wikilink
+ 0.15 * semantic
Os pesos não são definitivos.
Eles serão calibrados no PRD-012 e no PRD-014 através de dados reais.
17. Princípio: Contextual Boost
Se o usuário está em:
Page = WorkPermit
Tab = Components
um documento sobre:
WorkPermit.Components
deve receber um enorme boost em relação a um documento genérico contendo as mesmas palavras.
Isso é particularmente importante para o comando:
"Explique isso."
18. Princípio: Agent State
O agente deverá possuir estado operacional:
Conversation
│
▼
Agent State
│
├── Current context
├── Current intent
├── Current plan
├── Pending confirmation
├── Execution result
└── Navigation state
19. Princípio: Auditability
Toda ação deverá produzir um registro:
{
"requestId": "...",
"userId": "...",
"timestamp": "...",
"intent": "workPermit.update",
"capability": "workPermit.update",
"parameters": {},
"authorization": {},
"confirmation": true,
"result": "success"
}
Isso é particularmente importante em um sistema de Segurança e Saúde do Trabalho.
20. Princípio: API remains authoritative
O agente não implementará regras de negócio paralelas.
Se a API determina:
validity <= 30 days
o agente não poderá criar uma regra diferente.
O agente solicita:
workPermit.create(...)
e a API permanece responsável pela validação definitiva.
21. Princípio: Progressive Autonomy
O sistema deverá evoluir gradualmente:
Fase 1
Ask
↓
Search
↓
Answer
Fase 2
Ask
↓
Understand
↓
Navigate
Fase 3
Ask
↓
Understand
↓
Plan
↓
Confirm
↓
Execute
Fase 4
Ask
↓
Understand
↓
Plan
↓
Policy
↓
Execute
↓
Verify
22. Critério fundamental de sucesso
O usuário não deverá precisar saber:
- onde está a documentação;
- qual endpoint usar;
- qual API existe;
- qual página contém a informação;
- qual aba contém o campo;
- qual objeto representa o registro;
- qual procedimento deve ser seguido.
Ele deverá poder dizer:
"Crie uma nova APR para este funcionário, usando os dados deste registro, com validade de 30 dias."
ou:
"Abra os componentes e me explique este equipamento."
ou:
"Altere a validade para 30 dias."
E o sistema deverá compreender:
WHAT
↓
WHERE
↓
CONTEXT
↓
INTENT
↓
PLAN
↓
AUTHORIZATION
↓
ACTION
↓
VERIFICATION
Próximo documento: PRD-001
O PRD-001 — Agentic Architecture será o documento que transforma estes princípios em arquitetura concreta.
Ele definirá:
- componentes;
- responsabilidades;
- interfaces;
- protocolos;
- fluxo de uma requisição;
- fluxo de uma ação;
- fluxo de navegação;
- fluxo de confirmação;
- integração React;
- integração Hono;
- Cloudflare Workers;
- D1;
- KV;
- R2;
- Vectorize;
- cache;
- filas;
- versionamento;
- contratos TypeScript;
- sequência de implementação.
E, a partir dele, cada PRD seguinte poderá ser entregue isoladamente à equipe, sem obrigá-la a implementar toda a plataforma de uma vez.
Esse é, na minha opinião, o formato mais seguro para evitar exatamente o problema que você apontou: um projeto gigantesco que fica lento porque tenta construir tudo simultaneamente.
Evidência de implementação e produção — 2026-09-05
Os princípios-base já possuem contratos executáveis no Worker: contexto e estado tenant-safe, recuperação/knowledge com versão, intenção e planejamento determinísticos, policy/capability antes de qualquer execução, aprovação humana, audit ledger encadeado e seleção de release server-side. A rota de prévia permanece não executável; ela ignora o releaseId informado pelo cliente e falha fechada quando o control plane não possui uma release promovida.
Em 2026-09-05, a base foi recertificada por gates de contexto, retrieval, capability registry, intent, planner, policy, audit e estado, além de canários autenticados de índice, despacho, auditoria, risco e operações. As provas de produção confirmaram releases pinadas, execução não-autorizadora até os gates finais, isolamento tenant, ledger imutável, recuperação controlada e limpeza de dados sintéticos. O Worker e o portal de documentação seguem publicados no Cloudflare.
Isto não prova que cada domínio de negócio ou cada jornada de UI dos PRDs seguintes esteja completo. A plataforma mantém escopo incremental: automação efetiva exige capability ativa, policy, contexto atual e confirmação/revalidação apropriada; evidências e limites específicos permanecem documentados em cada PRD.
Backlog remanescente de implementação — 2026-09-05
Os critérios ainda abertos não são conclusão implícita. A próxima passagem deve priorizar: auditoria transversal e migração dos demais limites de bypass de Registry/Policy — com egress externo, intervenções e o dispatcher de plano já certificados (PRD-001); medição E2E de contexto (PRD-002); HAG/LLM auditável e trust/drift/histórico (PRDs 004, 005, 028 e 029); dashboards, rollout e operações de longa duração (PRDs 015–019); Runbook Registry e auditoria externa independente (PRDs 024–025); credenciais delegadas/OAuth/JIT (PRD-027); avaliação/replay/budget de agentes (PRD-030); prompt injection de planejamento (PRD-032); goals concorrentes/cancelamento/expiração/simulação (PRD-036); e integrações de risco ainda não exercitadas (PRD-047).
Cada item só poderá ser fechado com teste focado e typecheck, prova de runtime no Cloudflare quando houver Worker/rota, canário tenant-isolado com limpeza sintética e atualização da rota pública do PRD correspondente.