¿Tu librería es realmente usable por agentes? Cómo medirlo y qué mejorar

Introducción

Los agentes de código —modelos que generan, ejecutan y depuran código— cada vez interactúan más con nuestras bibliotecas en vez de pedirnos ayuda directa. Cuando una API es engorrosa o la documentación está desactualizada, el agente puede reescribir lógica o tomar rutas más costosas. Eso transforma los criterios de calidad del software: además de correcto y rápido, el código debe ser “conducible” por un agente.

Hugging Face presentó un enfoque práctico usando transformers como caso de estudio para medir no solo si un agente llega a la respuesta correcta, sino cuánto trabajo le costó llegar allí. En este artículo explico el razonamiento, la metodología y las implicancias para equipos y tomadores de decisión en América Latina.

Por qué no basta con evaluar la respuesta final

Dos agentes pueden dar la misma etiqueta correcta en una tarea de clasificación, pero recorrer caminos muy distintos. Uno puede:

• Generar y ejecutar un script Python de 40 líneas, importar transformers, arreglar errores y reintentar varias veces.
• Ejecutar un único comando en una CLI preparada: transformers classify —model … —text ”…” y terminar en una llamada.

Ambos obtienen “POSITIVE” en el ejemplo de sentimiento, pero difieren en costo, latencia, tokens consumidos y puntos de falla potenciales. Si su evaluación solo mira el resultado final, pierde estas diferencias críticas que afectan el coste operativo y la experiencia del desarrollador (y del agente).

Principios para diseñar librerías “agent-friendly”

Hugging Face propone dos principios simples pero poderosos:

• Si no está probado, no funciona.
• Si no está documentado, no existe.

Para que una herramienta exista para un agente debe ser descubrible y comprensible: APIs claras, documentación accesible, ejemplos auto-contenidos y estructuras de archivos que el agente pueda encontrar rápido. Además, esas pruebas y documentación deben diseñarse pensando en el flujo del agente (ejemplos ejecutables, CLI, Skills).

Caso de estudio: transformers y el enfoque de evaluación

Los autores usaron transformers como ejemplo para ver cuánto se podría simplificar su uso desde la perspectiva de un agente. La hipótesis fue que con unos pocos cambios —una CLI, un Skill y ejemplos compactos por tarea— el agente necesitaría menos pasos y tokens para completar tareas.

Para medirlo rigurosamente se creó un “harness” que evalúa no solo la respuesta final sino el proceso entero: comandos generados por el agente, número de ejecuciones, mensajes de error, tokens usados y tiempo. El experimento corrió completamente con modelos abiertos guiados por el pi coding agent, y cada combinación de modelo × revisión × tarea se ejecutó en Hugging Face Jobs para asegurar hardware idéntico entre corridas.

Cómo se estructuran las evaluaciones

Cada tarea se ejecuta bajo tres variantes (o “tiers”) que representan distintos niveles de ayuda que un agente puede recibir:

1. pip: instalación básica con pip install transformers, sin ayudas adicionales.
2. clone: el repositorio completo de transformers clonado en el directorio de trabajo (el agente puede leer el código fuente y archivos del proyecto).
3. skill: un paquete “Skill” que incluye la documentación de la CLI y ejemplos por tarea, cargado en contexto (no incluye todo el árbol fuente).

Estas opciones no son jerárquicas: “skill” no contiene “clone” y viceversa; cada una ofrece un tipo diferente de ayuda. En algunos casos un modelo se comportó mejor con clone que con skill y viceversa.

Qué métricas importan (y cuáles se evitan por ahora)

Para facilitar la comparación inicial, el experimento se enfocó en tareas determinísticas con respuestas exactas —ideal para medir impactos reproducibles. Las métricas observadas incluyen:

• Cantidad de tokens que el agente consumió para planear y ejecutar.
• Número de ejecuciones o reintentos necesarios.
• Latencia y tiempo total hasta la respuesta final.
• Tipos de fallas encontradas (errores de forma, imports, shape errors).

En trabajo previo sobre optimizar la CLI para agentes, Hugging Face observó reducciones de tokens del orden de 1.3–1.8× y en casos puntuales hasta 6× menos tokens cuando la CLI y la documentación fueron diseñadas para agentes. Esos ahorros reducen costos y velocidad de desarrollo, y amplían la viabilidad de usar modelos en entornos con presupuesto limitado —un punto relevante para equipos en América Latina.

Ejemplo ilustrativo

Considere la tarea de clasificar el sentimiento de: “I absolutely loved the movie, it was fantastic!”. Aquí se muestran dos caminos que un agente pudo tomar (resumidos):

• Generar y ejecutar un script Python que usa transformers, torch y procesamiento manual:

from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch
import torch.nn.functional as F

model = AutoModelForSequenceClassification.from_pretrained("distilbert/distilbert-base-uncased-finetuned-sst-2-english")
tokenizer = AutoTokenizer.from_pretrained("distilbert/distilbert-base-uncased-finetuned-sst-2-english")
inputs = tokenizer("I absolutely loved the movie, it was fantastic!", return_tensors="pt")
with torch.no_grad():
    logits = model(**inputs).logits
    probs = F.softmax(logits, dim=1)
    idx = torch.argmax(probs, dim=1).item()
    print(model.config.id2label[idx], probs[0][idx].item())

• Ejecutar un único comando con la CLI optimizada:

transformers classify \
  --model distilbert/distilbert-base-uncased-finetuned-sst-2-english \
  --text "I absolutely loved the movie, it was fantastic!"

Ambos llegan al mismo resultado, pero el segundo camino es mucho más eficiente para un agente.

Implicancias para equipos en América Latina

• Costos y recursos: reducir tokens y reintentos tiene un impacto directo en costos de inferencia y en tiempo de desarrollo. Para startups y áreas de TI con presupuestos acotados, estas optimizaciones son valiosas.
• Productividad: proporcionar Skills, ejemplos ejecutables y una CLI bien diseñada acelera el tiempo a valor y reduce dependencia de desarrolladores seniors para tareas rutinarias.
• Gobernanza y confiabilidad: medir el proceso facilita detectar puntos de falla recurrentes y planear tests automáticos orientados a agentes.

Qué pueden hacer los mantenedores hoy

• Priorizar ejemplos pequeños y auto-contenidos por tarea (scripts y comandos) que un agente pueda ejecutar sin navegar por docstrings largas.
• Añadir una CLI consistente y documentada con ejemplos en la documentación principal.
• Empaquetar “Skills” o guías condensadas orientadas a flujos concretos (clasificación, transcripción, etc.).
• Integrar pruebas que midan rutas agentic, no solo la salida final.

Cierre

El paso de humanos a agentes como usuarios principales de herramientas de ML exige cambiar la forma en que diseñamos, documentamos y testeamos bibliotecas. Medir el proceso —tokens, reintentos, latencia— nos da señales accionables sobre qué mejorar. Para equipos en Latinoamérica, donde presupuesto y tiempo son recursos críticos, optimizar la experiencia agentic puede significar ahorros concretos y despliegues más rápidos.

Si mantienen una librería o trabajan con herramientas ML, empiecen por tareas determinísticas y prueben las tres variantes (pip, clone, skill). Los cambios son, a menudo, menos ingresos de código y más en documentación estructurada y ejemplos ejecutables: inversiones con alto retorno.