Las cinco piezas de un agente, y qué se rompe en cada una

Casi todos los diagramas de agentes que circulan dibujan lo mismo: un modelo, unas herramientas, una flecha que vuelve. Es bonito y no sirve para gran cosa, porque un agente no falla por donde está dibujado.

Después de montar unos cuantos y ver romperse unos cuantos más, esta es la anatomía que uso. Cinco piezas, y lo que importa de cada una no es qué hace, sino cómo se rompe.

1 · El modelo

Es la pieza en la que todo el mundo se fija, y en mi experiencia la que menos decide el resultado. Si tu agente funciona mal, cambiar de modelo rara vez lo arregla; normalmente mueve el problema.

Cómo se rompe: no determinismo. El mismo encargo, dos caminos distintos. No es un defecto, es la naturaleza de la herramienta, pero convierte «no reproducible» en una respuesta frecuente, y eso contamina todo el diagnóstico.

Qué hago: fijar lo que se pueda fijar —temperatura baja, versión del modelo anclada— y aceptar que el resto hay que afirmarlo por resultado, no por camino. Si tu prueba exige que pase por los mismos cuatro pasos, va a fallar por motivos que no te importan.

2 · El contexto

Lo que el agente sabe en el momento de decidir: la instrucción, el historial, los documentos que recuperó, lo que devolvieron las herramientas.

Esta es, de largo, la pieza que más resultado explica. Y tiene dos averías distintas que se confunden todo el rato:

La segunda columna es contraintuitiva: más contexto no es mejor contexto. Un agente con demasiado delante se despista, mezcla tareas y arrastra decisiones viejas que ya no valen. Cuando algo va mal, mi primer movimiento ya no es añadir instrucciones: es mirar qué puedo quitar.

3 · Las herramientas

Lo que puede hacer de verdad: leer un fichero, llamar a una API, ejecutar un comando, escribir en una base de datos.

Aquí el agente deja de producir texto y empieza a producir efectos, y por eso cambia la naturaleza del riesgo.

La tercera es la que más me ha mordido. Una herramienta que atrapa su propio error y devuelve «ok» deja al agente avanzando sobre una premisa falsa, y el fallo aparece cinco pasos después, donde ya no se parece a su causa.

4 · El bucle

Qué pasa después de cada paso: si observa el resultado, si replanifica, si reintenta.

Cómo se rompe: el agente interpreta un fallo permanente como algo temporal y vuelve a intentarlo. Y otra vez. El servicio devuelve 403 porque faltan permisos —eso no se arregla esperando— y él lo trata como un parpadeo de red.

Cada vuelta consume tokens, tiempo y a veces dinero real. Y desde fuera no se ve: el agente «está trabajando».

Qué hago: distinguir en las propias herramientas lo que merece reintento —tiempo de espera agotado, 503— de lo que no —403, 404, validación—. Si el error dice que no vas a poder, reintentar es quemar presupuesto.

5 · El criterio de parada

La pieza que no sale en ningún diagrama y la que vacía la cuenta.

¿Cuándo deja de intentarlo? No cuando termina bien —eso es fácil— sino cuando no está consiguiéndolo.

El cuarto freno es cultural más que técnico. Un agente que se detiene y pregunta se percibe como que «no funciona», y hay presión para quitarle esa puerta. Es justo al revés: el que no sabe parar es el peligroso, porque va a hacer algo para no quedarse quieto.

Qué afirmo en cada pieza

Si me preguntas qué pruebo de un agente, es esto, y no «si la respuesta es buena»:

Lo desarrollé más en orquestar a mano o gestionar el estado, que va de cómo se prueba cada paso por separado sin tener que repetir el viaje entero.

Si el diagrama que tienes del agente solo lleva el modelo y las herramientas, te faltan las dos piezas que de verdad deciden si esto es sostenible: lo que sabe cuando decide, y cuándo acepta que no puede.

La primera explica casi todos los resultados malos. La segunda explica casi todas las facturas raras.