Skip to main content

PRD-011 — Agentic UI Intelligence & Semantic Interaction Layer

1. Objetivo​

O Agentic UI Intelligence & Semantic Interaction Layer define a camada que permite ao agente compreender e operar a interface React de forma semântica, sem depender de coordenadas de tela, seletores CSS frágeis ou interpretação visual do DOM.

O objetivo é que a interface deixe de ser apenas uma apresentação visual e passe a expor uma representação operacional estruturada para o agente.

React UI
   │
   ├── Page
   ├── Tab
   ├── Section
   ├── Form
   ├── Field
   ├── Table
   ├── Row
   ├── Action
   └── Entity
          │
          ▼
Semantic UI Layer
          │
          ▼
Agent Tool Runtime
          │
          ├── Intent Engine
          ├── Planner
          ├── Policy
          └── Conversation Runtime

2. Problema

Um agente que apenas conhece as APIs consegue executar operações de negócio, mas não necessariamente consegue controlar a experiência do usuário.

Por exemplo:

“Abra a permissão 123.”

A API pode localizar a permissão, mas o usuário espera que a aplicação:

  1. navegue para a tela;
  2. abra a permissão;
  3. selecione o registro;
  4. mostre a aba correta.

Outro exemplo:

“Agora vá para os componentes.”

O agente precisa saber que existe:

workPermit.components

e que isso corresponde à aba visual:

"Componentes"

Outro:

“Explique isso.”

O agente precisa saber qual elemento está semanticamente em foco.

3. Princípio fundamental

A aplicação não deve ensinar o agente através do DOM.

O agente deve receber uma representação semântica:

DOM
  ↓
React Components
  ↓
Semantic Metadata
  ↓
Semantic UI Registry
  ↓
Agent Context

Isso torna a integração:

  • estável;
  • rápida;
  • tipada;
  • independente do layout;
  • independente de CSS;
  • independente da resolução da tela;
  • compatível com mudanças visuais.

4. Escopo

O PRD cobre:

  • Semantic UI IDs;
  • registro de componentes;
  • páginas;
  • abas;
  • seções;
  • campos;
  • tabelas;
  • entidades;
  • ações;
  • navegação;
  • foco semântico;
  • seleção;
  • formulários;
  • estado visual;
  • comandos de UI;
  • eventos;
  • descoberta contextual;
  • integração com React;
  • integração com Tool Runtime;
  • sincronização UI ↔ Agent;
  • proteção contra contexto obsoleto.

Não cobre:

  • design visual;
  • criação de componentes React;
  • implementação do Agent Planner;
  • implementação do Policy Engine;
  • APIs de negócio.

5. Arquitetura

                    ┌───────────────────┐
                    │   React App      │
                    └─────────┬─────────┘
                              │
                    ┌─────────▼─────────┐
                    │ Semantic UI Layer │
                    └─────────┬─────────┘
                              │
             ┌────────────────┼────────────────┐
             │                │                │
             ▼                ▼                ▼
        UI Registry     Context Provider   Event Bus
             │                │                │
             └────────────────┼────────────────┘
                              │
                              ▼
                     Agent Tool Runtime
                              │
             ┌────────────────┼────────────────┐
             ▼                ▼                ▼
         Context          UI Commands       Events

6. Semantic UI ID

Todo elemento relevante para o agente deverá possuir um identificador semântico estável.

Exemplos:

workPermit
workPermit.header
workPermit.details
workPermit.validity
workPermit.components
workPermit.components.table
workPermit.components.add
workPermit.components.item
workPermit.risks
workPermit.approvals

Esses IDs não devem depender de:

  • classes CSS;
  • posição;
  • texto traduzido;
  • índice do elemento;
  • ID HTML gerado automaticamente.

7. Tipos de Semantic UI Node

O sistema deverá suportar pelo menos:

PAGE
SECTION
TAB
PANEL
FORM
FIELD
TABLE
TABLE_ROW
LIST
LIST_ITEM
BUTTON
LINK
ACTION
DIALOG
MODAL
MENU
ENTITY
ENTITY_REFERENCE

8. Semantic UI Node

interface SemanticUINode {
  semanticId: string;

  type: SemanticUIType;

  label?: string;

  description?: string;

  parentId?: string;

  entityType?: string;

  entityId?: string;

  capabilities?: string[];

  actions?: string[];

  state?: Record<string, unknown>;

  visible: boolean;

  enabled?: boolean;

  interactive?: boolean;

  sensitive?: boolean;
}

9. Semantic Tree

A interface deverá poder ser representada como uma árvore semântica.

Exemplo:

workPermit
│
├── workPermit.header
│
├── workPermit.details
│   ├── workPermit.number
│   ├── workPermit.status
│   └── workPermit.validity
│
├── workPermit.components
│   ├── workPermit.components.table
│   ├── workPermit.components.add
│   └── workPermit.components.item
│
├── workPermit.risks
│
└── workPermit.approvals

O agente não precisa conhecer todos os nós simultaneamente.

O Runtime poderá obter apenas o subconjunto relevante.

10. Semantic Context

A camada deverá alimentar o SemanticUIContext definido no PRD-007.

Exemplo:

interface SemanticUIContext {
  applicationId: string;

  route: string;

  page: SemanticReference;

  activeTab?: SemanticReference;

  focus?: SemanticReference;

  selection?: EntityReference;

  visibleEntities: EntityReference[];

  filters?: FilterState;

  form?: FormContext;

  breadcrumbs?: SemanticReference[];

  contextVersion: number;

  timestamp: string;
}

11. Context Provider

A aplicação deverá possuir um provider central.

Exemplo conceitual:

<AgentSemanticProvider>
  <Application />
</AgentSemanticProvider>

Esse provider será responsável por:

  • registrar nós;
  • atualizar foco;
  • registrar seleção;
  • registrar páginas;
  • registrar tabs;
  • registrar formulários;
  • emitir eventos;
  • produzir snapshots;
  • sincronizar com o Agent Runtime.

12. Registro de componente

Um componente poderá declarar:

<AgentSemantic
  id="workPermit.validity"
  type="FIELD"
  entityType="workPermit"
>
  ...
</AgentSemantic>

Ou, preferencialmente, através de componentes semânticos específicos:

<AgentField
  semanticId="workPermit.validity"
  capability="workPermit.updateValidity"
>
  ...
</AgentField>

A implementação final deverá evitar exigir alterações excessivas nos componentes existentes.

13. Semantic Hooks

A aplicação deverá disponibilizar hooks:

useSemanticContext()

useSemanticFocus()

useSemanticSelection()

useSemanticRegister()

useSemanticAction()

useAgentNavigation()

useAgentCommand()

Exemplo:

const { setFocus } = useSemanticFocus();

setFocus("workPermit.validity");

14. Semantic Focus

O foco semântico é diferente do foco do navegador.

Browser focus:

<input>

Semantic focus:

workPermit.validity

Isso permite:

“Explique isso.”

mesmo quando o agente não precisa saber qual elemento HTML possui foco.

15. Semantic Selection

Exemplo:

selection:
  entityType = workPermit
  entityId = WP-123

Ou:

selection:
  entityType = component
  entityId = COMP-81

A seleção deve ser atualizada quando o usuário:

  • clica em uma linha;
  • abre um registro;
  • escolhe uma entidade;
  • muda a seleção em uma tabela;
  • navega para outra entidade.

16. Tabelas

Tabelas são especialmente importantes em sistemas SST.

A tabela deverá expor:

semanticId
columns
rows
selectedRows
filters
sorting
pagination
availableActions

Exemplo:

workPermit.components.table

poderá informar:

{
  "entityType": "component",
  "rows": [
    {
      "id": "COMP-81",
      "semanticId": "workPermit.components.item"
    }
  ]
}

17. Não enviar todas as linhas ao agente

Uma tabela com 10.000 registros não deve ser enviada integralmente ao Runtime.

O contexto deverá informar:

totalRows = 10000
visibleRows = 25
selectedRows = 1
filters = ...

Quando necessário, o agente poderá usar uma capability de busca.

Isso preserva performance e privacidade.

18. Forms

Formulários deverão possuir contexto semântico.

interface FormContext {
  formId: string;

  entityType?: string;

  entityId?: string;

  dirty: boolean;

  valid: boolean;

  fields: FormFieldContext[];

  submitCapabilityId?: string;

  cancelCapabilityId?: string;
}

19. Form Fields

Cada campo poderá expor:

semanticId
label
value
type
required
valid
dirty
editable
visible
sensitive
capability

Exemplo:

workPermit.validity

poderá indicar:

value = 30
type = number
required = true
editable = true

20. Dados sensíveis

Campos sensíveis não deverão ser enviados integralmente.

Exemplo:

CPF
document number
salary
medical information
private contact information

poderão aparecer apenas como:

sensitive = true

ou mascarados.

A regra de exposição deverá ser controlada pelo Policy Engine.

21. UI Command Registry

O agente não deverá executar comandos arbitrários no navegador.

Deverá existir um registry.

Exemplo:

NAVIGATE
OPEN_TAB
SELECT_ENTITY
FOCUS
OPEN_DIALOG
CLOSE_DIALOG
REFRESH
EXPAND
COLLAPSE
HIGHLIGHT
SCROLL_TO

22. Navigation Capability

Exemplo:

interface NavigateCommand {
  type: "NAVIGATE";

  target: {
    semanticId: string;
    entity?: EntityReference;
  };
}

O agente solicita:

NAVIGATE → workPermit.components

e a aplicação decide como chegar lá.

23. Nunca navegar por URL arbitrária

Não permitir:

navigate("https://...")

nem:

navigate("/admin/users/delete")

A navegação deverá ocorrer através de destinos registrados:

workPermit
workPermit.components
workPermit.risks
employee
employee.documents

Isso evita:

  • SSRF conceitual;
  • acesso indevido;
  • rotas internas não autorizadas;
  • URLs inventadas pelo LLM.

24. UI Actions

Ações visuais deverão possuir identidade semântica.

Exemplo:

workPermit.components.add
workPermit.components.remove
workPermit.save
workPermit.cancel
workPermit.submit

O agente não diz:

clique no botão azul.

Ele diz:

execute UI action:
workPermit.components.add

25. UI Action vs Business Capability

São conceitos diferentes.

UI Action​

Manipula a interface.

OPEN_TAB
OPEN_DIALOG
FOCUS
SELECT

Business Capability​

Manipula dados ou negócio.

workPermit.components.add
workPermit.updateValidity

Uma UI Action pode eventualmente iniciar uma Business Capability.

OPEN_DIALOG
      ↓
USER INPUT
      ↓
workPermit.components.add

26. Estado visual

O Semantic UI Layer deve informar estados relevantes:

visible
enabled
disabled
loading
expanded
selected
dirty
invalid
readonly
locked

Exemplo:

workPermit.components.add
enabled = false
reason = WORK_PERMIT_APPROVED

O agente poderá então responder:

Não posso adicionar componentes porque essa permissão está aprovada.

27. UI State ≠ Business State

O agente não deve confiar exclusivamente no estado visual.

Exemplo:

button.disabled = false

não significa que a operação está autorizada.

A autorização real continua sendo responsabilidade do backend/Policy Engine.

28. Event Bus

A camada semântica deverá emitir eventos.

PAGE_CHANGED
TAB_CHANGED
FOCUS_CHANGED
SELECTION_CHANGED
FORM_CHANGED
FORM_SUBMITTED
ENTITY_OPENED
ENTITY_CLOSED
UI_ACTION_STARTED
UI_ACTION_COMPLETED
UI_ERROR

Esses eventos alimentam o Conversation Runtime.

29. Context Delta

Não transmitir o contexto inteiro a cada alteração.

Exemplo:

Antes:
tab = details

Depois:
tab = components

Enviar somente:

{
  "type": "TAB_CHANGED",
  "previous": "workPermit.details",
  "current": "workPermit.components"
}

Isso reduz tráfego e processamento.

30. Context Snapshot

Periodicamente ou em eventos importantes:

Semantic Context Snapshot

deverá ser produzido.

Isso permite recuperar o estado caso eventos sejam perdidos.

31. Context Version

Cada alteração significativa incrementa:

contextVersion

Exemplo:

101 → page change
102 → tab change
103 → selection change
104 → form change

Operações críticas podem registrar:

expectedContextVersion = 103

e detectar mudanças posteriores.

32. Agent → UI

O fluxo inverso também é necessário.

Agent
  ↓
Tool Runtime
  ↓
UI Command
  ↓
Semantic UI Layer
  ↓
React

Exemplo:

{
  "command": "OPEN_TAB",
  "target": "workPermit.components"
}

33. UI Command Result

A UI deverá responder:

{
  "success": true,
  "commandId": "cmd_123",
  "newContextVersion": 105
}

ou:

{
  "success": false,
  "error": "TARGET_NOT_AVAILABLE"
}

O agente não deve assumir que um comando visual foi executado apenas porque o comando foi enviado.

34. Command Lifecycle

REQUESTED
   ↓
VALIDATING
   ↓
EXECUTING
   ↓
COMPLETED

ou:

REQUESTED
   ↓
FAILED

35. Contextual Tool Discovery

O Tool Runtime não deverá expor todas as ferramentas da aplicação simultaneamente.

Se o usuário está em:

workPermit.components

as capabilities mais relevantes podem ser:

workPermit.components.add
workPermit.components.remove
workPermit.components.update
workPermit.components.list

Isso reduz o espaço de decisão do agente.

36. Dynamic Capability Surface

O Runtime poderá calcular:

Available Tools =
Global Tools
+
Current Page Tools
+
Current Entity Tools
+
Current Selection Tools
+
Current Form Tools

Exemplo:

Current page:
workPermit.components

Current selection:
COMP-81

Resultado:

workPermit.components.update
workPermit.components.remove
workPermit.components.explain

37. Integração com Knowledge Graph

O Semantic UI Layer também será uma ponte para o HAG.

Exemplo:

UI:
workPermit.validity
       │
       ├── Documentation
       ├── Capability
       ├── Policy
       ├── Business Rule
       └── API

Assim, quando o usuário disser:

Explique isso.

o sistema poderá resolver:

UI Focus
   ↓
Semantic ID
   ↓
Knowledge Graph
   ↓
Documentation

sem precisar fazer uma busca semântica ampla.

38. Tradução e internacionalização

Semantic IDs não devem mudar conforme idioma.

Errado:

permissao.componentes
permiso.componentes
work-permit.components

Correto:

workPermit.components

O label pode ser traduzido.

semanticId = workPermit.components
label.pt-BR = Componentes
label.en-US = Components

39. Acessibilidade

A camada semântica deve complementar, e não substituir, acessibilidade.

Quando possível, deve haver integração com:

  • ARIA;
  • labels;
  • roles;
  • keyboard navigation;
  • focus management.

Mas o agente deve consumir a camada semântica própria, não depender de acessibilidade como única fonte de contexto.

40. Compatibilidade com React

A implementação deverá ser não invasiva.

Idealmente:

<AgentSemantic
  id="workPermit.components"
>
  <ExistingComponents />
</AgentSemantic>

ou wrappers/hook:

const semantic = useAgentSemantic({
  id: "workPermit.components"
});

O objetivo é evitar reescrever a aplicação existente.

41. Registro automático

Sempre que possível, informações deverão ser derivadas automaticamente de:

  • React component metadata;
  • TypeScript;
  • TypeDoc;
  • Semantic IDs;
  • Capability Registry;
  • UI Registry;
  • Knowledge Graph.

Isso reduz duplicação manual.

42. Build-time Manifest

O pipeline poderá gerar:

agent-ui-manifest.json

Exemplo:

{
  "version": "1.4.0",
  "pages": 82,
  "semanticNodes": 4217,
  "actions": 638,
  "forms": 143,
  "tables": 97
}

Esse manifesto poderá ser usado pelo Agent Runtime para discovery rápido.

43. Runtime Registry

O frontend não precisa enviar toda a árvore semântica a cada sessão.

O Runtime pode possuir:

Static UI Manifest
        +
Live UI Context

Assim:

Manifest
→ o que existe

Live Context
→ o que está acontecendo agora

Essa separação é fundamental para performance.

44. Performance

Objetivos:

Context update​

P50 < 5 ms no frontend.

Semantic lookup​

P50 < 5 ms.

Command dispatch​

P50 < 20 ms, excluindo navegação/renderização.

Context transmission​

Enviar somente deltas quando possível.

Agent discovery​

Não enviar centenas de capabilities ao LLM.

45. Segurança

O Semantic UI Layer não é uma camada de autorização.

Ele informa:

o que está disponível visualmente.

O backend decide:

o que o usuário pode realmente fazer.

Portanto:

UI says ENABLED
       ≠
Authorization ALLOWED

A autorização sempre deverá ser recalculada no servidor.

46. Proteção contra manipulação do contexto

O cliente pode enviar:

entityId = WP-999

O servidor deve validar:

user
tenant
resource
permission

antes de executar qualquer capability.

Contexto visual é input não confiável.

47. Auditabilidade

Comandos de UI importantes devem gerar eventos:

agent.ui.navigate
agent.ui.select
agent.ui.openDialog
agent.ui.focus

Operações de negócio continuam sendo auditadas pelo mecanismo de execução/política.

48. Exemplo completo

Usuário:

Abra a permissão 123.

Agent:

NAVIGATE
target = workPermit
entity = WP-123

UI:

PAGE_CHANGED
entity = WP-123
contextVersion = 201

Usuário:

Vá para os componentes.

Agent:

OPEN_TAB
target = workPermit.components

UI:

TAB_CHANGED
current = workPermit.components
contextVersion = 202

Usuário:

Selecione o componente de trabalho em altura.

Agent:

SELECT_ENTITY
entityType = component
entityId = COMP-81

UI:

SELECTION_CHANGED
entity = COMP-81
contextVersion = 203

Usuário:

Explique isso.

Runtime:

focus/selection
      ↓
COMP-81
      ↓
Knowledge Router
      ↓
documentation

O LLM recebe somente o contexto necessário para produzir a explicação.

49. Exemplo de formulário

Usuário:

Edite a validade para 60 dias.

Contexto:

page = workPermit
entity = WP-123
focus = workPermit.validity
form.dirty = false

Intent Engine produz:

UPDATE
target = WP-123
field = validity
value = 60

Planner seleciona:

workPermit.updateValidity

Policy valida.

Execution ocorre.

UI recebe:

REFRESH_DATA
target = workPermit.validity

50. Critérios de aceitação

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

O semantic registry e o frontend expõem IDs estáveis, independentes de CSS/posição, para página, tab, foco, seleção e comandos. O semantic-context-store gera mudanças versionadas e snapshots minimizados; o dispatcher aceita somente comandos registrados e o backend continua a validar escopo, sem tratar contexto como autorização. Testes de contexto, registry, dispatcher e navegação aprovaram 17 casos em 2026-09-04, cobrindo bloqueio de destino arbitrário, estado stale e resolução determinística.

Esta evidência não demonstra instrumentação de todos os formulários, tabelas e dialogs do produto, nem um canário de acessibilidade/navegador abrangente. O critério de adoção transversal de todos os elementos importantes permanece aberto.

Semantic Layer​

  • elementos importantes possuem Semantic IDs;
  • IDs são estáveis;
  • IDs não dependem de CSS ou posição;
  • páginas, tabs, forms, fields, tables e actions podem ser representados.

Context​

  • contexto semântico é atualizado em tempo real;
  • foco semântico é suportado;
  • seleção semântica é suportada;
  • contexto possui versionamento;
  • alterações podem ser transmitidas como deltas.

UI Commands​

  • navegação usa destinos registrados;
  • tabs podem ser abertas pelo agente;
  • entidades podem ser selecionadas;
  • foco pode ser alterado;
  • dialogs podem ser abertos;
  • UI pode informar sucesso ou falha.

Forms​

  • estado dirty é identificado;
  • campos obrigatórios podem ser identificados;
  • campos sensíveis podem ser protegidos;
  • capabilities associadas ao formulário podem ser descobertas.

Segurança​

  • UI context nunca é tratado como autorização;
  • tenant/user são validados no backend;
  • navegação arbitrária é bloqueada;
  • dados sensíveis são minimizados.

Performance​

  • contexto não envia DOM;
  • contexto não envia árvore completa desnecessariamente;
  • capabilities são filtradas;
  • lookup semântico é determinístico;
  • operações simples não dependem de LLM.

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

O workspace Work Permit usa Semantic IDs estáveis para página, detalhes, campos, ações e componentes; o board associa a entidade operacional real em data-agent-entity-id. O store publica contexto versionado de página/aba/foco/seleção sem DOM scraping, e o registry mantém comandos/capabilities declarados e filtrados. Contexto de UI é minimizado e não se torna autorização.

Em 2026-09-04, a tela Work Permit passou a receber elioria:ui-command e encaminha apenas workPermit.open pelo dispatcher local registrado. O dispatcher exige página e capability declaradas, valida parâmetros, rejeita URL/comando desconhecido/contexto incompatível e só seleciona a entidade já carregada; ele não chama endpoint nem concede execução.

Em 2026-09-04, Auditorias passou a declarar seleção inicial como entidade audit, em vez de herdar o padrão workPermit; assim o primeiro snapshot já preserva tipo e ID autoritativos do dossiê. O consumo SSE finito também encerra silenciosamente AbortError esperado no unmount, removendo rejeições não tratadas sem mascarar falhas de rede reais.

Em 2026-09-05, os contratos de registry semântico, discovery de capabilities, preview de intent e orchestration passaram com 19 testes em 4 arquivos, e o typecheck do Agent passou. A prova cobre IDs estáveis sem DOM/CSS, contexto versionado e em delta, foco/seleção/formulário, descoberta filtrada, navegação registrada e bloqueio de destino arbitrário; o backend preserva tenant/usuário como fonte de autorização. Pages ef7fecaf já havia publicado /auditorias e seu chunk JavaScript. Ainda falta cobertura de telas além de Work Permit e Auditorias; portanto o critério de instrumentar todos os elementos importantes permanece aberto.

Em 2026-09-06, a regressão atual de manifest, contexto semântico, dispatcher e página Work Permit passou com 12 testes, e o typecheck/build do Web passou. A rota pública /work-permits e seu asset JavaScript responderam HTTP 200 com MIME correto. A cobertura permanece PARTIAL, pois Work Permit e Auditorias ainda não representam todos os elementos e telas importantes.

51. Resultado arquitetural

Com o PRD-011, teremos uma separação muito importante:

                AGENT
                  │
        ┌─────────┴─────────┐
        │                   │
   Business World       UI World
        │                   │
Capabilities           Semantic UI
        │                   │
        └─────────┬─────────┘
                  │
           Agent Runtime

O agente passa a compreender simultaneamente:

o que o sistema pode fazer
+
onde o usuário está
+
qual entidade está selecionada
+
qual parte da interface está em foco
+
quais ações estão disponíveis
+
qual conhecimento explica aquela parte da interface

Isso fecha a integração entre agente, aplicação React, conhecimento, APIs e experiência visual.

PRD-012 — Agentic Task Memory & Operational Learning

O próximo estágio deverá tratar de uma questão diferente: como o agente aprende com a operação sem transformar cada conversa em treinamento do modelo.

O PRD-012 deverá definir uma camada de memória operacional e aprendizado baseado em evidências, capaz de registrar:

o que o usuário pediu
        ↓
o que o agente interpretou
        ↓
o que foi executado
        ↓
o que deu errado
        ↓
o que o usuário corrigiu
        ↓
qual foi o resultado final

O objetivo não será “treinar a IA automaticamente”, mas criar um mecanismo controlado para descobrir padrões como:

  • intents frequentemente ambíguas;
  • capabilities frequentemente confundidas;
  • referências que exigem esclarecimento;
  • comandos que os usuários corrigem repetidamente;
  • fluxos que deveriam virar novas capabilities;
  • documentação que não está suficientemente clara;
  • componentes da UI que precisam de melhor semanticização;
  • operações que geram frequentemente falhas;
  • pontos onde o agente está recorrendo ao LLM quando poderia existir uma resolução determinística.

Isso permitirá que o próprio sistema gere evidências para evolução da plataforma, sem permitir que o agente altere automaticamente suas próprias regras de segurança, capabilities ou políticas.