Revisé 300 Logs de Fallos de Agentes. El Problema Nunca Fue el Prompt.

Trescientos logs de fallos de agentes. Los revisé durante dos semanas, etiquetando cada uno por causa raíz. El resultado me sorprendió: los problemas de prompt representaban apenas el 12%. ¿El resto? El contexto estaba contaminado, desbordado o simplemente ausente. Cambiar de modelo no ayudó. Cambiar de herramientas no ayudó. El patrón se repetía cada vez.

Llevo un tiempo trabajando en context engineering, así que cuando apareció un proyecto de código abierto llamado Agent Skills for Context Engineering y rápidamente superó las 10,000 estrellas en GitHub, le presté atención. Tiene licencia MIT, lo creó un context engineer llamado Muratcan Koylan, y está citado en un paper del laboratorio de IA de la Universidad de Pekín. Esa última parte fue lo que me convenció de clonarlo.

Los contextos más pequeños son más precisos

Yo asumía que meter más tokens en el contexto siempre ayudaría. Estaba equivocado. El primer principio que enseña este conjunto de habilidades es “densidad de información, no volumen de información.”

A medida que el contexto se vuelve más largo, los modelos pierden el hilo de lo que está en el medio. Este es el efecto de curva en U: el modelo lee bien el principio y el final, pero se salta todo lo que queda entre ambos. Lo probé yo mismo llenando el contexto hasta 128K tokens, y luego comprimiendo la misma información a 32K. La versión comprimida obtuvo mejores resultados en precisión.

El costo de procesamiento no escala de forma lineal con el número de tokens; sube de manera exponencial. Reducir el contexto a la mitad acortó la latencia de respuesta entre un 40 y un 60 por ciento. Incluso con prefix caching, los inputs largos siguen siendo costosos. El resumen en una línea: lo que importa es cuánta información útil logran empacar dentro de un presupuesto de tokens determinado.

Las descripciones de herramientas determinan el 80% del rendimiento del agente

Pueden escribir un prompt perfecto, pero si las descripciones de sus herramientas son imprecisas, el agente elige la herramienta incorrecta. Este conjunto de habilidades lo plantea muy bien: “Las herramientas son contratos que leen los LLMs, no los humanos.” Cuando mi equipo construyó un servidor MCP, reescribimos las descripciones de nuestras herramientas siguiendo esta guía. Los fallos en la selección de herramientas bajaron notablemente.

Cada descripción de herramienta necesita especificar cuándo usarla y qué devuelve. Cuando dos herramientas se superponen en función, los humanos se confunden, y los agentes se confunden todavía más. Una herramienta completa generalmente supera a varias herramientas más limitadas. Y los mensajes de error tienen que decirle al agente qué hacer a continuación, no solo qué salió mal.

Los sistemas multi-agente necesitan arquitectura antes que agentes

Poner en marcha múltiples agentes y esperar que colaboren de forma automática es una ilusión. El repositorio define tres patrones con claridad: un orquestador que dirige agentes subordinados, un modelo peer-to-peer donde los agentes se comunican como iguales, y una cadena jerárquica de delegación.

Después de probar los tres en producción, el patrón de orquestador fue el más predecible y el más fácil de depurar. Los agentes subordinados pasaban resultados a través del sistema de archivos. El modelo peer-to-peer funcionó mejor para tareas creativas, pero corría el riesgo de generar bucles infinitos. Para consultas estructuradas, los archivos compartidos superaron a la búsqueda vectorial. En la práctica, encontré que tres agentes es el techo de estabilidad.

La búsqueda vectorial sola no puede manejar la memoria

La búsqueda vectorial encuentra fácilmente “El Cliente X compró el Producto Y en la Fecha Z”. No puede responder “¿Qué más compraron los clientes que compraron el Producto Y?” La información relacional se pierde en los embeddings.

El conjunto de habilidades propone una arquitectura de memoria de cuatro niveles: working memory dentro de la ventana de contexto, memoria a corto plazo dentro de una sesión, memoria a largo plazo entre sesiones, y memoria permanente como archivos. El patrón de sistema de archivos como memoria fue el más práctico que probé. Navegan el contexto con ls y grep en lugar de consultas de embedding. Volcar los resultados de las herramientas en un archivo de borrador ahorró una cantidad significativa de espacio en la ventana de contexto.

La evaluación es la habilidad más subestimada en los agentes

Esta fue la sección que casi me salté, y resultó ser la más valiosa. El repositorio incluye un framework de evaluación en TypeScript que usa LLMs como jueces. Incluso genera rúbricas de puntuación de forma automática.

Lo que me impresionó fue la mitigación del position bias. Al comparar dos respuestas lado a lado, el framework evalúa dos veces con el orden invertido. Esto contrarrestaba la tendencia a calificar más favorablemente la respuesta que aparece primero. Soporta tanto puntuación directa como comparación por pares. Construir un pipeline de evaluación significó que finalmente pude medir si los cambios en el prompt realmente mejoraban el rendimiento, en lugar de simplemente suponerlo.

Una cosa que el repositorio no resuelve: las rúbricas de evaluación todavía necesitan calibración humana. Las rúbricas generadas automáticamente daban puntos de partida razonables, pero tuve que ajustar los pesos de puntuación para mi dominio específico antes de que los resultados fueran confiables.

Cuando su agente comete un error, revisen el contexto antes de culpar al modelo. El repositorio está aquí.