Skip to main content

PRD-009 — Agent Knowledge-to-Capability Binding

1. Objetivo​

O Agent Knowledge-to-Capability Binding cria uma camada formal de ligação entre:

  • conhecimento existente no HAG;
  • documentação TypeDoc/Docusaurus;
  • entidades do sistema;
  • Semantic IDs;
  • telas React;
  • campos e componentes da UI;
  • APIs Hono;
  • capabilities;
  • regras de negócio;
  • workflows;
  • políticas de segurança.

O objetivo é permitir que o agente consiga responder:

“O que é isso?”

e também:

“O que posso fazer com isso?”

sem misturar as duas coisas.

2. O problema de escala

Em um sistema SST grande, teremos potencialmente:

milhares de entidades
milhares de funções TypeScript
centenas de telas
milhares de campos
centenas de APIs
centenas de capabilities
milhares de regras

Não é viável criar manualmente:

prompt para entidade A
prompt para entidade B
prompt para entidade C
...

Precisamos de uma estrutura declarativa que permita ao agente descobrir automaticamente as relações.

3. Modelo conceitual

O núcleo será um Agent Knowledge Graph.

                       DOMAIN
                         │
                         ▼
                      ENTITY
                         │
             ┌───────────┼───────────┐
             ▼           ▼           ▼
           UI          KNOWLEDGE   CAPABILITY
             │           │           │
             ▼           ▼           ▼
          SEMANTIC     HAG         POLICY
             │
             ▼
           FIELD
             │
             ▼
         BUSINESS RULE

Exemplo:

workPermit

relaciona-se com:

workPermit.details
workPermit.validity
workPermit.components
workPermit.risks
workPermit.approvals

E cada um desses elementos poderá apontar para:

documentation
capabilities
UI components
business rules
API operations

4. Princípio fundamental

Knowledge ≠ Capability​

A documentação pode dizer:

“Uma permissão aprovada não pode ser editada.”

Isso é conhecimento.

A capability:

workPermit.update

define uma operação.

A Policy:

permit.status == APPROVED
→ DENY

define autorização.

Portanto:

Knowledge
   ≠
Capability
   ≠
Policy

Mas elas precisam estar relacionadas.

5. Semantic Resource

O elemento central do binding será um Semantic Resource.

interface SemanticResource {
  id: string;

  type:
    | 'domain'
    | 'entity'
    | 'field'
    | 'component'
    | 'page'
    | 'section'
    | 'workflow'
    | 'rule'
    | 'api';

  name: string;

  labels: string[];

  parentId?: string;

  knowledgeRefs?: string[];

  capabilityRefs?: string[];

  policyRefs?: string[];

  uiRefs?: string[];

  apiRefs?: string[];

  metadata?: Record<string, unknown>;
}

6. Exemplo

{
  "id": "workPermit.validity",
  "type": "field",
  "name": "Validity",
  "parentId": "workPermit",

  "knowledgeRefs": [
    "docs/work-permit/validity"
  ],

  "capabilityRefs": [
    "workPermit.updateValidity"
  ],

  "policyRefs": [
    "workPermit.validity.update"
  ],

  "uiRefs": [
    "ui.workPermit.validity"
  ]
}

Agora temos uma relação formal entre:

Campo
 ↓
Documentação
 ↓
Capability
 ↓
Policy
 ↓
UI

7. Knowledge Binding

O HAG existente já possui:

  • Markdown;
  • índices;
  • keywords;
  • Wikilinks;
  • BM25;
  • Vectorize.

Não devemos recriar isso.

O PRD-009 adicionará metadata semântica aos documentos.

Exemplo:

semanticId: workPermit.validity

type: field

entity: workPermit

relatedCapabilities:
  - workPermit.updateValidity

relatedPolicies:
  - workPermit.validity.update

8. Frontmatter

Os documentos Docusaurus poderão possuir metadata estruturada:

---
semanticId: workPermit.validity
entity: workPermit
type: field
capabilities:
  - workPermit.updateValidity
policies:
  - workPermit.validity.update
---

O importante é que essa informação seja gerada automaticamente quando possível.

9. Não duplicar conhecimento

O sistema não deve criar outra documentação paralela.

A fonte principal continua sendo:

Source Code
      ↓
TypeDoc
      ↓
Docusaurus
      ↓
Markdown
      ↓
HAG

O Agent Knowledge-to-Capability Binding adiciona apenas o grafo de relacionamento operacional.

10. Source Mapping

Cada elemento poderá apontar para a origem no código.

Exemplo:

workPermit.updateValidity
       ↓
src/domain/workPermit/service.ts
       ↓
updateValidity()

Isso cria uma cadeia:

UI
 ↓
Semantic ID
 ↓
Capability
 ↓
Function
 ↓
Documentation

11. TypeDoc Integration

Como o sistema já possui TypeDoc, o pipeline poderá extrair:

  • funções;
  • classes;
  • interfaces;
  • types;
  • parâmetros;
  • retornos;
  • comentários;
  • exemplos;
  • módulos;
  • relações.

Exemplo:

src/workPermit/updateValidity.ts
       │
       ▼
TypeDoc
       │
       ▼
workPermit.updateValidity

12. Capability ↔ Function Binding

Uma capability deverá poder apontar para uma implementação.

Exemplo:

id: workPermit.updateValidity

implementation:
  module: workPermit
  function: updateValidity

Mas o LLM não recebe esse detalhe como autorização.

A implementação continua encapsulada no Runtime.

13. Capability ↔ API Binding

Também podemos ter:

Capability
    ↓
Service
    ↓
Hono API

Exemplo:

id: workPermit.updateValidity

api:
  service: workPermit
  method: PATCH
  route: /work-permits/:id/validity

Essa informação é infraestrutura interna.

O agente trabalha com:

workPermit.updateValidity

e não com:

PATCH /work-permits/...

14. UI Binding

A interface poderá declarar:

<ValidityField
  semanticId="workPermit.validity"
/>

O Context Bridge então sabe:

workPermit.validity

e o Registry sabe:

workPermit.validity
   ├── documentation
   ├── capability
   └── policy

15. React Semantic Components

Deveremos criar componentes/helpers para reduzir esforço dos desenvolvedores.

Por exemplo:

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

ou:

useSemanticContext(
  "workPermit.validity"
)

Isso permite que novas telas sejam automaticamente integradas ao agente.

16. Automatic Discovery

O objetivo final é minimizar configuração manual.

O pipeline poderá:

Source Code
   ↓
AST Analysis
   ↓
TypeDoc
   ↓
Semantic Extraction
   ↓
Capability Registry
   ↓
UI Semantic Registry
   ↓
Knowledge Graph

Assim, quando um desenvolvedor cria:

updateValidity()

o pipeline consegue detectar:

 ↓
documentação
 ↓
capability
 ↓
entidade

17. Semantic Naming Convention

Precisamos de uma convenção rígida.

Formato:

domain.entity
domain.entity.property
domain.entity.action
domain.entity.collection
domain.entity.collection.action

Exemplos:

workPermit
workPermit.validity
workPermit.responsible
workPermit.components
workPermit.components.add
workPermit.components.remove
workPermit.approve

18. Semantic IDs são contratos

Uma vez publicado:

workPermit.validity

não devemos mudar arbitrariamente para:

porque esse ID poderá estar referenciado por:

  • documentação;
  • HAG;
  • UI;
  • capabilities;
  • policies;
  • analytics;
  • prompts;
  • testes;
  • histórico.

Mudanças deverão utilizar aliases ou migrações.

19. Aliases

Podemos suportar:

semanticId: workPermit.validity

aliases:
  - permit.validity
  - workPermit.validityPeriod

Isso melhora a resolução de linguagem natural.

20. Synonyms

Além de aliases técnicos:

validity
validade
prazo
período de validade
tempo válido

podem ser associados ao Semantic ID.

Isso alimenta o mecanismo de retrieval.

21. Entity Resolution

Quando o usuário diz:

“Abra a permissão do João.”

O sistema pode:

"permissão"
    ↓
workPermit

"João"
    ↓
employee

relationship:
workPermit.responsible

O Knowledge Graph ajuda a resolver:

employee → responsible → workPermit

22. Relationship Types

O grafo deverá suportar relações tipadas.

Exemplos:

CONTAINS
BELONGS_TO
RELATED_TO
DOCUMENTED_BY
IMPLEMENTED_BY
EXPOSED_BY
USES
REQUIRES
DEPENDS_ON
AUTHORIZED_BY
VALIDATED_BY
NAVIGATES_TO

23. Exemplo de Graph

workPermit
   │
   ├── CONTAINS → workPermit.validity
   │                 │
   │                 ├── DOCUMENTED_BY → docs/validity
   │                 ├── UPDATED_BY → workPermit.updateValidity
   │                 └── PROTECTED_BY → validity.policy
   │
   ├── CONTAINS → workPermit.components
   │                 │
   │                 ├── ADD → components.add
   │                 └── REMOVE → components.remove
   │
   └── WORKFLOW → workPermit.approval

24. Knowledge Graph Expansion

Isso também melhora o retrieval.

Usuário:

“Posso alterar isso?”

Se:

focus = workPermit.validity

o agente pode navegar:

validity
 ↓
updateValidity
 ↓
policy
 ↓
business rules
 ↓
workflow state

Em vez de fazer uma busca genérica.

25. Capability Discovery

O Planner poderá perguntar ao Registry:

"What capabilities are relevant to workPermit.validity?"

Resposta:

[
  "workPermit.read",
  "workPermit.updateValidity"
]

O Planner não precisa conhecer previamente todas as capabilities.

26. Knowledge-Driven Planning

Agora o conhecimento pode ajudar a construir o plano.

Exemplo:

“Duplique essa permissão.”

O Knowledge Graph pode indicar:

workPermit.clone

não existe.

Mas existem:

workPermit.read
workPermit.create
workPermit.components.list
workPermit.components.add

E a documentação informa:

Componentes permitidos podem ser copiados entre permissões.

O Planner pode então construir:

READ
 ↓
CREATE
 ↓
COPY COMPONENTS

27. Knowledge Confidence

Nem todo binding terá a mesma confiabilidade.

Classificação:

SYSTEM_GENERATED
VERIFIED
MANUAL
INFERRED
DRAFT
DEPRECATED

Exemplo:

Capability → Function

detectado diretamente pelo código:

SYSTEM_GENERATED

Enquanto:

Capability → Documentation

inferido semanticamente:

INFERRED

28. Binding Validation

O pipeline deverá detectar inconsistências.

Exemplo:

UI references:
workPermit.updateValidity

mas Registry não possui a capability.

Resultado:

BROKEN_BINDING

Outro caso:

Capability:
workPermit.updateValidity

Documentation:
missing

Resultado:

MISSING_DOCUMENTATION

29. Quality Gate

O build do sistema deverá poder falhar quando houver inconsistências críticas.

Exemplo:

❌ Semantic ID duplicated
❌ Capability without implementation
❌ UI references unknown capability
❌ Policy references unknown capability

Isso evita que o agente opere sobre uma arquitetura inconsistente.

30. Agent Manifest

O pipeline deverá produzir um artefato versionado:

agent-manifest.json

Exemplo:

{
  "version": "2026.09.01",

  "entities": 842,

  "semanticResources": 12640,

  "capabilities": 731,

  "policies": 514,

  "bindings": 28391,

  "knowledgeVersion": "kb-2026-09-01"
}

Esse manifest permite ao Runtime saber exatamente qual conjunto está ativo.

31. Versionamento

Todos os artefatos devem possuir uma versão compatível:

Knowledge Version
Capability Version
Policy Version
UI Semantic Version
Agent Manifest Version

O Agent Runtime deverá conhecer a combinação ativa.

Exemplo:

Agent Manifest
    2026.09.01

Knowledge
    kb-428

Capabilities
    cap-91

Policies
    policy-33

32. Atomic Deployment

Não devemos atualizar:

Knowledge

sem garantir compatibilidade com:

Capabilities
Policies
Semantic Registry

O deployment deverá publicar uma nova versão do conjunto.

Conceito:

Bundle v41
  ├── knowledge
  ├── semantic graph
  ├── capabilities metadata
  └── policy references

Depois:

ACTIVE_VERSION = v41

33. Backward Compatibility

Uma execução já iniciada deve continuar usando o manifest com que foi criada.

Exemplo:

Execution E123
manifest = v40

Mesmo que:

production = v41

E123 não deve subitamente mudar de comportamento.

34. Agent Registry API

Deveremos expor uma interface interna:

interface AgentRegistry {
  getResource(id: string): SemanticResource | null;

  findResources(query: RegistryQuery): SemanticResource[];

  getCapabilities(resourceId: string): CapabilityRef[];

  getPolicies(resourceId: string): PolicyRef[];

  getKnowledgeRefs(resourceId: string): KnowledgeRef[];

  getUIRefs(resourceId: string): UIRef[];
}

35. Fast Lookup

O Registry deverá ser otimizado para acesso direto.

Exemplo:

workPermit.validity

→ O(1), idealmente.

Não queremos executar BM25 para descobrir que capability pertence a um campo já conhecido.

A sequência deve ser:

Semantic ID
 ↓
Registry lookup
 ↓
Capabilities

36. Hybrid Resolution

Quando o Semantic ID não for conhecido:

Natural Language
 ↓
Exact
 ↓
Alias
 ↓
Keyword
 ↓
BM25
 ↓
Graph
 ↓
Vectorize
 ↓
LLM

Isso aproveita toda a infraestrutura já existente.

37. HAG como Knowledge Layer

O HAG continuará responsável por:

"What does this mean?"
"What are the rules?"
"How does this work?"
"What is related?"

O Registry será responsável por:

"What exists?"
"What can I do?"
"Which capability?"
"Which UI?"
"Which policy?"

Essa divisão evita sobrecarga do HAG.

38. Capability Registry como Action Layer

Portanto:

HAG
  = knowledge

Registry
  = discoverability

Capability
  = action

Policy
  = authorization

Runtime
  = execution

Essa separação deverá permanecer uma regra arquitetural.

39. Exemplo de pergunta

Usuário:

“Como funciona a validade dessa permissão?”

Fluxo:

Context
 ↓
workPermit.validity
 ↓
Registry
 ↓
Knowledge refs
 ↓
HAG
 ↓
Answer

40. Exemplo de comando

Usuário:

“Coloque a validade para 30 dias.”

Fluxo:

Context
 ↓
workPermit.validity
 ↓
Registry
 ↓
workPermit.updateValidity
 ↓
Intent
 ↓
Planner
 ↓
Policy
 ↓
Execution

41. Exemplo de comando ambíguo

Usuário:

“Altere isso.”

Context:

page = workPermit
selection = WP-10231
focus = components

Registry pode identificar:

workPermit.components

mas não sabe qual alteração.

Resultado:

“Posso alterar os componentes da permissão WP-10231. O que você deseja modificar?”

Isso é muito melhor que executar uma ação arbitrária.

42. Automatic Documentation Coverage

O sistema poderá criar um relatório:

Entities:             842
Documented:           821
Capabilities:         731
Bound capabilities:   724
Missing bindings:       7
Broken references:      3

Isso transforma o Agent Registry também em ferramenta de governança arquitetural.

43. Developer Experience

Idealmente, para criar uma nova funcionalidade o desenvolvedor fará:

1. Implementar função
2. Documentar função
3. Definir capability
4. Adicionar semanticId
5. Declarar policy

O pipeline fará:

TypeDoc
 ↓
Semantic extraction
 ↓
Binding validation
 ↓
Agent manifest

44. Primeiro Vertical Slice

Novamente:

workPermit

Implementar bindings para:

workPermit
workPermit.details
workPermit.validity
workPermit.components
workPermit.approvals

Capabilities:

workPermit.read
workPermit.create
workPermit.update
workPermit.updateValidity
workPermit.components.list
workPermit.components.add
workPermit.components.remove

Policies correspondentes.

45. Critérios de Aceitação

AC-01​

Todo Semantic Resource deverá possuir ID estável.

AC-02​

O Registry deverá relacionar recursos às capabilities.

AC-03​

O Registry deverá relacionar recursos ao HAG.

AC-04​

O Registry deverá relacionar recursos à UI quando aplicável.

AC-05​

Capabilities deverão poder ser descobertas através de Semantic ID.

AC-06​

Aliases e sinônimos deverão ser suportados.

AC-07​

Bindings quebrados deverão ser detectados durante o build.

AC-08​

O Agent Manifest deverá ser versionado.

AC-09​

Execuções existentes deverão permanecer vinculadas à versão utilizada na criação.

AC-10​

O Registry deverá permitir lookup determinístico de baixa latência.

AC-11​

O LLM não poderá modificar bindings.

AC-12​

Knowledge, Capability e Policy deverão permanecer conceitos independentes.

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

O registry semântico relaciona recursos estáveis de UI, conhecimento e capabilities declaradas; discovery é determinístico por Semantic ID. O validador de build cria manifest v1 e interrompe a publicação para Semantic ID duplicado/desconhecido, capability ausente/inativa ou incompatibilidade entre documento e capability. Bindings são dados declarativos não mutáveis pelo LLM, enquanto Knowledge, Capability e Policy permanecem separados.

Em 2026-09-04, o registry passou a resolver aliases técnicos e sinônimos normalizados de forma determinística para o mesmo nó canônico, sem alterar capability, policy ou binding. workPermit.validity aceita permit.validity, workPermit.validityPeriod e sinônimos de validade; colisões no namespace fechado são rejeitadas no registro.

Em 2026-09-04, cada nó do registry pode declarar sourceRefs relativos e validados para apps/, packages/, docs/ ou scripts/; sourceMappings() os exporta em ordem determinística e somente como metadados imutáveis, sem conceder autoridade de runtime. O domínio Work Permit já aponta para apps/web/src/pages/work-permits.tsx, inclusive para o campo de validade. O teste focado do registry (5 casos) e o typecheck do pacote Agent passaram.

Em 2026-09-05, os contratos de intent, preview e orquestração passaram com 53 testes em 6 arquivos; registry, binding validator e router passaram com mais 21 testes em 3 arquivos, e o typecheck do Agent passou. A validação atual confirma IDs/aliases estáveis, lookup determinístico, bindings UI-HAG-capability, isolamento conceitual de policy, falha de build para binding inválido e previews não executáveis. A publicação atual do Worker mantém esses contratos em produção. Extração TypeDoc por símbolo/linha e expansão para novos domínios continuam melhorias de cobertura, sem alterar o contrato certificado do vertical Work Permit.

Em 2026-09-06, a regressão dos contratos atuais de registry, binding validator e router passou com 24 testes, e o typecheck do Agent passou novamente. O health público do Worker confirmou o runtime e seus bindings. A evidência mantém o recorte PARTIAL: sourceRefs declarativos não substituem extração automática por símbolo/linha do TypeDoc, e o domínio Work Permit ainda não representa a adoção em todos os domínios.

46. Arquitetura após PRD-009

Agora a arquitetura fica muito mais interessante:

                         ┌───────────────┐
                         │   React UI    │
                         └───────┬───────┘
                                 │
                         Semantic Context
                                 │
                                 ▼
                        ┌─────────────────┐
                        │ Context Bridge │
                        └────────┬────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │ Intent Engine  │
                        └────────┬────────┘
                                 │
                    ┌────────────┴────────────┐
                    │                         │
                    ▼                         ▼
              Knowledge Router          Agent Registry
                    │                         │
              ┌─────┴─────┐            ┌─────┼──────┐
              ▼           ▼            ▼     ▼      ▼
             HAG         BM25       UI   Capability Policy
              │           │                 │
              └─────┬─────┘                 │
                    │                       │
                    └──────────┬────────────┘
                               ▼
                        Agent Planner
                               │
                               ▼
                        Execution Plan
                               │
                               ▼
                         Policy Engine
                               │
                               ▼
                      Execution Runtime
                               │
                               ▼
                           Hono APIs
                               │
                               ▼
                         Application
                               │
                               ▼
                         Verification
                               │
                               ▼
                           React UI

47. O salto arquitetural produzido pelo PRD-009

Até aqui, o agente poderia ser inteligente, mas ainda dependeria de bastante configuração manual.

Com o PRD-009 começamos a construir algo diferente:

um sistema no qual o próprio software consegue descrever para o agente a sua estrutura operacional.

Isso abre caminho para escalar o Agentic Work para o sistema inteiro.

E há uma consequência ainda mais importante.

Se temos:

Source Code
 ↓
TypeDoc
 ↓
Semantic IDs
 ↓
Knowledge
 ↓
Capabilities
 ↓
Policies
 ↓
Agent Manifest

podemos fazer o agente entender uma nova funcionalidade assim que ela for corretamente registrada no pipeline, sem precisar modificar o “cérebro” do agente.

PRD-010 — Agentic Conversation Runtime

O próximo estágio deverá tratar de uma peça que ainda não formalizamos: a conversa como uma máquina de estados operacional.

Não será simplesmente um chat com histórico.

Precisaremos definir:

Conversation
   │
   ├── Intent
   ├── Context
   ├── Pending Clarification
   ├── Pending Confirmation
   ├── Execution
   ├── Execution Result
   ├── Follow-up Intent
   └── Conversation State

Isso permitirá interações naturais como:

Usuário: “Abra a permissão 123.”

Agente: “Abri.”

Usuário: “Agora vá para os componentes.”

Agente: “Abri a aba Componentes.”

Usuário: “Adicione o componente de trabalho em altura.”

Agente: “Encontrei o componente. Deseja adicioná-lo?”

Usuário: “Sim.”

Agente: “Adicionado.”

E depois:

Usuário: “Explique esse componente.”

Sem o usuário precisar repetir qual permissão, qual aba ou qual componente.

O PRD-010 vai definir justamente essa continuidade operacional, incluindo resolução de referências, estado conversacional, follow-up intents, correções do usuário, cancelamento de planos, “desfaça”, “não era isso”, retomada após erro e, principalmente, como impedir que o contexto de uma conversa antiga contamine uma nova operação.