Skip to content
Kevin Davila mascotkevindavila.dev> SOFTWARE ENGINEERES
AI•3 min read

Observability and traces: "the model failed" is rarely the model

Cuando un agente falla, el reflejo es culpar al modelo. Casi siempre el culpable es el harness: contexto que se recortó mal, una tool que devolvió un error silencioso, un timeout, un prompt que se armó distinto. Y no puedes ver nada de eso si no guardas trazas.

Qué es una traza

Una traza es el registro de cada paso del agente, no solo el resultado final. Por paso:

  • El prompt que vio el modelo (contexto incluido).
  • La tool que pidió y con qué parámetros.
  • El resultado que recibió (o el error).
  • Los tokens, el costo y la latencia.

Con eso dejas de tener una opinión ("creo que el modelo es malo") y tienes un diagnóstico.

Las 5 preguntas que responde una traza

  1. ¿Qué contexto vio realmente el modelo? (no el que crees que le mandaste)
  2. ¿Qué tool llamó y con qué argumentos? (los errores de parámetros desaparecen del radar sin esto)
  3. ¿La tool falló? (muchos "fallos del modelo" son tools devolviendo basura)
  4. ¿Cuánto costó? (un bucle infinito se ve en el costo por paso)
  5. ¿Dónde se fue el tiempo? (modelo, tool o red)

Por qué la culpa no es del modelo

Tres causas que se ven en las trazas y se confunden con "el modelo es tonto":

  • Contexto recortado o mal resumido: el agente olvida el paso 3 porque la compaction tiró lo importante. No es el modelo: es lo que le diste.
  • Tool con error silencioso: la tool devolvió null o un mensaje de error como si fuera datos válidos. El modelo razonó bien sobre basura.
  • Cuello de botella fuera del modelo: vLLM documenta que, con Llama-8B en una H100, la ejecución en GPU puede ser de ~5 ms y el resto del tiempo se va en CPU (tokenizar, preparar, hacer streaming). La lentitud que culpabas al modelo era tu loop. - Source: vLLM V1 - vLLM Team

Esta es la pieza 8 (observabilidad) de las 9 del harness, y es la que te deja depurar en vez de adivinar. → Harness Engineering: las 9 piezas

Qué ya traen los frameworks

Si usas un framework con esto integrado, actívalo el día uno. Si construyes a mano, el mínimo viable es un archivo JSON por ejecución con los 5 campos de arriba.

El mínimo viable (siempre)

{
  "run_id": "t-1042",
  "step": 3,
  "tool": "search_docs",
  "tool_args": { "q": "límite de reintentos" },
  "tool_result_chars": 8120,
  "error": null,
  "tokens_in": 4210,
  "tokens_out": 180,
  "cost_usd": 0.0043,
  "latency_ms": 940
}

Con eso ya puedes responder "¿por qué falló?" sin adivinar. Y con la traza se alimentan las evals: cada fallo real se convierte en un caso de prueba.

5 pasos

  1. Registra un archivo por ejecución con los 5 campos (prompt, tool, resultado, tokens/costo, latencia).
  2. Guarda el prompt completo que vio el modelo (es el dato que más se omite y más se necesita).
  3. Marca los errores explícitamente, incluidas las tools que devuelven vacío.
  4. Mira una traza completa a mano después de cada cambio grande; te vas a sorprender.
  5. Convierte cada fallo en una eval para que no vuelva.

El resto del harness está en la guía Agentes: de cero a producción.

¿Qué fue lo último que culpaste al modelo y no era el modelo? Cuéntame en los comentarios: apuesto a que fue contexto o una tool.

Referencias

> More posts