santismm-knowledge-mcp 0.2.1

package/content/harness/HRN-005-memory-in-agentic-systems.md

@@ -0,0 +1,145 @@
+---
+id: HRN-005
+title: Memory in Agentic Systems
+domain: Harness
+category: Memory
+status: Draft
+author: Santiago Santa María
+created: 2026-06-21
+updated: 2026-06-21
+summary: How the harness governs what the model sees and remembers — working, short-term, and long-term memory; the context window as a budget; retrieval, compression, and deliberate forgetting.
+evidence_level: theoretical
+confidence_level: medium
+source_type:
+  - industry_observation
+  - personal_experience
+related:
+  - HRN-003
+  - PAT-004
+  - PAT-006
+tags:
+  - memory
+  - context-window
+  - retrieval
+  - compression
+  - agentic-systems
+---
+
+# Memory in Agentic Systems
+
+## Executive Summary
+Memory is the harness component that decides what the model sees on every call and what persists across calls. Because the model is stateless and its context window is a hard, costly budget, memory is not a database feature bolted on — it is an active, opinionated curation system. This chapter covers the memory hierarchy (working, short-term, long-term), the context window as the binding constraint, and the three operations that make memory tractable at scale: retrieval, compression, and forgetting.
+
+## Key Concepts
+- **Working memory:** The immediate context the model is reasoning over right now — the current step's assembled prompt.
+- **Short-term memory:** The accumulated state of the current task or session (conversation, intermediate results, scratchpad).
+- **Long-term memory:** Persistent knowledge across sessions — user preferences, prior outcomes, organizational facts.
+- **Context window:** The fixed token budget for a single model call; the scarcest resource in the loop.
+- **Retrieval:** Selecting relevant items from a larger store to place into context.
+- **Compression:** Reducing the token footprint of information while preserving its useful content (summarization, distillation).
+- **Forgetting:** Deliberately dropping or down-weighting information to control cost, relevance, and staleness.
+
+## Definition
+**Memory in an agentic system** is the harness subsystem that manages the lifecycle of information the model uses — its acquisition, storage, selection into context, compression, and removal — across the time horizons of a single step, a single task, and the lifetime of the system. Its job is to put the *right* information in the model's limited context at the *right* time, and nothing else.
+
+## Architecture Diagram
+```mermaid
+flowchart TB
+  subgraph LTM["Long-term Memory (persistent)"]
+    VEC[(Vector / Semantic Store)]
+    KV[(Structured Facts / Profiles)]
+    EPI[(Episodic: past task outcomes)]
+  end
+  subgraph STM["Short-term Memory (per task)"]
+    HIST[Conversation / Step History]
+    SCR[Scratchpad / Intermediate Results]
+  end
+  RET[Retrieval] --> CTX
+  COMP[Compression] --> CTX
+  LTM --> RET
+  STM --> COMP
+  STM --> CTX
+  CTX[[Working Memory = Assembled Context]] --> MODEL{{Model}}
+  MODEL --> WRITE[Memory Writer]
+  WRITE --> STM
+  WRITE --> LTM
+  FORGET[Forgetting / Eviction] -.prunes.-> STM
+  FORGET -.prunes.-> LTM
+```
+
+## Detailed Explanation
+
+### The context window is a budget, not a container
+The single most important fact about memory is that the context window is *finite and expensive*, and quality degrades as you fill it. Even with large windows, packing everything in raises cost and latency and dilutes the model's attention on what matters (the "lost in the middle" effect). Memory engineering is therefore a *budgeting* problem: every token spent on history or retrieved context is a token not spent reasoning. The harness must continuously decide what earns its place in the window.
+
+### The memory hierarchy
+- **Working memory** is whatever is in the context window for the current call. It is assembled fresh every step from the other tiers.
+- **Short-term memory** holds the evolving state of the current task: the conversation so far, tool results, and a scratchpad of intermediate reasoning. It grows monotonically unless managed, which is why it is the primary target for compression and forgetting.
+- **Long-term memory** persists across tasks and sessions: semantic stores (often vector-indexed for similarity retrieval), structured profiles and facts (key-value or relational), and episodic records of past task outcomes the agent can learn from. Long-term memory is what lets an agent be *consistent* across sessions and *improve* over time.
+
+### Retrieval — choosing what to surface
+Retrieval selects relevant items from long-term (and sometimes short-term) memory to inject into working memory. The dominant approach is semantic similarity over embeddings, frequently augmented with keyword/lexical search (hybrid retrieval) and re-ranking. Retrieval quality dominates downstream answer quality: irrelevant or missing context cannot be fixed by a better prompt. Common refinements include query rewriting, metadata filtering, and recency/authority weighting. Patterns such as PAT-006 (knowledge retrieval) formalize these choices.
+
+### Compression — fitting more into the budget
+When short-term memory outgrows the budget, the harness compresses it. Techniques range from simple truncation (drop oldest turns), to rolling summarization (replace old turns with a running summary), to hierarchical/semantic compression (summarize at multiple granularities and keep pointers to detail). Compression is lossy by definition, so the engineering question is *what is safe to lose* — and that is task-specific. A coding agent must keep exact identifiers; a support agent can summarize chit-chat aggressively.
+
+### Forgetting — deliberate, not accidental
+Forgetting is an active control, not a bug. The harness must drop information that is stale (a fact that has changed), irrelevant (off-topic context), or out of budget (eviction under pressure). Without explicit forgetting, long-term memory accumulates contradictions and noise, and short-term memory overflows. Good forgetting policies down-weight by recency and relevance, expire facts with known volatility, and resolve conflicts (the newest authoritative value wins). Forgetting is also a *governance* surface: data-retention and right-to-be-forgotten requirements live here.
+
+### Memory writing and consolidation
+Closing the loop, the harness decides what from a completed step or task to *write back* to memory: extract durable facts, summarize the episode, update the user profile. This consolidation step — analogous to moving working memory into long-term storage — is what turns a stateless model into a system that accrues knowledge. Done carelessly, it is also how an agent poisons its own future context with a hallucinated "fact," which is why writes should be validated like any other actuation.
+
+### Memory as an attack surface
+Anything written to memory and later read into context is a prompt-injection vector. Retrieved documents and stored "facts" can carry adversarial instructions. Memory therefore intersects directly with security (HRN-011): treat retrieved and recalled content as untrusted input, not as trusted system prompt.
+
+## Production Evidence
+> **Evidence level:** theoretical · **Confidence:** medium · **Source:** industry_observation
+>
+> _Illustrative, representative scenario — not a verified single deployment._
+
+- **Context:** Long-running enterprise assistant agents (support, research, coding) operating over multi-turn sessions.
+- **Scenario:** Naive accumulation of full conversation history into the context window drives cost and latency up and answer quality down as sessions lengthen; introducing rolling summarization plus hybrid retrieval restores quality at a fraction of the token cost.
+- **Technology:** Frontier LLMs, vector store, hybrid retriever with re-ranking, summarization model for compression.
+- **Load:** Sessions ranging from a few turns to hundreds, with long-term stores from thousands to millions of items.
+- **Results:** Representative experience is a substantial reduction in tokens per turn and improved task consistency once memory is actively managed rather than passively accumulated.
+
+## Observed Failure Modes
+- **Context overflow:** Unmanaged short-term memory exceeds the window, causing truncation of exactly the information that mattered.
+- **Lost in the middle:** Over-stuffed context degrades attention to mid-prompt content; more context yields worse answers.
+- **Retrieval miss:** The relevant document is never surfaced, and the model confidently answers from a gap.
+- **Stale or contradictory memory:** Long-term store holds outdated or conflicting facts; the agent acts on the wrong one.
+- **Memory poisoning:** A hallucinated or adversarial "fact" is written back and contaminates future reasoning.
+
+## KPIs
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Retrieval precision/recall | Domain-dependent, measured | Quality of items surfaced into context |
+| Context utilization | Below window with headroom | Tokens used vs. budget per call |
+| Tokens per turn | Minimized for quality held constant | Direct cost driver |
+| Answer groundedness | High | Share of claims supported by retrieved context |
+
+## Cost Metrics
+Memory is a primary cost lever. Tokens placed in context are paid on every call, so compression and precise retrieval directly reduce inference spend. Long-term memory adds storage and embedding/indexing cost, and compression adds summarization-model calls. The net is almost always favorable: active memory management trades cheap batch summarization and indexing for expensive per-call context tokens.
+
+## Scaling Characteristics
+Memory scales along two axes: session length (drives short-term memory and compression frequency) and corpus size (drives long-term store and retrieval latency). Retrieval latency and quality are the usual bottlenecks as the long-term store grows; sharding, filtering, and re-ranking become necessary. Crucially, well-managed memory keeps per-call cost *flat* as sessions lengthen, whereas naive accumulation makes it grow without bound.
+
+## Related Content
+- HRN-003 — The Harness Taxonomy
+- PAT-004 — (memory / context pattern)
+- PAT-006 — (knowledge retrieval pattern)
+
+## References
+- Research on context-length effects in LLMs ("lost in the middle").
+- Practitioner literature on RAG, hybrid retrieval, and re-ranking.
+- Santa María, S. — Working notes on agent memory architecture.
+
+## FAQs
+**Q:** With million-token context windows, is memory engineering obsolete?
+**A:** No. Larger windows raise the budget but do not remove it — cost, latency, and attention dilution still scale with what you put in. Bigger windows make memory engineering *more* valuable, not less, because the temptation to over-stuff is greater.
+
+**Q:** Is memory just RAG?
+**A:** Retrieval (RAG) is one operation within memory. Memory also covers short-term/working state, compression, forgetting, and write-back consolidation. RAG without those is incomplete.
+
+**Q:** Should the model decide what to remember?
+**A:** Partly. The model can propose what to consolidate, but the harness should validate and govern writes — unvalidated self-writes are how agents poison their own memory.

package/content/harness/HRN-005-memory-in-agentic-systems.pt.md

@@ -0,0 +1,98 @@
+---
+title: "Memória em sistemas agênticos"
+summary: "O que o modelo vê e o que não vê: recuperação, compressão de contexto, memória de trabalho e de longo prazo, e as decisões de esquecimento que determinam custo e qualidade."
+---
+
+# Memória em sistemas agênticos
+
+## Resumo executivo
+A memória é o componente do harness que decide o que o modelo vê em cada chamada e o que persiste entre chamadas. Como o modelo não tem estado e sua janela de contexto é um orçamento rígido e caro, a memória não é uma funcionalidade de base de dados acrescentada no fim: é um sistema de curadoria ativo e com critério. Este capítulo cobre a hierarquia de memória (de trabalho, de curto prazo, de longo prazo), a janela de contexto como restrição determinante e as três operações que tornam a memória tratável à escala: recuperação, compressão e esquecimento.
+
+## Conceitos-chave
+- **Memória de trabalho:** o contexto imediato sobre o qual o modelo está raciocinando neste momento, ou seja, o prompt montado do passo atual.
+- **Memória de curto prazo:** o estado acumulado da tarefa ou sessão em andamento (conversa, resultados intermédios, bloco de rascunho).
+- **Memória de longo prazo:** conhecimento persistente entre sessões: preferências do usuário, resultados anteriores, fatos da organização.
+- **Janela de contexto:** o orçamento fixo de tokens de uma única chamada ao modelo; o recurso mais escasso do ciclo.
+- **Recuperação:** selecionar os elementos relevantes de um armazém maior para os colocar no contexto.
+- **Compressão:** reduzir a pegada em tokens de uma informação preservando seu conteúdo útil (resumo, destilação).
+- **Esquecimento:** descartar ou reduzir deliberadamente o peso de informação para controlar custo, relevância e desatualização.
+
+## Definição
+A **memória num sistema agêntico** é o subsistema do harness que gerencia o ciclo de vida da informação que o modelo utiliza — sua aquisição, armazenamento, seleção para o contexto, compressão e remoção — ao longo dos horizontes temporais de um passo, de uma tarefa e da vida inteira do sistema. Sua função é colocar a informação *certa* no contexto limitado do modelo no momento *certo*, e mais nada.
+
+## Explicação detalhada
+
+### A janela de contexto é um orçamento, não um contêiner
+O fato mais importante sobre a memória é que a janela de contexto é *finita e cara*, e que a qualidade se degrada à medida que se enche. Mesmo com janelas grandes, meter lá tudo eleva custo e latência e dilui a atenção do modelo sobre o que importa (o efeito “perdido no meio”). A engenharia de memória é, por isso, um problema de *orçamentação*: cada token gasto em histórico ou contexto recuperado é um token que não é gasto raciocinando. O harness tem de decidir continuamente o que merece seu lugar na janela.
+
+### A hierarquia de memória
+- A **memória de trabalho** é o que está na janela de contexto para a chamada atual. É montada de novo em cada passo a partir dos restantes níveis.
+- A **memória de curto prazo** guarda o estado em evolução da tarefa em andamento: a conversa até ao momento, os resultados de ferramentas e um bloco de raciocínio intermédio. Cresce de forma monótona se não for gerida, e por isso é o alvo principal da compressão e do esquecimento.
+- A **memória de longo prazo** persiste entre tarefas e sessões: armazéns semânticos (frequentemente indexados vetorialmente para recuperação por similaridade), perfis e fatos estruturados (chave-valor ou relacionais), e registros episódicos de resultados de tarefas passadas com que o agente pode aprender. A memória de longo prazo é o que permite a um agente ser *consistente* entre sessões e *melhorar* ao longo do tempo.
+
+### Recuperação: escolher o que trazer à superfície
+A recuperação seleciona elementos relevantes da memória de longo prazo (e por vezes da de curto prazo) para os injetar na memória de trabalho. A abordagem dominante é a similaridade semântica sobre embeddings, muitas vezes complementada com pesquisa lexical por palavras-chave (recuperação híbrida) e reordenação. A qualidade da recuperação domina a qualidade da resposta: um contexto irrelevante ou ausente não se corrige com um prompt melhor. Entre os refinamentos habituais estão a reescrita de consultas, a filtragem por metadados e a ponderação por recência ou autoridade. Padrões como PAT-006 (recuperação de conhecimento) formalizam estas decisões.
+
+### Compressão: caber mais dentro do orçamento
+Quando a memória de curto prazo transborda o orçamento, o harness comprime-a. As técnicas vão do truncamento simples (descartar os turnos mais antigos) ao resumo incremental (substituir os turnos velhos por um resumo acumulado) e à compressão hierárquica ou semântica (resumir a várias granularidades e guardar apontadores para o detalhe). A compressão é, por definição, com perda, portanto a pergunta de engenharia é *o que se pode perder sem risco*, e isso depende da tarefa. Um agente de programação tem de preservar os identificadores exatos; um agente de suporte ao cliente pode resumir a conversa de circunstância com agressividade.
+
+### Esquecimento: deliberado, não acidental
+O esquecimento é um controle ativo, não uma falha. O harness tem de descartar informação desatualizada (um dado que mudou), irrelevante (contexto fora de tema) ou fora de orçamento (despejo sob pressão). Sem esquecimento explícito, a memória de longo prazo acumula contradições e ruído, e a de curto prazo transborda. As boas políticas de esquecimento reduzem peso por recência e relevância, fazem expirar os fatos de volatilidade conhecida e resolvem conflitos (ganha o valor autorizado mais recente). O esquecimento é ainda uma superfície de *governança*: os requisitos de retenção de dados e de direito ao esquecimento vivem aqui.
+
+### Escrita e consolidação de memória
+Para fechar o ciclo, o harness decide o que *escrever de volta* na memória depois de um passo ou de uma tarefa: extrair fatos duradouros, resumir o episódio, atualizar o perfil do usuário. Esse passo de consolidação — análogo a passar a memória de trabalho para armazenamento de longo prazo — é o que converte um modelo sem estado num sistema que acumula conhecimento. Feito sem cuidado, é também a forma como um agente envenena seu próprio contexto futuro com um “fato” alucinado, e por isso as escritas devem ser validadas como qualquer outra atuação.
+
+### A memória como superfície de ataque
+Tudo o que é escrito em memória e depois lido para o contexto é um vetor de injeção de prompts. Os documentos recuperados e os “fatos” armazenados podem transportar instruções adversárias. A memória interseta, portanto, diretamente com a segurança (HRN-011): trate o conteúdo recuperado e recordado como entrada não confiável, não como prompt de sistema de confiança.
+
+## Evidência de produção
+> **Nível de evidência:** teórico · **Confiança:** média · **Fonte:** observação de indústria
+>
+> _Cenário ilustrativo e representativo, não uma implantação verificada concreta._
+
+- **Contexto:** agentes assistentes empresariais de longa duração (suporte ao cliente, investigação, programação) a operar em sessões de muitos turnos.
+- **Cenário:** a acumulação ingênua do histórico completo da conversa na janela de contexto dispara custo e latência e afunda a qualidade da resposta à medida que a sessão se prolonga; introduzir resumo incremental mais recuperação híbrida restaura a qualidade a uma fração do custo em tokens.
+- **Tecnologia:** LLM de fronteira, armazém vetorial, recuperador híbrido com reordenação, modelo de resumo para a compressão.
+- **Carga:** sessões que vão de uns poucos turnos a centenas, com armazéns de longo prazo de milhares a milhões de elementos.
+- **Resultados:** a experiência representativa é uma redução substancial de tokens por turno e uma maior consistência da tarefa assim que a memória é gerida ativamente em vez de acumulada de forma passiva.
+
+## Modos de falha observados
+- **Transbordo de contexto:** uma memória de curto prazo não gerida excede a janela e trunca precisamente a informação que importava.
+- **Perdido no meio:** um contexto sobrecarregado degrada a atenção ao conteúdo central do prompt; mais contexto produz piores respostas.
+- **Falha de recuperação:** o documento relevante nunca vem à superfície e o modelo responde com segurança a partir de uma lacuna.
+- **Memória desatualizada ou contraditória:** o armazém de longo prazo guarda fatos vencidos ou em conflito e o agente age sobre o errado.
+- **Envenenamento de memória:** um “fato” alucinado ou adversário é escrito de volta e contamina o raciocínio futuro.
+
+## KPIs
+| Métrica | Objetivo | Notas |
+|---------|----------|-------|
+| Precisão / abrangência de recuperação | Dependente do domínio, medida | Qualidade dos elementos trazidos para o contexto |
+| Utilização do contexto | Abaixo da janela, com folga | Tokens usados diante do orçamento por chamada |
+| Tokens por turno | Minimizados a qualidade constante | Motor direto de custo |
+| Ancoragem da resposta | Alta | Proporção de afirmações sustentadas pelo contexto recuperado |
+
+## Métricas de custo
+A memória é uma alavanca de custo de primeira ordem. Os tokens colocados em contexto são pagos em cada chamada, portanto a compressão e uma recuperação precisa reduzem diretamente a despesa de inferência. A memória de longo prazo acrescenta custo de armazenamento e de indexação por embeddings, e a compressão acrescenta chamadas a um modelo de resumo. O saldo é quase sempre favorável: a gestão ativa de memória troca resumo e indexação baratos em lote por tokens de contexto caros por chamada.
+
+## Características de escalabilidade
+A memória escala em dois eixos: duração da sessão (que governa a memória de curto prazo e a frequência de compressão) e dimensão do corpus (que governa o armazém de longo prazo e a latência de recuperação). A latência e a qualidade da recuperação são os gargalos habituais à medida que o armazém de longo prazo cresce; o particionamento, a filtragem e a reordenação se tornam necessários. E o essencial: uma memória bem gerida mantém *plano* o custo por chamada mesmo com sessões longas, enquanto a acumulação ingênua o faz crescer sem limite.
+
+## Conteúdo relacionado
+- HRN-003 — A taxonomia do harness
+- PAT-004 — (padrão de memória / contexto)
+- PAT-006 — (padrão de recuperação de conhecimento)
+
+## Referências
+- Investigação sobre os efeitos da dimensão do contexto nos LLM (“perdido no meio”).
+- Literatura de prática sobre RAG, recuperação híbrida e reordenação.
+- Santa María, S. — Notas de trabalho sobre arquitetura de memória de agentes.
+
+## Perguntas frequentes
+**P:** Com janelas de contexto de um milhão de tokens, a engenharia de memória não fica obsoleta?
+**R:** Não. As janelas maiores elevam o orçamento, mas não o eliminam: o custo, a latência e a diluição de atenção continuam a escalar com aquilo que se lá mete. As janelas grandes tornam a engenharia de memória *mais* valiosa, não menos, porque a tentação de sobrecarregar é maior.
+
+**P:** A memória não é simplesmente RAG?
+**R:** A recuperação (RAG) é uma operação dentro da memória. A memória cobre ainda o estado de trabalho e de curto prazo, a compressão, o esquecimento e a consolidação por escrita. RAG sem isso tudo está incompleto.
+
+**P:** Deve o modelo decidir o que recordar?
+**R:** Em parte. O modelo pode propor o que consolidar, mas o harness deve validar e governar as escritas: as autoescritas sem validação são a forma como os agentes envenenam sua própria memória.

package/content/harness/HRN-006-observability-for-agentic-systems.es.md

@@ -0,0 +1,97 @@
+---
+title: "Observabilidad para sistemas agénticos"
+summary: "Convertir cada paso del agente en una traza reproducible: spans, atribución de coste, depuración de bucles no deterministas y las señales que hacen medible la fiabilidad."
+---
+
+# Observabilidad para sistemas agénticos
+
+## Resumen ejecutivo
+La observabilidad es el componente del harness que convierte una ejecución de agente opaca y no determinista en un artefacto inspeccionable y reproducible. No se puede depurar, evaluar, gobernar ni confiar en un sistema estocástico de varios pasos que no se ve, y por eso la observabilidad es una precondición de casi cualquier otra capacidad del harness, no un añadido de segunda fase. Este capítulo cubre trazas y spans adaptados a agentes, la contabilidad de tokens y coste como telemetría de primera clase, los ganchos de evaluación y la reproducción determinista.
+
+## Conceptos clave
+- **Traza:** el registro completo de una única ejecución del agente, de principio a fin, del objetivo al resultado.
+- **Span:** una unidad de trabajo dentro de una traza (una llamada al modelo, una invocación de herramienta, una recuperación, una decisión) con entradas, salidas, tiempos y metadatos.
+- **Contabilidad de tokens y coste:** seguimiento por span y por traza de los tokens de entrada y salida y del coste resultante.
+- **Gancho de evaluación:** un punto de instrumentación donde la lógica de evaluación puede puntuar un span o una traza, en línea o fuera de línea.
+- **Reproducción (replay):** volver a ejecutar de forma determinista una traza grabada para reproducir y depurar el comportamiento.
+- **Cardinalidad:** la dimensionalidad de las etiquetas de telemetría; una cardinalidad alta ayuda al análisis pero eleva el coste de almacenamiento.
+
+## Definición
+La **observabilidad para sistemas agénticos** es el subsistema del harness que captura, estructura y almacena un registro completo y consultable de cada ejecución del agente —sus spans, entradas, salidas, llamadas al modelo, llamadas a herramientas, costes y decisiones— de modo que cualquier ejecución pueda entenderse a posteriori, compararse entre versiones, puntuarse mediante evaluación y reproducirse de forma determinista. Responde a la pregunta «¿qué pasó exactamente, y por qué?».
+
+## Explicación detallada
+
+### Por qué la observabilidad clásica no basta
+El APM tradicional asume servicios deterministas: una petición, unas cuantas llamadas síncronas, una respuesta. Los sistemas agénticos rompen esas premisas. Una misma ejecución puede tomar *un camino distinto cada vez*, abrirse en abanico sobre muchas llamadas a modelo y a herramientas, iterar un número desconocido de veces y producir entradas y salidas *en lenguaje natural* que las métricas ordinarias no saben resumir. La observabilidad para agentes debe capturar por tanto no solo latencia y errores, sino el *contenido semántico* de cada paso: el prompt enviado, la respuesta devuelta, los argumentos elegidos para la herramienta, el razonamiento. Sin ese contenido, una traza te dice *que* el agente falló pero nunca *por qué*.
+
+### Trazas y spans, adaptados a agentes
+El modelo de traza y span del trazado distribuido es la columna vertebral correcta, con tipos de span específicos de agentes:
+- Los **spans de llamada al modelo** registran el prompt ensamblado (o una referencia a él), la respuesta, el modelo y sus parámetros, los recuentos de tokens y la latencia.
+- Los **spans de llamada a herramienta** registran la herramienta, los argumentos (ya validados), el resultado o el error, y los reintentos.
+- Los **spans de recuperación** registran la consulta, los elementos devueltos y sus puntuaciones: imprescindible para diagnosticar fallos de memoria.
+- Los **spans de decisión o plan** registran la elección de la siguiente acción por parte del agente y, cuando existe, su justificación.
+
+Los spans se anidan hasta formar el árbol causal completo de una ejecución. Cuanto más rico sea el contenido capturado, más depurable es el sistema, a costa de almacenamiento y de exposición de datos, que deben gestionarse (redacción, muestreo, retención).
+
+### La contabilidad de tokens y coste como telemetría de primera clase
+En los sistemas agénticos el *coste es un comportamiento*, no solo una factura. Una regresión que provoca un bucle de razonamiento de más o un contexto inflado se manifiesta primero como un pico de tokens. La observabilidad debe tratar por tanto los recuentos de tokens y el coste derivado como métricas de primera clase, atribuidos por span, por traza, por usuario y por versión del agente. Eso hace detectables las regresiones de coste, alertables los bucles desbocados y medible la economía por tarea, cerrando el círculo con la disciplina de métricas de coste que recorre todo el manual.
+
+### Ganchos de evaluación
+Observabilidad y evaluación (HRN-007) son codependientes. La evaluación necesita las trazas; la observabilidad rinde más cuando sus datos alimentan la puntuación. El harness debe exponer *ganchos de evaluación*: puntos de instrumentación donde un evaluador (una regla, un clasificador o un LLM como juez) puede engancharse a un span o a una traza, ya sea *en línea* (puntuando tráfico vivo para monitorización) o *fuera de línea* (reproduciendo trazas almacenadas contra un modelo o un prompt nuevos). Diseñar esos ganchos dentro del formato de traza desde el primer día es lo que abarata la evaluación continua más adelante.
+
+### Reproducción determinista
+La capacidad más potente y específica de los agentes es la reproducción: volver a ejecutar una traza grabada para reproducir su comportamiento. Como el modelo no es determinista, una reproducción de verdad exige capturar lo suficiente para *fijar* la ejecución: salidas del modelo grabadas (para reproducir sin volver a llamarlo), resultados de herramientas, contexto recuperado y semillas aleatorias cuando aplique. La reproducción habilita tres cosas de otro modo casi imposibles: reproducir localmente un fallo de producción, someter a prueba de regresión un cambio de prompt o de modelo contra tráfico histórico real, y comparar en A/B dos versiones del harness sobre entradas idénticas. Un harness sin reproducción depura a base de conjeturas.
+
+### Privacidad, redacción y retención
+Capturar prompts y respuestas completas significa capturar datos potencialmente sensibles. La observabilidad debe integrar redacción (limpieza de datos personales), controles de acceso sobre el almacén de trazas y políticas de retención: son preocupaciones de gobernanza (HRN-008) y de seguridad (HRN-011) que la capa de observabilidad aplica en la práctica.
+
+## Evidencia de producción
+> **Nivel de evidencia:** teórico · **Confianza:** media · **Fuente:** observación de industria
+>
+> _Escenario ilustrativo y representativo, no un despliegue verificado concreto._
+
+- **Contexto:** equipos que operan agentes de varios pasos en producción y que salieron a producción con poco más que logging básico.
+- **Escenario:** un fallo intermitente (el agente toma de vez en cuando una acción equivocada) resulta indiagnosticable desde los logs; tras añadir captura completa de trazas y spans con reproducción, la ejecución fallida se reproduce en local y se rastrea hasta un fallo de recuperación que había alimentado al modelo con un documento engañoso.
+- **Tecnología:** backend de trazado con tipos de span conscientes del agente, almacén de trazas, utillaje de reproducción, telemetría de tokens y coste.
+- **Carga:** tráfico de producción con fallos de cola larga, difíciles de reproducir.
+- **Resultados:** la experiencia representativa es que el tiempo medio hasta el diagnóstico cae drásticamente en cuanto las ejecuciones están trazadas por completo y son reproducibles, y que las regresiones de coste se vuelven visibles en el mismo momento en que ocurren.
+
+## Modos de fallo observados
+- **Logs sin estructura:** texto libre que registra *que* algo pasó pero no el árbol de spans, las entradas y las salidas necesarias para entenderlo.
+- **Sin captura de contenido:** capturar latencia y errores pero no prompts ni respuestas, dejando los fallos indiagnosticables.
+- **Cardinalidad y almacenamiento sin límite:** capturarlo todo a máxima fidelidad en cada ejecución, disparando el coste de almacenamiento; hacen falta muestreo y política de retención.
+- **Sin reproducción:** incapacidad de reproducir fallos no deterministas, lo que fuerza a depurar por conjeturas.
+- **Fuga de privacidad:** capturar contenido sensible de prompts sin redacción ni control de acceso.
+
+## KPIs
+| Métrica | Objetivo | Notas |
+|---------|----------|-------|
+| Cobertura de trazado | ~100 % de las ejecuciones | Cada ejecución de producción produce una traza |
+| Tiempo medio hasta el diagnóstico | Minimizado | Del aviso de fallo a la causa raíz vía trazas y reproducción |
+| Cobertura de atribución de coste | Por span / traza / versión | Permite detectar regresiones de coste |
+| Fidelidad de reproducción | Alta | Proporción de trazas grabadas que se reproducen de forma determinista |
+
+## Métricas de coste
+La observabilidad añade coste de almacenamiento (proporcional a trazas × spans × contenido capturado) y una pequeña sobrecarga de ejecución por span. El muestreo, la redacción, la retención por niveles y el guardar referencias en lugar de cargas grandes lo mantienen a raya. El coste se devuelve con creces por la resolución más rápida de incidentes y por *hacer observable el propio token y su coste*, lo que suele sacar a la luz ahorros de inferencia que empequeñecen el gasto en observabilidad.
+
+## Características de escalado
+El volumen de trazas escala con tráfico × pasos por ejecución, así que los flujos agénticos profundos generan desproporcionadamente más telemetría que los servicios planos. El almacenamiento y el coste de consulta son los cuellos de botella; el muestreo por cabecera y por cola, la agregación y los niveles de retención lo mantienen acotado. El almacenamiento para reproducción escala con la fidelidad capturada, cambiando almacenamiento por reproducibilidad.
+
+## Contenido relacionado
+- HRN-003 — La taxonomía del harness
+- HRN-007 — Evaluación de sistemas agénticos
+
+## Referencias
+- Conceptos de trazado distribuido (spans, trazas) adaptados a cargas agénticas.
+- Literatura de práctica sobre observabilidad y utillaje de trazado para LLM.
+- Santa María, S. — Notas de trabajo sobre observabilidad y reproducción de agentes.
+
+## Preguntas frecuentes
+**P:** ¿No basta con los logs?
+**R:** No. Los logs sin estructura no permiten reconstruir el árbol causal de spans de una ejecución ramificada de varios pasos, y rara vez capturan el contenido semántico (prompts, respuestas, contexto recuperado) que hace falta para explicar un fallo. Se necesitan trazas estructuradas con reproducción.
+
+**P:** ¿Por qué medir el coste en la capa de observabilidad?
+**R:** Porque en los sistemas agénticos el coste es un *comportamiento*: los bucles de más y el contexto inflado aparecen como picos de tokens antes que en ningún otro sitio. La telemetría de coste es como se cazan esas regresiones.
+
+**P:** ¿Cuál es la capacidad más valiosa de todas?
+**R:** La reproducción determinista. Convierte «no somos capaces de reproducirlo» en una sesión de depuración local rutinaria y permite someter los cambios a prueba de regresión contra tráfico histórico real.

package/content/harness/HRN-006-observability-for-agentic-systems.md

@@ -0,0 +1,139 @@
+---
+id: HRN-006
+title: Observability for Agentic Systems
+domain: Harness
+category: Observability
+status: Draft
+author: Santiago Santa María
+created: 2026-06-21
+updated: 2026-06-21
+summary: How to make a non-deterministic, multi-step agent inspectable — traces and spans, token and cost accounting, evaluation hooks, and deterministic replay — so the system can be debugged, measured, and trusted.
+evidence_level: theoretical
+confidence_level: medium
+source_type:
+  - industry_observation
+  - personal_experience
+related:
+  - HRN-003
+  - HRN-007
+tags:
+  - observability
+  - tracing
+  - spans
+  - replay
+  - cost-accounting
+---
+
+# Observability for Agentic Systems
+
+## Executive Summary
+Observability is the harness component that turns an opaque, non-deterministic agent run into an inspectable, replayable artifact. You cannot debug, evaluate, govern, or trust a multi-step stochastic system you cannot see — which is why observability is a precondition for nearly every other harness capability, not a phase-two add-on. This chapter covers traces and spans adapted for agents, token and cost accounting as first-class telemetry, evaluation hooks, and deterministic replay.
+
+## Key Concepts
+- **Trace:** The complete record of a single agent run — every step from goal to outcome.
+- **Span:** A single unit of work within a trace (a model call, a tool invocation, a retrieval, a decision) with inputs, outputs, timing, and metadata.
+- **Token/cost accounting:** Per-span and per-trace tracking of tokens in/out and resulting cost.
+- **Evaluation hook:** An instrumentation point where evaluation logic can score a span or trace, online or offline.
+- **Replay:** Re-executing a recorded trace deterministically to reproduce and debug behavior.
+- **Cardinality:** The dimensionality of telemetry tags; high cardinality aids analysis but raises storage cost.
+
+## Definition
+**Observability for agentic systems** is the harness subsystem that captures, structures, and stores a complete, queryable record of every agent run — its spans, inputs, outputs, model calls, tool calls, costs, and decisions — such that any run can be understood after the fact, compared across versions, scored by evaluation, and replayed deterministically. It answers the question "what, exactly, happened, and why?"
+
+## Architecture Diagram
+```mermaid
+flowchart TB
+  RUN[Agent Run] --> TRACE[Trace]
+  subgraph TRACE[Trace: one run]
+    direction TB
+    S1[Span: Plan]
+    S2[Span: Model Call]
+    S3[Span: Tool Call]
+    S4[Span: Retrieval]
+    S5[Span: Decision]
+  end
+  S2 --> TOK[Token / Cost Accounting]
+  TRACE --> STORE[(Trace Store)]
+  STORE --> QUERY[Query & Dashboards]
+  STORE --> REPLAY[Deterministic Replay]
+  STORE --> EVALH[Evaluation Hooks]
+  EVALH --> EVAL[Evaluation HRN-007]
+  QUERY --> ALERT[Alerting / Monitors]
+```
+
+## Detailed Explanation
+
+### Why classic observability is not enough
+Traditional APM assumes deterministic services: a request, a few synchronous calls, a response. Agentic systems break those assumptions. A single run may take a *different path each time*, fan out across many model and tool calls, loop an unknown number of times, and produce *natural-language* inputs and outputs that ordinary metrics cannot summarize. Observability for agents must therefore capture not just latency and errors but the *semantic content* of each step — the prompt sent, the completion returned, the tool arguments chosen, the reasoning. Without that content, a trace tells you *that* the agent failed but never *why*.
+
+### Traces and spans, adapted for agents
+The trace/span model from distributed tracing is the right backbone, with agent-specific span types:
+- **Model-call spans** record the assembled prompt (or a reference to it), the completion, the model and parameters, token counts, and latency.
+- **Tool-call spans** record the tool, the (validated) arguments, the result or error, and retries.
+- **Retrieval spans** record the query, the items returned, and their scores — essential for diagnosing memory misses.
+- **Decision/plan spans** record the agent's choice of next action and, where available, its rationale.
+
+Spans nest to form the full causal tree of a run. The richer the captured content, the more debuggable the system — at the cost of storage and privacy exposure, which must be managed (redaction, sampling, retention).
+
+### Token and cost accounting as first-class telemetry
+In agentic systems, *cost is a behavior*, not just a bill. A regression that causes an extra reasoning loop or a bloated context shows up first as a token spike. Observability must therefore treat token counts and derived cost as first-class metrics, attributed per span, per trace, per user, and per agent version. This makes cost regressions detectable, runaway loops alertable, and per-task economics measurable — closing the loop with the cost-metrics discipline that recurs across the handbook.
+
+### Evaluation hooks
+Observability and evaluation (HRN-007) are co-dependent. Evaluation needs the traces; observability is most valuable when its data feeds scoring. The harness should expose *evaluation hooks* — instrumentation points where a scorer (a rule, a classifier, or an LLM-as-judge) can attach to a span or trace, either *online* (scoring live traffic for monitoring) or *offline* (replaying stored traces against a new model or prompt). Designing these hooks into the trace format from day one is what makes continuous evaluation cheap later.
+
+### Deterministic replay
+The most powerful agent-specific capability is replay: re-running a recorded trace to reproduce its behavior. Because the model is non-deterministic, true replay requires capturing enough to *pin* the run — recorded model outputs (to replay without re-calling the model), tool results, retrieved context, and random seeds where applicable. Replay enables three things that are otherwise nearly impossible: reproducing a production failure locally, regression-testing a prompt or model change against real historical traffic, and A/B comparing two harness versions on identical inputs. A harness without replay debugs by guesswork.
+
+### Privacy, redaction, and retention
+Capturing full prompts and completions means capturing potentially sensitive data. Observability must integrate redaction (PII scrubbing), access controls on the trace store, and retention policies — these are governance (HRN-008) and security (HRN-011) concerns that the observability layer enforces in practice.
+
+## Production Evidence
+> **Evidence level:** theoretical · **Confidence:** medium · **Source:** industry_observation
+>
+> _Illustrative, representative scenario — not a verified single deployment._
+
+- **Context:** Teams operating multi-step agents in production who initially shipped with only basic logging.
+- **Scenario:** An intermittent failure (the agent occasionally takes a wrong action) is undiagnosable from logs; after adding full trace/span capture with replay, the failing run is reproduced locally and traced to a retrieval miss that fed the model a misleading document.
+- **Technology:** Tracing backend with agent-aware span types, trace store, replay tooling, token/cost telemetry.
+- **Load:** Production traffic with long-tail, hard-to-reproduce failures.
+- **Results:** Representative experience is that mean-time-to-diagnosis drops sharply once runs are fully traced and replayable, and that cost regressions become visible the moment they occur.
+
+## Observed Failure Modes
+- **Logs without structure:** Free-text logs that record *that* something happened but not the span tree, inputs, and outputs needed to understand it.
+- **No content capture:** Capturing latency and errors but not prompts/completions, leaving failures undiagnosable.
+- **Unbounded cardinality/storage:** Capturing everything at full fidelity for every run, exploding storage cost; needs sampling and retention policy.
+- **No replay:** Inability to reproduce non-deterministic failures, forcing debug-by-guesswork.
+- **Privacy leakage:** Capturing sensitive prompt content without redaction or access control.
+
+## KPIs
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Trace coverage | ~100% of runs traced | Every production run produces a trace |
+| Mean time to diagnosis | Minimized | Time from failure report to root cause via traces/replay |
+| Cost attribution coverage | Per span/trace/version | Enables cost-regression detection |
+| Replay fidelity | High | Share of recorded traces that replay deterministically |
+
+## Cost Metrics
+Observability adds storage cost (proportional to traces × spans × captured content) and a small runtime overhead per span. Sampling, redaction, tiered retention, and storing references to large payloads control this. The cost is repaid by faster incident resolution and by *making token/cost itself observable*, which typically surfaces inference savings that dwarf the observability spend.
+
+## Scaling Characteristics
+Trace volume scales with traffic × steps-per-run, so deep agentic workflows generate disproportionately more telemetry than shallow services. Storage and query cost are the scaling bottlenecks; head-based and tail-based sampling, aggregation, and retention tiers keep it bounded. Replay storage scales with the fidelity captured, trading storage for reproducibility.
+
+## Related Content
+- HRN-003 — The Harness Taxonomy
+- HRN-007 — Evaluation of Agentic Systems
+
+## References
+- Distributed tracing concepts (spans, traces) adapted to agentic workloads.
+- Practitioner literature on LLM observability and tracing tooling.
+- Santa María, S. — Working notes on agent observability and replay.
+
+## FAQs
+**Q:** Isn't logging enough?
+**A:** No. Unstructured logs cannot reconstruct the causal span tree of a multi-step, branching run, and they rarely capture the semantic content (prompts, completions, retrieved context) needed to explain a failure. Structured traces with replay are required.
+
+**Q:** Why track cost in the observability layer?
+**A:** Because in agentic systems cost is a *behavior*: extra loops and bloated context show up as token spikes before they show up anywhere else. Cost telemetry is how you catch those regressions.
+
+**Q:** What is the single most valuable capability?
+**A:** Deterministic replay. It turns "we can't reproduce it" into a routine local debug session and enables regression-testing changes against real historical traffic.

package/content/harness/HRN-006-observability-for-agentic-systems.pt.md

@@ -0,0 +1,97 @@
+---
+title: "Observabilidade para sistemas agênticos"
+summary: "Transformar cada passo do agente num traço reproduzível: spans, atribuição de custo, depuração de ciclos não determinísticos e os sinais que tornam a confiabilidade mensurável."
+---
+
+# Observabilidade para sistemas agênticos
+
+## Resumo executivo
+A observabilidade é o componente do harness que converte uma execução de agente opaca e não determinista num artefacto inspecionável e reproduzível. Não se pode depurar, avaliar, governar nem confiar num sistema estocástico de vários passos que não se vê, e por isso a observabilidade é uma precondição de quase todas as outras capacidades do harness, não um acrescento de segunda fase. Este capítulo cobre traços e spans adaptados a agentes, a contabilidade de tokens e custo como telemetria de primeira classe, os ganchos de avaliação e a reprodução determinista.
+
+## Conceitos-chave
+- **Traço:** o registro completo de uma única execução do agente, do princípio ao fim, do objetivo ao resultado.
+- **Span:** uma unidade de trabalho dentro de um traço (uma chamada ao modelo, uma invocação de ferramenta, uma recuperação, uma decisão) com entradas, saídas, tempos e metadados.
+- **Contabilidade de tokens e custo:** acompanhamento por span e por traço dos tokens de entrada e saída e do custo resultante.
+- **Gancho de avaliação:** um ponto de instrumentação onde a lógica de avaliação pode pontuar um span ou um traço, em linha ou fora de linha.
+- **Reprodução (replay):** voltar a executar de forma determinista um traço gravado para reproduzir e depurar o comportamento.
+- **Cardinalidade:** a dimensionalidade das etiquetas de telemetria; uma cardinalidade alta ajuda à análise mas eleva o custo de armazenamento.
+
+## Definição
+A **observabilidade para sistemas agênticos** é o subsistema do harness que captura, estrutura e armazena um registro completo e consultável de cada execução do agente — seus spans, entradas, saídas, chamadas ao modelo, chamadas a ferramentas, custos e decisões — de modo que qualquer execução possa ser compreendida a posteriori, comparada entre versões, pontuada por avaliação e reproduzida de forma determinista. Responde à pergunta “o que aconteceu exatamente, e por quê?”.
+
+## Explicação detalhada
+
+### Por que a observabilidade clássica não chega
+O APM tradicional assume serviços deterministas: um pedido, algumas chamadas síncronas, uma resposta. Os sistemas agênticos quebram essas premissas. Uma mesma execução pode seguir *um caminho diferente de cada vez*, abrir-se em leque sobre muitas chamadas a modelo e a ferramentas, iterar um número desconhecido de vezes e produzir entradas e saídas *em linguagem natural* que as métricas comuns não sabem resumir. A observabilidade para agentes tem, portanto, de capturar não só latência e erros, mas o *conteúdo semântico* de cada passo: o prompt enviado, a resposta devolvida, os argumentos escolhidos para a ferramenta, o raciocínio. Sem esse conteúdo, um traço diz *que* o agente falhou mas nunca *por quê*.
+
+### Traços e spans, adaptados a agentes
+O modelo de traço e span do tracing distribuído é a espinha dorsal certa, com tipos de span específicos de agentes:
+- Os **spans de chamada ao modelo** registam o prompt montado (ou uma referência a ele), a resposta, o modelo e seus parâmetros, as contagens de tokens e a latência.
+- Os **spans de chamada a ferramenta** registam a ferramenta, os argumentos (já validados), o resultado ou o erro, e as repetições.
+- Os **spans de recuperação** registam a consulta, os elementos devolvidos e suas pontuações: indispensável para diagnosticar falhas de memória.
+- Os **spans de decisão ou plano** registam a escolha da próxima ação pelo agente e, quando existe, sua justificação.
+
+Os spans se encaixam uns nos outros até formar a árvore causal completa de uma execução. Quanto mais rico for o conteúdo capturado, mais depurável é o sistema, à custa de armazenamento e de exposição de dados, que têm de ser geridos (redação, amostragem, retenção).
+
+### A contabilidade de tokens e custo como telemetria de primeira classe
+Nos sistemas agênticos o *custo é um comportamento*, não apenas uma fatura. Uma regressão que provoca um ciclo de raciocínio a mais ou um contexto inchado se manifesta primeiro como um pico de tokens. A observabilidade tem, por isso, de tratar as contagens de tokens e o custo derivado como métricas de primeira classe, atribuídos por span, por traço, por usuário e por versão do agente. Isso torna detectáveis as regressões de custo, alertáveis os ciclos descontrolados e mensurável a economia por tarefa, fechando o círculo com a disciplina de métricas de custo que atravessa todo o manual.
+
+### Ganchos de avaliação
+Observabilidade e avaliação (HRN-007) são codependentes. A avaliação precisa dos traços; a observabilidade rende mais quando seus dados alimentam a pontuação. O harness deve expor *ganchos de avaliação*: pontos de instrumentação onde um avaliador (uma regra, um classificador ou um LLM como juiz) se pode ligar a um span ou a um traço, seja *em linha* (pontuando tráfego vivo para monitoramento) ou *fora de linha* (reproduzindo traços armazenados contra um modelo ou um prompt novos). Desenhar esses ganchos dentro do formato de traço desde o primeiro dia é o que torna barata a avaliação contínua mais tarde.
+
+### Reprodução determinista
+A capacidade mais poderosa e específica dos agentes é a reprodução: voltar a executar um traço gravado para reproduzir seu comportamento. Como o modelo não é determinista, uma reprodução a sério exige capturar o suficiente para *fixar* a execução: saídas do modelo gravadas (para reproduzir sem voltar a chamá-lo), resultados de ferramentas, contexto recuperado e sementes aleatórias quando aplicável. A reprodução permite três coisas de outro modo quase impossíveis: reproduzir localmente uma falha de produção, submeter a teste de regressão uma alteração de prompt ou de modelo contra tráfego histórico real, e comparar em A/B duas versões do harness sobre entradas idênticas. Um harness sem reprodução depura à base de suposições.
+
+### Privacidade, redação e retenção
+Capturar prompts e respostas completos significa capturar dados potencialmente sensíveis. A observabilidade tem de integrar redação (limpeza de dados pessoais), controles de acesso sobre o armazém de traços e políticas de retenção: são preocupações de governança (HRN-008) e de segurança (HRN-011) que a camada de observabilidade aplica na prática.
+
+## Evidência de produção
+> **Nível de evidência:** teórico · **Confiança:** média · **Fonte:** observação de indústria
+>
+> _Cenário ilustrativo e representativo, não uma implantação verificada concreta._
+
+- **Contexto:** equipes que operam agentes de vários passos em produção e que entraram em produção com pouco mais do que logging básico.
+- **Cenário:** uma falha intermitente (o agente toma de vez em quando uma ação errada) é indiagnosticável a partir dos logs; depois de acrescentar captura completa de traços e spans com reprodução, a execução que falhou é reproduzida localmente e rastreada até uma falha de recuperação que tinha alimentado o modelo com um documento enganador.
+- **Tecnologia:** backend de tracing com tipos de span conscientes do agente, armazém de traços, ferramentaria de reprodução, telemetria de tokens e custo.
+- **Carga:** tráfego de produção com falhas de cauda longa, difíceis de reproduzir.
+- **Resultados:** a experiência representativa é que o tempo médio até ao diagnóstico cai drasticamente assim que as execuções estão completamente traçadas e são reproduzíveis, e que as regressões de custo se tornam visíveis no momento exato em que ocorrem.
+
+## Modos de falha observados
+- **Logs sem estrutura:** texto livre que regista *que* algo aconteceu mas não a árvore de spans, as entradas e as saídas necessárias para o compreender.
+- **Sem captura de conteúdo:** capturar latência e erros mas não prompts nem respostas, deixando as falhas indiagnosticáveis.
+- **Cardinalidade e armazenamento sem limite:** capturar tudo com fidelidade máxima em cada execução, disparando o custo de armazenamento; são precisos amostragem e política de retenção.
+- **Sem reprodução:** incapacidade de reproduzir falhas não deterministas, o que obriga a depurar por suposições.
+- **Fuga de privacidade:** capturar conteúdo sensível de prompts sem redação nem controle de acesso.
+
+## KPIs
+| Métrica | Objetivo | Notas |
+|---------|----------|-------|
+| Cobertura de tracing | ~100 % das execuções | Cada execução de produção produz um traço |
+| Tempo médio até ao diagnóstico | Minimizado | Do aviso de falha à causa raiz via traços e reprodução |
+| Cobertura de atribuição de custo | Por span / traço / versão | Permite detectar regressões de custo |
+| Fidelidade de reprodução | Alta | Proporção de traços gravados que se reproduzem de forma determinista |
+
+## Métricas de custo
+A observabilidade acrescenta custo de armazenamento (proporcional a traços × spans × conteúdo capturado) e uma pequena sobrecarga de execução por span. A amostragem, a redação, a retenção por níveis e o guardar referências em vez de cargas grandes mantêm isso sob controle. O custo é devolvido com juros pela resolução mais rápida de incidentes e por *tornar observável o próprio token e seu custo*, o que costuma trazer à luz economias de inferência que empequenecem a despesa em observabilidade.
+
+## Características de escalabilidade
+O volume de traços escala com tráfego × passos por execução, portanto os fluxos agênticos profundos geram desproporcionadamente mais telemetria do que os serviços planos. O armazenamento e o custo de consulta são os gargalos; a amostragem por cabeçalho e por cauda, a agregação e os níveis de retenção mantêm-no limitado. O armazenamento para reprodução escala com a fidelidade capturada, trocando armazenamento por reprodutibilidade.
+
+## Conteúdo relacionado
+- HRN-003 — A taxonomia do harness
+- HRN-007 — Avaliação de sistemas agênticos
+
+## Referências
+- Conceitos de tracing distribuído (spans, traços) adaptados a cargas agênticas.
+- Literatura de prática sobre observabilidade e ferramentaria de tracing para LLM.
+- Santa María, S. — Notas de trabalho sobre observabilidade e reprodução de agentes.
+
+## Perguntas frequentes
+**P:** Não bastam os logs?
+**R:** Não. Os logs sem estrutura não permitem reconstruir a árvore causal de spans de uma execução ramificada de vários passos, e raramente capturam o conteúdo semântico (prompts, respostas, contexto recuperado) necessário para explicar uma falha. São precisos traços estruturados com reprodução.
+
+**P:** Por que medir o custo na camada de observabilidade?
+**R:** Porque nos sistemas agênticos o custo é um *comportamento*: os ciclos a mais e o contexto inchado aparecem como picos de tokens antes de aparecerem em qualquer outro lugar. A telemetria de custo é como se caçam essas regressões.
+
+**P:** Qual é a capacidade mais valiosa de todas?
+**R:** A reprodução determinista. Converte “não conseguimos reproduzi-lo” numa sessão de depuração local rotineira e permite submeter as alterações a teste de regressão contra tráfego histórico real.