CH 29 · Observabilidad y gestión de contexto
Objetivo del capítulo
Cuando el Agent esté en marcha, tarde o temprano te encontrarás con estas preguntas: ¿por qué acaba de tomar esa decisión? ¿Cuántos tokens costó esta ronda? Las sesiones largas se vuelven más lentas y caras, ¿qué hacer?
El enfoque de dsh es mostrarte cada paso del Agent — qué vio, qué pensó, qué hizo, cuánto costó, todo trazable. CH 04 cubrió los básicos de la interfaz de Trajectory, CH 16 mencionó la tasa de acierto de caché; este capítulo aclara por completo la observabilidad y el rendimiento: cómo leer la Trajectory, dónde se almacenan los logs de sesión, cómo leer las métricas de tokens y caché, cómo gestionar el contexto. Una vez domines esto, podrás avanzar de "usable" a "usarlo de forma eficiente y estable".
Trajectory: la cuenta completa del Agent en ejecución
Qué es la Trajectory
Las herramientas de Agent ordinarias te muestran el "historial de chat" — lo que dijiste, lo que respondió. Pero, ¿qué pasó entre medias? Qué archivo leyó, qué herramienta llamó, qué devolvió la herramienta, por qué decidió llamar a esta herramienta y no a aquella — todo esto es invisible en la vista del chat.
La Trajectory resuelve este problema: registra el proceso de ejecución completo del Agent en una línea de tiempo, es "la cuenta del modelo en ejecución", no "la vista del usuario del historial de chat".
Qué se registra:
| Categoría | Qué registra |
|---|---|
| System prompt | El system prompt completo enviado al modelo en cada petición |
| Entrada del usuario | Tu mensaje, contexto inyectado |
| Petición al modelo | Contenido completo enviado al modelo, contenido completo devuelto por el modelo |
| Llamada a herramienta | Qué herramienta, qué parámetros, qué resultado devolvió |
| Programación de subagents | Cuántos subagents se iniciaron, qué hizo cada uno, cómo se agregaron los resultados |
| Interacción de aprobación | Qué operaciones pidieron aprobación, si permitiste o denegaste |
Todo esto se escribe en un único log de sesión append-only — solo se añade, nunca se modifica, garantizando integridad del registro y auditabilidad.
Dónde ver la Trajectory
En la interfaz de sesión de la Web UI, hay una pestaña Trajectory arriba, haz clic para entrar.
La interfaz se parece al panel de red de las dev tools del navegador:
- Línea de tiempo arriba: dibujada de izquierda a derecha por tiempos reales de inicio y fin, cada ronda de peticiones ocupa un segmento
- Lista de eventos a la izquierda: una fila por registro, agrupada por turn, cada una marcada con tipo (LLM / TOOL / SUBAGENT / APPROVAL)
- Panel de detalle a la derecha: haz clic en un registro para expandir y ver el contenido completo — Schema / Payload / Result de la llamada a herramienta, el prompt y la respuesta completos de la petición al modelo
Para qué sirve la Trajectory
- Solución de problemas: ¿el Agent hizo algo inesperado? Vuelve atrás en la Trajectory y mira qué recibió en ese momento, por qué tomó esa decisión. El 90% de los casos de "la IA se porta raro" se pueden encontrar en la Trajectory — normalmente leyó un archivo que no notaste, o la herramienta devolvió un valor anómalo.
- Revisión: la tarea fue bien o mal, vuelve atrás en la Trajectory y mira qué paso fue el punto de inflexión clave, qué paso desperdició tokens. La próxima vez puedes optimizar el prompt o el flujo.
- Reproducir experimentos: al hacer investigación con Agent, la Trajectory es el registro completo del experimento — misma entrada, misma herramienta, misma versión del modelo, puede reproducir el mismo resultado.
- Auditoría: cuando lo comparte el equipo, la Trajectory puede responder "¿cuándo cambió este archivo, por qué" — más granular que git log, porque incluso registra "por qué lo cambió".
Log de sesión: dónde vive, cómo usarlo
Los datos de la Trajectory finalmente aterrizan en archivos locales, no solo en memoria.
Ubicación de almacenamiento
Todas las sesiones se almacenan en el directorio ~/.dsh/sessions/ (en Windows: C:\Users\<tu-usuario>\.dsh\sessions\), organizadas por directorio de workspace.
El nombre del directorio del workspace es la forma escapada de la ruta — envuelta con --, separadores de ruta reemplazados con -, caracteres especiales URL-encoded. Por ejemplo, el workspace E:\software-workspace\DeepSeek harness demo corresponde al nombre de directorio --E-software-workspace-DeepSeek~0020harness~0020demo--.
Cada sesión es un subdirectorio, nombrado con el formato session-<uuid> (creado por la Web UI) o puro <uuid> (ejecutado por headless), conteniendo un archivo session.jsonl.zstd (JSONL comprimido con zstd, un evento por línea).
~/.dsh/sessions/
├── --E-software-workspace-DeepSeek~0020harness~0020demo--/
│ ├── session-05da13b1-c7bf-4f42-843b-.../
│ │ └── session.jsonl.zstd
│ ├── session-06451c43-35fb-4338-bc87-.../
│ │ └── session.jsonl.zstd
│ └── 37e884fa-7c73-40fa-81fc-.../ ← sesión ejecutada por headless
│ └── session.jsonl.zstd
└── --E-software-workspace-doubaowork-DeepSeekHarnessGuide--/
└── session-f417b4dd-3c8f-4098-85.../
└── session.jsonl.zstdTres capacidades de una sesión
Basándose en este log, dsh admite tres operaciones:
- Reanudar: cierra dsh y vuelve a abrirlo, la sesión anterior sigue ahí, puedes continuar el chat — porque el log es persistente, no en memoria.
- Fork: haz clic en el icono de fork bajo un mensaje histórico, inicia un nuevo camino desde ese mensaje, sin tocar la sesión original. Por ejemplo, si el Agent llegó al paso 5 y crees que la dirección es incorrecta, puedes hacer fork al paso 4 y probar un prompt diferente, la sesión original se preserva. La nueva sesión del fork tendrá un sufijo
(1),(2)en su nombre, distinguiéndola de la original. - Replay: reproduce el flujo de eventos de una sesión, ve la entrada y salida de cada paso. Adecuado para depurar plugins o reproducir problemas.
Métricas de rendimiento: tokens, caché, contexto
dsh muestra varias métricas clave de rendimiento en tiempo real en la interfaz; aprende a leer estas y podrás controlar coste y velocidad.
Uso de tokens
Tras cada ronda de peticiones, en la parte inferior de la interfaz se muestran las estadísticas de tokens de esa ronda:
- Input Token: total de tokens enviados al modelo (incluyendo system prompt, historial de conversación, resultados de herramientas)
- Output Token: tokens generados por el modelo
- Cache hit Token: porción de input que acertó la caché de contexto de DeepSeek
El uso acumulado está en las estadísticas de la sesión — cuántos tokens usó toda la sesión, cuánto costó.
Tasa de ocupación del contexto
Hay un anillo a la derecha de la caja de entrada, mostrando el porcentaje actual de ocupación del contexto. Este es un diseño único de dsh — te permite ver en tiempo real "cuánto espacio de contexto queda".
El contexto es finito (diferentes tamaños de ventana del modelo, generalmente desde 128K). Cuando la ocupación se acerca al 100%, dsh auto-comprime el contexto — resume el historial antiguo en un digest, reemplazando la conversación multi-turno original, asegurando que la conversación pueda continuar sin fallar por exceder la ventana.
La auto-compresión es un mecanismo de respaldo. Así que un enfoque más recomendado es: en el momento adecuado, dispara manualmente la compresión tú mismo — escribe el comando /compact en la caja de entrada, y dsh comprimirá inmediatamente la conversación actual en un resumen, reemplazando el historial multi-turno original. Comprimiendo a tu propio ritmo, no se perderá información clave.
Cuando la ocupación esté casi llena, dos opciones: escribe /compact para comprimir manualmente, o simplemente abre una nueva sesión.
Gestión de contexto: cómo evitar que las sesiones largas se rompan
Las sesiones del Agent tienen un problema natural: cuanto más chateas, más tokens gastas, y el modelo "recuerda" menos del principio. dsh ofrece varias herramientas para gestionar esto.
Cuándo abrir una nueva sesión
No todas las tareas deben hacerse en una sola sesión. Las siguientes situaciones sugieren abrir una nueva sesión:
- Cambió el tipo de tarea: hace un momento escribías código, ahora necesitas hacer un PPT — abre una nueva sesión, no dejes que el contexto del código contamine la tarea del PPT
- Cambió el workspace: cambiaste de directorio de proyecto — abre una nueva sesión, las sesiones de dsh están vinculadas al workspace
- Ocupación de contexto por encima del 70%: seguir chateando hará que el modelo suelte contenido antiguo, y las reacciones se ralentizarán — a veces de repente sientes que el modelo se volvió más tonto, por eso. Abre una nueva sesión, o primero
/compactpara comprimir
Algunos hábitos de control de coste
- No hagas todo en una sola sesión — divide las sesiones por tarea, cada sesión tiene poco contexto, alta tasa de acierto de caché, bajo coste
- No leas repetidamente archivos grandes — el Agent leer un archivo de 1000 líneas cuesta tokens cada vez. Tras leerlo una vez, haz que escriba la información clave en un archivo de resumen, luego simplemente lee el resumen más tarde
- Usa el modelo adecuado — tareas simples con flash, razonamiento complejo con pro, tareas visuales con vision — no uses el más caro para todo
- Revisa el uso acumulado regularmente — las estadísticas de la sesión muestran el total de tokens y el coste estimado, no esperes a final de mes para llevarte una sorpresa
Lo que aprendiste en este capítulo
Apruebas si puedes completar los puntos siguientes:
- [ ] Sabes qué es la Trajectory, dónde verla, qué contenido se registra en la Trajectory
- [ ] Sabes que los logs de sesión se almacenan en
~/.dsh/sessions/, admitiendo reanudar, fork, replay - [ ] Puedes entender qué son input / output / cache hit en las estadísticas de tokens
- [ ] Sabes dónde se muestra la tasa de ocupación del contexto, qué hacer cuando esté casi llena
- [ ] Sabes cómo usar el comando
/compact, y cuándo comprimir manualmente - [ ] Puedes enunciar al menos 3 hábitos de control de coste