PRD-012 — Agentic Task Memory & Operational Learning
1. Objetivo
O Agentic Task Memory & Operational Learning define a camada responsável por transformar as operações realizadas pelo agente em evidências estruturadas para melhoria contínua do sistema.
O objetivo não é criar um agente que “aprende sozinho” alterando seu próprio comportamento.
O objetivo é muito mais controlado:
registrar o que aconteceu, identificar padrões, medir qualidade e produzir sugestões verificáveis para evolução do produto.
A arquitetura deverá separar claramente:
Memória operacional
≠
Memória do usuário
≠
Conhecimento do sistema
≠
Treinamento do LLM
≠
Regras de segurança
2. Problema
Depois que os PRDs anteriores estiverem implementados, teremos um agente capaz de:
entender
↓
buscar conhecimento
↓
resolver intenção
↓
planejar
↓
validar política
↓
executar
↓
interagir com UI
↓
responder
Mas surgirá uma nova questão:
Como saber se o sistema está ficando melhor ou pior?
Por exemplo, suponha que em 10.000 operações:
2.100
"mude a validade"
sejam corretamente resolvidas.
Mas:
600
exijam esclarecimento.
E:
180
sejam corrigidas pelo usuário.
Isso é uma evidência de que existe um problema em algum ponto:
NLU
Context
Knowledge
Capability naming
UI semantics
Reference resolution
O sistema precisa capturar essa informação.
3. Princípio fundamental
O agente não aprende diretamente com qualquer interação.
O fluxo será:
Interaction
↓
Operational Event
↓
Evidence
↓
Aggregation
↓
Pattern Detection
↓
Human Review
↓
Approved Improvement
↓
Versioned Artifact
↓
Deployment
Portanto:
observação automática, mudança controlada.
4. O que pode ser aprendido
O sistema poderá identificar:
Linguagem
Novos sinônimos.
Exemplo:
"validade"
"prazo"
"tempo da permissão"
"data de validade"
Intenções
Comandos que repetidamente correspondem à mesma capability.
Referências
Expressões recorrentes:
"esse"
"essa"
"o de cima"
"o último"
"aquele funcionário"
UI
Elementos frequentemente procurados pelos usuários.
Capabilities
Operações que aparecem repetidamente em sequências.
Knowledge
Documentação frequentemente consultada.
Erros
Falhas recorrentes de API ou validação.
5. O que NÃO pode ser aprendido automaticamente
O sistema nunca deverá alterar automaticamente:
- políticas de segurança;
- permissões;
- RBAC;
- ABAC;
- limites de batch;
- requisitos de confirmação;
- segregação de funções;
- capabilities críticas;
- endpoints;
- regras de negócio;
- schemas de produção.
Essas alterações continuam dependendo de desenvolvimento/revisão.
6. Arquitetura
Agent Interaction
│
▼
Conversation Runtime
│
▼
Operational Telemetry
│
┌────────────┼────────────┐
▼ ▼ ▼
Events Outcomes Errors
│ │ │
└────────────┼────────────┘
▼
Evidence Pipeline
│
▼
Pattern Detection
│
┌────────────┼────────────┐
▼ ▼ ▼
Suggestions Metrics Alerts
│
▼
Human Review
│
▼
Versioned Changes
7. Operational Event
Cada operação relevante deverá gerar eventos estruturados.
interface AgentOperationalEvent {
eventId: string;
timestamp: string;
tenantId: string;
userId?: string;
conversationId: string;
operationId?: string;
intentId?: string;
capabilityId?: string;
eventType: OperationalEventType;
payload: unknown;
durationMs?: number;
outcome?: OperationOutcome;
}
8. Tipos de eventos
No mínimo:
MESSAGE_RECEIVED
INTENT_RESOLVED
INTENT_AMBIGUOUS
CLARIFICATION_REQUESTED
CLARIFICATION_RESOLVED
REFERENCE_RESOLVED
REFERENCE_AMBIGUOUS
PLAN_CREATED
POLICY_ALLOWED
POLICY_DENIED
CONFIRMATION_REQUESTED
CONFIRMATION_ACCEPTED
CONFIRMATION_REJECTED
EXECUTION_STARTED
EXECUTION_SUCCEEDED
EXECUTION_FAILED
USER_CORRECTION
USER_CANCELLATION
USER_RETRY
UNDO_REQUESTED
UNDO_SUCCEEDED
UNDO_FAILED
UI_COMMAND_SUCCEEDED
UI_COMMAND_FAILED
KNOWLEDGE_RETRIEVED
RESPONSE_GENERATED
9. Task Record
Além dos eventos individuais, deverá existir uma visão consolidada da tarefa.
interface AgentTaskRecord {
taskId: string;
conversationId: string;
tenantId: string;
initialMessage: string;
normalizedIntent?: IntentSnapshot;
capabilityIds: string[];
planId?: string;
operations: OperationSnapshot[];
finalOutcome: TaskOutcome;
clarificationCount: number;
correctionCount: number;
retryCount: number;
durationMs: number;
completedAt?: string;
}
10. Task Outcome
Valores:
SUCCESS
PARTIAL_SUCCESS
FAILED
CANCELLED
ABANDONED
UNRESOLVED
Exemplo:
Task:
"Adicione o componente de trabalho em altura"
Outcome:
SUCCESS
Clarifications:
0
Corrections:
0
Duration:
420ms
11. Task Quality Score
O sistema poderá calcular uma métrica operacional.
Exemplo conceitual:
Task Quality
=
Success
+ Correctness
+ Efficiency
+ Context Accuracy
+ Low Clarification
Não deve ser interpretado como uma “verdade absoluta”.
Será uma métrica operacional para comparação.
12. Métricas principais
Task Completion Rate
completed tasks / total tasks
First-pass success
Percentual de tarefas concluídas sem:
- esclarecimento;
- correção;
- retry.
Clarification Rate
tasks requiring clarification / total tasks
Correction Rate
tasks corrected by user / total tasks
Wrong Reference Rate
Referências que inicialmente foram resolvidas incorretamente.
LLM Dependency Rate
Percentual de turnos que necessitaram LLM.
Execution Failure Rate
Falhas das capabilities.
13. Métrica extremamente importante
Uma métrica estratégica será:
Deterministic Resolution Rate
Ou seja:
% das interações resolvidas sem LLM
Exemplo:
100.000 interações
72.000 → determinísticas
18.000 → retrieval
10.000 → LLM
Resultado:
72%
A meta deverá aumentar progressivamente.
Isso está diretamente alinhado ao objetivo de reduzir latência e custo.
14. Identificação de padrões
O sistema deverá procurar padrões estatísticos.
Exemplo:
"mude para X"
frequentemente resulta em:
clarification:
"Qual permissão?"
Mas o usuário normalmente está na página:
workPermit
Isso pode indicar que o contexto atual deveria resolver automaticamente:
target = selectedWorkPermit
O sistema gera uma sugestão:
A resolução de
workPermit.validitypoderia usar a entidade selecionada quando não houver referência explícita.
15. Suggestion Engine
interface ImprovementSuggestion {
suggestionId: string;
category:
| "INTENT"
| "REFERENCE"
| "KNOWLEDGE"
| "CAPABILITY"
| "UI"
| "PERFORMANCE"
| "ERROR";
description: string;
evidenceCount: number;
confidence: number;
affectedResources: string[];
examples: EvidenceExample[];
status:
| "PROPOSED"
| "REVIEWING"
| "APPROVED"
| "REJECTED"
| "IMPLEMENTED";
}
16. Exemplo de sugestão
Suggestion #183
Categoria:
REFERENCE
Problema:
"essa permissão" frequentemente requer clarification.
Evidências:
1.284 interações
Contexto predominante:
Página workPermit
Entidade selecionada: workPermit
Sugestão:
Resolver "essa permissão" como entidade atualmente selecionada.
Confidence:
97%
Um desenvolvedor poderá aceitar a sugestão.
17. Human-in-the-loop
Toda alteração comportamental significativa deverá passar por revisão.
PROPOSED
↓
REVIEW
↓
APPROVED
↓
IMPLEMENTED
Isso é particularmente importante em SST.
18. Evidence Store
As evidências deverão ser armazenadas separadamente do conhecimento principal.
Não inserir automaticamente:
"usuário X disse Y"
na documentação oficial.
Teremos:
Official Knowledge
+
Operational Evidence
19. Privacidade
A telemetria não deverá armazenar desnecessariamente:
- conteúdo completo de documentos;
- dados pessoais;
- informações sensíveis;
- valores de campos protegidos.
Sempre que possível:
raw value
↓
redaction
↓
normalized representation
Exemplo:
CPF: 123.456.789-00
pode ser registrado apenas como:
field = cpf
sensitive = true
20. Tenant Isolation
As métricas devem respeitar tenant.
Não permitir que padrões de:
Tenant A
sejam utilizados automaticamente para:
Tenant B
quando houver risco de vazamento de dados ou regras específicas.
Pode existir:
Global Pattern
Tenant Pattern
com regras claras de promoção.
21. Global Learning
Somente padrões anonimizados e generalizáveis poderão ser promovidos globalmente.
Exemplo seguro:
"prazo da permissão"
→ workPermit.validity
Exemplo que não deve ser promovido:
"João"
→ employee:EMP-123
22. Feedback explícito
O usuário poderá fornecer feedback:
Isso está errado.
Não era isso.
Perfeito.
Funcionou.
Não entendi.
Esses sinais deverão gerar evidências.
23. Feedback implícito
Também podem existir sinais indiretos.
Exemplo:
Agent executes action
↓
User immediately undoes it
Isso pode indicar possível interpretação incorreta.
Outro:
Agent asks clarification
↓
User repeats entire command
Pode indicar que a primeira interpretação foi inadequada.
24. Não assumir que Undo = erro
O sistema não deve interpretar automaticamente:
desfaça
como falha.
O usuário pode simplesmente ter mudado de ideia.
Portanto:
Undo
é um sinal fraco.
Já:
"Você fez errado"
é um sinal forte.
25. Error Intelligence
Erros deverão ser agrupados por causa.
Exemplo:
500 API
não basta.
Devemos classificar:
AUTHORIZATION_ERROR
VALIDATION_ERROR
RESOURCE_NOT_FOUND
CONFLICT
STALE_VERSION
BUSINESS_RULE
NETWORK
TIMEOUT
SYSTEM_ERROR
Isso permitirá identificar problemas reais.
26. Capability Analytics
Para cada capability:
invocations
successRate
failureRate
averageLatency
confirmationRate
cancellationRate
retryRate
undoRate
Exemplo:
workPermit.components.add
Invocations: 14.320
Success: 98.2%
Average: 182ms
Clarification: 3.1%
Correction: 0.8%
27. Capability Discovery
O sistema poderá identificar que usuários frequentemente solicitam uma sequência:
buscar funcionário
↓
abrir funcionário
↓
abrir documentos
↓
adicionar documento
Isso pode sugerir uma nova capability composta:
employee.documents.add
ou:
employee.documentWorkflow.create
Mas a capability somente será criada após revisão de desenvolvimento.
28. Workflow Mining
Sequências frequentes poderão ser detectadas.
Exemplo:
workPermit.open
→ workPermit.components.open
→ component.search
→ component.add
→ workPermit.save
Se isso ocorrer milhares de vezes, pode existir uma oportunidade de criar uma operação composta.
29. Knowledge Gap Detection
Se usuários perguntarem repetidamente:
O que significa esse campo?
e o agente frequentemente utilizar LLM porque a documentação não possui informação suficiente, o sistema poderá registrar:
Knowledge Gap
Exemplo:
semanticId:
workPermit.validity
Queries:
4.821
Low-confidence retrieval:
38%
Suggestion:
Improve documentation.
30. Documentation Quality
A integração com TypeDoc/Docusaurus permitirá identificar:
Capability
↓
Documentation
↓
Usage frequency
↓
User questions
Se uma capability muito utilizada possui documentação insuficiente, isso vira uma tarefa de melhoria.
31. UI Semantic Gap
Da mesma maneira:
User asks:
"onde altero a validade?"
Se o agente não consegue resolver:
workPermit.validity
mas o usuário está claramente nessa tela, pode existir uma lacuna de semanticização.
Resultado:
UI Semantic Gap
32. LLM Optimization
O sistema também deve descobrir onde eliminar chamadas ao LLM.
Exemplo:
1.000.000 requests
e:
"sim"
representa 100.000.
Se esses turnos ainda chegam ao LLM, o sistema pode gerar:
Optimization Suggestion:
Resolve confirmation deterministically.
33. Cache Optimization
Também poderão ser detectados padrões de consultas repetitivas.
Exemplo:
"o que é PGR?"
10.000 vezes.
O sistema poderá recomendar:
Knowledge Cache
ou aumentar prioridade do conteúdo correspondente.
34. Feedback Loop
O ciclo completo será:
┌──────────────────┐
│ USER │
└────────┬─────────┘
│
▼
AGENT EXECUTION
│
▼
OPERATIONAL DATA
│
▼
PATTERN ANALYSIS
│
▼
IMPROVEMENT
SUGGESTION
│
▼
HUMAN REVIEW
│
▼
VERSIONED CHANGE
│
▼
DEPLOY
│
└───────────────┐
│
▼
NEW DATA
35. Versionamento
Toda alteração resultante de aprendizado deverá possuir versão.
Exemplo:
intent-rules v1.8
reference-rules v2.1
knowledge v4.3
capabilities v3.7
ui-manifest v2.9
Nunca modificar silenciosamente o comportamento de produção.
36. A/B Testing
Quando apropriado, melhorias poderão ser testadas.
Exemplo:
Rule A:
"esse" → selectedEntity
Rule B:
"esse" → lastReferencedEntity
Distribuição controlada:
90% → A
10% → B
Métricas:
- success;
- correction;
- clarification;
- latency.
37. Shadow Mode
Antes de ativar uma nova regra:
Production
↓
Current behavior
+
Shadow behavior
O novo comportamento é calculado mas não executado.
Permite comparar:
Current:
clarification required
Shadow:
deterministic resolution
sem risco operacional.
38. Canary
Depois do shadow:
1%
↓
5%
↓
25%
↓
50%
↓
100%
com rollback automático caso métricas críticas piorem.
39. Rollback
Toda melhoria deverá poder ser revertida.
Version 12
↓
Version 13
↓
problem detected
↓
rollback
↓
Version 12
40. Agent Quality Dashboard
Deverá existir uma visão operacional com:
Task Success Rate
First Pass Success
Clarification Rate
Correction Rate
LLM Usage
Deterministic Resolution
Average Latency
P95 Latency
Capability Failures
Policy Denials
Knowledge Gaps
UI Semantic Gaps
41. Métricas por domínio
Exemplo:
Work Permit
Success 98.4%
Clarification 2.1%
Correction 0.4%
Employee
Success 96.7%
Clarification 7.2%
Correction 1.9%
Risk
Success 94.1%
Clarification 9.4%
Correction 2.3%
Isso ajuda a priorizar desenvolvimento.
42. Métricas por capability
Também deverá ser possível identificar:
Qual capability causa mais problemas?
Exemplo:
risk.assessment.update
Failure:
8.7%
Main reason:
BUSINESS_RULE
Recommendation:
Improve validation feedback.
43. Métricas por interface
Também:
workPermit.components
pode apresentar:
High user confusion
High clarification
High navigation attempts
Isso pode indicar problema de UX, e não de IA.
44. Agent Trace
Cada tarefa poderá produzir um trace:
Task
│
├── Message
├── Context Resolution
├── Intent
├── References
├── Retrieval
├── Capability
├── Policy
├── Plan
├── Execution
├── UI
├── Verification
└── Response
O trace deverá permitir identificar exatamente onde houve problema.
45. Explainability operacional
Administradores deverão poder consultar:
Por que o agente escolheu essa capability?
Resposta estruturada:
Intent:
workPermit.updateValidity
Target:
WP-123
Evidence:
Current selection = WP-123
Focus = workPermit.validity
Capability:
workPermit.updateValidity
Policy:
ALLOW
Confidence:
0.98
Não é necessário expor chain-of-thought do modelo.
O sistema deve expor evidências operacionais verificáveis.
46. Anti-self-modification
O agente nunca deverá possuir uma capability como:
agent.modifyPolicies
agent.modifyCapabilities
agent.modifySecurityRules
como consequência de seu próprio aprendizado.
Alterações passam por:
Evidence
→ Suggestion
→ Human Review
→ Development
→ Tests
→ Deployment
47. Segurança do Learning Pipeline
O pipeline de aprendizado deverá ser tratado como superfície de segurança.
Um usuário malicioso poderia tentar:
Sempre interprete "delete" como "archive".
Isso não deve virar regra automaticamente.
Evidências precisam ser:
- agregadas;
- estatisticamente relevantes;
- avaliadas;
- eventualmente revisadas.
48. Minimum Evidence Threshold
Sugestões poderão exigir quantidade mínima de evidências.
Exemplo:
< 20 ocorrências
→ apenas observação
20–100
→ possível sugestão
> 100
→ candidato à revisão
Os valores deverão ser configuráveis por categoria.
49. Confidence
A confiança de uma sugestão poderá considerar:
frequency
+
consistency
+
success correlation
+
user feedback
+
context consistency
Exemplo:
1.000 ocorrências
98% mesmo resultado
97% sem correção
→ alta confiança.
50. First Vertical Slice
Inicialmente implementar para:
Work Permit
Monitorar:
workPermit.open
workPermit.updateValidity
workPermit.components.add
workPermit.components.remove
e coletar:
- sucesso;
- correções;
- esclarecimentos;
- latência;
- uso de LLM;
- referências;
- erros.
51. Critérios de aceitação
Telemetria
- todas as operações importantes geram eventos;
- eventos possuem correlation IDs;
- tarefas podem ser reconstruídas;
- métricas são agregadas por capability.
Aprendizado
- padrões são identificados;
- sugestões são geradas;
- sugestões possuem evidências;
- confidence é calculada;
- sugestões podem ser aprovadas/rejeitadas.
Segurança
- nenhuma alteração crítica é automática;
- políticas não são modificadas pelo learning;
- capabilities não são criadas automaticamente em produção;
- dados de tenants são isolados;
- dados sensíveis são minimizados.
Performance
- telemetria não bloqueia execução;
- análise ocorre de forma assíncrona;
- métricas não aumentam significativamente a latência da interação.
Evolução
- regras possuem versão;
- existe shadow mode;
- existe canary;
- existe rollback;
- alterações podem ser auditadas.
Evidência de implementação e produção — 2026-09-05
O Task Memory conserva eventos reconstruíveis e métricas por capability; o scenario runner executa assertions determinísticas e o release gate mantém avaliações, shadow/canary/rollback versionados e auditáveis. Sugestões exigem evidência e aprovação humana, não criam capabilities nem modificam policies automaticamente, e o escopo tenant permanece separado.
Em 2026-09-04, o cron do Agent passou a analisar assincronamente eventos operacionais persistidos de clarificação/correção em janela de 30 dias e grava somente sugestões tenant-safe SHADOW/PENDING com evidência e confiança limitada. A análise não toca capability, policy ou execução; uma mudança continua exigindo revisão humana e fluxo de release separado.
Em 2026-09-04, o limiar de evidência passou a contar correlation_id distintos, não eventos brutos: retransmissões de uma mesma tarefa não elevam confiança nem criam sugestão. O teste cobre a consulta com COUNT(DISTINCT correlation_id) e preserva sugestões somente SHADOW/PENDING.
Em 2026-09-05, os testes focados de Task Memory e runtime assíncrono passaram (3 testes em 2 arquivos) e o typecheck completo do Agent passou. A evidência cobre a reconstrução/correlação de tarefas, agregação por capability, limiar de evidência independente, sugestão SHADOW/PENDING, cálculo de confiança, aprovação/rejeição humana, canário somente após aprovação e rollback para shadow. A análise é acionada pelo cron com waitUntil, não autoriza execução, não altera capability ou policy e mantém a separação por tenant; a migração D1 0126_learning_analysis.sql e o Worker já publicado sustentam o fluxo em produção.
Em 2026-09-06, os três testes atuais de Task Memory/runtime e o typecheck do Agent passaram novamente. O D1 remoto confirmou que não há migrações pendentes, incluindo 0126_learning_analysis.sql, e o health público confirmou o runtime com os bindings esperados. O estado permanece PARTIAL porque ainda falta um corpus amplo de evidências operacionais.
52. Resultado arquitetural
Com o PRD-012, teremos:
AGENT
│
▼
EXECUTION
│
▼
OBSERVABILITY
│
▼
OPERATIONAL EVIDENCE
│
▼
PATTERN ENGINE
│
▼
IMPROVEMENT SUGGESTIONS
│
▼
HUMAN REVIEW
│
▼
VERSIONED PLATFORM
O sistema passa a possuir um ciclo de melhoria contínua controlado, sem cair no problema perigoso de permitir que o próprio agente altere suas regras.
PRD-013 — Agentic Security, Audit & Compliance Fabric
O próximo PRD deve consolidar um aspecto particularmente importante para o domínio de SST: rastreabilidade e governança completa das ações realizadas pelo agente.
Até aqui definimos segurança distribuída entre:
Capability Registry
↓
Policy Engine
↓
Execution Engine
↓
Conversation Runtime
↓
Semantic UI
O PRD-013 deverá transformar isso em uma camada transversal de Security, Audit & Compliance Fabric, capaz de responder, para qualquer operação:
Quem pediu?
O que pediu?
O que o agente entendeu?
Qual contexto estava ativo?
Qual capability foi selecionada?
Qual política autorizou?
Qual plano foi executado?
Quais APIs foram chamadas?
Qual dado foi alterado?
Qual foi o resultado?
Houve confirmação humana?
Qual versão do agente, knowledge base, capability registry e policy estava ativa?
Essa camada será especialmente importante porque, no sistema final, o agente não será apenas um mecanismo de consulta: ele terá capacidade real de alterar dados e executar processos de negócio.