Skip to main content

Debuggear agentes: trazar una corrida cuando sale mal

Un agente falló en producción y tenés que arreglarlo. El movimiento que lo hace posible es el que casi todos se saltean: trazá primero, teorizá después — no podés arreglar lo que no podés reproducir. El playbook por síntoma para cinco formas en que un agente sale mal — loops descontrolados, tool calls equivocadas, respuestas equivocadas con seguridad, degradación silenciosa, lento y caro — cada una con qué leer en la traza, el arreglo, y el caso de eval que evita que vuelva.

Cómo hacerlo·Actualizado 2026-06-01·Escrito por Lira · Editado por German Medina

Un agente falló en producción y alguien está esperando el arreglo. El instinto es abrir el prompt y empezar a adivinar — y es el instinto equivocado, porque el camino de un agente es no-determinístico y estás por debuggear una corrida que no podés ver. El movimiento que cambia todo es el que casi todos se saltean bajo presión: no podés arreglar lo que no podés reproducir. Trazá primero, teorizá después. Con la traza completa de la corrida fallida adelante — los inputs, el contexto recuperado, cada tool call y su resultado, la salida final — el bug casi siempre se nombra solo. Sin ella, estás tuneando un prompt contra una historia que te inventaste sobre lo que pasó (principio 11).

Esta página asume que trazaste todo antes de salir a producción — si no lo hiciste, el primer arreglo es agregar tracing y reproducir, porque nada de lo de abajo funciona sobre una corrida que no podés reproducir. Es por síntoma: encontrá la falla que coincide con lo que estás viendo, leé la traza en la capa que la sección señala, aplicá el arreglo, y — el paso que separa debuggear de jugar al topo — convertí la corrida fallida en un caso de eval para que la regresión no pueda volver. Nada de esto depende del toolkit: un agente sobre Agentforce, uno sobre LangGraph y la Claude API, o uno conectado sobre MCP falla en las mismas cinco formas, y la traza es donde las cazás a todas.

El loop: trazar → reproducir → arreglar con evals

Cada sesión de debug de abajo corre los mismos tres pasos, en este orden:

  1. Trazar. Traé el registro completo de la corrida fallida — inputs, contexto recuperado, las tool calls con sus argumentos y resultados, el razonamiento del modelo donde lo capturás, la salida final. Si no podés, tenés un hueco de tracing que arreglar antes que nada; un agente lanzado sin traza es uno que debuggeás por superstición.
  2. Reproducir. Reproducí la corrida desde la traza hasta que puedas hacer que la falla pase cuando quieras. Un bug que no podés reproducir es un bug que no podés confirmar que arreglaste — y el no-determinismo de un agente hace que "funcionó cuando lo probé" no pruebe nada.
  3. Arreglar con evals. Agregá el caso fallido al set de eval antes de cambiar nada, miralo fallar, aplicá el arreglo, miralo pasar, y corré el set entero para confirmar que no rompiste un vecino. El caso de eval es lo que hace permanente el arreglo — sin él, la misma falla vuelve a entrar en la próxima edición del prompt o actualización del modelo y nadie lo nota (principio 3).

Entra en loop o se descontrola

Cómo reconocerlo. Una corrida que nunca termina, un pico de latencia, o un solo pedido que cuesta mucho más que el resto. El agente planifica, actúa, observa y replanifica — para siempre.

Qué leer en la traza. Recorré los pasos y encontrá dónde replanifica. Estás buscando una de dos formas: el agente repite la misma tool call con los mismos argumentos y obtiene el mismo resultado que no puede usar, u oscila entre dos planes sin converger. En cualquier caso, la traza muestra que el modelo nunca llega a un estado que lea como "listo" — la condición de parada que necesitaba nunca fue expresable desde lo que estaba viendo.

El arreglo. Dos partes. Primero, un tope duro de pasos, un presupuesto de tokens y un timeout aplicados en código, no pedidos en el prompt — a un agente al que le pedís amablemente que "sea eficiente" igual se le va la mano; un agente que llega a su techo frena (gotcha 3). El tope es el cinturón de seguridad: acota el costo de la falla mientras arreglás la causa. Segundo, la causa — casi siempre una condición de parada faltante o inalcanzable. El agente entra en loop porque nada de lo que puede observar le dice que la tarea está completa, así que dale una definición de "listo" explícita y chequeable, o una tool cuyo resultado pueda leer como terminal.

Cómo hacerlo sostener. Agregá el input que entra en loop al set de eval y afirmá dos cosas: la corrida termina dentro del tope de pasos, y termina porque terminó, no porque chocó contra el muro. Una corrida que solo frena en el techo sigue rota — el tope la atajó, la causa sigue ahí.

Llama una tool equivocada o inventada

Cómo reconocerlo. Una acción tomada sobre basura — un registro actualizado con un valor que el modelo inventó, una query corrida contra un campo que no existe, la tool equivocada disparada para la situación. O una llamada que falla al ejecutar porque un argumento está malformado.

Qué leer en la traza. Encontrá la tool call y leela literal: el nombre de la tool, cada argumento, y el valor de cada uno. Compará contra el schema de la tool. El modelo inventa un parámetro que no está, llena uno real con un valor plausible-pero-equivocado, o elige una tool cuya descripción leyó mal. La traza te muestra exactamente cuál — y muestra si algo validó la llamada antes de ejecutar.

El arreglo. Dos capas, las dos cubiertas en Tools y acciones. Primero, validá cada tool call contra un schema estricto antes de ejecutar, y decidí deliberadamente qué pasa cuando la validación falla — reintenta, pregunta o frena — para que un argumento alucinado nunca llegue a la acción real (gotcha 4). Segundo, si el modelo eligió la tool equivocada o la llenó mal, el arreglo suele ser las palabras que escribiste: el modelo razona sobre el nombre y la descripción de la tool, nada más, así que una descripción vaga — "actualiza la cuenta" — invita al mal uso. Apretala para que diga qué hace la tool, cuándo usarla, cuándo no, y qué significa cada argumento. Un enum sobre un campo al que el modelo le inventaba valores termina con esa clase de bug de raíz.

Cómo hacerlo sostener. Agregá el input que produjo la llamada equivocada al set de eval y afirmá que el agente ahora llama la tool correcta con argumentos válidos — o que correctamente se abstiene. Si apretaste una descripción, el eval es lo que prueba que el nuevo texto arregló el caso real y no rompió en silencio uno adyacente.

Está equivocado con seguridad

Cómo reconocerlo. El agente afirma algo falso, con fluidez, y actúa como si estuviera seguro. Es la falla más peligrosa porque se ve exactamente igual que una respuesta correcta — la única pista es que el contenido está mal, y alguien puede actuar sobre él antes de que nadie lo note.

Qué leer en la traza. Sospechá del retrieval antes que del modelo. Encontrá qué se le dio de verdad para leer al agente en esta corrida — los chunks recuperados, los registros groundeados, los resultados de tools sobre los que razonó — y fijate si la respuesta correcta siquiera estaba ahí. Un modelo al que le pasaron los tres chunks equivocados va a defender la respuesta equivocada de manera impecable; la falla está aguas arriba del razonamiento, en lo que devolvió el grounding (gotcha 8, principio 2). Leé el contexto recuperado antes de leer el prompt.

El arreglo. Si el retrieval volvió vacío o equivocado, arreglá el retrieval, no el prompt — la query, el índice, la fuente de grounding, el modelo de datos debajo. Un prompt ingenioso sin grounding es una suposición con seguridad; tunear el prompt para que suene menos equivocado deja al agente igual de equivocado. Y hacé de "no tengo eso" un camino que el agente tiene permitido tomar: un agente que no puede decir "no sé" va a inventar, cada vez que el retrieval le falle. Si un analista humano no pudiera contestar la pregunta desde el mismo contexto recuperado, el bug es el grounding, no el agente — el agente heredó el hueco.

Cómo hacerlo sostener. Agregá el caso al set de eval con el resultado conocido, y puntuá la respuesta contra los hechos — no contra qué tan segura suena. Incluí al menos un caso donde el comportamiento correcto sea "no sé", para que una regresión que traiga de vuelta la alucinación con seguridad falle a los gritos.

Se degrada en silencio

Cómo reconocerlo. Mismo código, peor salida — a lo largo de días o semanas, sin nada en los logs que apunte a algo. La calidad se cae y no salta ningún error. Las causas habituales son una actualización del modelo debajo tuyo, drift en los datos sobre los que el agente groundea, o un cambio lento en los inputs que los usuarios mandan de verdad.

Qué leer en la traza. Esta es la falla para la que existe el tracing, porque no hay error que la cace (principio 11). Compará una corrida fallida reciente contra una vieja que pasaba sobre un input parecido: ¿mismo contexto recuperado? ¿mismos resultados de tools? ¿misma versión del modelo? El diff entre una corrida que funcionó y una que no, las dos capturadas enteras, es lo que localiza una degradación que ninguna excepción anunció.

El arreglo. Los evals de regresión son el arreglo de verdad, y corren antes de que un usuario encuentre el problema. Un set de eval fijo puntuado en un schedule — y en cada cambio de modelo o de prompt — convierte una degradación silenciosa en un test que falla el día que arranca (gotcha 2, principio 3). Cuando el set se cae, el diff de la traza te dice qué capa se movió: una actualización del modelo significa revalidar contra la suite y pinear o migrar deliberadamente; data drift significa que la fuente de grounding cambió y el retrieval necesita atención; input drift significa que el uso real se corrió más allá de lo que tu set de eval cubre, así que el set necesita casos nuevos.

Cómo hacerlo sostener. El set de eval es el mecanismo acá — el arreglo y la guarda de regresión son el mismo artefacto. Cada degradación silenciosa que encontrás se vuelve un caso en el set, así que la próxima instancia la caza un test en rojo en vez de un usuario. Un agente sobre un modelo en movimiento sin evals de regresión se degrada a oscuras; eso es lo default, no la excepción.

Es lento o caro

Cómo reconocerlo. El agente produce la respuesta correcta demasiado lento para ser usable, o a un costo por corrida que no sobrevive el tamaño real de audiencia. El costo y la latencia son features, no algo para después (principio 6) — una respuesta correcta pero impagable no resolvió el problema.

Qué leer en la traza. Perfilá la corrida paso a paso: tokens de entrada y salida por paso, latencia por paso, cantidad de llamadas al modelo. La traza te muestra dónde va el presupuesto de verdad — y rara vez es donde adivinarías. Los culpables habituales: una ventana de contexto que creció sin límite a medida que la corrida acumulaba la salida de cada paso, un paso llamando a un modelo grande donde uno chico alcanzaría, o una orquestación con más hops de modelo que los que la tarea necesita.

El arreglo. Hacé coincidir el arreglo con el paso que la traza señaló. Si el costo es el contexto, curá la ventana — el contexto es un presupuesto, no un balde; resumí, descartá o recuperá bajo demanda en vez de apilar todo "por las dudas" (principio 10), lo que además afila el razonamiento, ya que un contexto sobrecargado también degrada la calidad. Si un paso que no necesita un modelo de frontera está usando uno, ruteá a un tier más chico — un modelo chico para la llamada de rutina, uno grande solo donde se lo gana (principio 6). Si una respuesta determinística se recalcula en cada corrida, cacheala. Si la orquestación tiene hops que la tarea no necesita, colapsalos — el sistema de agentes más fuerte que podría funcionar suele ser el más chico.

Cómo hacerlo sostener. Agregá una afirmación de costo y latencia al set de eval: la corrida se mantiene bajo un presupuesto de tokens y un techo de latencia sobre inputs representativos. Las regresiones de costo son tan reales como las de correctitud y tan silenciosas como ellas — sin la afirmación, un cambio futuro que duplica el conteo de tokens sale sin que nadie lo note hasta que la factura lo cuenta.

El hilo

Cinco fallas, un método debajo: trazá la corrida, reproducila, arreglá la capa que la traza realmente señala, y trabá el arreglo detrás de un caso de eval para que no pueda volver en silencio. El no-determinismo del agente es justo por lo que adivinar falla y trazar gana — no podés razonar sobre una corrida que no capturaste, y no podés probar un arreglo sobre un sistema cuya salida cambia entre intentos. Cada arreglo de arriba es un lugar donde el camino fácil de la demo se separó de producción, y la traza es donde encontrás la separación en vez de teorizar sobre ella.

Si un modo de falla le pegó a tu agente y no está acá, escribí a hello@wearecleon.com — lo agregamos, con crédito.

Related

Reference: