Lección 11 — Hacé observable el runtime del agente
Lección 11 — Hacé observable el runtime del agente
Le pedís a un agente que implemente una función. Corre 20 minutos, modifica muchos archivos y después dice: “terminado, pero fallan dos tests”. Preguntás por qué fallan: “no estoy seguro, quizá sea un problema de timing”. Preguntás qué rutas críticas cambió: “dejame mirar el código…”.
No es que al agente le falte capacidad. Tu harness no le da suficiente observabilidad. Sin observabilidad, los agentes toman decisiones bajo incertidumbre, las evaluaciones se vuelven juicios subjetivos y los reintentos son tanteos a ciegas. Tanto OpenAI como Anthropic tratan la fiabilidad como un problema de evidencia: el harness debe exponer el comportamiento en runtime y las señales de evaluación de una forma que guíe la decisión siguiente.
Conceptos clave
- Observabilidad de runtime: señales de sistema como logs, trazas, eventos de proceso y health checks. Responde “qué hizo el sistema”.
- Observabilidad de proceso: visibilidad sobre artefactos de decisión del harness —planes, rúbricas de puntuación y criterios de aceptación—. Responde “por qué debería aceptarse este cambio”.
- Traza de tarea: registro completo del camino de decisión desde el inicio hasta la finalización, análogo al tracing de requests en sistemas distribuidos.
- Sprint contract: acuerdo de corto plazo negociado antes de programar, que especifica alcance, estándares de verificación y exclusiones. Es la herramienta central de la observabilidad de proceso.
- Rúbrica de evaluación: transforma la evaluación de calidad de juicio subjetivo a puntuación estructurada basada en evidencia.
- Observabilidad por capas: sistema y proceso diseñados juntos y reforzándose. Las señales de runtime explican el comportamiento; los artefactos de proceso explican la intención.
Observabilidad por capas
flowchart TB
subgraph P["Capa de proceso — «por qué»"]
SC["Sprint contract<br/>alcance, estándares, exclusiones"]
RU["Rúbrica de evaluación<br/>dimensiones y niveles A-D"]
AC["Criterios de aceptación<br/>por función"]
end
subgraph S["Capa de sistema — «qué»"]
LG["Logs estructurados"]
TR["Trazas de tarea<br/>spans por paso"]
EV["Eventos de proceso<br/>startup, ready, shutdown"]
HC["Health checks"]
end
P --> D["Decisión de aceptar<br/>o reintentar"]
S --> D
D --> N["Siguiente acción<br/>informada, no a ciegas"]El costo real de no tener observabilidad
Cuando un harness no tiene observabilidad aparecen sistemáticamente cuatro problemas:
No se distingue “correcto” de “parece correcto”. Una función puede verse perfecta en code review —sintaxis correcta, lógica razonable—. Pero en runtime, un error en un caso borde produce resultados incorrectos con ciertas entradas. Solo las trazas muestran que la ruta real de ejecución se desvió de lo esperado.
La evaluación se vuelve mística. Sin rúbricas y criterios de aceptación, los evaluadores —humanos o agentes— dependen de supuestos implícitos. La misma salida puede recibir evaluaciones muy distintas. La calidad deja de ser reproducible.
Los reintentos se vuelven conjeturas ciegas. Cuando el agente no sabe por qué falló algo, la dirección del reintento es aleatoria. Cada reintento ciego cuesta tokens y tiempo.
Acantilado de información en el handoff. Cuando se entrega trabajo incompleto a la sesión siguiente, la falta de observabilidad obliga a diagnosticar el estado del sistema desde cero. Las observaciones de Anthropic muestran que ese diagnóstico redundante puede consumir 30-50% del tiempo total de sesión.
Un escenario realista
Imaginá un harness con workflow de tres roles —planner, generator, evaluator— ejecutando “agregá modo oscuro a la app”.
| Sin observabilidad | Con observabilidad completa | |
|---|---|---|
| Plan | Descripción vaga | Sprint contract con componentes, estándares y exclusiones |
| Implementación | Basada en la vaguedad | Basada en el contrato |
| Evidencia de runtime | Ninguna | Trazas de carga y aplicación de estilos por componente |
| Evaluación | ”No se siente bien” | Rúbrica con evidencias concretas por dimensión |
| Iteraciones | 3-4 rondas ciegas | 1 |
| Tiempo | ~45 min | ~15 min |
La diferencia de eficiencia es 3x. Lo único que cambió fue la observabilidad.
Por qué los agentes no pueden resolverlo solos
Podrías pensar: “¿no puede el agente imprimir sus propios logs?”. Tres problemas:
- El agente no sabe lo que no sabe; no va a registrar señales que no sabe que necesita.
- Los formatos de log son inconsistentes; distintas sesiones usan distintos formatos, lo que impide análisis sistemático.
- La observabilidad de proceso no se resuelve con logs: sprint contracts y rúbricas son artefactos estructurados que necesitan soporte a nivel de harness.
Cómo hacerlo bien
1. Integrá la recolección de señales de runtime en el harness
No dependas de que el agente imprima sus propios logs. El harness debería recoger automáticamente:
- Ciclo de vida de la aplicación: estados de startup, ready, running y shutdown
- Ejecución de rutas de función: registros de rutas críticas con puntos de entrada, checkpoints y salidas
- Flujo de datos: registros de datos que pasan entre componentes
- Uso de recursos: patrones anómalos, por ejemplo memoria que crece sin parar
- Errores y excepciones: contexto completo, no solo el mensaje
2. Implementá sprint contracts
Antes de iniciar cada tarea, el generator y el evaluator —que pueden ser invocaciones distintas del mismo agente— negocian un contrato:
# Sprint Contract: soporte de modo oscuro
## Alcance
- Modificar el componente de toggle de tema
- Actualizar las variables CSS globales
- Agregar tests de modo oscuro
## Estándares de verificación
- Los tests de regresión visual pasan para cada componente
- Los tests end-to-end del flujo principal pasan
- Sin flash de contenido sin estilo (FOUC)
## Exclusiones
- No se manejan estilos de impresión
- No se maneja el modo oscuro de componentes de terceros3. Establecé una rúbrica de evaluación
Convertí “¿está bien o no?” en puntuación cuantificable:
| Dimensión | A | B | C | D |
|---|---|---|---|---|
| Corrección del código | Todos los tests pasan | Pasa el flujo principal | Pasa parcialmente | Falla el build |
| Cumplimiento arquitectónico | Totalmente conforme | Desviaciones menores | Desviaciones obvias | Violaciones serias |
| Cobertura de tests | Principal + casos borde | Solo flujo principal | Solo esqueleto | Sin tests |
4. Estandarizá con OpenTelemetry
Creá una traza por sesión de harness, un span por tarea y sub-spans por cada paso de verificación. Usá atributos estándar para anotar información clave. Así los datos de observabilidad se integran con herramientas como Jaeger o Zipkin.
flowchart LR
T["trace: sesión de harness"] --> S1["span: tarea F03"]
S1 --> SS1["span: implementación"]
S1 --> SS2["span: verificación nivel 1"]
S1 --> SS3["span: verificación nivel 2"]
S1 --> SS4["span: verificación E2E"]
SS4 --> A["atributos:<br/>resultado, duración,<br/>evidencia, commit"]Ideas clave
- La observabilidad es una propiedad arquitectónica del harness, no una función que se agrega al final.
- Ambas capas son esenciales: las señales de runtime explican qué pasó; los artefactos de proceso explican por qué se hizo así.
- Los sprint contracts alinean por adelantado, evitando que el generator construya algo que el evaluator va a rechazar por razones previsibles.
- Las rúbricas hacen reproducible la evaluación.
- La falta de observabilidad desperdicia 30-50% del tiempo de sesión en diagnóstico redundante.
Ejercicios
- Análisis de brecha de observabilidad: auditá tu harness actual en la capa de sistema y de proceso. Encontrá estados que no se distinguen con las señales existentes y proponé señales nuevas.
- Práctica de sprint contract: escribí un sprint contract para una tarea real. Hacé que el agente lo ejecute y compará eficiencia y calidad con y sin contrato.
- Construcción de traza de tarea: registrá cada paso de un agente durante una tarea completa. Anotá con convenciones semánticas de OpenTelemetry y analizá dónde falta señal suficiente para decidir.
Lecturas adicionales
- Observability Engineering — Charity Majors
- Dapper — Google (Sigelman et al.)
- Anthropic: Harness design for long-running application development
- Site Reliability Engineering — Google
Anterior: Lección 10 — Solo las pruebas end-to-end son verificación real · Siguiente: Lección 12 — Dejá un handoff limpio al final de cada sesión