Skip to main content

PRD-001 — Agentic Architecture

Arquitetura da Camada Agentic sobre a HAG existente​

Versão: 1.0 Status: Proposta para desenvolvimento Dependências: ADR-000 Próximo documento: PRD-002 — Agent Context Engine

1. Objetivo​

Implementar a camada Agentic sobre a infraestrutura de conhecimento já existente, sem reconstruir a HAG, o Docusaurus, o Obsidian ou a documentação existente.

A camada deverá transformar a aplicação em um sistema capaz de:

entender → pesquisar → decidir → navegar → executar → verificar

utilizando linguagem natural.

O agente deverá funcionar tanto como:

  1. Assistente de conhecimento, respondendo perguntas;
  2. Assistente contextual, entendendo onde o usuário está;
  3. Assistente de navegação, levando o usuário ao local correto;
  4. Agente operacional, executando ações autorizadas;
  5. Orquestrador, combinando múltiplas operações em uma única solicitação.

2. Escopo

Este PRD define somente a arquitetura de integração.

Não implementa ainda:

  • BM25;
  • Context Engine;
  • Capability Registry;
  • Intent Engine;
  • Planner;
  • Execution Engine;
  • Navigation Engine.

Esses componentes serão especificados nos PRDs seguintes.

Aqui definiremos como eles se encaixarão.

3. Arquitetura conceitual

A arquitetura proposta:

                         ┌──────────────────────┐
                         │      Usuário         │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │   Agent UI / Chat    │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │   Context Engine     │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │   Agent Gateway      │
                         └──────────┬───────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    │               │               │
                    ▼               ▼               ▼
             Knowledge Router   Intent Engine   Capability
                    │               │             Registry
                    │               ▼
                    │            Planner
                    │               │
                    └───────┬───────┘
                            ▼
                     Policy Engine
                            │
                 ┌──────────┴──────────┐
                 │                     │
                 ▼                     ▼
         Navigation Engine      Execution Engine
                 │                     │
                 ▼                     ▼
              React UI             Hono API
                                       │
                                       ▼
                                  Sistema

4. Agent Gateway

O Agent Gateway será o ponto único de entrada.

Exemplo:

POST /api/agent

Request:

interface AgentRequest {
  message: string;

  conversationId?: string;

  context: AgentContext;
}

Response:

interface AgentResponse {
  type:
    | "answer"
    | "navigation"
    | "confirmation"
    | "execution"
    | "error";

  message: string;

  citations?: KnowledgeReference[];

  actions?: AgentAction[];

  navigation?: NavigationInstruction;

  confirmation?: ConfirmationRequest;
}

5. Por que um Gateway?

O frontend nunca deverá conversar diretamente com:

  • Vectorize;
  • D1;
  • KV;
  • R2;
  • LLM;
  • Execution Engine.

Tudo deverá passar pelo Gateway.

Isso fornece:

  • autenticação;
  • autorização;
  • rate limiting;
  • observabilidade;
  • controle de contexto;
  • versionamento;
  • segurança;
  • políticas centralizadas.

6. Context Engine

O frontend React fornecerá um contexto estruturado.

Exemplo:

interface AgentContext {
  applicationId: string;

  route: string;

  page: {
    id: string;
    title?: string;
  };

  tab?: {
    id: string;
    title?: string;
  };

  focus?: {
    componentId?: string;
    elementId?: string;
    fieldName?: string;
    label?: string;
  };

  selection?: {
    entityType?: string;
    entityId?: string;
  };

  visibleArea?: {
    componentIds: string[];
  };
}

O Context Engine será detalhado no PRD-002.

7. Knowledge Router

O Knowledge Router será responsável por decidir:

Onde procurar a resposta?

Ele combinará:

Exact Match
    +
Keywords
    +
BM25
    +
Wikilinks
    +
Metadata
    +
Contextual Ranking
    +
Vector Search

A consulta não será enviada indiscriminadamente para todo o conhecimento.

8. Knowledge Sources

A camada Agentic deverá enxergar a HAG existente como uma fonte versionada.

                  Knowledge Package
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
        Markdown       Metadata       Graph
          │              │              │
          ▼              ▼              ▼
        R2/D1          D1/KV        D1/KV
          │
          ├───────────────► BM25
          │
          └───────────────► Vectorize

A arquitetura não deverá exigir que o Markdown seja abandonado.

9. Knowledge Reference

Todo resultado de conhecimento deverá possuir identidade própria.

interface KnowledgeReference {
  id: string;

  type:
    | "document"
    | "section"
    | "component"
    | "function"
    | "entity"
    | "keyword";

  title: string;

  source: string;

  version: string;

  score?: number;
}

Isso permitirá ao agente dizer:

"Segundo a documentação de Permissão de Trabalho..."

e fornecer a referência correspondente.

10. Intent Engine

Depois do contexto e da recuperação inicial, o sistema determinará a intenção.

Exemplo:

"Explique este campo"

↓

{
  "type": "EXPLAIN",
  "target": {
    "source": "ui-context"
  }
}

Outro exemplo:

"Altere a validade para 30 dias"

↓

{
  "type": "UPDATE",
  "entity": "workPermit",
  "field": "validity",
  "value": 30
}

O Intent Engine será especificado no PRD-005.

11. Capability Registry

A intenção não chama uma API diretamente.

Exemplo:

Intent
   │
   ▼
workPermit.update
   │
   ▼
Capability Registry
   │
   ▼
API contract

Capability:

interface Capability {
  id: string;

  description: string;

  inputSchema: JSONSchema;

  outputSchema: JSONSchema;

  riskLevel:
    | "read"
    | "low"
    | "medium"
    | "high"
    | "critical";

  requiredPermissions: string[];

  endpoint: string;

  httpMethod: string;
}

12. Planner

Para operações simples:

Intent → Capability → Execute

Para operações complexas:

Intent
  ↓
Planner
  ↓
Step 1
  ↓
Step 2
  ↓
Step 3
  ↓
Validation
  ↓
Execution

Exemplo:

"Crie uma nova permissão copiando os dados desta e altere a validade para 30 dias."

Plano:

1. READ current work permit
2. CREATE new work permit
3. UPDATE validity
4. VERIFY created record
5. NAVIGATE to new record

13. Policy Engine

Antes de executar:

Plan
 ↓
Policy Engine

O Policy Engine verifica:

  • usuário;
  • tenant;
  • roles;
  • permissões;
  • registro;
  • operação;
  • risco;
  • estado atual;
  • necessidade de confirmação.

Somente após aprovação:

Policy = ALLOW

o Execution Engine poderá continuar.

14. Execution Engine

O Execution Engine será o único componente autorizado a executar operações de negócio.

Agent
 ↓
Execution Engine
 ↓
Capability
 ↓
Authorization
 ↓
API

O agente nunca receberá:

database credentials

nem:

direct database access

15. Navigation Engine

A navegação será tratada como uma capacidade formal.

Exemplo:

{
  "action": "NAVIGATE",
  "route": "/work-permits/123",
  "tab": "components",
  "focus": "components-table"
}

O React recebe essa instrução e executa:

agent.navigate({
  route: "/work-permits/123",
  tab: "components",
  focus: "components-table"
});

16. Fluxo de pergunta

Usuário:

"O que significa isso?"

Pipeline:

                    User
                     │
                     ▼
                  React
                     │
              UI Context
                     │
                     ▼
              Agent Gateway
                     │
                     ▼
             Knowledge Router
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
      BM25       Wikilinks     Vectorize
        │            │            │
        └────────────┼────────────┘
                     ▼
                Re-ranking
                     │
                     ▼
               Context Builder
                     │
                     ▼
                    LLM
                     │
                     ▼
                  Answer

17. Fluxo de execução

Usuário:

"Altere a validade para 30 dias."

User
 │
 ▼
Context Engine
 │
 ▼
Agent Gateway
 │
 ▼
Intent Engine
 │
 ▼
Intent
 │
 ▼
Capability Registry
 │
 ▼
Policy Engine
 │
 ├── DENY
 │
 ├── CONFIRM
 │
 └── ALLOW
       │
       ▼
Execution Engine
       │
       ▼
Hono API
       │
       ▼
Database
       │
       ▼
Verification
       │
       ▼
Agent Response

18. Fluxo de confirmação

Exemplo:

"Exclua este registro."

O agente deverá responder:

Esta operação excluirá permanentemente o registro PT-12345. Deseja continuar?

Somente:

CONFIRM

permitirá continuar.

A confirmação deverá estar vinculada ao:

requestId
+
planHash
+
user
+
resource

Isso impede que uma confirmação antiga seja reutilizada.

19. Cloudflare

A infraestrutura poderá ser distribuída da seguinte forma:

Cloudflare
│
├── Workers
│    ├── Agent Gateway
│    ├── Knowledge Router
│    ├── Intent/Orchestration
│    └── Execution Gateway
│
├── D1
│    ├── Knowledge metadata
│    ├── capabilities
│    ├── relationships
│    ├── agent state
│    └── audit
│
├── R2
│    ├── Markdown
│    ├── Knowledge packages
│    └── generated artifacts
│
├── Vectorize
│    └── semantic embeddings
│
├── KV
│    ├── active version
│    ├── hot cache
│    └── configuration
│
└── Queues
     └── asynchronous operations

A utilização exata de cada serviço será detalhada nos PRDs específicos.

20. Fast Path / Slow Path

Esse conceito será central.

Fast Path​

Pergunta simples:

Query
 ↓
Context
 ↓
Exact/Keyword
 ↓
BM25
 ↓
Cached Knowledge
 ↓
Response

Objetivo:

dezenas de milissegundos, quando possível.

Slow Path​

Pergunta complexa:

Query
 ↓
Context
 ↓
Hybrid Retrieval
 ↓
Intent
 ↓
Planning
 ↓
LLM Reasoning
 ↓
Policy
 ↓
Execution
 ↓
Verification

O usuário perceberá o sistema como rápido porque perguntas simples não precisarão atravessar todo o pipeline.

21. Streaming

Respostas longas deverão utilizar streaming.

Agent Gateway
      │
      ▼
   SSE/Stream
      │
      ▼
React Chat

O usuário poderá começar a ler enquanto a resposta ainda está sendo produzida.

Para operações:

"Estou consultando..."
"Registro encontrado."
"Validando..."
"Operação concluída."

Isso melhora significativamente a percepção de velocidade.

22. Estado do agente

O estado deverá ser separado da conversa.

interface AgentState {
  conversationId: string;

  contextVersion: string;

  currentIntent?: Intent;

  currentPlan?: Plan;

  pendingConfirmation?: Confirmation;

  execution?: ExecutionState;
}

Não armazenar indiscriminadamente toda a conversa em cada request.

23. Idempotência

Toda operação de escrita deverá possuir:

idempotencyKey

Exemplo:

agent:{conversationId}:{requestId}

Isso evita duplicação caso:

  • o usuário recarregue;
  • a rede falhe;
  • o cliente repita a requisição;
  • o Worker seja reexecutado.

24. Observabilidade

Toda requisição deverá receber:

traceId
requestId
conversationId
tenantId
userId
knowledgeVersion
agentVersion

O tracing deverá permitir reconstruir:

Pergunta
 ↓
Contexto
 ↓
Documentos recuperados
 ↓
Intent
 ↓
Plan
 ↓
Policy
 ↓
API
 ↓
Resultado

25. Segurança

A segurança será defense in depth.

Authentication
      ↓
Tenant isolation
      ↓
Authorization
      ↓
Capability authorization
      ↓
Input validation
      ↓
Policy
      ↓
Execution
      ↓
Audit

O LLM nunca será uma autoridade de segurança.

26. Multi-tenant

Se o sistema possuir múltiplos clientes/organizações, o contexto deverá carregar:

tenantId: string;

A recuperação deverá ser tenant-aware.

Nunca permitir:

Tenant A
   ↓
Knowledge
   ↓
Tenant B

nem através de:

  • D1;
  • Vectorize;
  • KV;
  • cache;
  • memória;
  • embeddings.

O tenantId deverá participar da chave de todos os objetos sensíveis.

27. Versionamento do Agent

Além da versão do conhecimento:

knowledgeVersion

teremos:

agentVersion

Exemplo:

Agent: 1.4.2
Knowledge: 2026.09.01.153

Isso permite reproduzir exatamente o comportamento.

28. Contrato entre módulos

Todos os módulos deverão possuir contratos TypeScript compartilhados.

Recomendação:

packages/
└── agent-contracts/
     ├── context.ts
     ├── intent.ts
     ├── capability.ts
     ├── plan.ts
     ├── execution.ts
     ├── navigation.ts
     ├── knowledge.ts
     └── response.ts

Isso será especialmente importante porque frontend e backend compartilharão os mesmos conceitos.

29. Critérios de aceite do PRD-001

Evidência de implementação e produção — 2026-09-05​

Os contratos compartilhados de identidade e contexto, o Context Engine, o Capability Registry, o Intent Engine, o Policy Engine e o preview determinístico de Work Permit estão implementados. O fluxo exercitado liga contexto confiável a intent, autorização, policy, plano, confirmação e navegação sem conceder autoridade ao LLM; capabilities carregam semântica de idempotência e o runtime de plano mantém confirmações e transições explícitas. Os testes focados de contratos, contexto, registry, intent, policy, preview e runtime aprovaram 43 casos em 7 arquivos em 2026-09-04.

Em 2026-09-05, a cadeia foi recertificada pelos gates de Context Engine, Knowledge Router, Capability Registry, Intent, Planner, Context Bridge e Policy, além de canários autenticados de índice e despacho em produção. Os contratos comprovam contexto confiável, versões de knowledge/agent, descoberta e execução exclusiva por capabilities registradas no vertical certificado, confirmação/idempotência/requestId e ausência de autoridade do LLM. Uma auditoria transversal ainda é necessária para provar, literalmente, que nenhum agente ou toda operação futura do produto não possa contornar os gates.

Na mesma data, o Gateway de Integrações Externas recebeu um limite adicional de execução: cada autorização gera, no servidor, um receipt ALLOW de Policy com vida de cinco minutos, gravado imutavelmente na migração remota 0141_external_execution_policy_receipts.sql junto da operação. Referências de Policy fornecidas pelo cliente são ignoradas. Antes de obter credencial ou alcançar o provider, o executor revalida exatamente tenant, operação, ator, integração e versão, binding, capability e versão, hash canônico do input, aprovação e expiração; receipt ausente, expirado ou divergente falha fechada. A gravação de receipt e operação é condicional e atômica, evitando receipt órfão em admissão recusada.

O Worker e95ef1e1-3ca4-4053-8632-2ac8e04f97ef foi publicado a 100% no Cloudflare após a migração. O canário tenant-isolado de LMS confirmou receipt emitido pelo servidor nas autorizações síncrona e enfileirada, execução e despacho assíncronos, verificação de provider, enforcement de delegação e zero linhas residuais no PostgreSQL; receipts D1 imutáveis são retidos como trilha de auditoria. Os canários transversais de intent audit e control plane/release continuaram aprovados. Isto certifica o ponto de egress desse Gateway, não os demais despachantes: plano, intervenções, workflows e novas operações ainda exigem auditoria e migração explícitas.

Também em 2026-09-05, a migração remota 0142_intervention_execution_policy_receipts.sql passou a proteger a execução de intervenções. A autorização exige papel servidor e revisão humana, gera UUID de decisão no servidor e ignora referências de Policy fornecidas pelo cliente. A admissão resolve permissões no Capability Registry e RBAC servidor e vincula receipt imutável a intervenção, ator, approval_ref, binding, capability e hash do input. O Workflow valida o receipt e a identidade/input persistidos antes de RUNNING, antes de acessar Secrets Store e novamente antes de cada egress; expiração entre a leitura de credencial e a chamada ao provider também falha fechada. O Worker 024fdbfc-eee6-4581-acb4-986eeedc387e foi publicado a 100%; o canário sintético confirmou ambas as decisões server-side, rejeição de referências forjadas, provider limitado alcançado e zero linhas residuais no PostgreSQL. Uma tentativa remota controlada de atualizar o receipt foi abortada pelo trigger INTERVENTION_EXECUTION_POLICY_RECEIPT_IMMUTABLE; os receipts D1 da execução são deliberadamente retidos como trilha imutável e não contam como limpeza pendente.

Ainda em 2026-09-05, as confirmações sintéticas de action order de renovação e manutenção receberam o mesmo fence antes do segundo egress ao provider. Ambas carregam o receipt 0142 pelo tenant, intervenção, execução e decisão, e revalidam ator original, empresa persistida na execução, receiver com role server-side daquela empresa, Registry/binding/capability, input canônico, aprovação e expiração antes de Secrets Store e novamente antes do LMS_SANDBOX.fetch. Empresa forjada, receipt ausente, expirado ou divergente falham fechadas. O Worker 538970bc-294c-4bfc-99d6-f110a7f305c3 foi publicado a 100%; o canário confirmou negação de empresa forjada, confirmação limitada válida e limpeza PostgreSQL zero. Uma tentativa remota controlada de alteração do receipt sintético foi novamente abortada pelo trigger INTERVENTION_EXECUTION_POLICY_RECEIPT_IMMUTABLE; o receipt D1 retido é trilha de auditoria imutável.

Também em 2026-09-05, a migração remota 0143_plan_dispatch_policy_receipts.sql passou a proteger o dispatcher de planos confirmados. A confirmação gera UUID de decisão no servidor, ignora referência de Policy enviada pelo cliente e grava receipt ALLOW imutável, tenant-scoped, vinculado ao owner, plano, empresa persistida, binding do Registry, capability, hash do input e hash da aprovação. A revisão independente encontrou e a versão final corrigiu o risco de usar permissões de outra empresa: cabeçalho de empresa divergente agora falha, e a ausência de cabeçalho calcula roles exclusivamente da empresa gravada no snapshot. O Workflow relê e revalida receipt, snapshot, owner, empresa, adapter, capability, input, confirmação e expiração antes de RUNNING e imediatamente antes do único AGENT_API.fetch; divergência, ausência ou expiração falham fechadas. O Worker a1141136-dfdc-4d25-85e5-69067e13d297 foi publicado a 100% após os gates; o canário sintético confirmou recibo server-side, rejeição da referência forjada, vínculo persistido e caminho interno limitado, com limpeza do PostgreSQL e D1 mutável. A tentativa remota controlada de alterar o receipt sintético foi abortada pelo trigger PLAN_DISPATCH_POLICY_RECEIPT_IMMUTABLE; o único receipt D1 retido é a trilha de auditoria imutável.

Isto certifica o fluxo de execução de intervenções, o Gateway de Integrações Externas e o dispatcher de planos confirmados. Os demais workflows e novas rotas de operação continuam pendentes; os três critérios transversais abaixo permanecem deliberadamente abertos até a auditoria completa.

Também em 2026-09-05, as migrações remotas 0144_attention_notification_policy_receipts.sql e 0145_attention_notification_created_by.sql certificaram o egress de e-mail do Attention Center. A capability attention.notification.deliverEmail@1 é um contrato interno não descobrível por UI/modelo: continua governada pelo Registry e exige aprovação técnica e de negócio independentes para ativação, mas não aceita uma permissão ou confirmação fornecida pelo solicitante. O publisher grava, na mesma transação D1, um receipt ALLOW imutável e tenant-scoped com ator criador, delivery, integração/binding/capability pinados, destinatário, template, canal e hash canônico do payload. O gateway reconstrói a autoridade somente desse estado persistido e revalida os pins, o ator, a expiração e o Registry ativo imediatamente antes do envio.

O Worker 84f4eaca-a959-4915-b669-24c9674bb816 foi publicado a 100% após 53 arquivos e 446 testes. O canário sintético publicado confirmou: duas aprovações independentes; um receipt de policy e um receipt de entrega persistidos; rejeição pelo trigger de atualização do receipt; capability desativada bloqueando a criação antes de persistir notification, delivery ou receipt (0/0/0); 23 ocorrências agregadas, escore 80, ciclo OPEN → ACKNOWLEDGED → IN_PROGRESS → ESCALATED → RESOLVED → CLOSED, isolamento de tenant e endpoint sem autenticação bloqueado. providerReceiptRecorded=true registra somente o receipt de provider aceito pela rota; providerCallObserved=false, portanto esta certificação não afirma observação externa de envio pelo provedor. A limpeza PostgreSQL terminou com zero linhas; receipts D1 imutáveis permanecem deliberadamente como trilha de auditoria. O canário anterior no Worker sem a capability falhou como FEATURE_ABSENT, conforme esperado.

Esta certificação cobre exclusivamente o egress de e-mail do Attention Center. Ela não fecha os critérios globais deste PRD nem substitui a auditoria dos demais despachantes, workflows e novas rotas de operação.

A arquitetura será considerada aprovada quando:

  • nenhum agente possuir acesso direto ao banco;
  • todas as ações passarem pelo Capability Registry;
  • todas as operações passarem por Policy;
  • o contexto da UI puder ser transmitido ao Agent Gateway;
  • o Knowledge Router puder receber contexto;
  • o sistema suportar Fast Path e Slow Path;
  • ações puderem exigir confirmação;
  • operações possuírem idempotência;
  • toda execução possuir requestId;
  • conhecimento possuir versão;
  • agente possuir versão;
  • tenant isolation estiver definida;
  • frontend e backend compartilharem contratos TypeScript;
  • navegação for tratada como capacidade;
  • execução e navegação forem separadas;
  • LLM não possuir autoridade de segurança.

30. Ordem de implementação

Não implementar tudo simultaneamente.

A sequência recomendada é:

PRD-001
Architecture
   │
   ▼
PRD-002
Context Engine
   │
   ▼
PRD-003
Knowledge Router + BM25
   │
   ▼
PRD-004
Capability Registry
   │
   ▼
PRD-005
Intent Engine
   │
   ▼
PRD-006
Planner
   │
   ├──────────────┐
   ▼              ▼
PRD-007        PRD-008
Execution      Navigation
   │              │
   └──────┬───────┘
          ▼
      PRD-009
 Security
          │
          ▼
      PRD-010
 Agent State
          │
          ▼
      PRD-011
Observability
          │
          ▼
      PRD-012
Performance
          │
          ▼
      PRD-013
Agent SDK
          │
          ▼
      PRD-014
Testing
          │
          ▼
      PRD-015
Production

31. Resultado esperado

Ao final dessa arquitetura, a aplicação deixará de possuir simplesmente um:

Chatbot com RAG

e passará a possuir uma camada:

Agentic Application Intelligence Layer

capaz de compreender:

quem
+
onde
+
o quê
+
sobre qual registro
+
sobre qual componente
+
qual intenção
+
qual ação
+
se possui autorização
+
qual resultado esperado

e então:

RESPONDER
NAVEGAR
OU
EXECUTAR

de forma controlada.

Próximo documento — PRD-002​

O próximo será PRD-002 — Agent Context Engine.

Esse é particularmente importante para o que você descreveu, porque vamos especificar exatamente como o React informará ao agente a página atual, rota, aba ativa, componente em foco, campo sob o cursor, registro selecionado, elementos visíveis e estado relevante da UI, sem mandar o DOM inteiro nem gerar uma carga enorme de dados.

Também vamos definir o mecanismo para o agente interpretar comandos extremamente curtos como:

"Explique."

"Faça isso."

"Altere para 30."

"Abra o outro."

usando o contexto da interface como parte da semântica da linguagem, que é uma das partes mais interessantes dessa arquitetura.