PRD-015 — Agentic Observability, Performance & Cost Optimization
1. Objetivo
Criar a camada responsável por medir, diagnosticar e otimizar o comportamento do Agentic Work em produção.
O objetivo é que qualquer operação possa responder rapidamente:
- quanto tempo levou;
- onde ocorreu a latência;
- quantas chamadas ao LLM foram feitas;
- quanto contexto foi enviado;
- quanto custou;
- qual retrieval foi utilizado;
- quantos cache hits ocorreram;
- quais APIs foram chamadas;
- onde ocorreu uma falha;
- qual etapa pode ser otimizada.
O princípio é:
Performance e custo devem ser propriedades observáveis de cada operação do agente.
2. Problema
O agente será composto por diversas camadas:
Conversation
↓
Intent
↓
Context
↓
Knowledge
↓
Reference Resolution
↓
Capability
↓
Planner
↓
Policy
↓
Execution
↓
API
↓
Verification
↓
Response
Uma operação aparentemente simples poderá atravessar 10 ou 20 componentes.
Sem observabilidade distribuída, será impossível determinar se uma resposta demorou:
1.2s
porque:
- retrieval demorou;
- Vectorize foi chamado;
- houve cache miss;
- LLM foi chamado duas vezes;
- API demorou;
- ou houve retry.
3. Objetivos
O sistema deverá fornecer:
Observabilidade
Visibilidade completa do fluxo.
Performance
Identificação de gargalos.
Cost Intelligence
Custo por operação, usuário, tenant, capability e modelo.
Optimization
Identificação automática de oportunidades.
Capacity Planning
Previsão de crescimento.
4. Arquitetura
Agent Request
│
▼
Trace / Span
│
┌───────────────┼────────────────┐
▼ ▼ ▼
Runtime Retrieval LLM
│ │ │
▼ ▼ ▼
Execution Cache Model
│ │ │
└───────────────┼────────────────┘
▼
APIs
│
▼
Metrics
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Traces Metrics Costs
│ │ │
└──────────────┼──────────────┘
▼
Observability
Dashboard
5. Trace
Cada operação terá um trace:
interface AgentTrace {
traceId: string;
operationId: string;
conversationId?: string;
tenantId: string;
userId: string;
startedAt: string;
completedAt?: string;
durationMs?: number;
status: TraceStatus;
}
6. Spans
Cada etapa será um span.
Exemplo:
trace
├── conversation.resolve
├── intent.resolve
├── context.resolve
├── knowledge.retrieve
│ ├── cache.lookup
│ ├── exact.lookup
│ ├── bm25.search
│ └── vectorize.search
├── capability.resolve
├── policy.evaluate
├── planner.create
├── execution
│ ├── api.call
│ └── verification
└── response.generate
7. Span Model
interface AgentSpan {
spanId: string;
parentSpanId?: string;
traceId: string;
operation: string;
component: string;
startedAt: string;
durationMs: number;
status: "OK" | "ERROR";
metadata?: Record<string, unknown>;
}
8. Correlation
Os mesmos IDs definidos no PRD-013 deverão atravessar todo o sistema:
traceId
conversationId
messageId
intentId
planId
operationId
executionId
Isso permite correlacionar:
Performance
+
Audit
+
Security
+
Execution
sem criar sistemas paralelos desconectados.
9. Latency Breakdown
Para cada operação:
Total: 742 ms
Intent: 31 ms
Context: 8 ms
Knowledge: 42 ms
Capability: 4 ms
Policy: 7 ms
Planning: 12 ms
Execution: 480 ms
Verification: 91 ms
Response: 67 ms
Isso deverá estar disponível no dashboard.
10. Performance Budget
Cada camada terá um orçamento.
Exemplo inicial:
| Componente | P50 | P95 |
|---|---|---|
| Context | < 10 ms | < 25 ms |
| Capability | < 10 ms | < 20 ms |
| Policy | < 10 ms | < 30 ms |
| Exact retrieval | < 10 ms | < 20 ms |
| BM25 | < 30 ms | < 80 ms |
| Vectorize | < 80 ms | < 150 ms |
| Deterministic intent | < 50 ms | < 100 ms |
Esses valores são budgets iniciais, não contratos absolutos. Deverão ser calibrados após benchmarks reais.
11. Fast Path
O sistema deverá distinguir:
FAST PATH
de:
LLM PATH
Exemplo:
“Abra os componentes.”
Não deveria precisar de LLM.
Fluxo:
Context
↓
Semantic UI Registry
↓
Navigation Capability
↓
UI Command
12. LLM Avoidance Rate
Criar métrica:
LLM Avoidance Rate
Definição:
Percentual de solicitações resolvidas sem chamada ao LLM.
Exemplo:
10.000 requests
7.300 sem LLM
LLM Avoidance Rate = 73%
Esse indicador será central para a estratégia de performance.
13. LLM Calls per Task
Registrar:
llmCalls
Exemplo:
Task A → 0
Task B → 1
Task C → 3
Uma tarefa simples que passa de:
1 → 3 chamadas
deverá gerar alerta de regressão.
14. Retrieval Observability
Como o sistema já possui o HAG, índice de keywords, BM25, Wikilinks e Vectorize, a observabilidade deverá mostrar qual caminho foi utilizado.
Exemplo:
Knowledge Retrieval
Exact: HIT
Keyword: HIT
BM25: SKIPPED
Graph: 2 expansions
Vectorize: SKIPPED
LLM: SKIPPED
15. Retrieval Decision Trace
Registrar:
interface RetrievalTrace {
exactHit: boolean;
keywordHit: boolean;
bm25Executed: boolean;
graphExpansionCount: number;
vectorSearchExecuted: boolean;
cacheHit: boolean;
resultCount: number;
confidence: number;
durationMs: number;
}
16. Cache Observability
Medir:
cacheHit
cacheMiss
cacheWrite
cacheEviction
cacheStale
Separadamente por:
knowledge
intent
context
capability
policy
response
17. Cache Hit Ratio
Exemplo:
Knowledge cache:
94.2%
Intent cache:
88.7%
Capability cache:
99.8%
Uma queda abrupta deverá gerar alerta.
18. Cache Efficiency
Não basta medir hit ratio.
Também:
savedLatency
savedLLMCalls
savedCost
Exemplo:
Cache hits:
1.2M
Estimated LLM calls avoided:
240k
Estimated latency saved:
18 hours aggregate
19. Context Efficiency
O sistema deverá medir:
contextTokens
retrievedTokens
historyTokens
systemTokens
outputTokens
O objetivo é impedir que o agente envie contexto excessivo.
20. Context Compression
Medir:
rawContextSize
compressedContextSize
compressionRatio
Exemplo:
Raw: 24 KB
Compressed: 4.2 KB
Ratio: 5.7x
21. Conversation History
Não enviar automaticamente toda a conversa ao modelo.
Medir:
conversationHistorySize
structuredStateSize
llmContextSize
A Conversation Runtime deverá fornecer apenas o contexto necessário.
22. Token Observability
Para cada chamada ao modelo:
interface LLMUsage {
provider: string;
model: string;
promptTokens: number;
completionTokens: number;
totalTokens: number;
latencyMs: number;
estimatedCost?: number;
}
23. Cost Model
O sistema deverá calcular custo estimado:
LLM
+
Vectorize
+
Workers
+
storage
+
API
Não precisa representar custo financeiro exato inicialmente.
Pode começar com:
estimatedCost
e depois incorporar preços reais.
24. Cost Dimensions
Permitir análise por:
tenant
user
capability
domain
conversation
operation
model
provider
day
month
25. Cost per Task
Exemplo:
Average cost/task:
Navigation $0.0000
Knowledge query $0.0008
Create record $0.0012
Complex workflow $0.0047
Isso ajuda a identificar workflows caros.
26. Cost Guardrails
Poderá existir:
maxCostPerOperation
maxLLMCalls
maxTokens
maxRetrievedDocuments
Exemplo:
maxLLMCalls: 2
maxInputTokens: 12000
maxOutputTokens: 3000
Se o limite for atingido:
STOP
ou:
FALLBACK
conforme política.
27. Tenant Cost Controls
Um tenant poderá ter:
monthlyAgentBudget
dailyAgentBudget
maxLLMCalls
Ao atingir o limite:
LLM-heavy operations
↓
restricted
mas operações determinísticas poderão continuar.
28. Cost-Aware Routing
O Agent Runtime poderá escolher estratégias diferentes:
Simple
↓
No LLM
Moderate
↓
small/fast model
Complex
↓
strong model
O modelo não deverá ser escolhido pelo usuário diretamente para operações críticas.
29. Model Routing
Registrar:
taskType
modelSelected
reason
fallback
Exemplo:
Intent classification
→ small model
Complex planning
→ reasoning model
30. Fallback
Se um modelo estiver indisponível:
Model A
↓ failure
Model B
↓
continue
O fallback deverá ser auditável e observável.
31. Error Taxonomy
Erros deverão ser classificados.
INTENT_ERROR
REFERENCE_ERROR
KNOWLEDGE_ERROR
CAPABILITY_ERROR
POLICY_ERROR
EXECUTION_ERROR
API_ERROR
VERIFICATION_ERROR
LLM_ERROR
TIMEOUT
RATE_LIMIT
CONTEXT_STALE
Isso permite identificar a verdadeira origem.
32. Error Rate
Dashboard:
Intent errors 0.8%
Reference errors 0.4%
Policy denials 3.2%
Execution errors 0.7%
Verification errors 0.2%
LLM errors 0.1%
33. Error Budget
Para serviços críticos:
availability target
latency target
error target
Exemplo:
P95 < 500ms
successful execution > 99%
Os valores definitivos deverão ser estabelecidos após produção.
34. Distributed Tracing
Como o sistema usa Cloudflare Workers e múltiplos serviços, o trace deverá atravessar:
Browser
↓
Worker
↓
Agent Runtime
↓
Knowledge
↓
Policy
↓
API
↓
Database
O mecanismo de tracing deverá preservar o traceId.
35. Browser → Backend
O frontend poderá fornecer um identificador de interação:
interactionId
mas:
identidade, tenant e autorização continuam sendo determinadas no backend.
36. UI Performance
Medir também:
context update latency
UI command latency
semantic registration time
context serialization
context transmission
O Semantic UI Layer não poderá causar degradação significativa da aplicação.
37. Context Delta
Em vez de transmitir todo o contexto:
Snapshot:
50 KB
usar:
Delta:
200 bytes
Exemplo:
{
"event": "TAB_CHANGED",
"activeTab": "components"
}
38. Event Batching
Mudanças rápidas de UI:
FOCUS_CHANGED
FOCUS_CHANGED
FOCUS_CHANGED
poderão ser agregadas.
Evitar milhares de eventos redundantes.
39. Backpressure
Se o agente produzir eventos mais rapidamente que o cliente consegue consumir:
Agent
↓
Event Queue
↓
UI
deverá existir controle de backpressure.
40. Streaming Observability
Operações longas deverão emitir:
EXECUTION_STARTED
STEP_STARTED
STEP_COMPLETED
STEP_STARTED
...
EXECUTION_COMPLETED
O trace deverá mostrar a progressão.
41. Real-Time Dashboard
Para operações em andamento:
Operation #123
✓ Intent
✓ Policy
✓ Plan
▶ Step 3/5
Updating components
○ Verification
○ Response
42. Slow Operation Detection
Criar alertas:
operation > budget
Exemplo:
P95 normally = 420ms
Current = 2.8s
Gerar:
PERFORMANCE_ALERT
43. Regression Detection
Comparar automaticamente:
release N
vs
release N+1
Exemplo:
Intent latency:
42ms → 48ms
LLM calls:
0.32 → 0.71
Cost/task:
$0.0012 → $0.0029
Isso deverá sinalizar regressão.
44. Automated Optimization Suggestions
O sistema poderá produzir recomendações:
Optimization Suggestion
BM25 is being executed in 37%
of requests where exact lookup succeeds.
Potential latency reduction:
~42ms/request
Outro exemplo:
Capability lookup is missing cache
for repeated semantic IDs.
Potential reduction:
15ms P95
45. Knowledge Optimization
Como o conhecimento já possui:
- keywords;
- frequent-word index;
- Wikilinks;
- BM25;
- Vectorize;
o observability layer deverá identificar:
queries frequently falling through
exact → keyword → BM25 → Vectorize
Isso pode indicar:
- synonym gap;
- missing semantic ID;
- missing keyword;
- broken Wikilink;
- missing documentation.
46. Capability Optimization
Identificar capacidades que:
frequently require clarification
pode indicar que sua definição está inadequada.
Exemplo:
workPermit.update
pode estar sendo usado para alterações específicas que deveriam possuir:
workPermit.updateValidity
47. Intent Optimization
Medir:
intent confidence
clarification
correction
wrong capability
Se:
"validade"
frequentemente gera:
UPDATE
mas deveria gerar:
UPDATE_VALIDITY
isso será detectado pelo evaluation/observability layer.
48. Reference Resolution Optimization
Medir:
explicit reference
selection
focus
current page
conversation
HAG
LLM
Exemplo:
70% selection
20% semantic focus
8% conversation
2% LLM
Idealmente, o LLM deverá ser fallback.
49. Agent Efficiency Score
Criar indicador composto:
Agent Efficiency Score
considerando:
latency
LLM calls
tokens
cache efficiency
successful resolution
execution success
Não deverá substituir métricas individuais, apenas fornecer visão executiva.
50. SLOs
Cada categoria poderá ter SLO próprio.
Read-only
P95 < 500ms
Navigation
P95 < 300ms
Simple mutation
P95 < 1s
Complex workflow
Medido por etapa e não por um único limite rígido.
51. Cold Start Observability
Cloudflare Workers poderá apresentar comportamento diferente em cold/warm execution.
Registrar:
coldStart
workerInstance
initializationMs
quando disponível.
52. Database Observability
Medir chamadas:
D1
KV
R2
Vectorize
com:
operation
duration
result
errors
53. External API Observability
Para APIs externas:
provider
endpoint class
latency
status
retry count
timeout
Nunca registrar secrets ou tokens.
54. API Dependency Map
Construir automaticamente:
Agent
↓
Capability
↓
Hono endpoint
↓
External service
Isso permite responder:
Quais capabilities serão afetadas se determinado serviço estiver indisponível?
55. Capacity Planning
A plataforma deverá acompanhar:
requests/day
tasks/day
LLM calls/day
Vector searches/day
API calls/day
storage/day
e projetar:
30 days
90 days
12 months
56. Tenant Analytics
Dashboard por tenant:
Tenant A
Tasks: 82,430
Success: 98.7%
Avg latency: 421ms
LLM calls/task: 0.42
Estimated cost: ...
Sem permitir que um tenant visualize dados de outro.
57. User Analytics
Usuários autorizados poderão consultar:
my operations
my task success
my frequent corrections
Administradores, conforme policy, poderão acessar métricas agregadas.
58. Privacy
Observability deverá seguir:
data minimization
tenant isolation
PII redaction
retention policy
access control
Não registrar automaticamente:
- senhas;
- tokens;
- secrets;
- dados sensíveis desnecessários;
- conteúdo completo de campos sem necessidade.
59. Logs vs Metrics vs Traces
Separar claramente:
Logs
Eventos técnicos.
Metrics
Valores agregados.
Traces
Fluxo de uma operação.
Audit
Evidência de negócio/segurança.
Evaluation
Qualidade comportamental do agente.
60. Unified Operation View
O maior benefício será uma visão unificada:
Operation OP-123
User:
USER-42
Intent:
UPDATE
Target:
WP-123
Capability:
workPermit.updateValidity
Policy:
ALLOW
LLM calls:
0
Knowledge:
Exact HIT
Latency:
284ms
API:
142ms
Result:
SUCCESS
61. Observability API
Interface:
interface AgentObservability {
startTrace(
context: TraceContext
): AgentTrace;
startSpan(
operation: string
): AgentSpan;
recordMetric(
metric: Metric
): void;
recordLLMUsage(
usage: LLMUsage
): void;
recordCost(
cost: CostRecord
): void;
finishTrace(
traceId: string
): void;
}
62. Sampling
Não será necessário armazenar todos os traces detalhados para sempre.
Estratégia:
Critical/error → 100%
Slow operations → 100%
Security events → 100%
Normal operations → sampled
Aggregated metrics → retained
63. Adaptive Sampling
A taxa de sampling poderá aumentar automaticamente quando:
error rate ↑
latency ↑
security anomaly ↑
Isso permite obter mais evidência justamente durante incidentes.
64. Alerting
Alertas para:
latency regression
error spike
LLM usage spike
cost spike
cache degradation
Vectorize degradation
API dependency failure
unsafe action
policy anomaly
tenant abuse
65. Cost Anomaly
Exemplo:
Normal:
$20/day
Current:
$190/day
O sistema deverá identificar:
Cost anomaly
e mostrar a causa:
LLM calls +620%
66. Performance Anomaly
Exemplo:
P95:
420ms → 1.4s
Root cause:
Vectorize:
70ms → 540ms
O dashboard deverá permitir chegar ao componente responsável.
67. Root Cause Analysis
A observabilidade deverá permitir navegar:
Slow Task
↓
Slow Span
↓
Slow Dependency
↓
Error / bottleneck
Não depender de análise manual de centenas de logs.
68. First Vertical Slice
Implementar inicialmente para:
workPermit.updateValidity
Medindo:
intent
context
knowledge
capability
policy
execution
API
verification
audit
LLM
tokens
cost
latency
69. Acceptance Criteria
Tracing
- cada operação possui trace;
- spans representam etapas;
- IDs são correlacionáveis;
- dependências externas aparecem no trace.
Performance
- P50/P95/P99 disponíveis;
- budgets configuráveis;
- slow operations detectadas;
- regressões comparáveis entre versões.
LLM
- chamadas contabilizadas;
- tokens contabilizados;
- latência contabilizada;
- modelo identificado;
- custo estimado calculado.
Retrieval
- cache hit/miss;
- exact lookup;
- keyword;
- BM25;
- graph;
- Vectorize;
- fallback LLM.
Segurança
- secrets nunca aparecem;
- tenant isolation;
- dados sensíveis redigidos;
- security events correlacionados.
Operação
- dashboards;
- alertas;
- anomaly detection;
- capacity metrics;
- cost analytics.
Evidência parcial de implementação — 2026-09-04
O TraceStore aceita spans correlacionados por trace/correlation/tenant/capability, redige atributos sensíveis e expõe latência, P50/P95/P99, budget/slow flag e custo estimado por modelo/tokens. Métricas são particionadas por tenant, capability e release, preservando dados de observabilidade sem converter trace em canal de segredo.
Em 2026-09-04, TraceStore.detectLatencyAnomaly passou a comparar uma observação com P95 tenant-scoped, exigir baseline mínimo de três operações e sinalizar somente quando ultrapassa 2x o baseline. Sem baseline suficiente, retorna explicitamente INSUFFICIENT_BASELINE e não gera alerta espúrio.
Em 2026-09-05, os contratos de tracing/retrieval passaram com 8 testes em 2 arquivos e o typecheck passou. Os canários LMS e Knowledge confirmaram bytes/custo quando aplicável, integridade de retrieval, isolamento e ausência de segredo. Dashboards, entrega de alertas, métricas de capacidade e cost analytics amplas permanecem abertos para prova pública dedicada.
Em 2026-09-06, os quatro testes atuais de TraceStore e o typecheck do Agent passaram novamente. O health público confirmou runtime e bindings, mas não é usado como prova de Server-Timing: essa superfície requer verificação em uma rota operacional própria. Dashboards, entrega de alertas, métricas de capacidade e cost analytics amplas continuam pendentes de prova pública dedicada.
Em 2026-09-06, operational_task_events passou a persistir llm_calls, tokens de prompt/conclusão, custo estimado em microunidades USD e provider/modelo. O consumidor rejeita telemetria LLM incompleta e o endpoint tenant-scoped de métricas agrega taxa de evasão, chamadas, tokens e custo sem inferir valores ausentes. Foram aprovados 48 testes focados e o typecheck; a migração 0149_operational_task_cost_telemetry.sql foi aplicada no D1 remoto e o Worker 3377063c-b961-4c0c-8ca0-d25350f5d1c4 está ativo a 100%. Isso não prova dashboard, alertas ou cost analytics por todas as dimensões do PRD.
Ainda em 2026-09-06, GET /operations/costs passou a agregar, por tenant e intervalo ISO limitado a 31 dias, operações, chamadas, tokens e custo estimado por capability/provider/modelo. O Worker 6a35b5e1-9b67-4907-b87e-3c2c14cd2c50 foi publicado a 100%; o canário de Work Permit projetou novos pares determinísticos STARTED/SUCCEEDED no D1 remoto, todos com uso/custo zero coerente. O endpoint não substitui um dashboard, alertas de anomalia ou análise por todas as dimensões de negócio.
Também em 2026-09-06, a visão por correlação em GET /operations/tasks/:correlationId passou a incluir chamadas, tokens, custo estimado, provider e modelo de cada evento. O Worker fa90e300-3a3c-42e7-b4dc-b08e381b8761 foi publicado a 100% após o teste de contrato e typecheck.
Em seguida, GET /operations/anomalies passou a comparar a última operação concluída a um P95 tenant-local de operações anteriores: requer ao menos três ocorrências no baseline, usa multiplicador 2x para latência e custo, e retorna INSUFFICIENT_BASELINE quando não há evidência suficiente. O Worker ce8a0d35-1c89-4ecc-9432-19eb894b4193 foi publicado a 100%; o canário de Work Permit confirma o caminho de baseline insuficiente para uma operação real, sem alerta espúrio.
Em 2026-09-07, o dashboard web somente-leitura /operacoes foi publicado no Pages em 4d6586b5-ae52-4bdd-b4b1-65ed12b88b79, com agregados tenant-scoped de capability, P50/P95/P99, custo, anomalias, alertas de fila e capacidade. O Worker 65f9fb15-41d1-4f88-8f13-c0f7e00de666 expôs /operations/capabilities limitado a 100 e /capacity/metrics sem identidades de recurso. A suíte completa aprovou 7.661 testes; o canário LMS autenticado comprovou catálogo, alertas, métricas, custo, anomalias e capacidade no tenant sintético, e terminou com cleanup PostgreSQL remainingRows: 0.
70. Resultado
Com o PRD-015, a plataforma passa a ter uma visão operacional completa:
AGENTIC WORK
│
┌───────────────┼────────────────┐
▼ ▼ ▼
Security Quality Performance
│ │ │
Audit Evaluation │
│ │ │
└───────────────┼────────────────┘
▼
Observability
│
┌─────────┼─────────┐
▼ ▼ ▼
Latency Cost Errors
│ │ │
└─────────┼─────────┘
▼
Optimization
O agente deixa de ser uma “caixa-preta” operacional.
Passamos a saber o que ele fez, por que fez, quanto custou, quanto demorou e onde melhorar.
PRD-016 — Agentic Deployment, Versioning & Release Management
O próximo problema é consequência direta dos PRDs anteriores.
Agora temos múltiplos artefatos independentes:
Knowledge
Capability Registry
Policy Registry
Agent Manifest
UI Semantic Manifest
Intent Engine
Planner
Conversation Runtime
Security Fabric
Evaluation Dataset
Prompts
Models
Uma simples atualização de documentação, capability ou policy poderá alterar o comportamento do agente.
Portanto, precisamos de uma unidade formal de release:
Agent Release Bundle
O PRD-016 deverá definir como versionar, empacotar, validar, publicar, fazer rollout, realizar canary, rollback e manter compatibilidade entre todas essas versões.
A ideia central será sair de:
Deploy do código
para:
Agent Release
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
Code Version Manifest Knowledge
│ │ │
▼ ▼ ▼
Capabilities Policies UI Semantics
│ │ │
└─────────────────┼─────────────────┘
▼
Evaluation
│
▼
Release Gate
│
┌──────────┴──────────┐
▼ ▼
Canary Deploy
│ │
└──────────┬──────────┘
▼
Monitor
│
┌──────┴──────┐
▼ ▼
Stable Rollback
Esse será o mecanismo que permitirá evoluir o Agentic Work rapidamente sem perder segurança, compatibilidade ou previsibilidade.