Skip to main content

PRD-002 — Agent Context Engine

Contexto semântico da aplicação React para o Agente​

Versão: 1.0 Status: Proposta para desenvolvimento Dependências: ADR-000, PRD-001 Próximo documento: PRD-003 — Knowledge Router + BM25

1. Objetivo

Criar o Agent Context Engine, responsável por informar ao agente o que o usuário está vendo, onde está, o que está selecionado e onde está sua atenção.

O objetivo não é capturar a tela inteira nem enviar o DOM ao LLM.

O objetivo é construir um modelo semântico, pequeno e determinístico da interface.

Assim, a frase:

"Explique."

poderá ser interpretada de maneira diferente dependendo do contexto.

Por exemplo:

Página: Permissão de Trabalho
Tab: Componentes
Componente em foco: Tabela de Componentes
Registro: PT-2026-004821
Campo: Tipo de Equipamento

A pergunta:

"Explique."

será semanticamente equivalente a:

"Explique o campo Tipo de Equipamento do registro PT-2026-004821, dentro da aba Componentes da Permissão de Trabalho."

2. Problema atual

Um chatbot convencional recebe:

message = "Explique isso"

e tenta inferir o significado.

Isso gera ambiguidade.

O Agent Context Engine acrescentará:

message
+
application context
+
UI context
+
semantic focus
+
selection context

produzindo uma solicitação semanticamente enriquecida.

3. Princípio fundamental

O contexto da aplicação é parte da linguagem do usuário.

Em uma aplicação complexa, palavras como:

  • isso;
  • este;
  • aquele;
  • aqui;
  • acima;
  • abaixo;
  • o outro;
  • esse campo;
  • este registro;

são referências contextuais.

O agente deverá resolver essas referências antes de tentar responder.

4. O que será capturado

O contexto deverá ser dividido em níveis.

Application
    │
    ▼
Route
    │
    ▼
Page
    │
    ▼
Section
    │
    ▼
Tab
    │
    ▼
Component
    │
    ▼
Element
    │
    ▼
Field
    │
    ▼
Selection

Nem todos os níveis precisam existir em todas as telas.

5. AgentContext

Contrato inicial:

export interface AgentContext {
  application: ApplicationContext;

  navigation: NavigationContext;

  page: PageContext;

  focus?: FocusContext;

  selection?: SelectionContext;

  viewport?: ViewportContext;

  user: UserContext;

  timestamp: string;

  contextVersion: number;
}

6. ApplicationContext

export interface ApplicationContext {
  applicationId: string;
  applicationVersion: string;
  environment: "production" | "staging" | "development";
}

Exemplo:

{
  "applicationId": "sst",
  "applicationVersion": "8.14.2",
  "environment": "production"
}

7. NavigationContext

export interface NavigationContext {
  route: string;

  routeName?: string;

  params?: Record<string, string>;

  breadcrumbs?: Breadcrumb[];

  history?: NavigationEntry[];
}

Exemplo:

{
  "route": "/work-permits/4821",
  "routeName": "workPermit.details",
  "params": {
    "id": "4821"
  }
}

8. PageContext

export interface PageContext {
  id: string;

  type: string;

  title: string;

  semanticId?: string;

  metadata?: Record<string, unknown>;
}

O semanticId será especialmente importante para ligação com a HAG.

Exemplo:

work-permit.components

pode corresponder diretamente a documentos Markdown:

work-permit-components.md

9. Tabs

Aplicações complexas frequentemente utilizam múltiplas abas.

O contexto deverá registrar:

export interface TabContext {
  id: string;
  title: string;
  index: number;
  active: boolean;
}

A página poderá conter:

tabs: TabContext[];
activeTabId: string;

Exemplo:

{
  "activeTabId": "components",
  "tabs": [
    {
      "id": "general",
      "title": "Geral",
      "index": 0,
      "active": false
    },
    {
      "id": "components",
      "title": "Componentes",
      "index": 1,
      "active": true
    },
    {
      "id": "documents",
      "title": "Documentos",
      "index": 2,
      "active": false
    }
  ]
}

10. Focus Context

O foco será uma das informações mais importantes.

export interface FocusContext {
  semanticId: string;

  type:
    | "page"
    | "section"
    | "tab"
    | "component"
    | "field"
    | "button"
    | "table"
    | "row"
    | "cell"
    | "menu";

  label?: string;

  parentIds?: string[];

  value?: unknown;
}

11. Exemplo de foco

Usuário está com o cursor em:

Validade

Context:

{
  "semanticId": "workPermit.validity",
  "type": "field",
  "label": "Validade",
  "parentIds": [
    "workPermit",
    "workPermit.components"
  ]
}

Então:

"Explique."

pode ser resolvido sem procurar o sistema inteiro.

12. Não utilizar o DOM como contexto

Uma decisão arquitetural importante:

não enviar HTML/DOM para o agente.

Errado:

DOM completo
 ↓
LLM

Problemas:

  • enorme;
  • lento;
  • caro;
  • contém informação irrelevante;
  • pode conter dados sensíveis;
  • instável entre versões.

Correto:

React Component
 ↓
Semantic Context
 ↓
Compact JSON

13. Semantic UI IDs

Os componentes relevantes deverão possuir identificadores semânticos.

Exemplo:

<ValidityField
  data-agent-id="workPermit.validity"
/>

Ou, preferencialmente, através de um componente próprio:

<AgentContext
  id="workPermit.validity"
  type="field"
>
  <ValidityField />
</AgentContext>

14. React Agent Context

Será criado um provider:

<AgentProvider>
  <Application />
</AgentProvider>

Internamente:

AgentProvider
     │
     ├── route
     ├── page
     ├── tab
     ├── focus
     ├── selection
     └── user

15. Hooks

API proposta:

const agent = useAgentContext();

Exemplo:

agent.setPage({
  id: "workPermit.details",
  title: "Permissão de Trabalho"
});

Tab:

agent.setActiveTab("components");

Focus:

agent.setFocus({
  semanticId: "workPermit.validity",
  type: "field"
});

Selection:

agent.setSelection({
  entityType: "workPermit",
  entityId: "4821"
});

16. Não enviar cada mudança ao backend

O contexto local deverá existir no React.

UI
 ↓
Local Agent Context

Somente quando o usuário interagir com o agente:

User Message
+
Current Context
       ↓
Agent Gateway

Isso evita tráfego desnecessário.

17. Context Snapshot

Cada solicitação criará um snapshot:

interface AgentContextSnapshot {
  id: string;

  context: AgentContext;

  createdAt: string;
}

O snapshot permite reproduzir exatamente o contexto que existia quando a pergunta foi feita.

18. Context Delta

Para otimizar conversas, o frontend poderá enviar somente mudanças.

Exemplo:

Context #100
Tab = general

↓

Context #101
Tab = components

Em vez de reenviar tudo.

O backend mantém:

Base Context
+
Delta
=
Current Context

19. Context Resolution

Antes do LLM, haverá uma etapa determinística:

"Explique isso"
       │
       ▼
Reference Resolver
       │
       ├── "isso" → Focus
       │
       ├── "este" → Selection
       │
       └── "aqui" → Page

Isso será muito importante para reduzir o trabalho do modelo.

20. Pronoun / Reference Resolution

Exemplo:

Usuário:

"Explique isso."

Focus:

workPermit.validity

Resultado:

target = workPermit.validity

Outro:

"Altere isso para 30."

Se o foco for:

workPermit.validity

resultado:

{
  "intent": "UPDATE",
  "target": "workPermit.validity",
  "value": 30
}

21. Contextual Hierarchy

O agente deverá conhecer a hierarquia.

WorkPermit
└── Components
    └── Equipment
        └── Validity

Se o foco for Validity, o sistema saberá automaticamente:

parent = Equipment
parent = Components
parent = WorkPermit

Isso permitirá contextualização sem enviar documentos inteiros.

22. Contexto + HAG

Aqui está a integração fundamental:

React Semantic ID
       │
       ▼
workPermit.components
       │
       ▼
Knowledge Router
       │
       ├── exact match
       ├── keyword
       ├── BM25
       ├── Wikilinks
       └── Vectorize

O semanticId poderá funcionar como uma espécie de ponte determinística entre UI e conhecimento.

23. Contextual Knowledge Boost

Se:

focus = workPermit.components

o Knowledge Router deverá priorizar documentos relacionados a:

workPermit.components

e seus vizinhos no grafo.

Conceitualmente:

Focus
 ↓
Exact semantic match
 ↓
Wikilinks neighbors
 ↓
BM25
 ↓
Vector search

24. Selected Record

Um dos elementos mais importantes será o registro selecionado.

Exemplo:

interface SelectionContext {
  entityType: string;

  entityId: string;

  displayName?: string;

  fields?: Record<string, unknown>;
}

Entretanto, não devemos enviar todos os campos automaticamente.

O backend deverá buscar somente os dados necessários.

25. Data minimization

Se o usuário perguntar:

"Qual é a validade?"

não será necessário enviar:

nome
CPF
endereço
telefone
salário
documentos
histórico
...

O sistema deverá buscar somente:

workPermit.validity

Isso reduz:

  • tokens;
  • latência;
  • exposição de dados;
  • risco de vazamento.

26. Hidden UI Areas

O problema das áreas escondidas será tratado explicitamente.

O contexto deverá distinguir:

visibility:
  | "visible"
  | "hidden"
  | "collapsed"
  | "inactive"
  | "disabled";

Assim:

Tab = Documents
visible = false

não será considerada automaticamente como foco.

27. Viewport Context

Opcionalmente:

interface ViewportContext {
  scrollContainer?: string;

  visibleSemanticIds?: string[];

  topVisibleElement?: string;

  bottomVisibleElement?: string;
}

Isso permite compreender:

"O que é esse item aqui embaixo?"

sem capturar uma imagem da tela.

28. Mouse Cursor

O cursor físico não deve ser rastreado continuamente.

Isso seria:

  • caro;
  • desnecessário;
  • potencialmente invasivo.

Em vez disso, o sistema deverá registrar elemento semanticamente focado/interagido.

Exemplo:

mouseenter
click
focus
selection
keyboard navigation

podem atualizar o foco sem transmitir coordenadas continuamente.

29. Teclado

O sistema deverá suportar navegação por teclado.

Exemplo:

Tab → campo A
Tab → campo B
Tab → campo C

O foco semântico muda:

field:A
 ↓
field:B
 ↓
field:C

O agente sempre recebe o foco atual.

30. Context Confidence

Nem sempre o foco será inequívoco.

Portanto:

interface ContextReference {
  semanticId: string;

  confidence:
    | "exact"
    | "high"
    | "medium"
    | "low";
}

Se houver ambiguidade:

"Você quer que eu explique o campo Validade ou o campo Data de Início?"

em vez de adivinhar.

31. Context Expiration

O contexto pode ficar obsoleto.

Exemplo:

Usuário pergunta
 ↓
registro 4821
 ↓
usuário muda para registro 4922

A conversa antiga não deve automaticamente operar sobre o novo registro.

Cada mensagem deverá possuir:

contextSnapshotId

32. Context Security

O frontend não é autoridade de segurança.

Um usuário malicioso poderia alterar:

{
  "entityId": "another-user-record"
}

Portanto:

Client Context
      ↓
Backend
      ↓
Authorization
      ↓
Validated Context

O backend deverá validar se o usuário realmente pode acessar aquele recurso.

33. Context Schema Registry

Os tipos semânticos deverão ser registrados.

Exemplo:

workPermit
workPermit.components
workPermit.validity
workPermit.documents
workPermit.approval

Isso cria uma ligação direta com a HAG.

Idealmente:

UI semantic ID
        ↕
Knowledge semantic ID
        ↕
Capability semantic ID

Essa convergência será uma das maiores vantagens da arquitetura.

34. Context Graph

No futuro, poderemos representar:

Page
 │
 ├── Tab
 │    │
 │    ├── Component
 │    │     │
 │    │     └── Field
 │    │
 │    └── Table
 │
 └── Actions

Isso forma um UI Knowledge Graph.

Ele não substitui a HAG.

Ele complementa a HAG.

35. Performance

O contexto deverá ser extremamente pequeno.

Meta inicial:

Typical context:
< 5 KB

Ideal:

1–3 KB

Não deverá conter:

  • DOM;
  • HTML;
  • imagens;
  • documentos;
  • listas gigantes;
  • dados completos do registro.

36. Cache

Contextos estáticos poderão ser cacheados.

Exemplo:

page schema
component metadata
semantic mappings

KV poderá ser usado posteriormente para dados quentes.

O contexto dinâmico:

current focus
current selection
active tab

permanece no cliente até a requisição.

37. Fluxo completo

                     React
                       │
             ┌─────────┴─────────┐
             │                   │
          UI Events          Navigation
             │                   │
             └─────────┬─────────┘
                       ▼
               Agent Context
                       │
                       ▼
               Context Snapshot
                       │
                       ▼
                Agent Gateway
                       │
                       ▼
             Context Validation
                       │
                       ▼
              Reference Resolver
                       │
                       ▼
              Knowledge Router

38. Exemplo completo

Usuário está em:

Permissão de Trabalho

Na aba:

Componentes

Selecionou:

Equipamento: Andaime

Foco:

Validade

Ele digita:

"Altere isso para 30 dias."

O sistema monta:

{
  "message": "Altere isso para 30 dias.",
  "context": {
    "page": "workPermit",
    "tab": "components",
    "selection": {
      "entityType": "equipment",
      "entityId": "equipment-827"
    },
    "focus": {
      "semanticId": "workPermit.components.equipment.validity",
      "type": "field"
    }
  }
}

O Intent Engine poderá produzir:

{
  "intent": "UPDATE_FIELD",
  "target": "workPermit.components.equipment.validity",
  "value": 30,
  "unit": "days"
}

O Planner encontra:

Capability:
workPermit.equipment.updateValidity

O Policy Engine verifica autorização.

O Execution Engine executa a operação.

Depois:

Verification
 ↓
UI refresh
 ↓
Agent response

"A validade do equipamento foi alterada para 30 dias."

39. Critérios de aceite

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

O Context Engine e o semantic-context-store do frontend registram página, rota, tab, foco, seleção e elementos visíveis sem depender do DOM. Cada mudança incrementa versão e TTL; snapshots minimizados preservam semantic IDs, redigem campos sensíveis, calculam hash e resolvem referências por prioridade determinística. As rotas de intent e orchestration validam identificadores e limite de contexto antes de usar o snapshot; contexto stale, cross-tenant ou fora do TTL é rejeitado. Os testes de engine/bridge aprovaram 8 casos e os testes de frontend/rotas aprovaram 14 casos em 2026-09-04.

Em 2026-09-05, os contratos de bridge, store semântico, atualização de UI e rotas passaram com 17 testes em 5 arquivos; os typechecks do Web e do Agent passaram. A cobertura comprova registro de contexto, snapshots/versionamento, resolução determinística, redaction, validação de backend e rejeição de contexto stale. O store mede o JSON por TextEncoder, congela o snapshot típico abaixo de 5.120 bytes e rejeita qualquer excesso com CONTEXT_SIZE_LIMIT_EXCEEDED; o chunk publicado execution-event-stream da Pages df7377f9-317a-494d-88df-d5bcd7d1c1a1 confirmou ambos os marcadores no artefato servido.

Em 2026-09-05, a versão de Worker 22b33d21-9018-4583-af20-b57025181a19 foi validada em Cloudflare por canário autenticado e tenant sintético isolado. O mesmo contrato mínimo de contexto usado pela UI de Work Permit retornou READY quando atual e retornou precisamente 409 STALE_CONTEXT_AGE quando o capturedAt tinha 310 segundos de idade, isto é, 10 segundos além do TTL de 300 segundos; o request expirado também não deixou linha em intent_audit_trail ou audit_ledger. O preview continuou não autorizador, e a trilha do preview aceito reteve somente hashes de contexto/utterance. A limpeza removeu as tabelas mutáveis de release no D1 e os dados sintéticos no PostgreSQL (remainingRows:0); os recibos imutáveis de intent_audit_trail e audit_ledger são deliberadamente retidos. Esta é uma prova Worker/API do contrato de contexto, complementada pelos testes React; não representa nem afirma E2E autenticado de navegador.

O PRD será considerado concluído quando:

  • React conseguir registrar a página atual;
  • React conseguir registrar a rota;
  • React conseguir registrar tab ativa;
  • React conseguir registrar foco semântico;
  • React conseguir registrar seleção;
  • contexto puder ser enviado junto à pergunta;
  • contexto não depender do DOM;
  • contexto possuir versionamento;
  • contexto possuir snapshot;
  • referências "isso", "este", "aqui" puderem ser resolvidas;
  • contexto puder apontar para semantic IDs;
  • semantic IDs puderem ser relacionados à HAG;
  • backend validar contexto e autorização;
  • dados sensíveis não sejam enviados desnecessariamente;
  • contexto típico permanecer abaixo de 5 KB;
  • mudança de tab atualizar o contexto;
  • mudança de seleção atualizar o contexto;
  • mudança de foco atualizar o contexto;
  • contexto antigo não seja utilizado inadvertidamente após mudança de registro.

40. Resultado arquitetural

Ao concluir este PRD, teremos algo extremamente importante:

             APLICAÇÃO
                 │
                 ▼
          SEMANTIC UI MODEL
                 │
       ┌─────────┼─────────┐
       ▼         ▼         ▼
      HAG      Agent      APIs
              Context

Ou seja, o agente deixa de receber simplesmente:

"O usuário perguntou X."

e passa a receber:

"O usuário perguntou X enquanto estava neste ponto semântico específico da aplicação."

Essa diferença será decisiva para a qualidade do sistema.

Próximo: PRD-003 — Knowledge Router + BM25

Este será provavelmente o PRD tecnicamente mais importante para atingir a velocidade que você está buscando.

Vamos especificar a camada de recuperação híbrida em detalhes:

Query
 │
 ├── Exact Match
 ├── Keyword Index
 ├── BM25
 ├── Semantic ID
 ├── Wikilinks
 ├── Metadata
 ├── Vectorize
 └── Context Boost
          │
          ▼
      Fusion/Ranking
          │
          ▼
     Knowledge Set

E, principalmente, vamos definir como evitar que uma pergunta simples percorra Vectorize + LLM + dezenas de documentos, criando um retrieval cascade com Fast Path, cache, BM25 e busca semântica somente quando realmente necessária.